@gr8ful/spf 0.1.6 → 0.2.1

package/README.md

@@ -28,12 +28,15 @@ spf scout "describe this repo"      # a real, read-only run, no setup required
 ### Customizing a repo
 
 ```bash
-spf init                       # seed .spf/spf.config.yaml — override only what you want to change
+spf init                       # on a TTY: an interview — agent, model, quality checks, spf watch, secrets
+spf init --yes                 # skip the interview — seed the commented, all-defaults starter config instead
 spf init --template ts-cc      # or start from a packaged, ready-to-run template instead
 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. `--template <name>` writes a real, filled-in config instead of the commented-out starter — every packaged template's name prints after `spf init` runs, and the same files live in [`assets/templates/`](assets/templates/) to browse directly. Nothing here needs to exist for `spf` to run; it's how you make one repo's roster diverge from the defaults.
+On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code` or `flue`) and model, which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
+
+Without an interview, `spf init` writes the same small starter `.spf/spf.config.yaml`, commented, that merges on top of the packaged built-ins field by field. `--template <name>` writes a real, filled-in config instead of the commented-out starter — every packaged template's name prints after `spf init` runs, and the same files live in [`assets/templates/`](assets/templates/) to browse directly. Nothing here needs to exist for `spf` to run; it's how you make one repo's roster diverge from the defaults.
 
 ### Local development
 
@@ -242,6 +245,8 @@ Polls an issue tracker for issues labeled `<prefix>:ready`, runs a configured ch
 
 The tracker (`issue_provider`) and the code host (`code_host`) are independent config choices, not one bundled "provider" — a tracker and a host are independent choices in practice (Jira issues against a Bitbucket repo is a real setup). Supported today: `issue_provider: github | jira`, `code_host: github | bitbucket` — any combination works, including Jira+GitHub or GitHub-issues+Bitbucket.
 
+The easiest way into any of this is `spf init`'s interview: it asks whether to enable `spf watch`, which tracker and code host, and collects exactly the env vars that combination needs (below) straight into `.env` — no hand-editing YAML or hunting down which credential pair a given combination wants.
+
 ```yaml
 # .spf/spf.config.yaml — GitHub issues + GitHub PRs (the default)
 watch:

package/assets/skill/cookbooks/authoring_chains.md

@@ -1,17 +1,19 @@
 # Authoring Chains
 
-Creating a new chain, extending an existing one, and adding the engine
-primitives a chain needs (an output type, a gate) are one skill with three
-doors. All three live in `src/` inside the SPF package itself — there is no
-per-repo copy to edit. If you need to change engine behavior for a specific
-target repo without forking the package, that's `spf eject` (prints the path
-to the installed package's `src/` for you to copy and load from your own
-`.spf/` — engine-level changes are the one thing `.spf/` config can't express).
+Composing a new chain, extending an existing one, and adding the engine
+primitives a chain needs (an output type, a gate, a step) are one skill with
+three doors. All three live in `src/` inside the SPF package itself — there
+is no per-repo copy to edit. If you need to change engine behavior for a
+specific target repo without forking the package, that's `spf eject` (prints
+the path to the installed package's `src/` for you to copy and load from your
+own `.spf/` — engine-level changes are the one thing `.spf/` config can't
+express).
 
 ## Step 1 — design the chain before writing code
 
 Lay out the phases as a table: name, kind, owner, output type (if `agent`),
-gates. This is the same table `spf list` will end up describing.
+gates. This is the same table `spf list` will end up describing (derived from
+the step list itself — see Step 2 — so it can't drift from what actually runs).
 
 | Phase | Kind | Owner | Output type | Gates |
 |---|---|---|---|---|
@@ -34,62 +36,52 @@ gates. This is the same table `spf list` will end up describing.
   (`quality.runSuite`, `changes.capture`, `run.git.commitAll`). If a human
   could write the exact steps down without judgment, it's `code`.
 
-## Step 2 — write the chain module
+## Step 2 — compose the chain from steps
 
-A chain is a module exporting `REQUIRED_AGENTS`, `REQUIRED_SUITES`, and
-`main(ctx: ChainContext): Promise<number>`. No shebang, no `import.meta.main`
-block — the CLI's chain registry (`src/chains/index.ts`) calls `main()`
-directly, and `dist/cli/bin.js` is the only entry point that ever runs.
+Almost every chain is a flat array of **steps** — named primitives from
+`src/chains/steps.ts`, each one a `run.phase(...)` call (or a small bounded
+group of them, for the two loops). There is no module to write and nothing to
+register anywhere else: a `CHAINS` entry built with `stepChain()` *is* the
+registration, in `src/chains/index.ts`.
 
 ```ts
