fullstack-agentic-flow 2.0.0

package/payload/ai-agents/toolchain.md

@@ -0,0 +1,214 @@
+# Toolchain — skills, plugins, and tools the agents use
+
+The pipeline works without any of these. Each one makes a specific agent faster
+or sharper, and each one has a stated fallback. Installed and checked by
+`npx fullstack-agentic-flow init` and `… doctor`; the installed set is recorded in
+`.ai-agents/pipeline.config.json`.
+
+**Read the precedence section before anything else.** Several of these tools
+ship their own workflow, and two workflows running at once is how an agent ends
+up brainstorming a feature that already has a frozen contract.
+
+---
+
+## Precedence
+
+When instructions conflict, the higher line wins:
+
+1. **The human at a gate.**
+2. **Pipeline state files** — `contract-seam.md`, the contracts, `current-plan.md`.
+3. **`architecture-context.md`** and the canon (`canon/*.md`), including typed-data T1–T6.
+4. **The agent file** in `.ai-agents/agents/` for the current step.
+5. **Discipline skills** — superpowers TDD / debugging / verification, ponytail's decision ladder, impeccable's design rules.
+6. **Memory and recall** — claude-mem observations, graph query results.
+
+Two consequences worth stating plainly:
+
+- **Memory is recall, never truth.** If claude-mem remembers a decision that the
+  state files do not record, the state files win and the discrepancy is
+  reported.
+- **Graphs are an index, never truth.** A graph result tells an agent where to
+  look. Every claim written into a contract is verified by opening the file.
+
+---
+
+## The pipeline owns the workflow; skills own the discipline
+
+`superpowers` ships a full brainstorm → plan → execute workflow. This pipeline
+already has one (intake → contract → sequence → implement), with human gates the
+superpowers flow does not have. So:
+
+| superpowers skill | Use in this pipeline? | Where |
+|-------------------|------------------------|-------|
+| `test-driven-development` | **Yes — mandatory** | 04a, 04b, 00a, 00b: every task |
+| `systematic-debugging` | Yes | Any implementer when a test fails for an unexpected reason; CI failure triage |
+| `verification-before-completion` | Yes | 04a, 04b self-check before commit |
+| `requesting-code-review` / `receiving-code-review` | Yes | Gate 2 preparation and response |
+| `using-git-worktrees` | Yes, optional | Running the backend and UI tracks side by side |
+| `brainstorming` | **No** during a feature | Replaced by 01 intake. Allowed only before `/intake`, to explore whether a feature is worth doing |
+| `writing-plans` / `executing-plans` | **No** | Replaced by 02–03 contracts and sequences |
+| `subagent-driven-development` | **No** | Replaced by `/implement`, one task per invocation |
+
+If a superpowers skill auto-triggers into a replaced step, the agent says so in
+one line and continues with the pipeline's step instead.
+
+---
+
+## Tool reference
+
+### find-skills — `vercel-labs/skills`
+
+- **What**: discovers installable agent skills via the `npx skills` CLI.
+- **Used by**: 00a scaffold and 00 bootstrap, when the stack includes a framework
+  or library the pipeline has no mapping for; any agent, on explicit request.
+- **Rule**: discovering is free, installing is a human decision. Proposed skills
+  are listed with install count and source; nothing is installed without a yes.
+  Adopted skills are recorded in §Project additions below.
+- **Fallback**: none needed.
+
+### superpowers — `obra/superpowers`
+
+- **What**: discipline skills (TDD, debugging, verification, review).
+- **Used by**: see the table above.
+- **Fallback**: the TDD loop is written out in full in `04a`/`04b` §TDD loop, so
+  the pipeline still enforces red-green-refactor without the plugin.
+
+### claude-mem — `thedotmack/claude-mem`
+
+- **What**: captures session activity, compresses it, and injects relevant
+  context into later sessions. Works with Claude Code and Codex CLI.
+- **Used by**: every agent, passively. Particularly valuable for `/resume` and
+  for implementers picking up a track after a break.
+- **Rule**: see Precedence — recall only. Never cite a memory as the reason for a
+  design decision; cite the state file or the code.
+- **Privacy**: its data lives in `~/.claude-mem/`, outside the repo. Nothing it
+  stores is committed.
+- **Fallback**: the state files. The pipeline was designed to survive losing its
+  conversation; claude-mem makes that faster, not possible.
+
+### impeccable — `pbakaus/impeccable`
+
+- **What**: design language and commands for UI quality, plus a deterministic
+  anti-pattern detector (`npx impeccable detect`) that needs no model.
+- **Context files it owns**: `PRODUCT.md`, `DESIGN.md`, `.impeccable/`.
+- **Used by**:
+  - 00a scaffold — `/impeccable init` (writes `PRODUCT.md`) before tokens; `/impeccable document` after the UI slice (writes `DESIGN.md`)
+  - 00 bootstrap — reads `DESIGN.md` into §8.4; if the two disagree, raises it instead of choosing
+  - 02c UI contract — `shape` for new screens; `DESIGN.md` constrains token use
+  - 04b UI implementer — `npx impeccable detect <changed files>` in the self-check; `polish`/`harden` only on the files in the task
+  - 05 CI — `impeccable detect` on the diff as a non-blocking job until the team promotes it
+  - 06 QA — `/impeccable audit` on each new screen, findings folded into §7 Accessibility
+- **Rule**: impeccable's suggestions never add a component to `shared/ui` or a
+  token to the token set. Those remain Gate 1 decisions. `bolder`, `overdrive`,
+  `delight` and similar taste-changing commands run only when a UI contract asks
+  for them.
+- **Fallback**: §8 of the architecture context.
+
+### task-observer — `rebelytics/one-skill-to-rule-them-all`
+
+- **What**: watches sessions for repeated corrections and patterns, and writes
+  observation logs proposing new skills or improvements to existing ones.
+- **Log location for this pipeline**: `.ai-agents/observations/` (the installer
+  writes the activation instruction pointing there).
+- **Used by**: runs alongside every agent. 09b (`/release`) reads the logs at
+  release time and turns recurring ones into proposed edits to agent files, the
+  canon, or §10 — for a human to accept.
+- **Rule**: observations never edit agent files or the architecture context
+  directly.
+- **Codex**: use the community port `AllstarGER/one-skill-to-rule-them-all`
+  (older version) or skip.
+- **Fallback**: `decisions-log.md`.
+
+### ponytail — `DietrichGebert/ponytail`
+
+- **What**: a decision ladder that pushes agents toward the least code — reuse,
+  stdlib, platform, existing dependency, one line, then the minimum.
+- **Used by**: 04a/04b while implementing; `/ponytail-review` on the task diff
+  before Gate 2; 02b/02c when choosing between designs.
+- **Rule**: ponytail governs **logic, abstractions, and dependencies**. It does
+  not govern **types** (typed-data wins), **tests** (TDD wins), **states** (UI
+  required states win), or anything a contract explicitly specified. Its
+  "never cut validation, security, or accessibility" line aligns with the
+  pipeline; its brevity does not extend to Data classes.
+- **Suggested level**: `lite` during implementation, `full` for `/ponytail-review`.
+- **Fallback**: the "do not optimise beyond stated scale" rules already in the
+  contracts.
+
+### headroom — `headroomlabs-ai/headroom`
+
+- **What**: a local proxy that compresses tool output, logs, and files before
+  they reach the model. Not a skill — it wraps the session.
+- **Used by**: the developer, around the whole session: `headroom wrap claude`
+  or `headroom wrap codex`. Most useful for 00 bootstrap, 02a, 06, and 07, which
+  read a lot.
+- **Caveat**: wrapping routes the agent through a local base URL. Check the
+  current headroom release notes for context-window caveats before relying on
+  a long-context model through it.
+- **Fallback**: none needed.
+
+### code-review-graph — `tirth8205/code-review-graph`
+
+- **Role in this pipeline: the impact engine.** Incremental, SQLite-backed
+  (`.code-review-graph/`), exposed over MCP.
+- **Tools the agents call**: `get_impact_radius_tool` (blast radius),
+  `detect_changes_tool` (risk-scored diff impact), `query_graph_tool`
+  (callers / callees / tests), `semantic_search_nodes_tool`,
+  `get_architecture_overview_tool`.
+- **Used by**:
+  - 01b impact analysis — predicted blast radius from intake, actual from the diff
+  - 02a dependency map — callers of every symbol the feature touches; tests that cover them
+  - 04a/04b — `detect-changes --brief` output attached to every Gate 2 report
+  - 06 QA — regression scope; 07 security — new reachable paths into sensitive
+    code, on the branch before it merges
+- **Keeping it current**: `code-review-graph install` sets up hooks/watch; agents
+  run `code-review-graph update` before querying if the last update is older than
+  the last commit.
+- **Without MCP** (a runtime where the server is not connected), the CLI answers
+  the same questions: `code-review-graph impact --base {base}` (blast radius),
+  `code-review-graph detect-changes` (risk-scored diff), `code-review-graph query`.
+- **Fallback**: grep for symbol references plus the test runner's coverage report,
+  with the impact report marked `confidence: reduced`.
+
+### graphify — `safishamsi/graphify`
+
+- **Role in this pipeline: the architecture map.** Whole-repo knowledge graph
+  across code, SQL schemas, docs, and configs, with a human-readable report.
+- **Outputs**: `graphify-out/GRAPH_REPORT.md`, `graph.json`, `graph.html`.
+- **Used by**:
+  - 00 bootstrap — reads `GRAPH_REPORT.md` first to pick which files to sample
+    (communities, god nodes, surprising couplings) and to spot canon violations
+  - 00a scaffold — after the slice, to confirm the dependency direction is clean
+  - 01b impact — cross-cutting links code-review-graph cannot see (SQL views,
+    config, docs that describe behaviour)
+  - 08 performance — schema-to-query paths
+- **Keeping it current**: `graphify hook install` rebuilds on commit/checkout.
+- **Fallback**: bootstrap's recent-and-frequent sampling rule.
+
+---
+
+## Runtime matrix
+
+| Tool | Claude Code | Codex |
+|------|-------------|-------|
+| find-skills | skill (`.claude/skills`) | skill (`.agents/skills`) |
+| superpowers | plugin | plugin (via `/plugins`) |
+| claude-mem | plugin / `npx claude-mem install` | `npx claude-mem install` |
+| impeccable | plugin / `npx impeccable install` | `npx impeccable install --providers=codex` |
+| task-observer | skill | community port |
+| ponytail | plugin | plugin |
+| headroom | `headroom wrap claude` | `headroom wrap codex` |
+| code-review-graph | MCP (`code-review-graph install`) | MCP (`code-review-graph install`) |
+| graphify | skill (`graphify install`) | skill (`graphify install --platform codex`) |
+
+Exact install commands live in the installer's registry and in
+`.ai-agents/SETUP.md`, generated per repo by `init`.
+
+---
+
+## Project additions
+
+Skills adopted for this repository beyond the default set. Written by 00a/00
+after a human approves a find-skills proposal.
+
+| Skill | Source | Why | Used by | Approved |
+|-------|--------|-----|---------|----------|

