@gr8ful/spf 0.1.7 → 0.3.0

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 (optionally customized per agent instead of one model for the whole roster), which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host, and whether to push notifications to Slack/Teams/a webhook — 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:
@@ -317,6 +322,56 @@ export BITBUCKET_API_TOKEN=...   # same Atlassian API token mechanism as Jira ab
 
 **Bitbucket Cloud app passwords are being fully removed** (brownout window closing July 28, 2026) — this project only supports the replacement, API tokens, which need the account's email alongside the token (username alone no longer works).
 
+## Notifications
+
+Optional, off by default: push a curated set of milestones to Slack,
+Microsoft Teams, or a generic webhook. It's scoped to **unattended work**:
+`spf watch`'s daemon lifecycle, and every chain run (`spf <chain>` / `spf
+run`, including watch's own per-issue runs). Interactive commands — `doctor`,
+`list`, `sessions`, `phases`, `events`, `init`, `ui`, `migrate`, `eject`,
+`abort`, `version` — never notify; you're already looking at the terminal
+for those.
+
+```yaml
+# .spf/spf.config.yaml
+notifications:
+  events: errors            # off (default) | errors | all
+  channels:
+    - kind: slack            # slack | teams | webhook
+      webhook_url_env: SLACK_WEBHOOK_URL   # optional; this is the default for slack
+```
+
+`events` is the whole filter: `errors` sends only failed runs/phases, blocked
+issues, and watch errors; `all` adds every milestone — run started/finished,
+issue claimed, PR opened, issue done. A channel's own `events` overrides the
+top-level scope for just that channel. `spf doctor` reports whether each
+configured channel's env var is set.
+
+The webhook URL is a secret and lives only in `.env` — `webhook_url_env`
+names the key, never the URL itself, matching `GITHUB_TOKEN`/
+`JIRA_API_TOKEN`. Defaults per kind: `SLACK_WEBHOOK_URL`, `TEAMS_WEBHOOK_URL`,
+`SPF_WEBHOOK_URL`. `spf init`'s interview asks for this section and collects
+the URL straight into `.env`, same as every other credential.
+
+Getting each channel's URL:
+
+- **Slack** — [Sending messages using Incoming Webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks): create a Slack app, enable Incoming Webhooks, "Add New Webhook to Workspace".
+- **Microsoft Teams** — [Send messages in Teams using incoming webhooks](https://support.microsoft.com/en-us/office/post-a-workflow-when-a-webhook-request-is-received-in-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498): in the target channel, add a Workflows webhook template (search for one along the lines of "Post to a channel when a webhook request is received" / "Send webhook alerts to a channel" — Microsoft's own naming here has shifted between revisions) and copy the generated URL. This is the *only* supported path now — the old Office 365 connector webhook has been retired by Microsoft.
+- **webhook** — any endpoint that accepts a JSON POST of the event: Discord,
+  n8n, Zapier, a homegrown receiver.
+
+Delivery never blocks or fails a run: an unconfigured/misconfigured channel
+is skipped with one warning, and a failed POST logs one line and is
+swallowed — never changes a run's exit code. One thing worth knowing under
+`events: all`: `spf watch` runs its per-issue chains in-process, so a failed
+issue produces **two** notifications for the same failure — `run_failed`
+(keyed to the chain's own `adw_id`, e.g. `issue-142`) from the chain-run
+side, and `issue_blocked` (keyed to the issue) from watch itself. Both are
+genuinely informative, just worth expecting.
+
+Full field reference: `spf install-skill`'s installed skill
+(`references/config.md`).
+
 ## What's in this repo
 
 ```

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

@@ -12,14 +12,18 @@ always shows the resolved, merged result for the repo you're in.
 1. The packaged built-in default (`assets/defaults/spf.config.yaml` inside
    the installed CLI).
 2. `.spf/spf.config.yaml` in the target repo, if present — merged on top,
-   field by field (`defaults`/`observability`/`quality` merge key-by-key;
-   `agents` merges by `name`: a matching name patches that entry, a new name
-   appends).
+   field by field (`defaults`/`observability`/`quality`/`watch`/`notifications`
+   merge key-by-key — `notifications.channels` replaces wholesale, same as
+   `quality.checks`; `agents` merges by `name`: a matching name patches that
+   entry, a new name appends).
 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
 
@@ -104,6 +108,49 @@ sections: `assets/templates/ts.spf.config.yaml` in the spf package (or
 `spf init --template ts` to write it straight into `.spf/spf.config.yaml`).
 `spf init` with no `--template` prints every packaged template's name.
 
+### `notifications`
+
+Optional outbound push for unattended work — `spf watch`'s daemon lifecycle,
+and every chain run (`spf <chain>` / `spf run`, including watch's own
+per-issue runs). Interactive commands (`doctor`, `list`, `sessions`,
+`phases`, `events`, `init`, `ui`, `migrate`, `eject`, `abort`, `version`)
+never notify — you're already looking at the terminal for those. Off by
+default; adding it is entirely additive.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `events` | `"off"` \| `"errors"` \| `"all"` | The whole filter. `off` (default): nothing. `errors`: only failed runs/phases, blocked issues, watch errors. `all`: every curated milestone (run started, issue claimed, PR opened, ...) plus errors. |
+| `timeout_ms` | int | Per-request timeout for a channel's HTTP POST. Default `5000`. |
+| `channels[]` | array | See below. |
+
+`channels[].kind`: `"slack"` \| `"teams"` \| `"webhook"`. `channels[].events`
+overrides `events` for just that channel (unset = inherit). `webhook_url_env`
+names the `.env` key holding the secret URL — never the URL itself, matching
+`GITHUB_TOKEN`/`JIRA_API_TOKEN`. Empty/omitted uses the kind's own default:
+`SLACK_WEBHOOK_URL`, `TEAMS_WEBHOOK_URL`, `SPF_WEBHOOK_URL`. `name` is a
+cosmetic label for warning lines when you have two channels of the same
+kind.
+
+```yaml
+notifications:
+  events: errors
+  channels:
+    - kind: slack
+      webhook_url_env: SLACK_WEBHOOK_URL   # optional; this is the default for slack
+    - kind: teams
+      events: all                           # per-channel override
+    - kind: webhook
+      webhook_url_env: OPS_WEBHOOK_URL
+      name: ops-bus
+```
+
+Delivery never blocks or fails a run: a channel with an unset env var is
+skipped with one warning at startup (`spf doctor` reports the same thing as
+a check); a failed POST logs one line and is swallowed, never changing the
+run's exit code. See the main README's "Notifications" section for how to
+get each channel's webhook URL, and `spf init`'s interview, which asks for
+this section and collects the URL straight into `.env`.
+
 ### `agents[]`
 
 | Field | Required | Meaning |

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

@@ -64,3 +64,15 @@ agents:
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+
+# Optional: push notifications for unattended work — spf watch's daemon
+# lifecycle, and every chain run (including watch's own per-issue runs).
+# Interactive commands (doctor, list, sessions, ...) never notify. events:
+# "errors" sends only failures/blocked issues; "all" adds every milestone.
+# The webhook URL is a secret — put it in .env under the key named below,
+# never here. See the main README's "Notifications" section.
+# notifications:
+#   events: errors            # off (default) | errors | all
+#   channels:
+#     - kind: slack            # slack | teams | webhook
+#       webhook_url_env: SLACK_WEBHOOK_URL

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>;