-/**
- * ADW <Name> — <one sentence: what this chain is for and when to pick it>.
- *
- * Phases: engineer(request) -> scout -> planner -> builder -> code(test) -> git(commit)
- */
-import * as agents from "../core/agents.ts";
-import * as gates from "../core/gates.ts";
-import * as quality from "../core/quality.ts";
-import * as session from "../core/session.ts";
-import { BuildOutput, PlanOutput, makeAgentCall, makePhaseParams } from "../core/data_types.ts";
-import type { ChainContext } from "./context.ts";
-
-export const REQUIRED_AGENTS = ["planner", "builder"];
-export const REQUIRED_SUITES: string[] = ["test"]; // [] if this chain runs no quality suite
-
-export async function main(ctx: ChainContext): Promise<number> {
-  const { prompt, config_paths, adw_id, cwd } = ctx;
-  const cfg = agents.loadConfig(config_paths);
-  agents.validate(cfg, REQUIRED_AGENTS, REQUIRED_SUITES, cwd);
-  const run = session.ensure(cfg, adw_id, cwd);
-
-  await run.phase(
-    makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }),
-    async (ph) => { ph.log({ input: prompt }); },
-  );
-
-  const plan = await run.phase(
-    makePhaseParams({ name: "plan", kind: "agent", owner: "planner", description: "Turn the request into an implementable plan" }),
-    (ph) => ph.call(makeAgentCall({ output_type: PlanOutput, prompt, gates: [gates.artifactsExist] })),
-  );
-
-  const build = await run.phase(
-    makePhaseParams({ name: "build", kind: "agent", owner: "builder", description: "Implement the plan" }),
-    (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: plan, gates: [gates.diffMatchesClaims] })),
-  );
-
-  await run.phase(
-    makePhaseParams({ name: "commit", kind: "code", owner: "git", description: "Commit the implementation" }),
-    async () => run.git.commitAll(build.commit_message || `spf: ${prompt.slice(0, 72)}`),
-  );
-
-  return run.finish();
-}
+stepChain("plan-build-test", "the standard chain — plan, build, test, commit", [
+  steps.request(),
+  steps.plan(),
+  steps.build(),
+  steps.fixLoop({ suite: "test" }),
+  steps.commit({ onlyIfAccepted: true }),
+]),
 ```
 
-Then register it in `src/chains/index.ts`'s `CHAINS` array (name, describe,
-phases string, `requiredAgents`/`requiredSuites`, `run`) — that's what makes
-it show up in `spf list` and dispatchable as `spf <name>`.
+`stepChain()` derives `phases` (the `spf list` display string),
+`requiredAgents`, and `requiredSuites` from the step list itself — nothing to
+keep in sync by hand. The available steps:
+
+| Step | What it replaces | Notes |
+|---|---|---|
+| `request({description?, logBaseline?})` | the opening `engineer(request)` phase | every chain starts with this |
+| `plan()` | a `planner` phase producing `PlanOutput` | — |
+| `build({fromPlan?, retries?})` | a `builder` phase producing `BuildOutput` | `fromPlan` only changes the phase's description |
+| `scout()` | a `scout` phase producing `ScoutOutput` | read-only |
+| `promptOnly()` | the `prompt` chain's one step | owner comes from `--agent`, default `builder` |
+| `qualityCheck({suite})` | one deterministic quality/test phase | never fails its own phase — see below |
+| `fixLoop({suite, max?, owner?})` | a bounded check→fix loop | owns its own iteration and phase naming (`test_1`, `fix_1`, ...) |
+| `reviseLoop({max?})` | a bounded review→revise loop | same idea, for `reviewer`/`builder` |
+| `changes({base?})` | a `git diff`-against-a-base code phase | feeds `document()` |
+| `document()` | a `documenter` phase | requires a preceding `changes()` |
+| `commit({onlyIfAccepted?})` | a `git commit` code phase | commits whatever the last agent step produced |
+
+**Why the loops are steps, not a `for` you write in the chain.** `fixLoop`
+and `reviseLoop` own their bounded iteration internally, so a chain's step
+list is always flat — no loop or conditional syntax at the composition
+layer. This is also what keeps a future declarative (YAML) chain tractable:
+it only ever needs to name steps and pass them tuning params.
+
+Steps read and write a shared `ChainState` (`prompt`, `options`, `previous` —
+the last agent envelope, `accepted`/`reason` for `run.finish()`, etc.) so a
+step never has to be told what the step before it produced; it just reads
+`state.previous`.
 
 **Before you ship it:** run it against a scratch repo (`spf <name> "..." --cwd
 /tmp/scratch-repo`), then `spf phases <adw_id>` and `spf events <adw_id>` to
@@ -98,47 +90,67 @@ expect, and open one `envelope.json` under
 `.spf/data/sessions/<adw_id>/<agent>/` to confirm it matches the type you
 declared.
 
-## Step 3 — add a phase to an existing chain
-
-Insert a `run.phase(...)` block in sequence; nothing else in the chain needs
-to change unless the new phase's output feeds a later one (thread it through
-as a local variable, the way `plan`/`build` are threaded above).
+### When a chain doesn't fit the step vocabulary
 
-Removing a phase: delete the block; check nothing downstream reads its
-return value, and check `REQUIRED_AGENTS`/`REQUIRED_SUITES` no longer needs
-whatever only that phase used.
+`simple-sdlc` (`src/chains/simple_sdlc.ts`) is the one exception: three
+commits, a pinned baseline, and a conditional retest don't collapse into a
+flat list. A chain like that is still a module exporting `REQUIRED_AGENTS`,
+`REQUIRED_SUITES`, and `main(ctx: ChainContext): Promise<number>`, registered
+in `CHAINS` with a `run:` field instead of `steps:`. Reuse
+`steps.startRun`/`commitEnvelope`/`logChangeset` and `quality.record` rather
+than re-copying them — read `simple_sdlc.ts` before reaching for this escape
+hatch; it is meant for the rare chain whose control flow genuinely doesn't
+reduce to a list, not a shortcut around learning the step vocabulary.
 
-## Step 4 — add a bounded fix loop
+## Step 3 — add a phase to an existing chain
 
-The pattern every quality-gated chain uses — run a check, and if it fails,
-loop the builder back in with the failure as `previous`, bounded so a chain
-can't spin forever:
+Most of the time this means adding, removing, or reordering an entry in a
+`stepChain(...)` array in `src/chains/index.ts` — nothing else needs to
+change unless the new step's output feeds a later one (it will, automatically,
+if it writes to `state.previous`/`state.changeset`/etc., since every step
+reads from the same shared state).
+
+If no existing step does what you need, write one in `src/chains/steps.ts`:
+a function returning a `Step` (a `(run, state) => Promise<void>`), doing one
+`run.phase(...)` call (or a small bounded group, if it's loop-shaped like
+`fixLoop`/`reviseLoop`). Declare what it needs via the optional
+`requiredAgents`/`requiredSuites`/`label` properties so
+`deriveRequiredAgents`/`deriveRequiredSuites`/`derivePhases` pick it up
+automatically — `makeStep(fn, meta)` attaches these for you.
+
+## Step 4 — the bounded fix loop, if you need a different shape than `fixLoop()` provides
+
+`steps.fixLoop({suite, max, owner})` already covers the common case — a
+known check, and if it fails, the builder repairs it, bounded so a chain
+can't spin forever, never leaving an unverified fix on the last iteration.
+Reach for it first. If you need a genuinely different shape (a different
+envelope type feeding the fix, say), its body in `src/chains/steps.ts` is the
+reference implementation to start from:
 
 ```ts