package/payload/commands/bootstrap.md

@@ -0,0 +1,17 @@
+Read `.ai-agents/agents/00-bootstrap.md` and follow it exactly.
+
+This produces `.ai-agents/architecture-context.md`, the file every other agent
+depends on. Nothing else in the pipeline runs until it exists and is filled in.
+
+Use the reasoning-tier model with extended thinking. Inferring an architecture
+from source is genuinely hard, and the failure mode — confidently documenting a
+pattern that appears twice and nowhere else — quietly corrupts every downstream
+agent.
+
+If `architecture-context.md` already exists, this is a refresh: read it first,
+diff your findings against it, and present the differences for approval before
+writing. Never silently overwrite a section a human hand-corrected.
+
+Afterwards, tell the user to read §5.8 and §8.10 — the backend and UI exemplars —
+before anything else. Those two sections shape generated code more than the rest
+of the document combined.

package/payload/commands/contract.md

@@ -0,0 +1,64 @@
+This is the orchestration point of the pipeline. Three agents run concurrently,
+then a fourth reconciles two of their outputs.
+
+## Preconditions
+
+1. `.ai-agents/architecture-context.md` exists with no `{PLACEHOLDER}` text.
+   If not: stop, tell the user to run `/bootstrap`.
+2. `.ai-agents/state/current-stage.md` shows `impact-assessed`.
+   If it shows `gate-0-approved`: stop, tell the user to run `/impact` first.
+   If earlier: stop, tell the user to run `/intake` and approve Gate 0.
+3. Read the **Risk class** from the stage file. Tell each contract agent; L2 and
+   L3 add obligations to their output (characterisation tests, rollout plan).
+4. `split-frontend` only: the contract this feature consumes has been imported
+   with `/seam import`. If `contracts/` has nothing for it, stop and say so.
+
+Read `.ai-agents/state/current-feature.md` and note its **Tracks** value. It
+decides which agents run.
+
+## Launch
+
+Run these **in parallel** — as concurrent sub-tasks in one conversation, or as
+separate sessions, whichever this environment supports:
+
+| Agent | Instructions | Runs when |
+|-------|-------------|-----------|
+| 02a dependency-map | `.ai-agents/agents/02a-dependency-map.md` | always |
+| 02b backend-contract | `.ai-agents/agents/02b-backend-contract.md` | tracks is `backend` or `both` |
+| 02c ui-contract | `.ai-agents/agents/02c-ui-contract.md` | tracks is `ui` or `both` |
+
+They all read the same intake. Do not serialise them and do not let one wait on
+another — designing both halves at once is the point, and the seam agent exists
+to make it safe.
+
+## Then freeze the seam
+
+When 02b and 02c have both finished (or the single one that applies has), run
+**02d** from `.ai-agents/agents/02d-interface-seam.md`. It picks its mode from the
+topology (page contracts, HTTP API, GraphQL, export, import), reconciles the two
+contracts, and writes `state/contract-seam.md` — plus `contracts/{slug}/` in
+`split-backend`.
+
+02d runs on every feature, including single-track ones — for a UI-only feature it
+verifies the endpoints already exist as claimed, which is a check worth having.
+
+## Gate 1
+
+02d announces Gate 1 and lists any escalated decisions. Present the review order
+it specifies: seam first, then the two contracts, then the dependency map.
+
+Surface prominently, if present:
+
+- **Blockers** from the dependency map
+- **Escalated decisions** from the seam — these need a human answer before
+  sequencing
+- **New components or design tokens** proposed in the UI contract §9 — these are
+  permanent additions to the design system and should not slip through as an
+  implementation detail
+
+On `approve`: write any verbally-resolved decisions into the seam document before
+setting stage to `gate-1-approved`. The implementers read files, not
+conversations.
+
+On `edit`: re-run only the affected contract agent, then **re-run 02d**. A
+contract that changed with a stale seam is worse than no seam.

