@gr8ful/spf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IndyDevDan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,321 @@
+# Super Portable Factory
+
+> **Repeatable agents-plus-code workflows, as a global CLI you run against any repo.**
+> Deterministic TypeScript owns the graph. Coding agents are bounded nodes inside it.
+
+A software factory does one thing: it gives you more leverage on your prompt. How much leverage depends entirely on what you invest in it. At the low end you chain two agents together and hope. At the high end you build a system of agents plus code that runs without you, and does the job about as well as you would.
+
+Everyone can get an agent to write code once. Almost nobody gets the same result twice. This fixes that by moving the control plane out of the prompt and into TypeScript. A chain script owns sequencing, retries, and acceptance. Agents work inside named phases. Typed JSON envelopes carry context across the seams. Every event streams into SQLite while it is still happening. **Agent proposes, code disposes.**
+
+---
+
+## Install
+
+```bash
+npm i -g @gr8ful/spf
+```
+
+No Bun, no separate coding-agent binary to install first, no template stamped into your repo. `spf` ships with a packaged default agent roster and default prompts — it runs against any repo with zero setup, and only writes files into that repo if you explicitly ask it to (`spf init`, `spf install-skill`).
+
+```bash
+cd your-repo
+spf doctor                          # confirm everything resolves — paths, roster, provider keys
+spf scout "describe this repo"      # a real, read-only run, no setup required
+```
+
+`spf doctor` is the answer to "why did nothing happen": it resolves and prints every path, validates the whole roster and every quality suite, and checks the things that fail silently otherwise — a missing provider key, a quality check whose binary isn't on `PATH`, a stale `protected_files` pattern.
+
+### Customizing a repo
+
+```bash
+spf init          # seed .spf/spf.config.yaml — override only what you want to change
+spf list          # every chain this install knows, its phases, what it needs
+```
+
+`spf init` writes a small starter `.spf/spf.config.yaml`, commented, that merges on top of the packaged built-ins field by field — override one model, one prompt, one quality check, and everything else stays inherited. Nothing here needs to exist for `spf` to run; it's how you make one repo's roster diverge from the defaults.
+
+### Local development
+
+Working from a clone instead of the published package:
+
+```bash
+git clone git@github.com:seesharpguy/super-portable-software-factory.git
+cd super-portable-software-factory
+npm install
+npm run build     # builds both the CLI (dist/) and the trace visualizer SPA (web/)
+npm link          # makes `spf` resolve globally to THIS checkout
+```
+
+`npm link` beats a real `npm i -g` here: it symlinks the global `spf` bin into this checkout, so every later `npm run build` takes effect immediately, no re-linking. Run it from any repo you want to test against.
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # node --test against dist/**/*.test.js (runs build:cli first)
+npm run size-check  # tarball size gate — what `npm pack` would actually publish
+```
+
+For a one-off check without touching global npm state at all, run the built CLI directly: `node dist/cli/bin.js doctor --cwd /path/to/repo`. When you're done with the linked version, `npm unlink -g @gr8ful/spf` removes it.
+
+---
+
+## Why this exists
+
+Hand a capable model your whole SDLC and you get a machine with no seams. There is no phase boundary, so you cannot say which step failed. There is no acceptance criterion you can name, so "done" means "the agent stopped talking." A retry is a cold start that throws away everything the agent just learned. The only trace is a transcript you have to read like a novel. Run it twice, get two different systems.
+
+The fix is not a better prompt. The fix is deciding, deliberately, that **code owns sequencing, retries, and acceptance, and the agent owns only the work inside one bounded phase**. Everything else falls out of that one line. Phases become the unit of the trace. Envelopes become the only way context crosses a seam. Gates become the definition of done. A correction becomes cheaper than a restart, because the session is still alive.
+
+### Agents are great. You do not always need one.
+
+This is the part most engineers are going to skip, and pay for later.
+
+Code costs nothing. It runs at the speed of light. You can change it in a second. And you actually own it, which is not true of any model you are renting by the token.
+
+So when the invocation is already known, write it down. `npm test` is not a judgement call. Neither is `tsc --noEmit`. An agent rediscovering your test runner burns a context window to learn what a subprocess already knows, and it charges you for the privilege every single run. Worse, it puts a passing test suite into a context window, which buys you nothing at all.
+
+Agents are for the parts that need reading and deciding. Everything else is a `kind: "code"` phase — SPF's own `quality:` config section names the commands, and a chain runs them as code, not as an agent's rediscovery project. When code fails, the failure comes back to the builder as an envelope, through the same door an agent's report would have used. The repair loop is identical. You just stopped paying an agent to do arithmetic.
+
+The bill for skipping this is not only tokens. It is cost, speed, and consistency, and you pay it on run one hundred and run one thousand, not on run one.
+
+> *Same models. Same prompts. The difference is who owns the loop.*
+
+---
+
+## The agent roster
+
+`spf.config.yaml` answers one question per entry: who is this agent. One agent, one prompt, one purpose. `spf init` seeds `.spf/spf.config.yaml`, merged on top of the packaged defaults — an entry only states what differs.
+
+```yaml
+defaults:
+  coding_agent: flue                 # the engine agents run on
+  model: google/gemini-3.6-flash     # provider/model-id — a bare id can match several providers
+  thinking: medium                   # off | minimal | low | medium | high | xhigh | max
+  protected_files: [.spf/, spf.config.yaml]   # no agent may edit the machinery that grades it
+  data_dir: .spf/data
+
+agents:
+  - name: planner
+    model: fireworks/accounts/fireworks/models/kimi-k3
+    thinking: high
+    color: "#a78bfa"                 # this agent's lane color in the trace UI
+    purpose: Turn a request into a plan the builder can implement without asking questions.
+    prompt_engineering:
+      system: planner/system.md
+      user: planner/user.md
+    writes: [specs/]                 # the plan is all it may leave in the repo
+```
+
+Five starter agents ship in the box: `planner`, `builder`, `scout` (read-only recon), `reviewer`, and `documenter`. There is no tester, because running a suite is a known command and therefore code, not an agent's job.
+
+Every agent gets its own model, thinking level, prompts, and tools. Give the planner a frontier model and the builder a cheap fast one. Give the reviewer no ability to write code at all.
+
+**`tools` is a capability list. `writes` is the boundary.** They are not the same thing: `bash` runs anything, including `git checkout`, and `write` reaches any path. So "this agent changes nothing" is enforced in code, after every call, by comparing the repo before and after. Unauthorized changes are rolled back and the phase fails. A read-only agent is read-only with respect to your repo, never unable to write its own report.
+
+Config defines who an agent **is**. The chain call site defines how it is **used**. That split is what lets one agent serve many different calls. **Chains name agents, never models.**
+
+### A second backend: Claude Code
+
+Set `coding_agent: claude_code` on any agent (or in `defaults`) to run it on your own installed [Claude Code](https://claude.com/product/claude-code) CLI instead of Flue — `spf doctor` checks it's on `PATH`. Model names follow Claude Code's own vocabulary (a bare alias like `sonnet`, not `provider/model-id`); everything else — `tools`, `writes`, `thinking` — stays the same shape. Pointing a `claude_code` agent at a local or cloud [Ollama](https://ollama.com) server needs no config at all — just `ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN` set before you run `spf`, since Claude Code's CLI reads those itself.
+
+---
+
+## Phases: three lanes, one primitive
+
+Every run is a sequence of phases, and every phase is the same async scope no matter who owns it.
+
+```ts
+const REQUIRED_AGENTS = ["planner", "builder"];   // names, never models
+
+const cfg = agents.loadConfig(configPaths);
+agents.validate(cfg, REQUIRED_AGENTS, REQUIRED_SUITES, cwd);   // a missing agent fails before anything spawns
+const run = session.ensure(cfg, adwId, cwd);                   // pin-or-create the session
+
+const plan = await run.phase(
+  makePhaseParams({ name: "plan", kind: "agent", owner: "planner", description: "Turn the request into a plan" }),
+  (ph) => ph.call(makeAgentCall({ output_type: PlanOutput, prompt, gates: [gates.artifactsExist] })),
+);
+
+await run.phase(
+  makePhaseParams({ name: "commit", kind: "code", owner: "git", description: "Commit the working tree" }),
+  async () => run.git.commitAll(build.commit_message || `spf: ${prompt.slice(0, 72)}`),
+);
+
+return run.finish();
+```
+
+Three kinds, three swim lanes. **engineer** is the human lane. **agent** is `ph.call(...)`: prompt in, typed envelope out, gates verified. **code** is a deterministic step that stands on its own — a commit, a quality suite — and is never buried inside an agent phase, so the trace shows exactly when code ran and when an agent was working.
+
+**Success must be earned.** Every phase defaults to `fail`. A clean exit flips it, and an agent phase also needs its envelope to parse and every gate to come back green. `run.finish(accepted, reason)` adds the second question, because phases passing is not the same as the run being acceptable: a test phase that ran a red suite did its job perfectly. One call settles the exit code, the session status, and the banner together, so they cannot disagree.
+
+---
+
+## Envelopes and gates
+
+An agent has exactly two output channels: reference files written into `context_handoff/`, and a final valid-JSON response validated against the output type the call declared. Code persists that response as `envelope.json`, records it, and injects it into the next agent's prompt. Context transfers in code, not in conversation.
+
+```ts
+const BuildOutput = envelopeType("BuildOutput", {
+  changed_files: v.optional(v.array(v.string()), () => []),
+  commit_message: v.optional(v.string(), ""),   // consumed by the git commit phase
+});
+```
+
+Determinism is wired into every step. Agents must return a specific structure, every time. If it does not validate, they get asked again until it does.
+
+Gates verify claims, never predictions. Nobody knows which files an agent will touch before it finishes, so gates run **after** the fact against the envelope's own declarations: `artifactsExist`, `filesNonEmpty`, `jsonParses`, `diffMatchesClaims`, `testsPass(...)`. A gate is a function with the signature `gate(envelope, run) -> GateReport`, one `check(item, ok, note)` per thing it examined, so a green gate tells you *what* it verified.
+
+When validation fails or a gate returns violations, **nothing restarts**. The harness re-prompts the same session with a correction naming exactly what was wrong, and the context window stays intact. A cold restart throws away everything the agent learned. A correction costs one message.
+
+The output contract lives in three places and they are one thing: the type in `data_types.ts`, the JSON example in that agent's `user.md` `## Report` section, and `output_type:` at the call site. **Change one, change all three in the same edit** — the synced triad.
+
+---
+
+## The trace
+
+One data path, no exceptions: **agents write to SQLite, readers poll SQLite.** Every event lands in `.spf/data/spf.db` while the agent is still working, not batched at the end — tool calls are visible mid-run.
+
+```bash
+spf sessions                       # recent runs
+spf phases <adw_id>                # phase-by-phase status for one run
+spf events <adw_id> --follow       # the live trace, tailable
+spf ui                             # a browser-based visualizer over the same db
+```
+
+That's the entire transport: a rowid-cursor poll query, run on demand. No push, no WebSocket, no ingest endpoint — live view and full history are the same query at different cadence.
+
+Files stay the raw record (`envelope.json`, `agent_map.json`, Flue's own conversation store). The db is the queryable mirror. Losing it loses nothing you cannot rebuild.
+
+---
+
+## The chains
+
+```bash
+spf list                                              # every chain, its phases, what it needs
+spf <chain> "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4] [--cwd <dir>]
+```
+
+| Chain | Phases | Reach for it when |
+|---|---|---|
+| `prompt` | engineer → \<agent\> | one agent, one prompt, `--agent NAME` picks who |
+| `scout` | engineer → scout | read-only recon, nothing changes |
+| `plan` | engineer → planner | you want the spec before any code |
+| `build` | engineer → builder | the plan already exists |
+| `quality` | engineer → code(quality) | lint, typecheck, build, no agents at all |
+| `plan-build` | planner, builder, git(commit) | small, well-understood work |
+| `build-test` | builder, code(test), bounded fix loop | there is a suite to satisfy |
+| `build-review` | builder, reviewer, bounded revise loop | "is this what was asked for" matters more than "does it run" |
+| `plan-build-test` | plan, build, code(test), git(commit) | the standard chain |
+| `plan-build-test-quality` | same, plus lint/typecheck/build gates | the repo has quality commands worth enforcing |
+| `document` | code(git diff), documenter | write up what just shipped |
+| `simple-sdlc` | plan, build, test, review, document | the work is real and its shape is not obvious |
+
+`--adw-id` is optional everywhere. Omit it and a fresh id is minted and printed. Supply it and the run joins that session — same session directory, each agent **resumes its existing context window** instead of starting cold. That's how you chain runs:
+
+```bash
+spf plan "add a /health endpoint"                        # prints adw_id a1b2c3d4
+spf build-test "implement the plan" --adw-id a1b2c3d4
+```
+
+---
+
+## `spf watch`
+
+Polls a GitHub repo for issues labeled `<prefix>:ready`, runs a configured chain against each in its own git worktree, opens a PR, and tracks it through to merged or blocked — driving the same chains above rather than reimplementing an SDLC. Labels are the whole state machine: `ready → working → review → done`/`blocked`.
+
+```yaml
+# .spf/spf.config.yaml
+watch:
+  repo: owner/name
+  label_prefix: spf          # polls issues labeled spf:ready
+  chain: plan-build-test     # any registered chain
+  base_branch: main
+  poll_ms: 60000
+  concurrency: 2
+```
+
+```bash
+export GITHUB_TOKEN=...     # classic PAT — see "GITHUB_TOKEN scope" below; spf doctor checks it's set
+spf watch init                # idempotently create/update the 5 labels below — run this first
+spf watch                    # foreground daemon; Ctrl-C drains in-flight claims first
+spf watch --once             # one poll tick, then exit — good for cron
+spf watch --dry-run          # log intended claims/transitions, mutate nothing
+```
+
+`spf watch init` seeds `<prefix>:ready`/`working`/`review`/`done`/`blocked` with a color and description each — safe to re-run any time (creates what's missing, corrects any that drifted, leaves the rest alone).
+
+No GitHub App, no webhook — it's a plain REST poll, same philosophy as the trace db's own polling contract. See [`docs/examples/`](docs/examples/) for full worked configs, and `spf install-skill`'s installed skill (`roster.md`, `references/config.md`) for the field-by-field reference.
+
+### `GITHUB_TOKEN` scope
+
+A **classic** PAT (fine-grained tokens use different permission names — not covered here), scoped to the minimum that covers every call `spf watch`/`spf watch init` makes: creating/editing labels, reading and labeling issues, posting comments, opening PRs, and reading PR/check-run status.
+
+| Target repo | Scope | Covers |
+|---|---|---|
+| Private | `repo` | Everything above, full read/write |
+| Public only | `public_repo` | The same, restricted to public repos |
+
+**Do not grant the `project` scope.** It's a separate, unrelated permission for GitHub Projects (classic/org/user boards) — `spf watch` doesn't touch Projects at all (deliberately out of scope for v1; see the label-based state machine above), so granting it would just be more access than this tool ever uses.
+
+There's no dedicated "issues" or "pull requests" scope on classic PATs — GitHub bundles both into `repo`/`public_repo`, which is why that's the whole table.
+
+## What's in this repo
+
+```
+super-portable-software-factory/
+├── src/
+│   ├── cli/        # the `spf` command surface
+│   ├── chains/      # the twelve starter chains + the registry
+│   ├── core/        # config, agents, gates, quality, the sqlite trace, paths
+│   └── ui/          # the trace visualizer's server side
+├── app/             # the trace visualizer SPA (Vue), built once at publish time
+└── assets/
+    ├── defaults/    # the packaged default roster
+    ├── prompts/     # default system.md + user.md per starter agent
+    └── skill/       # an optional Claude Code skill — `spf install-skill` to use it
+```
+
+There's no template stamped into your repo. Everything above ships inside the installed npm package; a repo you run `spf` against only ever gains a `.spf/` directory, and only if you ask for one.
+
+---
+
+## Where it can still fail
+
+Honest edges, because knowing them is cheaper than discovering them.
+
+| Failure | What actually happens | What to do |
+|---|---|---|
+| A quality-gated chain with no `quality:` configured | Fails loudly at `spf doctor`/validate time, before anything spawns | Add a `quality:` section to `.spf/spf.config.yaml` — there's no packaged default suite on purpose |
+| A bare model pattern | The same model can sit under several providers, so an unqualified pattern is ambiguous | Always write `provider/model-id` |
+| A coding agent hangs silently | No events, no tokens. The trace goes quiet rather than red | `spf phases <adw_id>` shows what's still `running`; `spf abort <adw_id>` stops it |
+| The synced triad drifts | Envelope type, `## Report` example, and `output_type:` disagree, so every call burns correction rounds | Grep the type name and fix all three in one edit |
+| Gates pass, output is bad | Gates check what a predicate can check, not plan quality or code taste | Run the `reviewer`, or read it yourself |
+| An agent edits something it shouldn't | Detected and rolled back after the call, and the phase fails | Expected. Widen that agent's `writes` if the change was legitimate |
+| Commit phase has nothing to commit | Throws if the cwd isn't a git repo or nothing changed | `git init` with one commit first |
+
+Also missing on purpose, so you know what to add: chains run on your current branch by default. For real work you want a branch or worktree per run and a merge step at the end.
+
+**Is this overkill for a one-off feature?** Yes. Prompt an agent and move on. This earns its keep when the same workflow runs a hundred times, when validation is the only thing standing between you and a bad merge, and when you need the thousandth run to look like the first.
+
+---
+
+## Built to be observed, customized, and reused
+
+Nothing here is meant to survive contact with your codebase unchanged. The prompts describe a demo app, not your domain. The roster names the models that were good the week it was written. All of that is supposed to be replaced — `spf init` gives you the seam to do it one field at a time, and `spf eject` gives you an editable copy of the engine itself if you need to go further than config.
+
+| Change | Where | Why |
+|---|---|---|
+| Your real commands | `.spf/spf.config.yaml`'s `quality:` | There's no packaged default suite — an unconfigured one fails loudly, on purpose |
+| Your prompts | `.spf/prompt_engineering/{agent}/` | Where your standards live: what a good plan looks like, what a review has to catch |
+| Your roster | `.spf/spf.config.yaml` | Models, thinking levels, tools, and what each agent is allowed to write |
+| Your definition of done | a new gate in `core/gates.ts` (via `spf eject`) | A gate is one function |
+
+So take it. Strip the parts you don't need, rename the agents, throw out half the chains, and roll what's left into the factory your project actually needs. The specific chains here matter far less than the shape: code owns the loop, agents own the phases, and every run leaves a trace you can go read.
+
+---
+
+## Provenance
+
+Super Portable Factory began as a fork of [disler/super-simple-software-factory](https://github.com/disler/super-simple-software-factory). Its MIT license is preserved unmodified in this repo's [`LICENSE`](LICENSE).
+
+## License
+
+MIT, see [`LICENSE`](LICENSE).

package/assets/defaults/spf.config.yaml

@@ -0,0 +1,141 @@
+# spf.config.yaml — the factory's agent roster. One agent, one prompt, one purpose.
+# Runs on Flue (@flue/runtime) — coding_agent: flue is the only implemented value.
+defaults:
+  coding_agent: flue
+  model: google/gemini-3.6-flash   # provider/id — a bare pattern is ambiguous across providers
+  thinking: medium                 # off | minimal | low | medium | high | xhigh | max
+  harness_engineering: []          # no Flue analogue — must stay empty, see agents.validate()
+  # Roster-wide allowlist; any agent may override with its own list. Known
+  # names: read, write, edit, bash, grep, glob, find (alias for glob). "ls" is
+  # a known name with no Flue builtin (bash/glob cover it) — harmless to list,
+  # it is simply dropped rather than mounted.
+  tools:
+    - read                         # read file contents
+    - bash                         # execute bash commands
+    - edit                         # find/replace edits
+    - write                        # create/overwrite files
+    - grep                         # search file contents  (pi default: OFF)
+    - find                         # find files by glob     (pi default: OFF)
+    - ls                           # list directories       (pi default: OFF)
+  # Off-limits to every agent that does not name them in its own `writes`.
+  # `tools` alone cannot protect these: bash runs `git checkout`, and write
+  # reaches any path. An agent must not be able to edit the machinery that
+  # decides whether its own work passed. Enforced in core/permissions.ts.
+  #
+  # `writes:` per agent says what it may change IN THE REPO. It never restricts
+  # the session runtime under data_dir — context_handoff/, envelopes, prompts,
+  # raw output. Every agent can always write its own report; `writes: []` means
+  # read-only with respect to the repo, not mute.
+  protected_files:
+    - .spf/
+    - spf.config.yaml
+  data_dir: .spf/data               # runtime home: {data_dir}/sessions/{adw_id}/{agent_name}/
+
+observability:
+  db: .spf/data/spf.db               # tracer writes here directly; the UI polls it
+  poll_ms: 500                     # visualizer live-poll cadence
+
+# No default quality checks or suites are shipped — an unconfigured chain
+# that needs one fails loudly at agents.validate() time (before anything
+# spawns) rather than reporting a placeholder green. Add your own, e.g.:
+#   quality:
+#     checks:
+#       - {name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 600}
+#       - {name: lint, operation: lint, argv: ["npx", "eslint", "."], timeout_seconds: 120}
+#     suites:
+#       test: [test]
+#       all: [test, lint]
+
+agents:
+  - name: planner
+    model: fireworks/accounts/fireworks/models/kimi-k3
+    thinking: high
+    color: "#a78bfa"                 # optional hex — the agent's lane color in the visualizer
+    purpose: Turn a request into a plan the builder can implement without asking questions.
+    prompt_engineering:
+      system: planner/system.md
+      user: planner/user.md
+    writes:                        # the plan is the only thing it may leave in the repo
+      - specs/
+    tools:                         # full recon + write for plan.md; no edit — the planner never touches repo files
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+
+  - name: builder
+    color: "#22d3ee"
+    purpose: Implement the plan exactly; report every changed file in the envelope.
+    prompt_engineering:
+      system: builder/system.md
+      user: builder/user.md
+    # No `writes` key: unrestricted, and the only agent that is. It still cannot
+    # touch defaults.protected_files — the builder does not get to edit its own grader.
+    tools:                         # the only agent that mutates the repo — everything on
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - edit
+      - write
+
+  - name: scout
+    color: "#fbbf24"
+    purpose: Find and report where things live; change nothing.
+    prompt_engineering:
+      system: scout/system.md
+      user: scout/user.md
+    writes: []                     # read-only, and now actually read-only: its findings
+                                   # go to context_handoff/, which is runtime, not the repo
+    tools:                         # search-heavy recon; write only so scout_findings.md lands without a bash heredoc
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+
+  # No tester agent: running the suite is a known command, so it is a kind="code"
+  # phase over core/quality.ts. See SKILL.md hard rule 8.
+
+  - name: reviewer
+    model: openai/gpt-5.6-terra
+    thinking: high
+    color: "#fb7185"
+    purpose: Confirm that what was built is what was asked for; change nothing.
+    prompt_engineering:
+      system: reviewer/system.md
+      user: reviewer/user.md
+    writes: []                     # a reviewer that cannot fix cannot quietly fix — the
+                                   # claim the tool list only implied, now enforced
+    tools:                         # full read surface; write only for review.md, no edit
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+
+  - name: documenter
+    model: openai/gpt-5.6-luna
+    color: "#e879f9"
+    purpose: Write up the change that was just made, from the diff; document only.
+    prompt_engineering:
+      system: documenter/system.md
+      user: documenter/user.md
+    writes:                        # documentation only — "document only" is a rule now,
+      - app_docs/                  # not a line in a prompt the model may drift from.
+      - docs/                      # Markdown anywhere, because docs live next to the
+      - "**/*.md"                  # code they describe as often as in a docs folder.
+      - "*.md"
+    tools:                         # reads the diff and the code; writes/edits documentation only
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+      - edit

package/assets/prompts/builder/system.md

@@ -0,0 +1,13 @@
+# Builder Agent
+
+## Purpose
+
+Implement the plan (or request) exactly; report every file you changed.
+
+## Instructions
+
+- If `previous_envelope` references a plan or test failures, follow them — they are your spec.
+- Make the smallest change that satisfies the request; do not refactor unrelated code.
+- When fixing test failures, address every reported failure.
+- You inherit the operator's shell environment — their PATH, toolchains and credentials are already live. Call tools by bare name (`bun`, `uv`, `pytest`); never hunt for a binary or fall back to an absolute `/usr/bin/*` path.
+- Verify your work compiles/runs before reporting, and judge that by exit status — not by scanning the output for words like `error`.

package/assets/prompts/builder/user.md

@@ -0,0 +1,34 @@
+# Build Task
+
+## Variables
+
+### prompt
+
+{{prompt}}
+
+### previous_envelope
+
+{{previous_envelope}}
+
+### context_handoff_dir
+
+{{context_handoff_dir}}
+
+## Task
+
+Implement the work described in `prompt`, guided by `previous_envelope` if present, then emit your `Report` JSON.
+
+## Report
+
+Respond with ONLY valid JSON matching `BuildOutput` — no prose before or after:
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence describing what you built>",
+  "changed_files": ["src/server.ts"],
+  "artifacts": [],
+  "commit_message": "<imperative one-line git subject for the code you changed — this is what the commit of your work will say>",
+  "notes_for_next_agent": "<how to verify this work>"
+}
+```

package/assets/prompts/documenter/system.md

@@ -0,0 +1,17 @@
+# Documenter Agent
+
+## Purpose
+
+Write up the change that was just made, from the diff, for the engineer who arrives next.
+
+## Instructions
+
+- `previous_envelope` carries the captured change: `base` (what it was measured against), `changed_files`, `stat`, and `diff_path`. **Read `diff_path`** — the full diff is the source of truth.
+- Everything you write must be traceable to that diff. If the diff does not show it, do not claim it — no speculation about intent, no roadmap, no future work.
+- **Name a file only if it is in `changed_files` or appears in the diff.** Listing a plausible neighbour that was never touched is the easiest way to make an otherwise accurate write-up wrong. Check the list before you write the sentence.
+- Document what the change does, where it lives, and how to use or verify it. It is a write-up for a human, not a commit log and not a replay of the diff.
+- Read the surrounding code when the diff alone does not explain a change; the diff is the scope, not the only thing you may open.
+- Write documentation only. Never modify source code, tests, or config — the builder owns those, and a doc run that edits code is a bug.
+- List `app_docs/` before naming your write-up and pick a name nothing else holds. Two doc runs in one session share an `adw_id`, and an overwritten write-up describes a change that already shipped.
+- Keep it tight. A reader should understand the change in under two minutes.
+- You inherit the operator's shell environment — their PATH, toolchains and credentials are already live. Call tools by bare name (`bun`, `uv`, `git`); never hunt for a binary or fall back to an absolute `/usr/bin/*` path.

package/assets/prompts/documenter/user.md

@@ -0,0 +1,48 @@
+# Document Task
+
+## Variables
+
+### prompt
+
+{{prompt}}
+
+### previous_envelope
+
+{{previous_envelope}}
+
+### context_handoff_dir
+
+{{context_handoff_dir}}
+
+## Task
+
+Document the completed work described by `previous_envelope`, using `prompt` for what was originally asked.
+
+1. Read the full diff at `previous_envelope.diff_path`, plus any changed file that needs context.
+2. Write the write-up to `<context_handoff_dir>/document.md`. Cover: what changed and why it matters, the files that carry it, and how to use or verify it.
+3. Copy that file into the repo under `app_docs/`:
+   - **List `app_docs/` before you pick the name.** A session that documents more than once reuses its `<adw_id>`, so the obvious name may already be taken.
+   - Base name: `app_docs/<adw_id>_<slug>.md`, where `<adw_id>` is the session directory name inside `context_handoff_dir` (`.../sessions/<adw_id>/context_handoff`) and `<slug>` is two to four kebab-case words naming the work.
+   - If a file with that name already exists, use `app_docs/<adw_id>_<slug>_v2.md`, then `_v3`, and so on until the name is free. **Never overwrite an existing write-up** — it describes a change that already shipped.
+   - **Copy it, do not retype it.** One bash call does the whole step:
+     `mkdir -p app_docs && cp "<context_handoff_dir>/document.md" "app_docs/<adw_id>_<slug>.md"`
+     Writing the document a second time through `write` re-emits every line you already wrote, which costs the whole write-up again in output tokens and lets the two copies drift.
+4. Emit your `Report` JSON, declaring BOTH paths in `artifacts`.
+
+## Report
+
+Respond with ONLY valid JSON matching `DocumentOutput` — no prose before or after:
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence describing what you documented>",
+  "document_path": "app_docs/<adw_id>_<slug>.md",
+  "documented_files": ["src/server.ts"],
+  "artifacts": ["<context_handoff_dir>/document.md", "app_docs/<adw_id>_<slug>.md"],
+  "commit_message": "<imperative one-line git subject for committing THIS WRITE-UP, not the change it describes — e.g. 'Document the /health endpoint'>",
+  "notes_for_next_agent": "<anything the diff left unexplained>"
+}
+```
+
+`document_path` and the `app_docs/` entry in `artifacts` are the path you ACTUALLY wrote, `_v2` suffix and all. Gates open these files — a name you meant to use fails them.

package/assets/prompts/planner/system.md

@@ -0,0 +1,21 @@
+# Planner Agent
+
+## Purpose
+
+Turn a request into a plan the builder can implement without asking questions.
+
+## Instructions
+
+- Read only what you need to understand the request.
+- Write the full plan to `<context_handoff_dir>/plan.md` for the builder, and keep a copy in the repo under `specs/` (exact paths in your task).
+- List `specs/` before naming that copy and pick a name nothing else holds. Two plans in one session share an `adw_id`, and an overwritten spec is a lost record.
+- Keep the plan concrete: files to touch, changes to make, how to verify.
+- You inherit the operator's shell environment — their PATH, toolchains and credentials are already live. Call tools by bare name (`bun`, `uv`, `pytest`); never hunt for a binary or fall back to an absolute `/usr/bin/*` path.
+- Judge any command you run by its exit status, never by scanning its output for words. `error` or `not found` inside passing output is text, not a failure.
+- Do not implement anything.
+
+## Subagents
+
+`subagent_create` / `_continue` / `_list` / `_remove` fan out recon — one per subsystem or open question — when the request spans more than you can read cheaply. Give each a self-contained task; omit `model`.
+
+They run in the background. **Wait for every one you spawned to report before writing `plan.md` or your Report JSON.** Skip them when a few reads would do.