-const MAX_FIX_LOOPS = 3;
-let test: QualityResult | null = null;
-for (let i = 1; i <= MAX_FIX_LOOPS; i++) {
-  test = await run.phase(
+for (let i = 1; i <= max; i++) {
+  const result = await run.phase(
     makePhaseParams({ name: `test_${i}`, kind: "code", owner: "quality", description: "Run the suite" }),
-    async (ph) => { const result = quality.runTests(run); ph.log({ passed: result.passed }); return result; },
+    async (ph) => { const r = quality.runTests(run); quality.record(ph, r); return r; },
   );
-  if (test.passed) break;
-  await run.phase(
+  if (result.passed) break;
+  if (i === max) break; // never leave an unverified fix on the table
+  state.previous = await run.phase(
     makePhaseParams({ name: `fix_${i}`, kind: "agent", owner: "builder", retries: 1, description: "Repair what the suite reported" }),
-    (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: quality.asEnvelope(test!, "tests"), gates: [gates.diffMatchesClaims] })),
+    (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt: state.prompt, previous: quality.asEnvelope(result, "tests"), gates: [gates.diffMatchesClaims] })),
   );
 }
-return run.finish(test !== null && test.passed, `the suite still failed after ${MAX_FIX_LOOPS} fix attempt(s)`);
 ```
 
 A failing suite does **not** fail its own phase — the runner did its job,
 the *code under test* is what failed. It's `run.finish()`'s job, at the end,
-to decide whether the whole run is accepted.
+to decide whether the whole run is accepted — which is why a step sets
+`state.accepted`/`state.reason` rather than throwing.
 
 ## Adding an engine primitive
 
-These live in `src/core/`, not in a chain. Chains stay thin: sequencing
-only, no business logic.
+These live in `src/core/`, not in a chain or a step. Chains and steps stay
+thin: sequencing only, no business logic.
 
 ### Adding an output type
 
@@ -153,7 +165,7 @@ export const MyOutput = envelopeType("MyOutput", {
 export type MyOutputT = v.InferOutput<typeof MyOutput.schema>;
 ```
 