package/payload/commands/finalize.md

@@ -0,0 +1,26 @@
+Read `.ai-agents/agents/09a-feature-notes.md` and follow it exactly.
+
+## Preconditions
+
+Gate 3 approved (`.ai-agents/state/current-stage.md` shows `review-complete`
+and the human answered `approve-merge`).
+
+The agent refuses, naming which, if: Critical security findings are unresolved;
+the risk class is L2+ with no performance review; the risk class is L3 with
+unresolved High findings; any task is still `pending`; or `impact.md` has no
+verify section or lists escapes that were neither covered nor accepted.
+
+## What it does
+
+On the feature branch, in one commit:
+
+1. Writes the feature's release note to `.ai-agents/changes/{slug}.md`
+2. Archives the contracts, plan, impact, decisions and TDD log to
+   `.ai-agents/archive/{slug}/`
+3. Resets `.ai-agents/state/` to idle
+
+## Afterwards
+
+The branch is finished. Push, merge the review unit, and run `/intake` for the
+next feature. Nothing in this pipeline runs against the merged code: the release
+note is already written, and `/release` only assembles notes at release time.

package/payload/commands/impact.md

@@ -0,0 +1,25 @@
+Read `.ai-agents/agents/01b-impact-analysis.md` and follow it exactly.
+
+## Arguments
+
+- `/impact` — mode `predict`. Stage must be `gate-0-approved`.
+- `/impact --verify` — mode `verify`. Every task in `state/current-plan.md` must be
+  `committed` or `merged`.
+
+Use the reasoning-tier model with extended thinking.
+
+## Before running
+
+Check which graph tools `.ai-agents/pipeline.config.json` records as installed.
+If code-review-graph is installed, run `code-review-graph update` when its last
+update is older than `HEAD`. If neither graph tool is available, say so up front:
+the report will carry `Confidence: reduced`.
+
+## Afterwards
+
+Lead with the risk class and the single dimension that set it, then what it
+changes downstream. For L3, offer the split before pointing at `/contract`.
+
+In verify mode, lead with any class change and with **escapes** — affected nodes
+no test on the branch exercised. Merge waits until each is covered or explicitly
+accepted by the human at Gate 2.

