From 9d842cdfc9793da4990bda4bbd0b62a06809eb89 Mon Sep 17 00:00:00 2001
From: Jakub Zika <zikajk@gmail.com>
Date: Thu, 10 Sep 2026 18:28:34 +0200
Subject: [PATCH] Make the brepl skill self-contained with verified CLI
 guidance

Replace repeated examples with a compact command reference and practical
safeguards for shell quoting, input precedence, server selection, raw
nREPL responses, and bracket repair.

Keep installation and optional hook setup in brepl's own documentation
so the skill-only plugin can be published independently.
---
 plugins/brepl/README.md             |  47 ++-----
 plugins/brepl/skills/brepl/SKILL.md | 202 +++++++++-------------------
 2 files changed, 80 insertions(+), 169 deletions(-)

diff --git a/plugins/brepl/README.md b/plugins/brepl/README.md
index 201cb75..6de50ba 100644
--- a/plugins/brepl/README.md
+++ b/plugins/brepl/README.md
@@ -1,45 +1,24 @@
 # brepl
 
-A skill that teaches ECA the correct heredoc pattern for evaluating Clojure code via [brepl](https://github.com/licht1stein/brepl), a REPL client.
+A skill for evaluating Clojure code with [brepl](https://github.com/licht1stein/brepl).
+This plugin provides instructions only. It does not install the brepl executable,
+configure hooks, or automatically evaluate edits.
 
 ## Requirements
 
-> ⚠️ **You must have `brepl` installed and available on your PATH.**
->
-> Install it from [github.com/licht1stein/brepl](https://github.com/licht1stein/brepl) before using this plugin.
->
-> You also need a running nREPL server (e.g., started via `lein repl`, `clj -M:nrepl`, or your build tool of choice).
+Install `brepl` separately and make it available on ECA's `PATH`.
+Evaluation requires a running nREPL server. Manual bracket repair does not.
 
-## What it provides
-
-- **`brepl` skill** — Must be loaded before any brepl usage. Teaches the heredoc pattern that eliminates shell quoting issues when evaluating Clojure expressions.
-
-## Why this skill matters
-
-Shell quoting with Clojure is error-prone: Clojure uses both single and double quotes, nested quotes require escaping, and reader macros can confuse the shell. The heredoc pattern (`<<'EOF'`) eliminates all these issues by passing code literally to brepl.
+See the [brepl repository](https://github.com/licht1stein/brepl) for installation
+instructions and optional hook setup.
 
 ## Usage
 
-The skill is automatically loaded when needed. You can also request it explicitly:
-
-```
-Load the brepl skill and evaluate my test
-```
-
-### Quick example
-
-```bash
-brepl <<'EOF'
-(require '[clojure.string :as str])
-(str/join ", " ["hello" "world"])
-EOF
-```
-
-## Features covered by the skill
+ECA normally loads the `brepl` skill automatically when needed. You can also
+ask ECA to load it explicitly. The skill covers command options, safe quoting,
+server selection, file loading, raw nREPL messages, error handling, and manual
+bracket repair. Its usage instructions are self-contained.
 
-- **Heredoc pattern** for reliable multi-line evaluation
-- **File loading** via `brepl -f`
-- **Bracket fixing** via `brepl balance`
-- **Common patterns** — namespace reloading, doc lookup, error inspection, test running
+Updating this plugin does not change existing hook configuration.
 
-Credits: Based on the [brepl](https://github.com/licht1stein/brepl) project by @licht1stein.
+Credits: Based on [brepl](https://github.com/licht1stein/brepl) by @licht1stein.
diff --git a/plugins/brepl/skills/brepl/SKILL.md b/plugins/brepl/skills/brepl/SKILL.md
index 0d40b80..375b8f4 100644
--- a/plugins/brepl/skills/brepl/SKILL.md
+++ b/plugins/brepl/skills/brepl/SKILL.md
@@ -1,51 +1,31 @@
 ---
 name: brepl
-description: "MANDATORY - Load this skill BEFORE using brepl in any way. Teaches the heredoc pattern for reliable Clojure code evaluation."
+description: "Evaluate Clojure code and use the REPL via brepl. Load this skill before using brepl."
 ---
 
-# brepl - Evaluating Clojure Code
+## Requirements
 
-## CRITICAL: Load This Skill First
+Use an installed `brepl` binary on `PATH`. Evaluation requires a running nREPL
+server; manual bracket repair does not.
 
-**You MUST load this skill before using brepl.** Do NOT attempt to use brepl without loading this skill first, or you will use incorrect syntax.
+## Command Reference
 
-## Overview
+- `brepl -e EXPR` or `brepl EXPR`: evaluate one expression argument.
+- `brepl` with stdin: evaluate code from a pipe or heredoc.
+- `brepl -f FILE`: load and execute a file.
+- `brepl -m MESSAGE`: send a raw nREPL message in EDN format.
+- `-p PORT`, `-h HOST`: select the nREPL server. `-h` is not help.
+- `--verbose`: show raw protocol messages instead of normal result output.
+- `--help` or `-?`: show help. `--version`: show the installed version.
+- `brepl balance FILE [--dry-run]`: repair brackets, or preview the repair.
 
-brepl is a REPL client for evaluating Clojure expressions. This skill teaches the heredoc pattern for reliable code evaluation.
+## Evaluating Code
 
-**Always load this skill before using brepl. Always use the heredoc pattern for all Clojure code evaluation.**
-
-## The Heredoc Pattern - Default Approach
-
-**Always use heredoc for brepl evaluation.** This eliminates quoting issues, works for all cases, and provides a consistent, reliable pattern.
-
-### Syntax (Stdin - Recommended)
-
-```bash
-brepl <<'EOF'
-(your clojure code here)
-EOF
-```
-
-This is the simplest heredoc syntax - stdin feeds directly to brepl.
-
-### Alternative Syntax (Positional Argument)
-
-For simple one-liners, you can use positional arguments:
-
-```bash
-brepl '(+ 1 2 3)'
-```
-
-Heredoc is preferred for anything with quotes or multiple lines.
-
-**Note**: The `-e` flag is optional - brepl automatically treats stdin and positional arguments as code to evaluate.
-
-**Important**: Use `<<'EOF'` (with quotes) not `<<EOF` to prevent shell variable expansion.
-
-### Examples
-
-**Multi-line expressions**:
+Prefer a quoted heredoc in a Bash-compatible shell. Use `<<'EOF'`, not
+`<<EOF`, to prevent shell expansion. Put the closing `EOF` on its own line.
+Write normal Clojure inside it without extra shell escaping; Clojure string
+escaping still applies. If the shell tool cannot pass multiline input, use a
+positional argument only for simple code that can be quoted safely.
 
 ```bash
 brepl <<'EOF'
@@ -54,137 +34,89 @@ brepl <<'EOF'
 EOF
 ```
 
-**Code with quotes**:
-
-```bash
-brepl <<'EOF'
-(println "String with 'single' and \"double\" quotes")
-EOF
-```
-
-**Reloading and testing**:
-
-```bash
-brepl <<'EOF'
-(require '[myapp.core] :reload)
-(myapp.core/some-function "test" 123)
-EOF
-```
-
-**Complex data structures**:
+A Clojure quote such as `'foo` breaks single-quoted shell arguments; use a
+heredoc for code containing `'`. For simple expressions without it, this works:
 
 ```bash
-brepl <<'EOF'
-(def config
-  {:database {:host "localhost"
-              :port 5432
-              :name "mydb"}
-   :api {:key "secret-key"
-         :endpoint "https://api.example.com"}})
-(println (:database config))
-EOF
+brepl '(+ 1 2 3)'
 ```
 
-**Running tests**:
+`-e` is optional for positional expressions and stdin. Choose one input method:
+`-e EXPR`, positional code, stdin, `-f`, or `-m`. An explicit or positional
+expression causes stdin to be ignored. Do not use bare `-e` with a heredoc;
+it can evaluate `true` instead of the supplied code. Put multiple forms in one
+expression argument or heredoc, not separate positional arguments.
 
-```bash
-brepl <<'EOF'
-(require '[clojure.test :refer [run-tests]])
-(require '[myapp.core-test] :reload)
-(run-tests 'myapp.core-test)
-EOF
-```
+## Selecting the Server
 
-## Alternative: Simple Expressions
+Port priority is `-p`, then `.nrepl-port`, then `BREPL_PORT`, then process discovery.
+Expression and raw-message modes check only the current directory's port file.
+File mode searches upward from the file's directory, stopping at the current
+working directory if it reaches it. Use explicit `-p` when working outside the
+project root or when discovery fails. A stale port file overrides `BREPL_PORT`.
+Select a host with `-h HOST`; the default is `localhost`. Do not rely on
+`BREPL_HOST` in brepl 2.7.1: the CLI default overrides it.
 
-For very simple expressions, you can use direct positional arguments:
+Flags also work with stdin, without `-e`:
 
 ```bash
-# Simple expression
-brepl '(inc 1)'
-
-# Same with heredoc (consistent approach)
-brepl <<'EOF'
-(inc 1)
+brepl -p 7888 <<'EOF'
+(+ 1 2 3)
 EOF
 ```
 
-**Why prefer heredoc:** No mental overhead deciding which pattern to use, no risk of quoting issues, easy to extend.
-
 ## Loading Files
 
-To load an entire file into the REPL:
-
 ```bash
 brepl -f src/myapp/core.clj
 ```
 
-After loading, you can evaluate functions from that namespace using either pattern.
+`-f` sends a `load-file` expression, not file contents. The file must exist locally
+and be accessible at that path on the server. Relative paths use the server's
+working directory; prefer an absolute path accessible to both.
 
-## Fixing Unbalanced Brackets
+## Raw nREPL Operations
 
-Use `brepl balance` to fix unbalanced brackets in Clojure files using parmezan:
+Use EDN (Clojure data notation) with string keys. Discover supported operations first:
 
 ```bash
-# Fix file in place (default)
-brepl balance src/myapp/core.clj
-
-# Preview fix to stdout
-brepl balance src/myapp/core.clj --dry-run
+brepl -m '{"op" "describe"}'
 ```
 
-This is useful for recovering files with bracket errors.
-
-## Common Patterns
-
-### Namespace reloading
+Only use operations advertised by that server. For example, if it supports `info`:
 
 ```bash
-brepl <<'EOF'
-(require '[myapp.core] :reload-all)
-EOF
+brepl -m '{"op" "info" "symbol" "map" "ns" "clojure.core"}'
 ```
 
-### Documentation lookup
+Other useful operations include `lookup`, `complete`, and `ls-sessions`.
+Add `--verbose` to inspect sent and received messages. Read response `status`
+and error fields: raw-message mode can exit `0` even for `eval-error` or `unknown-op`.
 
-```bash
-brepl <<'EOF'
-(require '[clojure.repl :refer [doc source]])
-(doc map)
-(source filter)
-EOF
-```
+## Checking Results
 
-### Error inspection
+Normal evaluation and file loading return exit `2` for evaluation errors;
+argument or connection failures return `1`. Inspect stderr as well as stdout.
+Neither plain evaluation nor `-f` automatically repairs brackets. An evaluation
+can change server state before failing; do not blindly repeat code with side effects.
 
-```bash
-brepl <<'EOF'
-*e
-(require '[clojure.repl :refer [pst]])
-(pst)
-EOF
-```
-
-## Critical Rules
-
-1. **Always use heredoc** - Use the heredoc pattern for all brepl evaluations
-2. **Quote the delimiter** - Always use `<<'EOF'` not `<<EOF` to prevent shell expansion
-3. **No escaping needed** - Inside heredoc, write Clojure code naturally
-4. **Multi-step operations** - Combine multiple forms in one heredoc block
-5. **Write correct Clojure** - Ensure proper bracket balancing and valid syntax
+## Manual Balance Recovery
 
-## Why Always Use Heredoc
+Use `brepl balance` only when an error or file inspection shows unbalanced
+delimiters (parentheses, brackets, or braces). Do not run it as a routine step
+after a successful hook or without delimiter evidence. If a hook reports a
+repair, respect that repair; inspect the current file before further changes.
 
-**Consistency over optimization.** While simple positional arguments work for basic cases, using heredoc everywhere means:
+Preview a repair without changing the file:
 
-1. **No decision fatigue** - One pattern for everything
-2. **No quoting errors** - Everything between `<<'EOF'` and `EOF` is literal
-3. **Easy to extend** - Add more lines without changing syntax
-4. **Readable** - Clear where the code starts and ends
-5. **Safe** - No shell interpretation of Clojure code
+```bash
+brepl balance src/myapp/core.clj --dry-run
+```
 
-Shell quoting with Clojure is error-prone: Clojure uses both single and double quotes, nested quotes require escaping, and reader macros can confuse the shell. Heredoc eliminates all these issues.
+Omit `--dry-run` to change the file in place. Review the resulting diff.
+Do not treat silence as proof that hooks are installed or that evaluation
+succeeded; check hook status and evaluation results separately.
 
 ## Resources
 
-brepl documentation: https://github.com/licht1stein/brepl
+https://github.com/licht1stein/brepl (installation instructions if brepl is unavailable).