-Then the two other legs of the synced triad: the calling chain's
+Then the two other legs of the synced triad: the calling step's
 `output_type: MyOutput`, and the agent's `user.md` `## Report` section
 showing the exact JSON shape. All three must move together — see
 `references/handoff.md`.

package/assets/skill/cookbooks/roster.md

@@ -155,7 +155,9 @@ startup, before anything spawns:
    `authoring_chains.md`. The user prompt's `## Report` section must show
    exactly that JSON shape.
 
-Then name the agent in a chain's `REQUIRED_AGENTS` and call it.
+Then use it as a step's `owner` (`steps.build()`, `steps.plan()`, ...) or write
+a new step naming it — see `authoring_chains.md`. A chain's `requiredAgents` is
+derived from its step list, not hand-maintained.
 
 ## Write permissions — `writes` and `protected_files`
 

package/assets/skill/references/config.md

@@ -18,8 +18,11 @@ always shows the resolved, merged result for the repo you're in.
 3. An explicit `--config <path>` replaces both — standalone, no built-in
    underneath it.
 
-`spf init` seeds step 2 with a commented starter; omitting it entirely means
-running off pure built-ins, which is a fully supported, valid state.
+`spf init` seeds step 2 — on a TTY, via an interview that asks the fields
+below and appends whatever secrets they imply to `.env`; non-interactively
+(`--yes`, `--template <name>`, or no TTY) it writes a commented starter
+instead. Omitting `.spf/spf.config.yaml` entirely means running off pure
+built-ins, which is a fully supported, valid state.
 
 ## Shape
 

package/assets/templates/ts-cc.spf.config.yaml

@@ -41,3 +41,19 @@ quality:
 defaults:
   coding_agent: claude_code
   model: qwen3-coder:30b # swap for whatever `ollama list` shows on your machine