package/payload/commands/implement.md

@@ -0,0 +1,58 @@
+## Arguments
+
+- `/implement` — pick the next available task across both tracks
+- `/implement backend` — next available backend task
+- `/implement ui` — next available UI task
+- `/implement --retry-task backend 3` — reset that task to `pending` and re-run it
+
+## Preconditions
+
+`.ai-agents/state/current-stage.md` shows `sequence-complete`, or a previous
+task committed or merged. If sequencing has not run, stop and say to run
+`/sequence`.
+
+## Choosing the task
+
+Read the task tables in `.ai-agents/state/current-plan.md`.
+
+A task is **available** when its status is `pending` and every entry in its
+`depends_on`, `depends_on_backend`, and `depends_on_ui` fields is `committed` or
+`merged`.
+
+With no track argument, prefer the backend track when both have work available.
+The UI track builds against mocks and can run behind without blocking; the
+backend track is what the UI integration task eventually waits on.
+
+Then dispatch by the task's **Agent** field:
+
+- **`module-scaffold` backend task** → `.ai-agents/agents/00b-module-scaffold.md`
+- **Backend task** → `.ai-agents/agents/04a-backend-implementer.md`
+- **UI task** → `.ai-agents/agents/04b-ui-implementer.md`
+
+Every task is executed test-first — the implementer's §TDD loop. Remind the
+reviewer that Gate 2 includes checking `state/tdd-log.md` for this task's
+red → green lines.
+
+## Exactly one task
+
+One task per invocation, always. Not two, however small the next one looks. The
+review gate between commits is the mechanism, not an obstacle to it.
+
+## When nothing is available
+
+Say why, specifically, rather than reporting "no tasks":
+
+- **All committed** → the branch still has work before it merges, in this order:
+  `/impact --verify`, then `/qa` and `/security` in parallel (and `/perf`, which
+  is mandatory for risk class L2+), then Gate 3, then `/finalize`. Only then push
+  and merge — nothing is scheduled after the merge
+- **Remaining UI tasks blocked on backend** → name the blocking backend task and
+  say to run `/implement backend`
+- **Only the UI integration task remains and its backend dependency is unmerged**
+  → say so; it needs the real endpoints, not mocks
+
+## After the agent finishes
+
+It commits but does not push. Confirm which track and task completed, what the
+reviewer should check, and what the next available task is — including whether it
+switches track.

