@zecalis/fael 0.20.0 → 0.22.0

package/README.md

@@ -5,30 +5,48 @@
 [![CI](https://github.com/zecalis/fael/actions/workflows/ci.yml/badge.svg)](https://github.com/zecalis/fael/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**The secretary for every agent on your team.** Every agent on your repo gets what git can't tell
-it — why a call was made, what was rejected, what's still open — next to the file it opens.
-
-One person runs five agents; a team runs fifty — and each of those hands work to sub-agents. Every
-one of them starts from zero: it finds the same flaky test, re-asks why that function looks weird,
-and repeats the mistake the last agent already fixed.
-Memory tools that try to help stuff a summary of everything into context before the agent has said
-what it's about to do — the one row that mattered gets averaged away, and a summary of stale notes
-is still stale.
-
-fael works the other way round: like a good secretary, it takes the notes nobody else will and hands
-each agent **only what matters for the file in front of it**. The agent writes down what it decided
-or found **in the same reply, at no extra turn**, and when it opens a file it gets **only what was
-written about that file**. The file it touches is the question.
-
-The team isn't only the people who write code. A PM, QA, EM or tech lead writes a requirement, a
-decision or an assignment once — through their own agent or the CLI — and every dev agent that
-touches that code later gets it, so the next feature doesn't forget what the last one agreed.
-
-fael gives the repo a memory that agents can't skip:
-
-- **Writing costs no extra turn.** The agent ends its reply with `fael decision|issue|note: …
-  [files: …]` lines and fael files them — no turn is stopped or re-prompted. Want the old
-  enforcement (no row, no end of turn)? Opt in with `[capture] block = true`.
+**A shared work ledger for every agent on your repo.** Hand work from one session, agent or person to
+the next — a decision, a requirement, an issue assigned to someone, a claim, where a plan stopped —
+and it shows up where the next agent is working: on the file it opens, and at session start for what
+is routed to it.
+
+One person runs five agents; a team runs fifty — and each of those hands work to sub-agents. They
+don't share a chat, so every one starts from zero: it finds the same flaky test, re-asks why that
+function looks weird, picks up the issue another agent is already on, and repeats the mistake the
+last agent already fixed. Tools that stuff a summary of everything into context before the agent has
+said what it's about to do average the one row that mattered away, and a summary of stale notes is
+still stale.
+
+fael works the other way round. The agent writes down what it decided or found **in the same
+message as its next tool call, at no extra turn**, and when it opens a file it gets **only what was
+written about that file**. The file it touches is the question. Work routed to an agent or a person
+lists in full at their session start.
+
+What moves through it:
+
+- **Hand-offs.** `fael add note "pricing page: copy approved, layout half-done" --files
+  src/pricing.tsx --key pricing:page` — the next session or agent gets it when it opens that file or
+  its prompt names the key.
+- **Assignments.** `fael add issue "…" --to ploy` — lists in full at the session start of whoever's
+  git `user.name` is `ploy` (lowercased). `--to opencode` (or `codex`, `claude`) reaches every
+  session of that agent in the repo — Claude hands a review to OpenCode, and what it answers comes
+  back as the close line (`fael find --all`). The receipt prints the line to paste to the other
+  agent and, for an agent, the command that starts it on the row (`opencode run "…"`) — fael
+  prints it, you or your agent runs it, in the worktree you chose. fael never wakes an agent:
+  it reads the row when it next starts or touches the file.
+- **Claims.** `fael claim <id>` — `fael find --kind issue` then shows `(held @<branch>)`, so another
+  agent picks something else. Never a lock.
+- **Requirements and decisions.** A PM, QA, EM or tech lead writes one once — through their own
+  agent or the CLI — and every dev agent that touches that code later gets it, so the next feature
+  doesn't forget what the last one agreed.
+- **Come-backs.** `--revisit <date|text>` brings a row back when it is due.
+
+How it behaves:
+
+- **Writing costs no extra turn.** The agent runs `fael add` in the same message as its next tool
+  call. When a turn ends with no tool call left, it can close its reply with `fael
+  decision|issue|note: … [files: …]` lines and fael files them — no turn is stopped or
+  re-prompted.
 - **Memory finds them.** When an agent reads a file, the decisions and open bugs about *that file*
   come attached — nobody has to remember to search. Sub-agents too: one starts with an empty
   context and only a short brief, and the file it opens brings the memory the brief left out.
@@ -47,7 +65,7 @@ fael gives the repo a memory that agents can't skip:
   shared at once by every worktree, so PRs never carry log lines to conflict on. `fael sync` carries
   them to teammates through your own remote (`refs/fael/*`). No server, no account.
 
-Works with **Claude Code, Codex and OpenCode**, and any MCP host. One small binary; hooks run in 2–3 ms.
+Works with **Claude Code, Codex and OpenCode**, and any MCP host. One small binary; a hook call takes about 10 ms on a repo with a thousand rows (a session start, once, about 100 ms).
 
 ## What you get
 
@@ -56,11 +74,32 @@ Works with **Claude Code, Codex and OpenCode**, and any MCP host. One small bina
 | Each session starts from zero | Session opens with what the last one left: open bugs, recent decisions |
 | "Why is it like this?" — ask again, guess again | The reason sits next to the file, from the agent that made the call |
 | Agent notices a bug mid-task, then forgets it | It's filed on the spot, and shown to whoever touches that file next |
-| Two agents in parallel worktrees hit the same problem | The first files it; the second gets it when it opens the file — the same hour, before any commit |
+| Two agents in parallel worktrees hit the same problem | The first files it; the second gets it when it opens the file — the same hour, before any commit (`fael stats` → `across agents` counts how often) |
 | A sub-agent finds something and its summary drops it | Its `fael issue: …` line is filed when it stops (Claude Code), and the parent gets it on that file |
+| Work is handed over in chat and lost between sessions | A hand-off note, an assigned issue or a claim sits in the ledger — the assignee sees it at session start |
+| Two agents pick the same issue | `fael claim <id>`: the second sees `(held @<branch>)` and picks another |
 | Knowledge stays in one person's chat history | It's in the clone — teammates and their agents get it on `fael sync` |
 | A PM's requirement lives in a ticket the agent never opens | `fael add decision … --files src/pay.rs` — it's in front of the agent the moment it opens the file |
 
+## Does it help? Check your own numbers
+
+fael does not claim to save tokens, turns or time: it cannot see what an agent would have done
+without it. It reports what it handed over, so you can judge on your own repo:
+
+```bash
+fael stats
+```
+
+- `hit N/M rows` per event — rows still in front of the agent when it edited that file. A lower
+  bound: a read-only session scores every row a miss.
+- `across agents` — rows one agent wrote that another was handed, and how many were written while
+  the receiver was working. If you run agents in parallel worktrees, watch this one.
+- `retired at touch`, `issues closed`, `handoffs picked up` — rows closed or picked up.
+
+Most useful when several agents (or people) work in one repo and return to the same files over
+days. Little to gain from one short session in a repo you will not touch again.
+Definitions: [docs/stats.md](docs/stats.md).
+
 ## Install
 
 **1. Get the binary** — prebuilt for macOS, Linux and Windows. No Rust needed.
@@ -105,7 +144,7 @@ Rather review memory in PRs? `store = "tracked"` in `.fael/config.toml` also wri
 ## How it works
 
 ```
-agent reads src/pay.rs   →  fael attaches: "[bug] refund rounds down on JPY → src/pay.rs"
+agent reads src/pay.rs   →  fael attaches: "[bug] refund rounds down on JPY"
 agent fixes it, replies  →  "…done. fael decision: refunds round half-up, per finance [files: src/pay.rs]"
 fael                     →  files that line as a row — no extra turn, nothing blocked
 fael sync                →  the next agent, on any machine, sees it when it opens src/pay.rs

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@zecalis/fael",
-      "version": "0.20.0"
+      "version": "0.22.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.20.0"
+  "version": "0.22.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/zecalis/fael/releases/download/v0.20.0"
+    "https://github.com/zecalis/fael/releases/download/v0.22.0"
   ],
   "bin": {
     "fael": "run-fael.js"
@@ -81,7 +81,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.20.0",
+  "version": "0.22.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"