+
+# REQUIRED, not just an example: the packaged default roster pins
+# planner/reviewer/documenter to their own explicit Flue-style
+# provider/model-id strings, which an agent's own model always wins over
+# defaults.model above — switching coding_agent globally does NOT reset
+# those three, so they'd run on Claude Code (redirected at Ollama) with a
+# model id Ollama has never heard of, and fail outright. builder/scout
+# have no model of their own in the packaged roster, so they correctly
+# inherit defaults.model above and need no override here.
+agents:
+  - name: planner
+    model: qwen3-coder:30b
+  - name: reviewer
+    model: qwen3-coder:30b
+  - name: documenter
+    model: qwen3-coder:30b

package/assets/templates/ts-flue-openrouter.spf.config.yaml

@@ -36,3 +36,18 @@ defaults:
   # (kimi-k3, gemini-3.6, gpt-5.6, claude-sonnet-5, ...), not a live catalog
   # entry verified against a real API.
   model: openrouter/moonshotai/kimi-k2.7
+
+# Not required the way the claude_code templates' agents: override is (an
+# agent's own model always wins over defaults.model, but Flue accepts any
+# provider/model-id, so the packaged roster's planner/reviewer/documenter
+# — fireworks/openai models, unrelated to OpenRouter — would still resolve
+# and run fine, just outside OPENROUTER_API_KEY's reach). Overridden here
+# anyway so every agent actually demonstrates the OpenRouter routing this
+# template is about, not just the three without their own packaged model.
+agents:
+  - name: planner
+    model: openrouter/moonshotai/kimi-k2.7
+  - name: reviewer
+    model: openrouter/moonshotai/kimi-k2.7
+  - name: documenter
+    model: openrouter/moonshotai/kimi-k2.7

package/assets/templates/ts.spf.config.yaml

@@ -27,14 +27,29 @@ quality:
 # Optional: run agents on Claude Code instead of the default Flue backend.
 # Needs the `claude` CLI installed and authenticated (`spf doctor` checks) —
 # no separate provider API key required if you're logged in via `claude
-# login`. Remove this whole block to stay on Flue with a `provider/model-id`
-# roster instead.
+# login`. Remove this whole block (and the agents: override below) to stay
+# on Flue with a `provider/model-id` roster instead.
 defaults:
   coding_agent: claude_code
   model: sonnet # claude_code's own alias — NOT provider/model-id
 
-# Optional: retune one agent without touching the rest of the roster.
-# agents:
+# REQUIRED alongside coding_agent: claude_code above, not just an example:
+# the packaged default roster pins planner/reviewer/documenter to their own
+# explicit Flue-style provider/model-id strings, which an agent's own model
+# always wins over defaults.model — switching coding_agent globally does
+# NOT reset those three, so they'd run on Claude Code with a model id it
+# can't resolve at all ("There's an issue with the selected model...").
+# builder/scout have no model of their own in the packaged roster, so they
+# correctly inherit defaults.model above and need no override here.
+agents:
+  - name: planner
+    model: sonnet
+  - name: reviewer
+    model: sonnet
+  - name: documenter
+    model: sonnet
+
+# Optional: retune one agent further without touching the rest of the roster.
 #   - name: builder
 #     thinking: high
 #     writes: [src/, tests/]   # narrow what this agent may change in the repo

package/dist/chains/context.d.ts

@@ -16,4 +16,6 @@ export interface ChainContext {
     adw_id: string | null;
     /** Absolute. The anchor session.ensure() resolves repo_root and data_dir from. */
     cwd: string;
+    /** The CLI name (`"plan-build-test"`), for session.ensure()'s trace record — see core/session.ts. */
+    chain_name: string;
 }

package/dist/chains/index.d.ts

@@ -2,18 +2,37 @@
  * The chain registry — the one place a CLI-facing short name maps to a
  * chain module. `spf list` reads this; `spf <name>`/`spf run <name>` dispatch
  * through it. Replaces guessing a module filename from the CLI argument.
+ *
+ * Every chain but `simple-sdlc` is a flat `steps` list composed from
+ * `./steps.ts`'s primitives — no module of its own, and no hand-written
+ * `phases`/`requiredAgents`/`requiredSuites` to keep in sync with what
+ * actually runs; those are derived from the step list itself.
+ * `simple-sdlc`'s three-commit, pinned-baseline shape is still imperative —
+ * see `./simple_sdlc.ts` — via the `run` escape hatch below.
  */
 import type { ChainContext } from "./context.ts";