package/payload/commands/intake.md

@@ -0,0 +1,16 @@
+Check `.ai-agents/architecture-context.md` exists with no `{PLACEHOLDER}` text.
+If not, stop and tell the user to run `/bootstrap` first.
+
+Check `.ai-agents/state/current-stage.md`. If a feature is already in progress
+(stage is anything other than empty, `bootstrapped`, `idle`, or `released`), stop
+and ask whether to abandon it or `/resume`.
+
+Read `.ai-agents/agents/01-intake.md` and follow it exactly.
+
+The agent must not discuss implementation — no frameworks, tables, components, or
+endpoints. It covers interface requirements as a business concern (who uses this,
+where, how often, with how much data), because those answers drive the UI
+contract later.
+
+It sets the feature's **Tracks** value, which decides which contract agents
+`/contract` launches.

package/payload/commands/perf.md

@@ -0,0 +1,20 @@
+Verify `.ai-agents/state/current-stage.md` shows `impact-verified`.
+
+**Mandatory** when the stage file records risk class L2 or L3; `/finalize`
+refuses such a feature until this has run.
+
+Read `.ai-agents/agents/08-performance.md` and follow it exactly.
+
+Use the reasoning-tier model with extended thinking — reasoning about behaviour
+at ten times the current volume is where this agent earns its cost.
+
+Worth running when QA or security flagged something, when the feature added
+aggregation, queries over growing data, bulk operations, or a screen that renders
+a lot at once — or as due diligence before a merge that matters.
+
+Output goes to `{docs_root}/performance/{feature-slug}.md`.
+
+Findings are judged against the scale posture recorded in the architecture
+context, and each one names the volume at which it becomes a real problem.
+Without that anchor the review is a list of theoretical improvements nobody acts
+on.