+import * as steps from "./steps.ts";
 export interface ChainDefinition {
     /** The name typed on the CLI: `spf <name> "..."`. */
     name: string;
     describe: string;
     phases: string;
-    /** Static for most chains; adw_prompt's depends on --agent, so it's a function there. */
+    /** Static for most chains; prompt's depends on --agent, so it's a function there. */
     requiredAgents: string[] | ((options: Record<string, string>) => string[]);
     requiredSuites: string[];
-    run: (ctx: ChainContext, options?: Record<string, string>) => Promise<number>;
+    /** The declarative path — a flat step list, run by runChain() via steps.runSteps(). */
+    steps?: steps.Step[];
+    /** The imperative escape hatch for a chain too shaped by its own logic to be a flat list (simple-sdlc). */
+    run?: (ctx: ChainContext, options?: Record<string, string>) => Promise<number>;
 }
 export declare const CHAINS: ChainDefinition[];
 export declare function findChain(name: string): ChainDefinition | undefined;
 export declare function resolveRequiredAgents(chain: ChainDefinition, options: Record<string, string>): string[];
+/**
+ * Run a chain, whichever path it defines: `run` (the imperative escape
+ * hatch) if it has one, otherwise `steps` through the shared driver. Both
+ * CLI dispatch sites (`spf <chain>` and `spf watch`) go through this, never
+ * `chain.run(...)` directly — the whole reason to route through here is that
+ * a `steps`-only chain has no `run` to call.
+ */
+export declare function runChain(chain: ChainDefinition, ctx: ChainContext, options?: Record<string, string>): Promise<number>;

package/dist/chains/index.js