package/payload/commands/qa.md

@@ -0,0 +1,15 @@
+Verify `.ai-agents/state/current-stage.md` shows `impact-verified`. If not, stop
+and name the missing step: every task committed, then `/impact --verify`. The QA
+spec is written against the branch diff, not the contract.
+
+Read `.ai-agents/agents/06-qa-spec.md` and follow it exactly.
+
+Runs in parallel with `/security`, before the merge, so the spec is committed to
+the branch with the code it describes.
+
+Output goes to `{docs_root}/qa/{feature-slug}.md`, using the docs path from the
+architecture context.
+
+The agent reads the branch diff as well as the contracts. Where they disagree, it
+tests what was built and reports the divergence — surface that prominently, since
+an undocumented deviation usually matters more than any single test scenario.

package/payload/commands/release.md

@@ -0,0 +1,22 @@
+Read `.ai-agents/agents/09b-release.md` and follow it exactly.
+
+Release administration, run by the release coordinator against the branch being
+released — not per feature. Every feature in it was already finished on its own
+branch by `/finalize`.
+
+## Arguments
+
+`--since {date}`, `--from {tag} --to {ref}`, or `--features {slug,slug}`. With
+no range, every changeset in `.ai-agents/changes/` counts as unreleased.
+
+## What it does
+
+1. Assembles `.ai-agents/changes/*.md` into a changelog entry, ordering upgrade
+   steps across features where they interact
+2. Moves the included changesets to `.ai-agents/changes/released/{version}/`
+3. Runs the retrospective over `.ai-agents/observations/` and writes
+   **proposed** pipeline improvements to
+   `.ai-agents/observations/proposals-{version}.md` — applying none of them
+
+If a merged feature has no changeset, it merged without `/finalize`. Say which,
+and have the note written before the release goes out.

package/payload/commands/resume.md