@@ -1,111 +1,68 @@
-import * as adwPrompt from "./adw_prompt.js";
-import * as adwScout from "./adw_scout.js";
-import * as adwPlan from "./adw_plan.js";
-import * as adwBuild from "./adw_build.js";
-import * as adwPlanBuild from "./adw_plan_build.js";
-import * as adwBuildTest from "./adw_build_test.js";
-import * as adwPlanBuildTest from "./adw_plan_build_test.js";
-import * as adwPlanBuildTestQuality from "./adw_plan_build_test_quality.js";
-import * as adwBuildReview from "./adw_build_review.js";
-import * as adwQuality from "./adw_quality.js";
-import * as adwDocument from "./adw_document.js";
-import * as adwSimpleSdlc from "./adw_simple_sdlc.js";
+import * as steps from "./steps.js";
+import * as simpleSdlc from "./simple_sdlc.js";
+/** Build a step-based ChainDefinition, deriving phases/requiredAgents/requiredSuites from its steps. */
+function stepChain(name, describe, list) {
+    return {
+        name,
+        describe,
+        phases: steps.derivePhases(list),
+        requiredAgents: steps.deriveRequiredAgents(list),
+        requiredSuites: steps.deriveRequiredSuites(list),
+        steps: list,
+    };
+}
 export const CHAINS = [
-    {
-        name: "prompt",
-        describe: "one agent, one prompt, traced end to end — --agent <name> picks who (default: builder)",
-        phases: "engineer(request) -> <agent>",
-        requiredAgents: (options) => [options["agent"] ?? "builder"],
-        requiredSuites: [],
-        run: adwPrompt.main,
-    },
-    {
-        name: "scout",
-        describe: "read-only recon; nothing changes",
-        phases: "engineer(request) -> scout",
-        requiredAgents: adwScout.REQUIRED_AGENTS,
-        requiredSuites: adwScout.REQUIRED_SUITES,
-        run: adwScout.main,
-    },
-    {
-        name: "plan",
-        describe: "turn a request into an implementable plan",
-        phases: "engineer(request) -> planner",
-        requiredAgents: adwPlan.REQUIRED_AGENTS,
-        requiredSuites: adwPlan.REQUIRED_SUITES,
-        run: adwPlan.main,
-    },
-    {
-        name: "build",
-        describe: "implement an existing plan",
-        phases: "engineer(request) -> builder",
-        requiredAgents: adwBuild.REQUIRED_AGENTS,
-        requiredSuites: adwBuild.REQUIRED_SUITES,
-        run: adwBuild.main,
-    },
-    {
-        name: "plan-build",
-        describe: "small, well-understood work — plan, build, commit",
-        phases: "engineer(request) -> planner -> builder -> git(commit)",
-        requiredAgents: adwPlanBuild.REQUIRED_AGENTS,
-        requiredSuites: adwPlanBuild.REQUIRED_SUITES,
-        run: adwPlanBuild.main,
-    },
-    {
-        name: "build-test",
-        describe: "there is a suite to satisfy — build, test, bounded fix loop",
-        phases: "engineer(request) -> builder -> code(test) [-> builder(fix) -> code(test) ...]",
-        requiredAgents: adwBuildTest.REQUIRED_AGENTS,
-        requiredSuites: adwBuildTest.REQUIRED_SUITES,
-        run: adwBuildTest.main,
-    },
-    {
-        name: "plan-build-test",
-        describe: "the standard chain — plan, build, test, commit",
-        phases: "engineer(request) -> planner -> builder -> code(test) [-> fix loop] -> git(commit)",
-        requiredAgents: adwPlanBuildTest.REQUIRED_AGENTS,
-        requiredSuites: adwPlanBuildTest.REQUIRED_SUITES,
-        run: adwPlanBuildTest.main,
-    },
-    {
-        name: "plan-build-test-quality",
-        describe: "the repo has quality commands worth enforcing beyond tests — same, plus lint/typecheck/build gates",
-        phases: "engineer(request) -> planner -> builder -> code(quality:all) [-> fix loop] -> git(commit)",
-        requiredAgents: adwPlanBuildTestQuality.REQUIRED_AGENTS,
-        requiredSuites: adwPlanBuildTestQuality.REQUIRED_SUITES,
-        run: adwPlanBuildTestQuality.main,
-    },
-    {
-        name: "build-review",
-        describe: "\"is this what was asked for\" matters more than \"does it run\"",
-        phases: "engineer(request) -> builder -> reviewer [-> revise loop]",
-        requiredAgents: adwBuildReview.REQUIRED_AGENTS,
-        requiredSuites: adwBuildReview.REQUIRED_SUITES,
-        run: adwBuildReview.main,
-    },
-    {
-        name: "quality",
-        describe: "lint, typecheck, build — no agents at all",
-        phases: "engineer(request) -> code(quality:all)",
-        requiredAgents: adwQuality.REQUIRED_AGENTS,
-        requiredSuites: adwQuality.REQUIRED_SUITES,
-        run: adwQuality.main,
-    },
-    {
-        name: "document",
-        describe: "write up the work that was just done, from the diff",
-        phases: "engineer(request) -> code(changes) -> documenter",
-        requiredAgents: adwDocument.REQUIRED_AGENTS,
-        requiredSuites: adwDocument.REQUIRED_SUITES,
-        run: adwDocument.main,
-    },
+    stepChain("prompt", "one agent, one prompt, traced end to end — --agent <name> picks who (default: builder)", [
+        steps.request(),
+        steps.promptOnly(),
+    ]),
+    stepChain("scout", "read-only recon; nothing changes", [steps.request(), steps.scout()]),
+    stepChain("plan", "turn a request into an implementable plan", [steps.request(), steps.plan()]),
+    stepChain("build", "implement an existing plan", [steps.request(), steps.build({ fromPlan: false, retries: 1 })]),
+    stepChain("plan-build", "small, well-understood work — plan, build, commit", [
+        steps.request(),
+        steps.plan(),
+        steps.build(),
+        steps.commit(),
+    ]),
+    stepChain("build-test", "there is a suite to satisfy — build, test, bounded fix loop", [
+        steps.request(),
+        steps.build({ fromPlan: false }),
+        steps.fixLoop({ suite: "test" }),
+    ]),
+    stepChain("plan-build-test", "the standard chain — plan, build, test, commit", [
+        steps.request(),
+        steps.plan(),
+        steps.build(),
+        steps.fixLoop({ suite: "test" }),
+        steps.commit({ onlyIfAccepted: true }),
+    ]),
+    stepChain("plan-build-test-quality", "the repo has quality commands worth enforcing beyond tests — same, plus lint/typecheck/build gates", [
+        steps.request(),
+        steps.plan(),
+        steps.build(),
+        steps.fixLoop({ suite: "all" }),
+        steps.commit({ onlyIfAccepted: true }),
+    ]),
+    stepChain("build-review", '"is this what was asked for" matters more than "does it run"', [
+        steps.request(),
+        steps.build({ fromPlan: false }),
+        steps.reviseLoop(),
+    ]),
+    stepChain("quality", "lint, typecheck, build — no agents at all", [
+        steps.request({ description: "Capture why quality verification was requested" }),
+        steps.qualityCheck({ suite: "all" }),
+    ]),
+    stepChain("document", "write up the work that was just done, from the diff", [steps.request(), steps.changes(), steps.document()]),
     {
         name: "simple-sdlc",
         describe: "the work is real and its shape is not obvious — plan, build, test, review, document; 3 commits",
-        phases: "engineer(request) -> planner -> builder -> code(test) -> reviewer -> code(changes) -> documenter",
-        requiredAgents: adwSimpleSdlc.REQUIRED_AGENTS,
-        requiredSuites: adwSimpleSdlc.REQUIRED_SUITES,
-        run: adwSimpleSdlc.main,
+        phases: "engineer(request) -> planner -> git(commit_plan) -> builder -> code(test) [-> builder(fix) -> code(test) ...] " +
+            "-> reviewer [-> builder(revise) -> reviewer ...] -> code(retest, if revised) -> git(commit_build) " +
+            "-> code(changes) -> documenter -> git(commit_docs)",
+        requiredAgents: simpleSdlc.REQUIRED_AGENTS,
+        requiredSuites: simpleSdlc.REQUIRED_SUITES,
+        run: simpleSdlc.main,
     },
 ];
 export function findChain(name) {
@@ -114,3 +71,15 @@ export function findChain(name) {
 export function resolveRequiredAgents(chain, options) {
     return typeof chain.requiredAgents === "function" ? chain.requiredAgents(options) : chain.requiredAgents;
 }
+/**
+ * Run a chain, whichever path it defines: `run` (the imperative escape
+ * hatch) if it has one, otherwise `steps` through the shared driver. Both
+ * CLI dispatch sites (`spf <chain>` and `spf watch`) go through this, never
+ * `chain.run(...)` directly — the whole reason to route through here is that
+ * a `steps`-only chain has no `run` to call.
+ */
+export async function runChain(chain, ctx, options = {}) {
+    if (chain.run)
+        return chain.run(ctx, options);
+    return steps.runSteps(ctx, resolveRequiredAgents(chain, options), chain.requiredSuites, chain.steps, options);
+}

package/dist/chains/{adw_simple_sdlc.d.ts → simple_sdlc.d.ts}

@@ -1,5 +1,5 @@
 /**
- * ADW Simple SDLC — plan, build, test, review, document, committing as it goes.
+ * Simple SDLC — plan, build, test, review, document, committing as it goes.
  *
  * Usage:
  *   spf simple-sdlc "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
@@ -36,6 +36,12 @@
  * The documenter measures against the commit this run STARTED from, not against
  * `main`, because by then the run has moved `main` itself. That baseline is
  * pinned before the first commit phase and printed in the request phase.
+ *
+ * This is the one chain still shaped by hand rather than by a `steps` list —
+ * three commits, a pinned baseline, and a conditional retest don't collapse
+ * cleanly into the flat, loop-free vocabulary `./steps.ts` provides for every
+ * other chain. It still reuses that module's shared helpers (`startRun`,
+ * `commitEnvelope`, `logChangeset`) rather than keeping its own copies.
  */
 import type { ChainContext } from "./context.ts";
 export declare const REQUIRED_AGENTS: string[];