@@ -0,0 +1,52 @@
+Read `.ai-agents/state/current-stage.md` and tell the user exactly what to do
+next. Resuming should cost one command and no reading of state files.
+
+Also read `.ai-agents/state/current-plan.md` when a plan exists, so you can name
+the specific next task rather than pointing at a command.
+
+## Dispatch table
+
+| Stage | Next action |
+|-------|-------------|
+| *(empty repo, no code)* | Run `/scaffold` — there is nothing for `/bootstrap` to read yet |
+| `scaffolded` | Gate A — review the slice as you would a colleague's pull request, then `/bootstrap`. Say plainly that these files become the exemplars every future feature imitates |
+| *(no architecture context, but code exists)* | Run `/bootstrap` — nothing else can run without it |
+| `bootstrapped` | Review `architecture-context.md`, especially the two exemplar sections, then `/intake` |
+| `idle` | `/intake` |
+| `intake-complete` | Gate 0 — review `state/current-feature.md`, then `approve` / `edit` / `split` |
+| `gate-0-approved` | `/impact` — measures blast radius and sets the risk class |
+| `impact-assessed` | `/contract` — name which agents will launch given the feature's tracks, and what the risk class adds |
+| *(some of 02a/02b/02c done)* | Say which are finished and which are still running |
+| `contracts-complete` | Gate 1 — review the seam first, then the contracts. Report escalated decisions, blockers, and any proposed new components |
+| `gate-1-approved` | `/sequence` |
+| *(one sequence agent done)* | Say which track is sequenced and which is pending |
+| `sequence-complete` | `/implement` — name the first available task and its track |
+| `{track}-task-{n}-committed` | Gate 2 — review the diff, then push. Then `/implement` for the next available task |
+| `{track}-task-{n}-ci-failed` | Show which CI job failed. Fix directly, or `/implement --retry-task {track} {n}` |
+| `{track}-task-{n}-merged` | Name the next available task and its track, or say all tasks are done |
+| *(every task committed, no verify line)* | `/impact --verify` — the last measurement before review |
+| `impact-verified` | `/qa` and `/security` — they run in parallel; `/perf` too, mandatory at L2+ |
+| *(one review agent done)* | Say which is finished and which is pending |
+| `review-complete` | Gate 3 — review QA, security, and performance if run. Report contract divergences and any critical findings. Then `approve-merge` or `block` |
+| `gate-3-approved` | `/finalize` — release note, archive, state reset, all on the branch |
+| `finalized` | Push and merge. Nothing runs against the merged code; `/intake` starts the next feature |
+
+## Always surface
+
+If any of these flags are present in the stage file, lead with them rather than
+with the next action:
+
+- `Critical security findings` — release is blocked
+- `Critical performance findings` — degrades at a named volume
+- Blockers recorded in the dependency map
+- Unresolved escalated decisions in the interface seam
+- Risk class L2/L3 and what it requires
+- Impact escapes not yet covered or accepted
+- `split-*`: a newer version of an imported contract than the one this feature froze
+
+## When state is inconsistent
+
+If the stage file disagrees with what the plan or the working tree shows — a task
+marked pending that is clearly committed, a stage naming an agent whose output is
+missing — say so plainly and propose the correction. Do not guess and carry on;
+a wrong resume sends the pipeline down a path nobody intended.

package/payload/commands/scaffold-module.md

@@ -0,0 +1,20 @@
+Read `.ai-agents/agents/00b-module-scaffold.md` and follow it exactly.
+
+## Arguments
+
+- `/scaffold-module {ModuleName}` — create the canon skeleton for a new backend
+  module, outside a feature.
+
+When the module is part of a feature, you do not need this command: 03a sequences
+a `module-scaffold` task and `/implement` dispatches it.
+
+## Preconditions
+
+`.ai-agents/architecture-context.md` exists and §5.0 (canon mapping) is filled.
+If §5.0 is missing, stop and tell the user to re-run `/bootstrap` so the canon
+mapping gets recorded first.
+
+## Afterwards
+
+One commit, not pushed. Show the tree that was created next to §5.0 so the
+reviewer can compare them line by line.

package/payload/commands/scaffold.md

@@ -0,0 +1,35 @@
+Read `.ai-agents/agents/00a-scaffold.md` and follow it exactly.
+
+Use the reasoning-tier model with extended thinking. The slice built here becomes
+the exemplars every future feature imitates structurally, so a wrong shape here
+does not cost one slice — it costs the shape of everything built after it.
+
+## When this is the right command
+
+- The repository is empty, or holds only a framework's default output
+- There is code, but no conventions worth documenting yet
+- A new service in an existing organisation whose conventions are not settled
+
+**Check the repository before asking.** If there is real, working application
+code, stop and redirect to `/bootstrap` — that documents what exists rather than
+inventing conventions alongside it.
+
+## What it produces
+
+An ordered sequence of small, reviewable commits — foundation, CI, design tokens,
+seed components, backend slice, UI slice, tests — not one large one. Review each
+before the next, the same cadence as `/implement`.
+
+The slice uses a **real entity from the actual domain**, with real validation and
+real authorization. Never a placeholder. A scaffold built around a demo entity
+produces exemplars for a system that does not exist.
+
+## Afterwards
+
+The developer reviews the slice as they would a colleague's pull request and
+changes anything they would ask a colleague to change — because `/bootstrap` is
+about to paste those files into the architecture context as the exemplars.
+
+Then `/bootstrap` runs and reads the slice like any other codebase. From that
+point the repository is in the state this system handles well, and nothing about
+the greenfield path applies again.

package/payload/commands/seam.md

@@ -0,0 +1,28 @@
+Manage cross-repository contracts for split topologies. Read
+`.ai-agents/agents/02d-interface-seam.md`, sections `export` and `import`.
+
+## Arguments
+
+- `/seam export` — **split-backend**. Writes (or refreshes) `contracts/{slug}/`
+  from the frozen `state/contract-seam.md`: `seam.md`, the schema fragment, and
+  `VERSION` with semver, timestamp, and sha256. Bumps the version per the rules
+  in 02d. Normally 02d does this at Gate 1; run it by hand after a seam change.
+- `/seam import {path-or-url}` — **split-frontend**. Copies a `contracts/{slug}/`
+  directory into this repository, verifies the sha256 in `VERSION`, and records
+  the version. Imported files are read-only here.
+- `/seam diff {slug}` — compares the imported version with a newer one at the
+  same source and classifies every difference (added, removed, type change,
+  nullability change). A major bump during an open feature is an escalated
+  decision.
+
+## Preconditions
+
+`architecture-context.md` §1.1 topology is `split-backend` (export) or
+`split-frontend` (import, diff). In any other topology, say the seam lives in
+`state/contract-seam.md` and nothing travels between repos.
+
+## Never
+
+- Never edit an imported contract. A missing field is a counterpart request to
+  the backend repo, raised at Gate 1.
+- Never export a seam with unresolved escalated decisions.

package/payload/commands/security.md

@@ -0,0 +1,16 @@
+Verify `.ai-agents/state/current-stage.md` shows `impact-verified`.
+
+Read `.ai-agents/agents/07-security.md` and follow it exactly. It audits the
+branch before it merges.
+
+Runs in parallel with `/qa`.
+
+Output goes to `{docs_root}/security/{feature-slug}.md`.
+
+The intake's role matrix is the specification the agent audits against — not
+"is the user logged in", but whether each role can do exactly what it was meant
+to and nothing more, enforced server-side.
+
+**Critical findings block the merge.** The agent sets a flag in the stage file
+and `/finalize` refuses a feature carrying it. Fixes are ordinary tasks on the
+same branch, reviewed at Gate 2, after which this review re-runs.