diff --git a/.claude/skills/codev/SKILL.md b/.claude/skills/codev/SKILL.md index 9c7a1b7e1..57d6f49c3 100644 --- a/.claude/skills/codev/SKILL.md +++ b/.claude/skills/codev/SKILL.md @@ -57,3 +57,34 @@ codev doctor - `codev init` creates a new directory — use `codev adopt` for existing projects - Always run `codev adopt` and `codev update` from the project root - `codev update` only updates framework files — it never touches specs/plans/reviews + +## Local build and install (this repository) + +Test changes locally before publishing. Run from the repository root: + +```bash +pnpm build # builds core first, then codev (including dashboard) +pnpm -w run local-install # packs both packages, installs globally, restarts Tower +``` + +`local-install` (`scripts/local-install.sh`) packs `@cluesmith/codev-core` and +`@cluesmith/codev`, installs both in a single `npm install -g` (separate installs fail — +`codev-core` is not on the public registry), restores the executable bit on +`scripts/forge/**/*.sh` that `pnpm pack` strips, and restarts Tower last. Install runs while +Tower is up; only the final restart causes downtime. **Do not stop Tower first**, and do not use +`npm link` / `pnpm link` — it breaks global installs. + +`pnpm build` also runs `copy-skeleton`, which copies `codev-skeleton/` into +`packages/codev/skeleton`. **Tests read that copy**, so after editing anything under +`codev-skeleton/` you must rebuild before the suite reflects your change. + +### Where to run things + +- `pnpm install` — repository root (installs all workspace packages) +- `pnpm build` / `pnpm test` — `packages/codev/`, or `pnpm --filter @cluesmith/codev build` +- Unit tests `packages/codev/tests/unit/` · E2E `packages/codev/tests/e2e/` +- Never run npm commands from the repository root unless told to + +### Measuring code size + +`tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .` diff --git a/.claude/skills/runnable-worktrees/SKILL.md b/.claude/skills/runnable-worktrees/SKILL.md new file mode 100644 index 000000000..c9163691d --- /dev/null +++ b/.claude/skills/runnable-worktrees/SKILL.md @@ -0,0 +1,119 @@ +--- +name: runnable-worktrees +description: Make builder worktrees runnable — the `.codev/config.json` `worktree` block (symlinks, postSpawn, devCommand), the `afx dev` CLI, VSCode dev controls, and per-stack config recipes. Use when configuring a repo so reviewers can run a builder's branch, when `afx dev` fails to bind or start, when a dev process is orphaned holding a port, or when asked why worktree dev uses the same ports as main. +--- + +# Runnable worktrees + +When configured, each builder worktree (`.builders//`) becomes runnable: reviewers can run +whatever your dev command starts — a dev server, `cargo run`, `expo start`, a test watcher, a +build script — against the builder's branch without `cd`'ing, installing, or hunting for the +command. Opt-in via `.codev/config.json`; unconfigured repos see zero behavior change. + +## Config: the `worktree` block + +```jsonc +{ + "worktree": { + "symlinks": ["..."], // globs symlinked from the workspace root into each new worktree + "postSpawn": ["..."], // shell commands run inside each new worktree after createWorktree + "devCommand": "..." // consumed by `afx dev ` + } +} +``` + +- **`symlinks`** — globs resolve from the workspace root and link into the worktree at the same + relative path. Root `.env` and `.codev/config.json` are *always* symlinked regardless. + **Symlinks, not copies**, so edits to main's env files reflect instantly in a running dev + session. A directory match is silently skipped (a glob cannot mask the worktree's own source) + **unless** the entry ends in a slash: `".local-user-data/"` is treated as a literal path and + links the directory whole — shared with the parent, not branch-isolated. A dangling link is + fine if the source does not exist yet. +- **`postSpawn`** — commands run sequentially with `cwd` = worktree path. A non-zero exit aborts + the spawn loudly; the half-built worktree stays for inspection. +- **`devCommand`** — the foreground command that starts your dev process. Required for + `afx dev`. + +**Codev does not auto-detect your stack.** Pick a recipe below. + +## CLI + +```bash +afx dev # start dev in that builder's worktree +afx dev main # start dev in the MAIN workspace (Codev-managed) +afx dev --stop # stop the running dev PTY (builder or main) +afx setup # re-apply symlinks + postSpawn to an existing worktree (idempotent) +``` + +**One dev PTY at a time**, across {main + all builders} — deliberate; see *URLs are +load-bearing*. `main` is a reserved target running `worktree.devCommand` in the main checkout as +a Codev-managed, swappable PTY, symmetric with builders. Starting a second target prompts to +swap; a same-target request prints the existing terminal URL and exits. Dev PTYs are +**non-persistent** — a Tower restart or crash kills them; re-run to restart. + +**Start main's dev with `afx dev main`, not a bare `pnpm dev`.** A hand-run `pnpm dev` is +invisible to Codev (which never kills what it did not spawn), so a builder dev started while it +holds the ports either fails to bind or — worse — serves main's code under the worktree URL. +`afx dev main` makes it a managed PTY that swap-detection can stop cleanly. This only helps if +used consistently. + +## VSCode + +Right-click a builder row in the Codev sidebar (Builders or Needs Attention): + +- **Open Builder Terminal** — that builder's AI terminal in a tab (same as left-click). +- **Open Worktree Folder** — `.builders//` in the OS file manager. +- **Run Worktree Setup** — re-applies `worktree.symlinks` and `worktree.postSpawn` to an + existing worktree (the git steps are skipped). Idempotent. Use when the lockfile changed, when + `symlinks`/`postSpawn` grew after the builder spawned, when a link was deleted, or when the + original setup aborted. Streams install output in a fresh terminal. CLI: `afx setup `. +- **View Diff** — unified `main...HEAD` diff for that worktree with a file-list pane. +- **Run Dev** / **Stop Dev** — spawn or kill the dev PTY as a `Codev: (dev)` tab; + prompts to swap if another dev is running. + +The sidebar's **Workspace** view carries a dev control for whatever folder the window is rooted +at — the main checkout resolves to `main`, a `.builders//` window resolves to that builder. +The row tooltip names the resolved target. Commands are also in the palette (Cmd+Shift+P); no +default keybindings. + +## URLs are load-bearing + +The dev PTY intentionally uses **the same ports and URLs as main**. OAuth callbacks, CORS +allowlists, cookie scoping, CSP `connect-src` and webhook URLs are all keyed off origin, so +running a worktree on a different port would break them. + +Consequence: stop main's dev before starting a builder's, or the spawned dev fails at bind time +with `EADDRINUSE`. + +## Cleanup and orphan recovery + +`afx dev --stop` and the swap path kill the entire PTY **process group** (SIGTERM, then SIGKILL +after 5s), which signals every grandchild of a monorepo orchestrator (`pnpm dev`, `turbo dev`, +`pnpm -r --parallel run dev`) at once. Ports are reclaimed by the OS as a consequence — Codev +never manipulates ports directly. + +If Tower hard-crashes mid-dev and a process is left holding a port outside Codev's records: + +```bash +lsof -ti : | xargs kill +lsof -ti :3000,:3001,:4000 | xargs kill +``` + +## Recipes + +**pnpm monorepo (Next.js / Turbo)** +```json +{"worktree": {"symlinks": [".env.local", ".env.development.local", "packages/*/.env", "packages/*/.env.local", "turbo.json"], "postSpawn": ["pnpm install --frozen-lockfile"], "devCommand": "pnpm dev"}} +``` + +**npm** — `{"symlinks": [".env.local", ".env.development"], "postSpawn": ["npm ci"], "devCommand": "npm run dev"}` + +**yarn** — `{"symlinks": [".env.local"], "postSpawn": ["yarn install --frozen-lockfile"], "devCommand": "yarn dev"}` + +**bun** — `{"symlinks": [".env.local"], "postSpawn": ["bun install --frozen-lockfile"], "devCommand": "bun dev"}` + +**cargo** — `{"symlinks": [".env"], "postSpawn": [], "devCommand": "cargo run"}` + +**poetry / uv** — `{"symlinks": [".env", ".env.local"], "postSpawn": ["uv sync"], "devCommand": "uv run python -m myapp"}` + +**go mod** — `{"symlinks": [".env"], "postSpawn": ["go mod download"], "devCommand": "go run ./cmd/server"}` diff --git a/.codex/skills/codev/SKILL.md b/.codex/skills/codev/SKILL.md index 9c7a1b7e1..57d6f49c3 100644 --- a/.codex/skills/codev/SKILL.md +++ b/.codex/skills/codev/SKILL.md @@ -57,3 +57,34 @@ codev doctor - `codev init` creates a new directory — use `codev adopt` for existing projects - Always run `codev adopt` and `codev update` from the project root - `codev update` only updates framework files — it never touches specs/plans/reviews + +## Local build and install (this repository) + +Test changes locally before publishing. Run from the repository root: + +```bash +pnpm build # builds core first, then codev (including dashboard) +pnpm -w run local-install # packs both packages, installs globally, restarts Tower +``` + +`local-install` (`scripts/local-install.sh`) packs `@cluesmith/codev-core` and +`@cluesmith/codev`, installs both in a single `npm install -g` (separate installs fail — +`codev-core` is not on the public registry), restores the executable bit on +`scripts/forge/**/*.sh` that `pnpm pack` strips, and restarts Tower last. Install runs while +Tower is up; only the final restart causes downtime. **Do not stop Tower first**, and do not use +`npm link` / `pnpm link` — it breaks global installs. + +`pnpm build` also runs `copy-skeleton`, which copies `codev-skeleton/` into +`packages/codev/skeleton`. **Tests read that copy**, so after editing anything under +`codev-skeleton/` you must rebuild before the suite reflects your change. + +### Where to run things + +- `pnpm install` — repository root (installs all workspace packages) +- `pnpm build` / `pnpm test` — `packages/codev/`, or `pnpm --filter @cluesmith/codev build` +- Unit tests `packages/codev/tests/unit/` · E2E `packages/codev/tests/e2e/` +- Never run npm commands from the repository root unless told to + +### Measuring code size + +`tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .` diff --git a/.codex/skills/runnable-worktrees/SKILL.md b/.codex/skills/runnable-worktrees/SKILL.md new file mode 100644 index 000000000..c9163691d --- /dev/null +++ b/.codex/skills/runnable-worktrees/SKILL.md @@ -0,0 +1,119 @@ +--- +name: runnable-worktrees +description: Make builder worktrees runnable — the `.codev/config.json` `worktree` block (symlinks, postSpawn, devCommand), the `afx dev` CLI, VSCode dev controls, and per-stack config recipes. Use when configuring a repo so reviewers can run a builder's branch, when `afx dev` fails to bind or start, when a dev process is orphaned holding a port, or when asked why worktree dev uses the same ports as main. +--- + +# Runnable worktrees + +When configured, each builder worktree (`.builders//`) becomes runnable: reviewers can run +whatever your dev command starts — a dev server, `cargo run`, `expo start`, a test watcher, a +build script — against the builder's branch without `cd`'ing, installing, or hunting for the +command. Opt-in via `.codev/config.json`; unconfigured repos see zero behavior change. + +## Config: the `worktree` block + +```jsonc +{ + "worktree": { + "symlinks": ["..."], // globs symlinked from the workspace root into each new worktree + "postSpawn": ["..."], // shell commands run inside each new worktree after createWorktree + "devCommand": "..." // consumed by `afx dev ` + } +} +``` + +- **`symlinks`** — globs resolve from the workspace root and link into the worktree at the same + relative path. Root `.env` and `.codev/config.json` are *always* symlinked regardless. + **Symlinks, not copies**, so edits to main's env files reflect instantly in a running dev + session. A directory match is silently skipped (a glob cannot mask the worktree's own source) + **unless** the entry ends in a slash: `".local-user-data/"` is treated as a literal path and + links the directory whole — shared with the parent, not branch-isolated. A dangling link is + fine if the source does not exist yet. +- **`postSpawn`** — commands run sequentially with `cwd` = worktree path. A non-zero exit aborts + the spawn loudly; the half-built worktree stays for inspection. +- **`devCommand`** — the foreground command that starts your dev process. Required for + `afx dev`. + +**Codev does not auto-detect your stack.** Pick a recipe below. + +## CLI + +```bash +afx dev # start dev in that builder's worktree +afx dev main # start dev in the MAIN workspace (Codev-managed) +afx dev --stop # stop the running dev PTY (builder or main) +afx setup # re-apply symlinks + postSpawn to an existing worktree (idempotent) +``` + +**One dev PTY at a time**, across {main + all builders} — deliberate; see *URLs are +load-bearing*. `main` is a reserved target running `worktree.devCommand` in the main checkout as +a Codev-managed, swappable PTY, symmetric with builders. Starting a second target prompts to +swap; a same-target request prints the existing terminal URL and exits. Dev PTYs are +**non-persistent** — a Tower restart or crash kills them; re-run to restart. + +**Start main's dev with `afx dev main`, not a bare `pnpm dev`.** A hand-run `pnpm dev` is +invisible to Codev (which never kills what it did not spawn), so a builder dev started while it +holds the ports either fails to bind or — worse — serves main's code under the worktree URL. +`afx dev main` makes it a managed PTY that swap-detection can stop cleanly. This only helps if +used consistently. + +## VSCode + +Right-click a builder row in the Codev sidebar (Builders or Needs Attention): + +- **Open Builder Terminal** — that builder's AI terminal in a tab (same as left-click). +- **Open Worktree Folder** — `.builders//` in the OS file manager. +- **Run Worktree Setup** — re-applies `worktree.symlinks` and `worktree.postSpawn` to an + existing worktree (the git steps are skipped). Idempotent. Use when the lockfile changed, when + `symlinks`/`postSpawn` grew after the builder spawned, when a link was deleted, or when the + original setup aborted. Streams install output in a fresh terminal. CLI: `afx setup `. +- **View Diff** — unified `main...HEAD` diff for that worktree with a file-list pane. +- **Run Dev** / **Stop Dev** — spawn or kill the dev PTY as a `Codev: (dev)` tab; + prompts to swap if another dev is running. + +The sidebar's **Workspace** view carries a dev control for whatever folder the window is rooted +at — the main checkout resolves to `main`, a `.builders//` window resolves to that builder. +The row tooltip names the resolved target. Commands are also in the palette (Cmd+Shift+P); no +default keybindings. + +## URLs are load-bearing + +The dev PTY intentionally uses **the same ports and URLs as main**. OAuth callbacks, CORS +allowlists, cookie scoping, CSP `connect-src` and webhook URLs are all keyed off origin, so +running a worktree on a different port would break them. + +Consequence: stop main's dev before starting a builder's, or the spawned dev fails at bind time +with `EADDRINUSE`. + +## Cleanup and orphan recovery + +`afx dev --stop` and the swap path kill the entire PTY **process group** (SIGTERM, then SIGKILL +after 5s), which signals every grandchild of a monorepo orchestrator (`pnpm dev`, `turbo dev`, +`pnpm -r --parallel run dev`) at once. Ports are reclaimed by the OS as a consequence — Codev +never manipulates ports directly. + +If Tower hard-crashes mid-dev and a process is left holding a port outside Codev's records: + +```bash +lsof -ti : | xargs kill +lsof -ti :3000,:3001,:4000 | xargs kill +``` + +## Recipes + +**pnpm monorepo (Next.js / Turbo)** +```json +{"worktree": {"symlinks": [".env.local", ".env.development.local", "packages/*/.env", "packages/*/.env.local", "turbo.json"], "postSpawn": ["pnpm install --frozen-lockfile"], "devCommand": "pnpm dev"}} +``` + +**npm** — `{"symlinks": [".env.local", ".env.development"], "postSpawn": ["npm ci"], "devCommand": "npm run dev"}` + +**yarn** — `{"symlinks": [".env.local"], "postSpawn": ["yarn install --frozen-lockfile"], "devCommand": "yarn dev"}` + +**bun** — `{"symlinks": [".env.local"], "postSpawn": ["bun install --frozen-lockfile"], "devCommand": "bun dev"}` + +**cargo** — `{"symlinks": [".env"], "postSpawn": [], "devCommand": "cargo run"}` + +**poetry / uv** — `{"symlinks": [".env", ".env.local"], "postSpawn": ["uv sync"], "devCommand": "uv run python -m myapp"}` + +**go mod** — `{"symlinks": [".env"], "postSpawn": ["go mod download"], "devCommand": "go run ./cmd/server"}` diff --git a/AGENTS.md b/AGENTS.md index 916f75dee..8e99f4c5e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,170 +16,69 @@ map to open the full arch.md / lessons-learned.md when relevant. -> **Always-on governance docs (Spec 987 — hot/cold tiers).** The block above is **auto-generated** from the HOT tier (`codev/resources/arch-critical.md` and `lessons-critical.md`) and refreshed by `codev init` / `codev update` — edit those source files, not the block. Each hot file is tiny, hard-capped, and injected into *every* porch phase prompt as well as here, so the most decision-relevant facts are always in context. Their full COLD counterparts (`codev/resources/arch.md` and `lessons-learned.md`) are the on-demand reference archives; the "consult when…" maps in the hot files point into them. New facts/lessons are **routed** by tier at review time and policed (cap + map accuracy) during MAINTAIN. +> The block above is **auto-generated** from the hot tier by `codev init` / `codev update` — +> edit those source files, not the block. Their COLD counterparts (`codev/resources/arch.md`, +> `lessons-learned.md`) are on-demand archives; the "consult when…" maps point into them. +> New facts are **routed** by tier at review time and policed during MAINTAIN. -> **Note**: This file is specific to Claude Code. An identical [AGENTS.md](AGENTS.md) file is also maintained following the [AGENTS.md standard](https://agents.md/) for cross-tool compatibility with Cursor, GitHub Copilot, and other AI coding assistants. Both files contain the same content and should be kept synchronized. +> **[AGENTS.md](AGENTS.md) is a byte-identical twin of this file** for tools that read the +> [AGENTS.md standard](https://agents.md/). Any edit here must be applied there. -## Project Context +## This repository is Codev, built with Codev -**THIS IS THE CODEV SOURCE REPOSITORY - WE ARE SELF-HOSTED** +Two trees, and the distinction governs almost every change: -This project IS Codev itself, and we use our own methodology for development. All new features and improvements to Codev should follow the SPIR protocol defined in `codev/protocols/spir/protocol.md`. - -### Important: Understanding This Repository's Structure - -This repository has a dual nature that's important to understand: - -1. **`codev/`** - This is OUR instance of Codev - - This is where WE (the Codev project) keep our specs, plans, reviews, and resources - - When working on Codev features, you work in this directory - - Example: `codev/specs/1-test-infrastructure.md` is a feature spec for Codev itself - -2. **`codev-skeleton/`** - This is the template for OTHER projects - - This is what gets copied to other projects when they install Codev - - Contains the protocol definitions, templates, and agents - - Does NOT contain specs/plans/reviews (those are created by users) - - Think of it as "what Codev provides" vs "how Codev uses itself" - -**When to modify each**: -- **Modify `codev/`**: When implementing features for Codev (specs, plans, reviews, our architecture docs) -- **Modify `codev-skeleton/`**: When updating protocols, templates, or agents that other projects will use - -### Release Process - -To release a new version, tell the AI: `Let's release v1.6.0`. The AI follows the **RELEASE protocol** (`codev/protocols/release/protocol.md`). Release candidate workflow and local testing procedures are documented there. For local testing shortcuts, see `codev/resources/testing-guide.md`. - -### Local Build Testing - -To test changes locally before publishing to npm: - -```bash -# From the repository root: - -# 1. Build (Tower stays up during this) -pnpm build - -# 2. Pack, install globally, and restart Tower (one command) -pnpm -w run local-install -``` - -- `pnpm build` builds artifact-canvas (needed by the VS Code extension, not part of codev's dependency closure), then the codev CLI; codev's own build script first builds its graph-derived workspace-dependency closure (types, sdk, core, dashboard) via `pnpm --filter "@cluesmith/codev^..." build` -- `pnpm -w run local-install` runs `scripts/local-install.sh`, which: - - Packs the `@cluesmith/codev-core`, `@cluesmith/codev-sdk`, and `@cluesmith/codev` tarballs into their package directories - - Globally installs all three in one `npm install -g` (separate installs fail because `@cluesmith/codev-core` isn't on the public npm registry) - - Restores the executable bit on `scripts/forge/**/*.sh` (pnpm pack strips it, causing "GitHub CLI unavailable" errors otherwise) - - Restarts Tower so it picks up the new code -- Install runs while Tower is up — only the final restart causes downtime -- Do NOT stop Tower yourself before running the script — the script handles restart at the end -- Do NOT use `npm link` or `pnpm link` — it breaks global installs - -### Testing - -When making changes to UI code (tower, dashboard, terminal), you MUST test using Playwright before claiming the fix works. See `codev/resources/testing-guide.md` for Playwright patterns and Tower regression prevention. - -## Quick Start - -> **New to Codev?** See the [Cheatsheet](codev/resources/cheatsheet.md) for philosophies, concepts, and tool reference. - -You are working in the Codev project itself, with multiple development protocols available: - -**Available Protocols**: -- **SPIR**: Multi-phase development with consultation - `codev/protocols/spir/protocol.md` -- **ASPIR**: Autonomous SPIR (no human gates on spec/plan) - `codev/protocols/aspir/protocol.md` -- **AIR**: Autonomous Implement & Review for small features - `codev/protocols/air/protocol.md` -- **BUGFIX**: Bug fixes from GitHub issues - `codev/protocols/bugfix/protocol.md` -- **PIR**: Plan / Implement / Review — issue-driven with two pre-PR human gates (plan-approval, dev-approval) plus a post-PR `pr` gate. Lighter than SPIR; stronger than BUGFIX/AIR. Useful when a change needs design review before coding OR pre-PR testing of running code (e.g., mobile / UI / cross-platform). See `codev/protocols/pir/protocol.md`. -- **EXPERIMENT**: Disciplined experimentation - `codev/protocols/experiment/protocol.md` -- **MAINTAIN**: Codebase maintenance (code hygiene + documentation sync) - `codev/protocols/maintain/protocol.md` -- **RESEARCH**: Multi-agent research with 3-way investigation, synthesis, and critique - `codev/protocols/research/protocol.md` - -### File Resolution (How Codev Finds Protocols and Templates) - -Codev resolves protocol files, prompts, agent definitions, and roles through a four-tier lookup (highest priority first): - -1. `.codev/` — user override (project-local customization) -2. `codev/` — project-local copy (customized and checked in) -3. Runtime cache -4. **Installed package skeleton** — ships with `@cluesmith/codev` (the default for every standard protocol) - -**The absence of `codev/protocols//` on disk is not a missing reference** — it's the normal case for any protocol you haven't customized. The protocol resolves from the installed package's skeleton at runtime. Only protocols you want to customize need to live in your repo's `codev/protocols/`. - -**Implication for `codev update` and CLAUDE.md / AGENTS.md merges:** when an updated template references a protocol (e.g., PIR), do NOT drop the reference because `codev/protocols//` is absent locally. The protocol resolves via the package skeleton, and dropping the reference removes the protocol from the user's available-protocol list while it's still callable from the CLI. - -### Framework files in prompts: deliver them, don't make the builder read them by path - -Framework files (protocol/role docs, the shipped `codev/resources/` reference docs) default to the package skeleton (see File Resolution above) and aren't guaranteed on disk in a fresh project. So when authoring any builder-facing prompt, role doc, or instruction, don't tell the builder to read a framework file by literal `codev/...` path — that bypasses the resolver and fails in fresh installs. Deliver the content instead (`protocol.md` is inlined into the spawn prompt; per-phase prompts and their templates arrive via porch). Mentioning a `codev/...` path in prose for orientation is fine — the rule is about *fetching*, not *referencing*. (`codev/resources/arch.md` and `codev/resources/lessons-learned.md` are user-evolved files, not framework files, so referencing those by path is correct.) +| Tree | What it is | When you edit it | +|---|---|---| +| `codev/` | **Our** instance — our specs, plans, reviews, resources | Implementing a feature *for* Codev | +| `codev-skeleton/` | The **template shipped to adopters** — protocols, roles, templates, agents | Changing what other projects receive | -### Protocol Verification (When You Don't Recognize a Protocol Name) +A framework change usually belongs in **both**. `codev-skeleton/` carries no specs or +plans — those are created by the projects that install it. -If the user mentions a protocol name you don't immediately recognize, verify against the CLI before responding: +### How framework files resolve -```bash -afx spawn --protocol --help -``` +Protocols, prompts, roles and templates resolve at **runtime** through four tiers, highest +first: `.codev/` → `codev/` → runtime cache → **installed package skeleton**. -This succeeds if the protocol is registered (including via the skeleton fallback in tier 4 of the resolution chain) and errors helpfully otherwise. The CLI is the source of truth — defer to it when in doubt. +The absence of `codev/protocols//` is normal, not a missing reference — it means the +protocol resolves from the installed package. Only protocols you customize need a local copy. +When `codev update` merges a template that references a protocol you don't have locally, keep +the reference. -Key locations: -- Protocol details: `codev/protocols/` (Choose appropriate protocol) -- **Project tracking**: GitHub Issues (source of truth for all projects) -- Specifications go in: `codev/specs/` -- Plans go in: `codev/plans/` -- Reviews go in: `codev/reviews/` +**Deliver framework content; don't instruct an agent to fetch it by path.** A builder-facing +prompt or role doc must not say "read `codev/protocols/…`" — that bypasses the resolver and +fails in fresh installs. `protocol.md` is inlined into the spawn prompt; phase prompts and +their templates arrive via porch. Naming a `codev/...` path in prose for orientation is fine; +the rule is about *fetching*. (`codev/resources/arch.md` and `lessons-learned.md` are +user-evolved files, not framework files — referencing those by path is correct.) -### Project Tracking +Verify an unfamiliar protocol against the CLI rather than assuming: `afx spawn --protocol + --help` succeeds if it is registered, including via the skeleton fallback. -**GitHub Issues are the source of truth for project tracking.** +## Irreversible acts — the rules that exist because something was destroyed -- Issues with the `spec` label have approved specifications -- Issues with the `plan` label have approved plans -- Active builders are tracked via `codev/projects//status.yaml` (managed by porch) -- The workspace overview Work view shows builders, PRs, and backlog derived from GitHub + filesystem state +These are not style preferences. Each one is here because an agent destroyed work or bypassed +a human decision. -**When to use which:** -- **Starting work**: Check GitHub Issues for priorities and backlog -- **During implementation**: Use `porch status ` for detailed phase status -- **After completion**: Close the GitHub Issue when PR is merged +- Never `git add -A` / `--all` / `.` — stage each file explicitly by path. +- Never destroy builder worktrees (`git worktree remove`, `git branch -D` on builder branches, `afx cleanup` + respawn). Use `afx spawn --resume`; if it fails, ask the human — what is expendable is never your call. +- Never run `git reset --hard`, `git checkout -- .`, `git clean -fd`, or `git stash` without explicit human permission — they destroy uncommitted work. +- Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization. +- Never hand-edit `status.yaml` — only porch commands modify project state. +- Run `afx` commands only from the main workspace root, never from inside a builder worktree — spawning from a worktree nests builders and breaks the workspace. +- Never kill a shellper process without verifying it is an orphan (match each PID to its workspace via Tower) — an 'extra' shellper may be a live architect session. +- Never restart or stop Tower without explicit human permission — it kills every running builder session. -### Area Labels — the organizing axis for issues +## Gates -`area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. +Two human approval gates plus the PR gate. Only a human transitions +`conceived → specified` and `committed → integrated`. Stop and wait at each; do not infer +approval from silence. -**Labels**: +**Approved specs and plans need frontmatter and must be committed to `main` before spawning.** +Porch runs the full protocol from `specify`, but treats an artifact carrying this as done: -| Label | Scope | -|---|---| -| `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | -| `area/vscode` | VSCode extension — sidebar views, panel-area views, commands, keybindings | -| `area/dashboard` | Tower web dashboard — the `@cluesmith/codev-web` React/Vite package, served by Tower and opened in a browser (distinct from any VSCode UI) | -| `area/consult` | `consult` CLI and consultation tooling | -| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | -| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | -| `area/porch` | Porch state machine / protocol orchestration | -| `area/protocols` | Protocol definitions (`codev/protocols/`, `codev-skeleton/protocols/`) — distinct from `area/porch` (orchestration) | -| `area/config` | `.codev/config.json` and workspace setup | -| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | -| `area/scaffold` | Install path — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, the four-tier resolver | -| `area/release` | Release tooling — version bumps, release protocol artifacts, release scripts | -| `area/web` | Marketing site / web content — the `marketing/` directory | -| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`, `packages/types`) | - -**Policy:** - -- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. -- **No `type:*` labels.** Codev classifies issues by area only. -- `area/` uses **slash**. Other label families (if ever introduced) would keep colons. - -**🚨 CRITICAL: Two human approval gates exist:** -- **conceived → specified**: AI creates spec, but ONLY the human can approve it -- **committed → integrated**: AI can merge PRs, but ONLY the human can validate production - -AI agents must stop at `conceived` after writing a spec, and stop at `committed` after merging. - -**🚨 CRITICAL: Approved specs/plans need YAML frontmatter and must be committed to `main`.** -When the architect creates and approves a spec or plan before spawning a builder, it must have YAML frontmatter marking it as approved and validated, and be committed to `main`. Porch always runs the full protocol from `specify` — but when it finds an existing artifact with this metadata, it skips that phase as a no-op. If no spec/plan exists, porch drives the builder to create one. - -Frontmatter format: ```yaml --- approved: 2026-01-29 @@ -187,555 +86,118 @@ validated: [gemini, codex, claude] --- ``` -## Agent Responsiveness - -**Responsiveness is paramount.** The user should never wait for you. Use `run_in_background: true` for any operation that takes more than ~5 seconds. - -| Task Type | Expected Duration | Action | -|-----------|------------------|--------| -| Running tests | 10-300s | `run_in_background: true` | -| Consultations (consult) | 60-250s | `run_in_background: true` | -| E2E test suites | 60-600s | `run_in_background: true` | -| pnpm install/build | 5-60s | `run_in_background: true` | -| Quick file reads/edits | <5s | Run normally | - -**Critical**: Using `&` at the end of the command does NOT work - you MUST set the `run_in_background` parameter. - -## Protocol Selection Guide - -### Use BUGFIX for (GitHub issue fixes): -- Bug reported as a **GitHub Issue** -- Fix is isolated (< 300 LOC net diff) -- No spec/plan artifacts needed -- Single builder can fix independently - -**BUGFIX uses GitHub Issues as source of truth.** See `codev/protocols/bugfix/protocol.md`. - -### Use AIR for (small features from GitHub issues): -- Small features (< 300 LOC) fully described in a **GitHub Issue** -- No architectural decisions needed -- No spec/plan artifacts — review goes in the PR body -- Would be overkill for full SPIR/ASPIR ceremony - -**AIR uses GitHub Issues as source of truth.** Two phases: Implement → Review. See `codev/protocols/air/protocol.md`. - -### Use PIR for (engineer-judged — based on the nature of the work, not its size): - -Pick PIR when ONE or BOTH of the following apply to a GitHub-issue-driven change: - -**1. The approach needs review before coding starts**: -- Root cause is ambiguous; multiple valid fixes exist -- Area is unfamiliar or high-blast-radius (shared utilities, auth, migrations, public APIs) -- Design-sensitive (affects conventions, patterns, architecture) -- Cheaper to redirect at plan time than at PR time - -**2. The implementation needs to be TESTED before a PR is created** (PR diff alone is insufficient): -- Mobile app changes (needs device testing on Android, iOS, possibly web) -- UI / UX changes (visual inspection, interaction flow, accessibility) -- Hardware-adjacent behavior (sensors, camera, permissions, notifications) -- Integration with external services that don't mock cleanly (OAuth, payments, analytics) -- User-journey changes that need a full-flow exercise -- Performance-sensitive changes that need profiling on the running app - -**PIR uses GitHub Issues as source of truth.** Three phases: Plan (gated by `plan-approval`) → Implement (gated by `dev-approval`) → Review (PR + CMAP-2 at PR, then gated by `pr` for merge synchronization — matching SPIR's pr-gate pattern but with no post-merge verify phase). Plan and review artifacts live in `codev/plans/` and `codev/reviews/` on the builder branch, ship to main with the merge. Review file is shaped identically to SPIR's (Summary + Architecture Updates + Lessons Learned + supporting sections) so `codev/reviews/` stays semantically consistent across protocols. Lighter than SPIR (no spec phase — the issue body is the implicit spec; consult footprint matches BUGFIX/AIR's "one consult at PR" pattern). Stronger than BUGFIX/AIR (two human gates pre-PR — the human reviews the running worktree at the `dev-approval` gate, not the PR diff post-creation). CMAP at the PR is a **single advisory pass** (`max_iterations: 1`) — no iterate-until-APPROVE loop; a `REQUEST_CHANGES` is escalated to the human at the `pr` gate, not auto-re-reviewed. The CMAP-2 footprint is a design invariant: porch's model precedence is *config > protocol*, so a project-wide `porch.consultation.models` (e.g. a SPIR-tuned 3-model list) silently inflates PIR — leave it unset or scope it per-protocol to preserve the BUGFIX/AIR-parity cost. See `codev/protocols/pir/protocol.md`. - -### Use SPIR for (new features): -- Creating a **new feature from scratch** (no existing spec to amend) -- New protocols or protocol variants -- Major changes to existing protocols -- Complex features requiring multiple phases -- Architecture changes - -### Use ASPIR for (autonomous SPIR): -- Same as SPIR but **without human approval gates** on spec and plan -- Trusted, low-risk work where spec/plan review can be deferred to PR -- Builder runs autonomously through Specify → Plan → Implement → Review (→ Verify) -- Human approval still required at the PR gate before merge - -**ASPIR is identical to SPIR** except `spec-approval` and `plan-approval` gates are removed. Both include an optional verify phase after review. See `codev/protocols/aspir/protocol.md`. - -### Use EXPERIMENT for: -- Testing new approaches or techniques -- Evaluating models or libraries -- Proof-of-concept work -- Research spikes - -### Use MAINTAIN for: -- Removing dead code and unused dependencies -- Quarterly codebase maintenance -- Before releases (clean slate for shipping) -- Syncing documentation (arch.md/arch-critical.md, lessons-learned.md/lessons-critical.md, CLAUDE.md/AGENTS.md) - -### Use RESEARCH for: -- Competitive analysis and technology evaluation -- Market research and "state of X" questions -- Architectural decision support when unfamiliar with the domain -- Triangulating across 3 AI models to get a high-confidence answer -- Output goes to `codev/research/.md` - -### Skip formal protocols for: -- README typos or minor documentation fixes -- Small bug fixes in templates -- Dependency updates - -## Core Workflow - -1. **When asked to build NEW FEATURES FOR CODEV**: Start with the Specification phase -2. **Create exactly THREE documents per feature**: spec, plan, and review (all with same filename) -3. **Follow the SPIR phases**: Specify → Plan → Implement → Review (→ Verify) -4. **Use multi-agent consultation by default** unless user says "without consultation" - -## Directory Structure -``` -project-root/ -├── codev/ -│ ├── protocols/ # Development protocols -│ │ ├── spir/ # Multi-phase development with consultation -│ │ ├── experiment/ # Disciplined experimentation -│ │ └── maintain/ # Codebase maintenance (code + docs) -│ ├── maintain/ # MAINTAIN protocol runtime artifacts -│ │ └── .trash/ # Soft-deleted files (gitignored, 30-day retention) -│ ├── projects/ # Active project state (managed by porch) -│ ├── specs/ # Feature specifications (WHAT to build) -│ ├── plans/ # Implementation plans (HOW to build) -│ ├── reviews/ # Reviews and lessons learned from each feature -│ └── resources/ # Reference materials -│ ├── arch.md # Architecture (COLD reference; maintained during MAINTAIN) -│ ├── arch-critical.md # Architecture HOT tier — capped, always-injected (Spec 987) -│ ├── testing-guide.md # Local testing, Playwright, regression prevention -│ ├── lessons-learned.md # Engineering wisdom (COLD reference; maintained during MAINTAIN) -│ └── lessons-critical.md # Engineering wisdom HOT tier — capped, always-injected (Spec 987) -├── .claude/ -│ ├── agents/ # AI agent definitions (custom project agents) -│ └── skills/ # Claude-native Codev skills -├── .codex/ -│ └── skills/ # Codex-native Codev skills -├── AGENTS.md # Universal AI agent instructions (AGENTS.md standard) -├── CLAUDE.md # This file (Claude Code-specific, identical to AGENTS.md) -└── [project code] -``` - -## Directory Map -- pnpm install → always run from the repository root (installs all workspace packages) -- pnpm build / pnpm test → run from `packages/codev/` or use `pnpm --filter @cluesmith/codev build` (the build script first builds codev's workspace deps via the graph-derived `pnpm --filter "@cluesmith/codev^..." build` closure, so a missing or stale dep `dist/` can't surface as false TS errors in codev's own sources) -- E2E tests → `packages/codev/tests/e2e/` -- Unit tests → `packages/codev/tests/unit/` -- Never run npm commands from the repository root unless explicitly told to. - -## File Naming Convention - -Use sequential numbering with descriptive names (no leading zeros): -- Specification: `codev/specs/42-feature-name.md` -- Plan: `codev/plans/42-feature-name.md` -- Review: `codev/reviews/42-feature-name.md` - -**CRITICAL: Keep Specs and Plans Separate** -- Specs define WHAT to build (requirements, acceptance criteria) -- Plans define HOW to build (phases, files to modify, implementation details) -- Each document serves a distinct purpose and must remain separate - -## Multi-Agent Consultation - -**DEFAULT BEHAVIOR**: Consultation is ENABLED by default with: -- **Gemini** via the **Antigravity CLI (`agy`)** for deep analysis (the retired Gemini CLI's - replacement; OAuth/subscription, agy's default model — no pinned model id). Skips non-blockingly - if `agy` is missing/unauthenticated. An unauthenticated `agy` is spawned **at most once per TTL - window** rather than once per consult: the verdict is cached across processes in - `~/.cache/codev/agy-auth.json`, because each spawn opens an OAuth browser tab before Codev can - detect the missing login (#1077). Sign in with `agy` in any terminal and the lane recovers on its - own; see `codev/resources/commands/consult.md` for the TTL/opt-out env vars. -- **GPT-5.6 Sol** (`gpt-5.6-sol`, medium reasoning effort) via the Codex SDK for coding and - architecture perspective. The `-sol` suffix is load-bearing — plain `gpt-5.6` and - `gpt-5.6-codex` are both rejected by Codex on a ChatGPT account. -- **Claude Opus 5** (`claude-opus-5`) via the Claude Agent SDK for balanced analysis with tool use - -To disable: User must explicitly say "without multi-agent consultation" - -**CRITICAL CONSULTATION CHECKPOINTS (DO NOT SKIP):** -- After writing implementation code → STOP → Consult GPT-5 and Gemini (via agy) -- After writing tests → STOP → Consult GPT-5 and Gemini (via agy) -- ONLY THEN present results to user for evaluation - -### cmap (Consult Multiple Agents in Parallel) - -**cmap** is shorthand for "consult multiple agents in parallel in the background." - -When the user says **"cmap the PR"** or **"cmap spec 42"**, this means: -1. Run a 3-way parallel review (Gemini, Codex, Claude) -2. Run all three in the **background** (`run_in_background: true`) -3. Return control to the user **immediately** -4. Retrieve results later with `TaskOutput` when needed - -**Always run consultations in parallel** using separate Bash tool calls in the same message, not sequentially. - -## CLI Command Reference - -**IMPORTANT: Never guess CLI commands.** Use the `/afx` skill to check the quick reference before running agent farm commands. Common mistakes to avoid: -- There is NO `codev tower` command — use `afx tower start` / `afx tower stop` -- There is NO `restart` subcommand — stop then start -- When unsure about syntax, check the docs below first - -Codev provides five CLI tools. For complete reference documentation, see: - -- **[Overview](codev/resources/commands/overview.md)** - Quick start and summary of all tools -- **[codev](codev/resources/commands/codev.md)** - Project management (init, adopt, doctor, update, tower) -- **[afx](codev/resources/commands/agent-farm.md)** - Agent Farm orchestration (start, spawn, status, cleanup, send, etc.) -- **[porch](codev/resources/commands/overview.md#porch---protocol-orchestrator)** - Protocol orchestrator (status, run, approve, pending) -- **[consult](codev/resources/commands/consult.md)** - AI consultation (general, protocol, stats) -- **[team](codev/resources/commands/team.md)** - Team coordination (list, message, update, add) - -## Runnable Worktrees - -When configured, each builder worktree (`.builders//`) becomes runnable — reviewers can run whatever your dev command starts against the builder's branch — a dev server, `cargo run`, `expo start`, a test watcher, a build script, whatever iterates on your project — without `cd`'ing, manually installing, or finding the right command. Opt-in via `.codev/config.json`; unconfigured repos see zero behavior change. - -### Config: the `worktree` block - -```jsonc -{ - "worktree": { - "symlinks": ["..."], // glob patterns of files to symlink from root into each new worktree - "postSpawn": ["..."], // shell commands run inside each new worktree after createWorktree - "devCommand": "..." // consumed by `afx dev ` - } -} -``` - -- `symlinks`: globs resolve from the workspace root; matches symlink into the worktree at the same relative path. Root `.env` and `.codev/config.json` are *always* symlinked regardless. **Symlinks, not copies** — edits to main's env files reflect instantly in any running dev session. A directory match is silently skipped (so a glob can't mask the worktree's own source) **unless** the entry ends with a trailing slash: `".local-user-data/"` is treated as a literal path and symlinks the directory whole (shared with the parent, not branch-isolated; a dangling link is fine if the source doesn't exist yet). -- `postSpawn`: each command runs sequentially with `cwd` = worktree path. Non-zero exit aborts the spawn loud (half-built worktree stays for inspection). -- `devCommand`: the foreground command that starts your dev process (a server, a watcher, `cargo run`, `expo start`, a build script — whatever iterates on your project). Required for `afx dev` to work. - -**Codev does not auto-detect your stack.** Pick the recipe below that matches your toolchain. - -### CLI - -```bash -afx dev # start dev in 's worktree -afx dev main # start dev in the MAIN workspace (Codev-managed) -afx dev --stop # stop the currently running dev PTY (builder or main) -``` - -Only one dev PTY runs at a time (by design — see "URLs are load-bearing" below), across **{main + all builders}**. `main` is a reserved target: it runs `worktree.devCommand` in the main checkout as a Codev-managed, swappable PTY, symmetric with builders. Starting any target while another is up prompts for swap (`afx dev ` while `main` runs, or vice-versa); same-target requests print the existing terminal URL and exit. Like builder dev, main dev is a **non-persistent** PTY — a Tower restart (`pnpm -w run local-install`, crash) kills it; re-run to restart. - -**Launch main dev via `afx dev main`, not a bare `pnpm dev`.** A manually-run `pnpm dev` at the repo root is invisible to Codev (the deliberate "never kill what it didn't spawn" policy) — start a builder dev while it holds the ports and the builder dev silently fails to bind, or worse serves main's code under the worktree URL. `afx dev main` makes it a managed PTY that swap-detection can cleanly stop first. This only helps if you use it *consistently*; a hand-started `pnpm dev` stays unmanaged. - -### VSCode - -The same actions are available via right-click on any builder row in the Codev sidebar (Builders or Needs Attention view): - -- **Codev: Open Builder Terminal** — opens that builder's AI terminal in a VSCode tab (same as left-clicking the row). -- **Codev: Open Worktree Folder** — opens `.builders//` in the OS file manager (Finder on macOS, Explorer on Windows, xdg-open on Linux). -- **Codev: Run Worktree Setup** — applies the configured `worktree.symlinks` and runs the `worktree.postSpawn` commands against the existing worktree (mirrors what spawn does, minus the git steps). Idempotent: existing symlinks are skipped, missing ones added. Useful when the lockfile changed (reinstall deps), `symlinks` or `postSpawn` was extended after the builder spawned, a symlink was accidentally deleted, or the original setup aborted mid-run. Opens a fresh VSCode terminal so install output streams live. Available via CLI too: `afx setup `. -- **Codev: View Diff** — opens a single unified diff editor for `main...HEAD` of that builder's worktree, with a file-list pane on the left (matches VSCode's built-in Source Control "Working Tree" view). Status icons indicate added / modified / deleted. Empty diff → friendly toast. -- **Codev: Run Dev** — reads `worktree.devCommand` from `.codev/config.json`, asks Tower to spawn a dev PTY in the builder's worktree, and opens it as a VSCode terminal tab named `Codev: (dev)`. If another builder's dev is already running, you get a modal asking whether to swap. -- **Codev: Stop Dev** — kills the running dev PTY and closes its tab. - -The Codev sidebar's **Workspace** view also carries a dev control for *whatever folder this VSCode window is rooted at* (it is not "main"-specific): - -- **Start Dev** — runs `worktree.devCommand` for the current workspace. Target is resolved from the open folder: the main checkout → `main`; a `.builders//` worktree opened as its own window (e.g. via *Open Worktree as Workspace*) → that builder. Same single-slot swap model as builder dev (prompts if another dev is running). The row tooltip names the resolved target. -- **Stop Dev** — stops this workspace's dev; the row appears only while it is running. Scoped to the resolved target — it does not touch other devs. - -The three commands are also available from the command palette (Cmd+Shift+P). No default keybindings; bind via `keybindings.json` if you use them often. - -### URLs are load-bearing - -The dev PTY uses **the same ports and URLs as main** intentionally. OAuth callbacks, CORS allowlists, cookie scoping, CSP `connect-src`, webhook URLs are all keyed off origin — running the worktree on a different port would break them. Consequence: stop main's `pnpm dev` before `afx dev`. If you don't, the spawned dev fails at bind time with its own `EADDRINUSE`. Prefer `afx dev main` (or the Workspace view's *Start Dev* row) over a hand-run `pnpm dev` so Codev owns the PTY and swap-detection can stop it for you automatically. - -### Cleanup semantics - -`afx dev --stop` and the swap path kill the entire PTY process group (SIGTERM, escalating to SIGKILL after 5s via `PtySession.kill`). That signals every grandchild of a monorepo dev orchestrator (`pnpm dev`, `turbo dev`, `pnpm -r --parallel run dev`, etc.) simultaneously. The OS reclaims ports as a consequence — Codev never touches ports directly. - -**Orphan recovery** — if Tower itself hard-crashes mid-dev and a process is left holding a port outside Codev's records: - -```bash -lsof -ti : | xargs kill # one port -lsof -ti :3000,:3001,:4000 | xargs kill # several at once -``` - -### Runnable Worktree Recipes +## Protocols -Ready-to-paste blocks per stack. Adjust ports / paths to your project. +Pick by the nature of the work, not its size. Full definitions in `codev/protocols//` +(or the package skeleton). -**pnpm monorepo (Next.js + Turbo style):** -```json -{ - "worktree": { - "symlinks": [".env.local", ".env.development.local", "packages/*/.env", "packages/*/.env.local", "turbo.json"], - "postSpawn": ["pnpm install --frozen-lockfile"], - "devCommand": "pnpm dev" - } -} -``` +| Protocol | Use when | +|---|---| +| **BUGFIX** | A bug in a GitHub issue; isolated fix; no spec/plan needed | +| **AIR** | Small feature fully described in an issue; no architectural decisions | +| **PIR** | The approach needs review before coding, **or** the change must be tested running (mobile, UI, hardware, OAuth) before a PR exists | +| **SPIR** | New feature from scratch, new protocol, architecture change | +| **ASPIR** | SPIR without the spec/plan human gates — trusted, low-risk work | +| **EXPERIMENT** | Proof of concept, model/library evaluation, research spike | +| **MAINTAIN** | Dead code, dependency cleanup, doc sync (arch/lessons, CLAUDE↔AGENTS) | +| **RESEARCH** | Competitive/technology analysis; output to `codev/research/` | -**npm (single package):** -```json -{ - "worktree": { - "symlinks": [".env.local", ".env.development"], - "postSpawn": ["npm ci"], - "devCommand": "npm run dev" - } -} -``` +Skip protocol ceremony for README typos, template one-liners, and dependency bumps. -**yarn:** -```json -{ - "worktree": { - "symlinks": [".env.local"], - "postSpawn": ["yarn install --frozen-lockfile"], - "devCommand": "yarn dev" - } -} -``` +**Issues are the source of truth for tracking.** `spec` and `plan` labels mark approved +artifacts; `porch status ` gives live phase detail; close the issue when the PR merges. -**bun:** -```json -{ - "worktree": { - "symlinks": [".env.local"], - "postSpawn": ["bun install --frozen-lockfile"], - "devCommand": "bun dev" - } -} -``` +### Artifacts -**cargo (Rust):** -```json -{ - "worktree": { - "symlinks": [".env"], - "postSpawn": [], - "devCommand": "cargo run" - } -} -``` +Three documents per feature, same filename in three directories — spec defines **what**, plan +defines **how**, review captures **what was learned**: -**poetry / uv (Python):** -```json -{ - "worktree": { - "symlinks": [".env", ".env.local"], - "postSpawn": ["uv sync"], - "devCommand": "uv run python -m myapp" - } -} ``` - -**go mod:** -```json -{ - "worktree": { - "symlinks": [".env"], - "postSpawn": ["go mod download"], - "devCommand": "go run ./cmd/server" - } -} +codev/specs/42-feature-name.md +codev/plans/42-feature-name.md +codev/reviews/42-feature-name.md ``` -## Architect-Builder Pattern - -The Architect-Builder pattern enables parallel AI-assisted development: -- **Architect** (human + primary AI): Creates specs and plans, reviews work -- **Builders** (autonomous AI agents): Implement specs in isolated git worktrees - -For detailed commands, configuration, and architecture, see: -- `codev/resources/commands/agent-farm.md` - Full CLI reference -- `codev/resources/arch.md` - Terminal architecture, state management -- `codev/resources/workflow-reference.md` - Stage-by-stage workflow - -### 🚨 NEVER DESTROY BUILDER WORKTREES 🚨 - -**When a worktree already exists for a project:** -1. Use `afx spawn XXXX --resume` -2. If `--resume` fails → **ASK THE USER** -3. Only destroy if the user explicitly says to - -**NEVER run without EXPLICIT user request:** -- `git worktree remove` (with or without --force) -- `git branch -D` on builder branches -- `afx cleanup` followed by fresh spawn - -**You are NOT qualified to judge what's expendable.** It is NEVER your call to delete a worktree. - -### 🚨 ALWAYS Operate From the Main Workspace Root 🚨 - -**ALL `afx` commands (`afx spawn`, `afx send`, `afx status`, `afx workspace`, `afx cleanup`) MUST be run from the repository root on the `main` branch.** +Sequential numbering, no leading zeros. Keep specs and plans separate; they answer different +questions. -- **NEVER** run `afx spawn` from inside a builder worktree — builders will get nested inside that worktree, breaking everything -- **NEVER** run `afx workspace start` from a worktree — there is no separate workspace per worktree -- **NEVER** `cd` into a worktree to run afx commands -- The **only exception** is `porch` commands that need worktree context (e.g. `porch approve` from a builder's worktree) +## Issue labels -**What happened**: On 2026-02-21, `afx spawn` was run from inside a builder's worktree. All new builders were nested inside that worktree, `afx send` couldn't find them, and `afx status` showed "not active in tower". Multiple builders had to be killed and respawned. +`area/*` is the **primary organizing axis** — group, audit and bulk-move issues by area first. -### Pre-Spawn Rule +**Exactly one `area/*` per issue.** Multi-area work uses `area/cross-cutting` *alone*. There +are no `type:*` labels. -**Commit all local changes before `afx spawn`.** Builders work in git worktrees branched from HEAD — uncommitted specs, plans, and codev updates are invisible to the builder. The spawn command enforces this (override with `--force`). +`area/`: docs · vscode · dashboard · consult · tower (includes afx; there is no +`area/agent-farm`) · porch · protocols (definitions, distinct from porch orchestration) · +config · terminal · scaffold · release · web · core · cross-cutting -### Key Commands +## Multi-agent consultation -```bash -afx workspace start # Start the workspace -afx spawn 42 --protocol spir # Spawn builder for SPIR project -afx spawn 42 --protocol spir --soft # Spawn builder (soft mode) -afx spawn 42 --protocol bugfix # Spawn builder for a bugfix -afx status # Check all builders -afx cleanup --project 0042 # Clean up (architect-driven, not automatic) -afx open file.ts # Open file in annotation viewer (NOT system open) -``` - -**IMPORTANT:** When the user says `afx open`, always run the `afx open` command — do NOT substitute the system `open` command. - -### Configuration - -Agent Farm is configured via `.codev/config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`. - -## Inter-agent messaging - -Agents within a workspace communicate through `afx send`. Four addressing forms are supported: - -### Addressing forms +**Enabled by default.** Three reviewers: **Gemini** via the Antigravity CLI (`agy`, skips +non-blockingly if unauthenticated), **GPT-5.6 Sol** (`gpt-5.6-sol` — the `-sol` suffix is +load-bearing) via the Codex SDK, and **Claude Opus 5** via the Agent SDK. Disable only when +the user says "without consultation". -| Form | Meaning | Allowed from | -|---|---|---| -| `afx send "msg"` | Send to a specific builder (e.g. `afx send 0823 "..."`). | Any sender. | -| `afx send architect "msg"` | From a builder: routes to the spawning architect via affinity (per #774). From an architect (or any non-builder sender): routes to the architect named `main` if present, else the first registered architect. | Any sender. | -| `afx send architect: "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect. This is the sibling-architect messaging form. **Builders**: allowed ONLY when `` matches the builder's own `spawnedByArchitect`. Mismatches are rejected by the spoofing check at `tower-messages.ts:213-218`. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). | -| `afx send :architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. | +Consult after writing implementation code and after writing tests, before presenting results. +**"cmap"** means run all three in parallel *in the background* and return control immediately. -### Sibling-architect messaging +## Git -When a workspace hosts more than one architect (added via `afx workspace add-architect --name `), sibling architects message each other via the `architect:` form. Example: +Commit messages: -```bash -# From main's terminal to a sibling architect named ob-refine -afx send architect:ob-refine "PR-iter-2 feedback ready" -``` - -This works because sender = architect bypasses the spoofing check. - -### Builder spoofing-check (verified at `tower-messages.ts:213-218`) - -Builder `spir-823` running `afx send architect:ob-refine "..."` is rejected unless its `spawnedByArchitect == 'ob-refine'`. A builder cannot use `architect:` to address an architect other than its spawning architect — that's an attempted spoof. - -### Discovering active agents - -- `afx status` lists all architects (post-#786) alongside builders, with names, terminal IDs, and PIDs where available. -- Each active builder maintains a free-text narrative log at `codev/state/_thread.md` (relative to its worktree, so `.builders//codev/state/_thread.md` from the main workspace root). **In-flight discovery**: `ls .builders/*/codev/state/*.md` and `cat .builders//codev/state/_thread.md`. **Post-merge discovery**: after a builder's PR merges, its thread lands in `codev/state/` on `main`, alongside `codev/reviews/` — list with `ls codev/state/` and read with `cat codev/state/_thread.md` from the main checkout. - -## Porch - Protocol Orchestrator - -Porch drives SPIR, ASPIR, AIR, and BUGFIX protocols via a state machine with phase transitions, gates, and multi-agent consultations. - -### Key Commands - -```bash -porch init spir 0073 "feature-name" --worktree .builders/0073 -porch status 0073 -porch run 0073 -porch approve 0073 spec-approval # Human only -porch pending # List pending gates -``` - -### Project State - -State is stored in `codev/projects/-/status.yaml`, managed automatically by porch. See `codev/resources/protocol-format.md` for protocol definition format. - -## Git Workflow - -### 🚨 ABSOLUTE PROHIBITION: NEVER USE `git add -A` or `git add .` 🚨 - -**THIS IS A CRITICAL SECURITY REQUIREMENT - NO EXCEPTIONS** - -```bash -git add -A # ABSOLUTELY FORBIDDEN -git add . # ABSOLUTELY FORBIDDEN -git add --all # ABSOLUTELY FORBIDDEN -``` - -**MANDATORY APPROACH - ALWAYS ADD FILES EXPLICITLY**: -```bash -git add codev/specs/42-feature.md -git add src/components/TodoList.tsx -``` - -**BEFORE EVERY COMMIT**: Run `git status`, add each file explicitly by name. - -### Commit Messages ``` [Spec 42] Initial specification draft [Spec 42][Phase: user-auth] feat: Add password hashing [Bugfix #42] Fix: URL-encode username before API call ``` -### Branch Naming -``` -spir/42-feature-name/phase-name -builder/bugfix-42-description -``` - -### Pull Request Merging - -**DO NOT SQUASH MERGE** - Always use regular merge commits: -```bash -gh pr merge --merge # CORRECT -``` +Branches: `spir/42-feature-name/phase-name`, `builder/bugfix-42-description`. -Individual commits document the development process. Squashing loses this valuable history. +**Merge PRs with `gh pr merge --merge` — never squash.** Individual commits document the +development process; squashing destroys it. -## Code Metrics +## Working with builders -Use **tokei** for measuring codebase size: `tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .` +Architects create specs and plans and review work; builders implement in isolated worktrees +under `.builders//`. Commit everything before `afx spawn` — builders branch from HEAD, so +uncommitted work is invisible to them. -## Before Starting ANY Task +Agents message each other with `afx send`: -### ALWAYS Check for Existing Work First - -**BEFORE writing ANY code, run these checks:** - -```bash -# Check if there's already a PR for this -gh pr list --search "XXXX" - -# Check GitHub Issues for status -gh issue list --search "XXXX" +| Form | Meaning | +|---|---| +| `afx send "…"` | A specific builder | +| `afx send architect "…"` | From a builder: its spawning architect. From anyone else: the architect named `main`, else the first registered | +| `afx send architect: "…"` | A named architect. Architects may address any architect; a **builder may only use this for its own spawning architect** — mismatches are rejected as spoofing | +| `afx send :architect "…"` | Cross-workspace | -# Check if implementation already exists -git log --oneline --all | grep -i "feature-name" -``` +`afx send` requires the workspace active in Tower (`afx workspace start`). -**If existing work exists**: READ it first, TEST if it works, IDENTIFY specific bugs, FIX minimally. +Each builder keeps a narrative log at `codev/state/_thread.md` — in-flight at +`.builders//codev/state/`, and on `main` after the PR merges. -### When Stuck: STOP After 15 Minutes +## Tooling -**If you've been debugging the same issue for 15+ minutes:** -1. **STOP coding immediately** -2. **Consult external models** (GPT-5, Gemini) with specific questions -3. **Ask the user** if you're on the right path -4. **Consider simpler approaches** - you're probably overcomplicating it +Each CLI has a skill carrying its commands and flags — **check the skill before running the +command rather than guessing**: `afx` (spawn, status, send, dev, cleanup, Tower), +`codev` (init, adopt, update, doctor, local build/test), `porch` (status, run, approve), +`consult` (reviews, cmap, stats), `runnable-worktrees` (making builder +worktrees runnable), `update-arch-docs`. -**Warning signs you're in a rathole:** -- Making incremental fixes that don't work -- User telling you you're overcomplicating it (LISTEN TO THEM) -- Trying multiple approaches without understanding why none work -- Not understanding the underlying technology +`afx open ` opens the annotation viewer — it is not the system `open`. -### Understand Before Coding +**Run anything slower than ~5s in the background** (`run_in_background: true`, not a trailing +`&`): tests, consultations, installs, e2e suites. -**Before implementing, you MUST understand:** -1. **The protocol/API** - Read docs, don't guess -2. **The module system** - ESM vs CommonJS vs UMD vs globals -3. **What already exists** - Check the codebase and git history -4. **The spec's assumptions** - Verify they're actually true +Configuration lives in `.codev/config.json`. -## Important Notes +## Testing -1. **ALWAYS check `codev/protocols/spir/protocol.md`** for detailed phase instructions -2. **Use provided templates** from `codev/protocols/spir/templates/` -3. **Document all deviations** from the plan with reasoning -4. **Create atomic commits** for each phase completion -5. **Maintain >90% test coverage** where possible +UI changes (tower, dashboard, terminal) must be verified in a browser via Playwright before +being called done — see `codev/resources/testing-guide.md`. ---- +## Releasing -*Remember: Context drives code. When in doubt, write more documentation rather than less.* +Say "Let's release v1.6.0"; the RELEASE protocol (`codev/protocols/release/protocol.md`) +carries the procedure. diff --git a/CLAUDE.md b/CLAUDE.md index 916f75dee..8e99f4c5e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,170 +16,69 @@ map to open the full arch.md / lessons-learned.md when relevant. -> **Always-on governance docs (Spec 987 — hot/cold tiers).** The block above is **auto-generated** from the HOT tier (`codev/resources/arch-critical.md` and `lessons-critical.md`) and refreshed by `codev init` / `codev update` — edit those source files, not the block. Each hot file is tiny, hard-capped, and injected into *every* porch phase prompt as well as here, so the most decision-relevant facts are always in context. Their full COLD counterparts (`codev/resources/arch.md` and `lessons-learned.md`) are the on-demand reference archives; the "consult when…" maps in the hot files point into them. New facts/lessons are **routed** by tier at review time and policed (cap + map accuracy) during MAINTAIN. +> The block above is **auto-generated** from the hot tier by `codev init` / `codev update` — +> edit those source files, not the block. Their COLD counterparts (`codev/resources/arch.md`, +> `lessons-learned.md`) are on-demand archives; the "consult when…" maps point into them. +> New facts are **routed** by tier at review time and policed during MAINTAIN. -> **Note**: This file is specific to Claude Code. An identical [AGENTS.md](AGENTS.md) file is also maintained following the [AGENTS.md standard](https://agents.md/) for cross-tool compatibility with Cursor, GitHub Copilot, and other AI coding assistants. Both files contain the same content and should be kept synchronized. +> **[AGENTS.md](AGENTS.md) is a byte-identical twin of this file** for tools that read the +> [AGENTS.md standard](https://agents.md/). Any edit here must be applied there. -## Project Context +## This repository is Codev, built with Codev -**THIS IS THE CODEV SOURCE REPOSITORY - WE ARE SELF-HOSTED** +Two trees, and the distinction governs almost every change: -This project IS Codev itself, and we use our own methodology for development. All new features and improvements to Codev should follow the SPIR protocol defined in `codev/protocols/spir/protocol.md`. - -### Important: Understanding This Repository's Structure - -This repository has a dual nature that's important to understand: - -1. **`codev/`** - This is OUR instance of Codev - - This is where WE (the Codev project) keep our specs, plans, reviews, and resources - - When working on Codev features, you work in this directory - - Example: `codev/specs/1-test-infrastructure.md` is a feature spec for Codev itself - -2. **`codev-skeleton/`** - This is the template for OTHER projects - - This is what gets copied to other projects when they install Codev - - Contains the protocol definitions, templates, and agents - - Does NOT contain specs/plans/reviews (those are created by users) - - Think of it as "what Codev provides" vs "how Codev uses itself" - -**When to modify each**: -- **Modify `codev/`**: When implementing features for Codev (specs, plans, reviews, our architecture docs) -- **Modify `codev-skeleton/`**: When updating protocols, templates, or agents that other projects will use - -### Release Process - -To release a new version, tell the AI: `Let's release v1.6.0`. The AI follows the **RELEASE protocol** (`codev/protocols/release/protocol.md`). Release candidate workflow and local testing procedures are documented there. For local testing shortcuts, see `codev/resources/testing-guide.md`. - -### Local Build Testing - -To test changes locally before publishing to npm: - -```bash -# From the repository root: - -# 1. Build (Tower stays up during this) -pnpm build - -# 2. Pack, install globally, and restart Tower (one command) -pnpm -w run local-install -``` - -- `pnpm build` builds artifact-canvas (needed by the VS Code extension, not part of codev's dependency closure), then the codev CLI; codev's own build script first builds its graph-derived workspace-dependency closure (types, sdk, core, dashboard) via `pnpm --filter "@cluesmith/codev^..." build` -- `pnpm -w run local-install` runs `scripts/local-install.sh`, which: - - Packs the `@cluesmith/codev-core`, `@cluesmith/codev-sdk`, and `@cluesmith/codev` tarballs into their package directories - - Globally installs all three in one `npm install -g` (separate installs fail because `@cluesmith/codev-core` isn't on the public npm registry) - - Restores the executable bit on `scripts/forge/**/*.sh` (pnpm pack strips it, causing "GitHub CLI unavailable" errors otherwise) - - Restarts Tower so it picks up the new code -- Install runs while Tower is up — only the final restart causes downtime -- Do NOT stop Tower yourself before running the script — the script handles restart at the end -- Do NOT use `npm link` or `pnpm link` — it breaks global installs - -### Testing - -When making changes to UI code (tower, dashboard, terminal), you MUST test using Playwright before claiming the fix works. See `codev/resources/testing-guide.md` for Playwright patterns and Tower regression prevention. - -## Quick Start - -> **New to Codev?** See the [Cheatsheet](codev/resources/cheatsheet.md) for philosophies, concepts, and tool reference. - -You are working in the Codev project itself, with multiple development protocols available: - -**Available Protocols**: -- **SPIR**: Multi-phase development with consultation - `codev/protocols/spir/protocol.md` -- **ASPIR**: Autonomous SPIR (no human gates on spec/plan) - `codev/protocols/aspir/protocol.md` -- **AIR**: Autonomous Implement & Review for small features - `codev/protocols/air/protocol.md` -- **BUGFIX**: Bug fixes from GitHub issues - `codev/protocols/bugfix/protocol.md` -- **PIR**: Plan / Implement / Review — issue-driven with two pre-PR human gates (plan-approval, dev-approval) plus a post-PR `pr` gate. Lighter than SPIR; stronger than BUGFIX/AIR. Useful when a change needs design review before coding OR pre-PR testing of running code (e.g., mobile / UI / cross-platform). See `codev/protocols/pir/protocol.md`. -- **EXPERIMENT**: Disciplined experimentation - `codev/protocols/experiment/protocol.md` -- **MAINTAIN**: Codebase maintenance (code hygiene + documentation sync) - `codev/protocols/maintain/protocol.md` -- **RESEARCH**: Multi-agent research with 3-way investigation, synthesis, and critique - `codev/protocols/research/protocol.md` - -### File Resolution (How Codev Finds Protocols and Templates) - -Codev resolves protocol files, prompts, agent definitions, and roles through a four-tier lookup (highest priority first): - -1. `.codev/` — user override (project-local customization) -2. `codev/` — project-local copy (customized and checked in) -3. Runtime cache -4. **Installed package skeleton** — ships with `@cluesmith/codev` (the default for every standard protocol) - -**The absence of `codev/protocols//` on disk is not a missing reference** — it's the normal case for any protocol you haven't customized. The protocol resolves from the installed package's skeleton at runtime. Only protocols you want to customize need to live in your repo's `codev/protocols/`. - -**Implication for `codev update` and CLAUDE.md / AGENTS.md merges:** when an updated template references a protocol (e.g., PIR), do NOT drop the reference because `codev/protocols//` is absent locally. The protocol resolves via the package skeleton, and dropping the reference removes the protocol from the user's available-protocol list while it's still callable from the CLI. - -### Framework files in prompts: deliver them, don't make the builder read them by path - -Framework files (protocol/role docs, the shipped `codev/resources/` reference docs) default to the package skeleton (see File Resolution above) and aren't guaranteed on disk in a fresh project. So when authoring any builder-facing prompt, role doc, or instruction, don't tell the builder to read a framework file by literal `codev/...` path — that bypasses the resolver and fails in fresh installs. Deliver the content instead (`protocol.md` is inlined into the spawn prompt; per-phase prompts and their templates arrive via porch). Mentioning a `codev/...` path in prose for orientation is fine — the rule is about *fetching*, not *referencing*. (`codev/resources/arch.md` and `codev/resources/lessons-learned.md` are user-evolved files, not framework files, so referencing those by path is correct.) +| Tree | What it is | When you edit it | +|---|---|---| +| `codev/` | **Our** instance — our specs, plans, reviews, resources | Implementing a feature *for* Codev | +| `codev-skeleton/` | The **template shipped to adopters** — protocols, roles, templates, agents | Changing what other projects receive | -### Protocol Verification (When You Don't Recognize a Protocol Name) +A framework change usually belongs in **both**. `codev-skeleton/` carries no specs or +plans — those are created by the projects that install it. -If the user mentions a protocol name you don't immediately recognize, verify against the CLI before responding: +### How framework files resolve -```bash -afx spawn --protocol --help -``` +Protocols, prompts, roles and templates resolve at **runtime** through four tiers, highest +first: `.codev/` → `codev/` → runtime cache → **installed package skeleton**. -This succeeds if the protocol is registered (including via the skeleton fallback in tier 4 of the resolution chain) and errors helpfully otherwise. The CLI is the source of truth — defer to it when in doubt. +The absence of `codev/protocols//` is normal, not a missing reference — it means the +protocol resolves from the installed package. Only protocols you customize need a local copy. +When `codev update` merges a template that references a protocol you don't have locally, keep +the reference. -Key locations: -- Protocol details: `codev/protocols/` (Choose appropriate protocol) -- **Project tracking**: GitHub Issues (source of truth for all projects) -- Specifications go in: `codev/specs/` -- Plans go in: `codev/plans/` -- Reviews go in: `codev/reviews/` +**Deliver framework content; don't instruct an agent to fetch it by path.** A builder-facing +prompt or role doc must not say "read `codev/protocols/…`" — that bypasses the resolver and +fails in fresh installs. `protocol.md` is inlined into the spawn prompt; phase prompts and +their templates arrive via porch. Naming a `codev/...` path in prose for orientation is fine; +the rule is about *fetching*. (`codev/resources/arch.md` and `lessons-learned.md` are +user-evolved files, not framework files — referencing those by path is correct.) -### Project Tracking +Verify an unfamiliar protocol against the CLI rather than assuming: `afx spawn --protocol + --help` succeeds if it is registered, including via the skeleton fallback. -**GitHub Issues are the source of truth for project tracking.** +## Irreversible acts — the rules that exist because something was destroyed -- Issues with the `spec` label have approved specifications -- Issues with the `plan` label have approved plans -- Active builders are tracked via `codev/projects//status.yaml` (managed by porch) -- The workspace overview Work view shows builders, PRs, and backlog derived from GitHub + filesystem state +These are not style preferences. Each one is here because an agent destroyed work or bypassed +a human decision. -**When to use which:** -- **Starting work**: Check GitHub Issues for priorities and backlog -- **During implementation**: Use `porch status ` for detailed phase status -- **After completion**: Close the GitHub Issue when PR is merged +- Never `git add -A` / `--all` / `.` — stage each file explicitly by path. +- Never destroy builder worktrees (`git worktree remove`, `git branch -D` on builder branches, `afx cleanup` + respawn). Use `afx spawn --resume`; if it fails, ask the human — what is expendable is never your call. +- Never run `git reset --hard`, `git checkout -- .`, `git clean -fd`, or `git stash` without explicit human permission — they destroy uncommitted work. +- Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization. +- Never hand-edit `status.yaml` — only porch commands modify project state. +- Run `afx` commands only from the main workspace root, never from inside a builder worktree — spawning from a worktree nests builders and breaks the workspace. +- Never kill a shellper process without verifying it is an orphan (match each PID to its workspace via Tower) — an 'extra' shellper may be a live architect session. +- Never restart or stop Tower without explicit human permission — it kills every running builder session. -### Area Labels — the organizing axis for issues +## Gates -`area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. +Two human approval gates plus the PR gate. Only a human transitions +`conceived → specified` and `committed → integrated`. Stop and wait at each; do not infer +approval from silence. -**Labels**: +**Approved specs and plans need frontmatter and must be committed to `main` before spawning.** +Porch runs the full protocol from `specify`, but treats an artifact carrying this as done: -| Label | Scope | -|---|---| -| `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | -| `area/vscode` | VSCode extension — sidebar views, panel-area views, commands, keybindings | -| `area/dashboard` | Tower web dashboard — the `@cluesmith/codev-web` React/Vite package, served by Tower and opened in a browser (distinct from any VSCode UI) | -| `area/consult` | `consult` CLI and consultation tooling | -| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | -| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | -| `area/porch` | Porch state machine / protocol orchestration | -| `area/protocols` | Protocol definitions (`codev/protocols/`, `codev-skeleton/protocols/`) — distinct from `area/porch` (orchestration) | -| `area/config` | `.codev/config.json` and workspace setup | -| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | -| `area/scaffold` | Install path — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, the four-tier resolver | -| `area/release` | Release tooling — version bumps, release protocol artifacts, release scripts | -| `area/web` | Marketing site / web content — the `marketing/` directory | -| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`, `packages/types`) | - -**Policy:** - -- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. -- **No `type:*` labels.** Codev classifies issues by area only. -- `area/` uses **slash**. Other label families (if ever introduced) would keep colons. - -**🚨 CRITICAL: Two human approval gates exist:** -- **conceived → specified**: AI creates spec, but ONLY the human can approve it -- **committed → integrated**: AI can merge PRs, but ONLY the human can validate production - -AI agents must stop at `conceived` after writing a spec, and stop at `committed` after merging. - -**🚨 CRITICAL: Approved specs/plans need YAML frontmatter and must be committed to `main`.** -When the architect creates and approves a spec or plan before spawning a builder, it must have YAML frontmatter marking it as approved and validated, and be committed to `main`. Porch always runs the full protocol from `specify` — but when it finds an existing artifact with this metadata, it skips that phase as a no-op. If no spec/plan exists, porch drives the builder to create one. - -Frontmatter format: ```yaml --- approved: 2026-01-29 @@ -187,555 +86,118 @@ validated: [gemini, codex, claude] --- ``` -## Agent Responsiveness - -**Responsiveness is paramount.** The user should never wait for you. Use `run_in_background: true` for any operation that takes more than ~5 seconds. - -| Task Type | Expected Duration | Action | -|-----------|------------------|--------| -| Running tests | 10-300s | `run_in_background: true` | -| Consultations (consult) | 60-250s | `run_in_background: true` | -| E2E test suites | 60-600s | `run_in_background: true` | -| pnpm install/build | 5-60s | `run_in_background: true` | -| Quick file reads/edits | <5s | Run normally | - -**Critical**: Using `&` at the end of the command does NOT work - you MUST set the `run_in_background` parameter. - -## Protocol Selection Guide - -### Use BUGFIX for (GitHub issue fixes): -- Bug reported as a **GitHub Issue** -- Fix is isolated (< 300 LOC net diff) -- No spec/plan artifacts needed -- Single builder can fix independently - -**BUGFIX uses GitHub Issues as source of truth.** See `codev/protocols/bugfix/protocol.md`. - -### Use AIR for (small features from GitHub issues): -- Small features (< 300 LOC) fully described in a **GitHub Issue** -- No architectural decisions needed -- No spec/plan artifacts — review goes in the PR body -- Would be overkill for full SPIR/ASPIR ceremony - -**AIR uses GitHub Issues as source of truth.** Two phases: Implement → Review. See `codev/protocols/air/protocol.md`. - -### Use PIR for (engineer-judged — based on the nature of the work, not its size): - -Pick PIR when ONE or BOTH of the following apply to a GitHub-issue-driven change: - -**1. The approach needs review before coding starts**: -- Root cause is ambiguous; multiple valid fixes exist -- Area is unfamiliar or high-blast-radius (shared utilities, auth, migrations, public APIs) -- Design-sensitive (affects conventions, patterns, architecture) -- Cheaper to redirect at plan time than at PR time - -**2. The implementation needs to be TESTED before a PR is created** (PR diff alone is insufficient): -- Mobile app changes (needs device testing on Android, iOS, possibly web) -- UI / UX changes (visual inspection, interaction flow, accessibility) -- Hardware-adjacent behavior (sensors, camera, permissions, notifications) -- Integration with external services that don't mock cleanly (OAuth, payments, analytics) -- User-journey changes that need a full-flow exercise -- Performance-sensitive changes that need profiling on the running app - -**PIR uses GitHub Issues as source of truth.** Three phases: Plan (gated by `plan-approval`) → Implement (gated by `dev-approval`) → Review (PR + CMAP-2 at PR, then gated by `pr` for merge synchronization — matching SPIR's pr-gate pattern but with no post-merge verify phase). Plan and review artifacts live in `codev/plans/` and `codev/reviews/` on the builder branch, ship to main with the merge. Review file is shaped identically to SPIR's (Summary + Architecture Updates + Lessons Learned + supporting sections) so `codev/reviews/` stays semantically consistent across protocols. Lighter than SPIR (no spec phase — the issue body is the implicit spec; consult footprint matches BUGFIX/AIR's "one consult at PR" pattern). Stronger than BUGFIX/AIR (two human gates pre-PR — the human reviews the running worktree at the `dev-approval` gate, not the PR diff post-creation). CMAP at the PR is a **single advisory pass** (`max_iterations: 1`) — no iterate-until-APPROVE loop; a `REQUEST_CHANGES` is escalated to the human at the `pr` gate, not auto-re-reviewed. The CMAP-2 footprint is a design invariant: porch's model precedence is *config > protocol*, so a project-wide `porch.consultation.models` (e.g. a SPIR-tuned 3-model list) silently inflates PIR — leave it unset or scope it per-protocol to preserve the BUGFIX/AIR-parity cost. See `codev/protocols/pir/protocol.md`. - -### Use SPIR for (new features): -- Creating a **new feature from scratch** (no existing spec to amend) -- New protocols or protocol variants -- Major changes to existing protocols -- Complex features requiring multiple phases -- Architecture changes - -### Use ASPIR for (autonomous SPIR): -- Same as SPIR but **without human approval gates** on spec and plan -- Trusted, low-risk work where spec/plan review can be deferred to PR -- Builder runs autonomously through Specify → Plan → Implement → Review (→ Verify) -- Human approval still required at the PR gate before merge - -**ASPIR is identical to SPIR** except `spec-approval` and `plan-approval` gates are removed. Both include an optional verify phase after review. See `codev/protocols/aspir/protocol.md`. - -### Use EXPERIMENT for: -- Testing new approaches or techniques -- Evaluating models or libraries -- Proof-of-concept work -- Research spikes - -### Use MAINTAIN for: -- Removing dead code and unused dependencies -- Quarterly codebase maintenance -- Before releases (clean slate for shipping) -- Syncing documentation (arch.md/arch-critical.md, lessons-learned.md/lessons-critical.md, CLAUDE.md/AGENTS.md) - -### Use RESEARCH for: -- Competitive analysis and technology evaluation -- Market research and "state of X" questions -- Architectural decision support when unfamiliar with the domain -- Triangulating across 3 AI models to get a high-confidence answer -- Output goes to `codev/research/.md` - -### Skip formal protocols for: -- README typos or minor documentation fixes -- Small bug fixes in templates -- Dependency updates - -## Core Workflow - -1. **When asked to build NEW FEATURES FOR CODEV**: Start with the Specification phase -2. **Create exactly THREE documents per feature**: spec, plan, and review (all with same filename) -3. **Follow the SPIR phases**: Specify → Plan → Implement → Review (→ Verify) -4. **Use multi-agent consultation by default** unless user says "without consultation" - -## Directory Structure -``` -project-root/ -├── codev/ -│ ├── protocols/ # Development protocols -│ │ ├── spir/ # Multi-phase development with consultation -│ │ ├── experiment/ # Disciplined experimentation -│ │ └── maintain/ # Codebase maintenance (code + docs) -│ ├── maintain/ # MAINTAIN protocol runtime artifacts -│ │ └── .trash/ # Soft-deleted files (gitignored, 30-day retention) -│ ├── projects/ # Active project state (managed by porch) -│ ├── specs/ # Feature specifications (WHAT to build) -│ ├── plans/ # Implementation plans (HOW to build) -│ ├── reviews/ # Reviews and lessons learned from each feature -│ └── resources/ # Reference materials -│ ├── arch.md # Architecture (COLD reference; maintained during MAINTAIN) -│ ├── arch-critical.md # Architecture HOT tier — capped, always-injected (Spec 987) -│ ├── testing-guide.md # Local testing, Playwright, regression prevention -│ ├── lessons-learned.md # Engineering wisdom (COLD reference; maintained during MAINTAIN) -│ └── lessons-critical.md # Engineering wisdom HOT tier — capped, always-injected (Spec 987) -├── .claude/ -│ ├── agents/ # AI agent definitions (custom project agents) -│ └── skills/ # Claude-native Codev skills -├── .codex/ -│ └── skills/ # Codex-native Codev skills -├── AGENTS.md # Universal AI agent instructions (AGENTS.md standard) -├── CLAUDE.md # This file (Claude Code-specific, identical to AGENTS.md) -└── [project code] -``` - -## Directory Map -- pnpm install → always run from the repository root (installs all workspace packages) -- pnpm build / pnpm test → run from `packages/codev/` or use `pnpm --filter @cluesmith/codev build` (the build script first builds codev's workspace deps via the graph-derived `pnpm --filter "@cluesmith/codev^..." build` closure, so a missing or stale dep `dist/` can't surface as false TS errors in codev's own sources) -- E2E tests → `packages/codev/tests/e2e/` -- Unit tests → `packages/codev/tests/unit/` -- Never run npm commands from the repository root unless explicitly told to. - -## File Naming Convention - -Use sequential numbering with descriptive names (no leading zeros): -- Specification: `codev/specs/42-feature-name.md` -- Plan: `codev/plans/42-feature-name.md` -- Review: `codev/reviews/42-feature-name.md` - -**CRITICAL: Keep Specs and Plans Separate** -- Specs define WHAT to build (requirements, acceptance criteria) -- Plans define HOW to build (phases, files to modify, implementation details) -- Each document serves a distinct purpose and must remain separate - -## Multi-Agent Consultation - -**DEFAULT BEHAVIOR**: Consultation is ENABLED by default with: -- **Gemini** via the **Antigravity CLI (`agy`)** for deep analysis (the retired Gemini CLI's - replacement; OAuth/subscription, agy's default model — no pinned model id). Skips non-blockingly - if `agy` is missing/unauthenticated. An unauthenticated `agy` is spawned **at most once per TTL - window** rather than once per consult: the verdict is cached across processes in - `~/.cache/codev/agy-auth.json`, because each spawn opens an OAuth browser tab before Codev can - detect the missing login (#1077). Sign in with `agy` in any terminal and the lane recovers on its - own; see `codev/resources/commands/consult.md` for the TTL/opt-out env vars. -- **GPT-5.6 Sol** (`gpt-5.6-sol`, medium reasoning effort) via the Codex SDK for coding and - architecture perspective. The `-sol` suffix is load-bearing — plain `gpt-5.6` and - `gpt-5.6-codex` are both rejected by Codex on a ChatGPT account. -- **Claude Opus 5** (`claude-opus-5`) via the Claude Agent SDK for balanced analysis with tool use - -To disable: User must explicitly say "without multi-agent consultation" - -**CRITICAL CONSULTATION CHECKPOINTS (DO NOT SKIP):** -- After writing implementation code → STOP → Consult GPT-5 and Gemini (via agy) -- After writing tests → STOP → Consult GPT-5 and Gemini (via agy) -- ONLY THEN present results to user for evaluation - -### cmap (Consult Multiple Agents in Parallel) - -**cmap** is shorthand for "consult multiple agents in parallel in the background." - -When the user says **"cmap the PR"** or **"cmap spec 42"**, this means: -1. Run a 3-way parallel review (Gemini, Codex, Claude) -2. Run all three in the **background** (`run_in_background: true`) -3. Return control to the user **immediately** -4. Retrieve results later with `TaskOutput` when needed - -**Always run consultations in parallel** using separate Bash tool calls in the same message, not sequentially. - -## CLI Command Reference - -**IMPORTANT: Never guess CLI commands.** Use the `/afx` skill to check the quick reference before running agent farm commands. Common mistakes to avoid: -- There is NO `codev tower` command — use `afx tower start` / `afx tower stop` -- There is NO `restart` subcommand — stop then start -- When unsure about syntax, check the docs below first - -Codev provides five CLI tools. For complete reference documentation, see: - -- **[Overview](codev/resources/commands/overview.md)** - Quick start and summary of all tools -- **[codev](codev/resources/commands/codev.md)** - Project management (init, adopt, doctor, update, tower) -- **[afx](codev/resources/commands/agent-farm.md)** - Agent Farm orchestration (start, spawn, status, cleanup, send, etc.) -- **[porch](codev/resources/commands/overview.md#porch---protocol-orchestrator)** - Protocol orchestrator (status, run, approve, pending) -- **[consult](codev/resources/commands/consult.md)** - AI consultation (general, protocol, stats) -- **[team](codev/resources/commands/team.md)** - Team coordination (list, message, update, add) - -## Runnable Worktrees - -When configured, each builder worktree (`.builders//`) becomes runnable — reviewers can run whatever your dev command starts against the builder's branch — a dev server, `cargo run`, `expo start`, a test watcher, a build script, whatever iterates on your project — without `cd`'ing, manually installing, or finding the right command. Opt-in via `.codev/config.json`; unconfigured repos see zero behavior change. - -### Config: the `worktree` block - -```jsonc -{ - "worktree": { - "symlinks": ["..."], // glob patterns of files to symlink from root into each new worktree - "postSpawn": ["..."], // shell commands run inside each new worktree after createWorktree - "devCommand": "..." // consumed by `afx dev ` - } -} -``` - -- `symlinks`: globs resolve from the workspace root; matches symlink into the worktree at the same relative path. Root `.env` and `.codev/config.json` are *always* symlinked regardless. **Symlinks, not copies** — edits to main's env files reflect instantly in any running dev session. A directory match is silently skipped (so a glob can't mask the worktree's own source) **unless** the entry ends with a trailing slash: `".local-user-data/"` is treated as a literal path and symlinks the directory whole (shared with the parent, not branch-isolated; a dangling link is fine if the source doesn't exist yet). -- `postSpawn`: each command runs sequentially with `cwd` = worktree path. Non-zero exit aborts the spawn loud (half-built worktree stays for inspection). -- `devCommand`: the foreground command that starts your dev process (a server, a watcher, `cargo run`, `expo start`, a build script — whatever iterates on your project). Required for `afx dev` to work. - -**Codev does not auto-detect your stack.** Pick the recipe below that matches your toolchain. - -### CLI - -```bash -afx dev # start dev in 's worktree -afx dev main # start dev in the MAIN workspace (Codev-managed) -afx dev --stop # stop the currently running dev PTY (builder or main) -``` - -Only one dev PTY runs at a time (by design — see "URLs are load-bearing" below), across **{main + all builders}**. `main` is a reserved target: it runs `worktree.devCommand` in the main checkout as a Codev-managed, swappable PTY, symmetric with builders. Starting any target while another is up prompts for swap (`afx dev ` while `main` runs, or vice-versa); same-target requests print the existing terminal URL and exit. Like builder dev, main dev is a **non-persistent** PTY — a Tower restart (`pnpm -w run local-install`, crash) kills it; re-run to restart. - -**Launch main dev via `afx dev main`, not a bare `pnpm dev`.** A manually-run `pnpm dev` at the repo root is invisible to Codev (the deliberate "never kill what it didn't spawn" policy) — start a builder dev while it holds the ports and the builder dev silently fails to bind, or worse serves main's code under the worktree URL. `afx dev main` makes it a managed PTY that swap-detection can cleanly stop first. This only helps if you use it *consistently*; a hand-started `pnpm dev` stays unmanaged. - -### VSCode - -The same actions are available via right-click on any builder row in the Codev sidebar (Builders or Needs Attention view): - -- **Codev: Open Builder Terminal** — opens that builder's AI terminal in a VSCode tab (same as left-clicking the row). -- **Codev: Open Worktree Folder** — opens `.builders//` in the OS file manager (Finder on macOS, Explorer on Windows, xdg-open on Linux). -- **Codev: Run Worktree Setup** — applies the configured `worktree.symlinks` and runs the `worktree.postSpawn` commands against the existing worktree (mirrors what spawn does, minus the git steps). Idempotent: existing symlinks are skipped, missing ones added. Useful when the lockfile changed (reinstall deps), `symlinks` or `postSpawn` was extended after the builder spawned, a symlink was accidentally deleted, or the original setup aborted mid-run. Opens a fresh VSCode terminal so install output streams live. Available via CLI too: `afx setup `. -- **Codev: View Diff** — opens a single unified diff editor for `main...HEAD` of that builder's worktree, with a file-list pane on the left (matches VSCode's built-in Source Control "Working Tree" view). Status icons indicate added / modified / deleted. Empty diff → friendly toast. -- **Codev: Run Dev** — reads `worktree.devCommand` from `.codev/config.json`, asks Tower to spawn a dev PTY in the builder's worktree, and opens it as a VSCode terminal tab named `Codev: (dev)`. If another builder's dev is already running, you get a modal asking whether to swap. -- **Codev: Stop Dev** — kills the running dev PTY and closes its tab. - -The Codev sidebar's **Workspace** view also carries a dev control for *whatever folder this VSCode window is rooted at* (it is not "main"-specific): - -- **Start Dev** — runs `worktree.devCommand` for the current workspace. Target is resolved from the open folder: the main checkout → `main`; a `.builders//` worktree opened as its own window (e.g. via *Open Worktree as Workspace*) → that builder. Same single-slot swap model as builder dev (prompts if another dev is running). The row tooltip names the resolved target. -- **Stop Dev** — stops this workspace's dev; the row appears only while it is running. Scoped to the resolved target — it does not touch other devs. - -The three commands are also available from the command palette (Cmd+Shift+P). No default keybindings; bind via `keybindings.json` if you use them often. - -### URLs are load-bearing - -The dev PTY uses **the same ports and URLs as main** intentionally. OAuth callbacks, CORS allowlists, cookie scoping, CSP `connect-src`, webhook URLs are all keyed off origin — running the worktree on a different port would break them. Consequence: stop main's `pnpm dev` before `afx dev`. If you don't, the spawned dev fails at bind time with its own `EADDRINUSE`. Prefer `afx dev main` (or the Workspace view's *Start Dev* row) over a hand-run `pnpm dev` so Codev owns the PTY and swap-detection can stop it for you automatically. - -### Cleanup semantics - -`afx dev --stop` and the swap path kill the entire PTY process group (SIGTERM, escalating to SIGKILL after 5s via `PtySession.kill`). That signals every grandchild of a monorepo dev orchestrator (`pnpm dev`, `turbo dev`, `pnpm -r --parallel run dev`, etc.) simultaneously. The OS reclaims ports as a consequence — Codev never touches ports directly. - -**Orphan recovery** — if Tower itself hard-crashes mid-dev and a process is left holding a port outside Codev's records: - -```bash -lsof -ti : | xargs kill # one port -lsof -ti :3000,:3001,:4000 | xargs kill # several at once -``` - -### Runnable Worktree Recipes +## Protocols -Ready-to-paste blocks per stack. Adjust ports / paths to your project. +Pick by the nature of the work, not its size. Full definitions in `codev/protocols//` +(or the package skeleton). -**pnpm monorepo (Next.js + Turbo style):** -```json -{ - "worktree": { - "symlinks": [".env.local", ".env.development.local", "packages/*/.env", "packages/*/.env.local", "turbo.json"], - "postSpawn": ["pnpm install --frozen-lockfile"], - "devCommand": "pnpm dev" - } -} -``` +| Protocol | Use when | +|---|---| +| **BUGFIX** | A bug in a GitHub issue; isolated fix; no spec/plan needed | +| **AIR** | Small feature fully described in an issue; no architectural decisions | +| **PIR** | The approach needs review before coding, **or** the change must be tested running (mobile, UI, hardware, OAuth) before a PR exists | +| **SPIR** | New feature from scratch, new protocol, architecture change | +| **ASPIR** | SPIR without the spec/plan human gates — trusted, low-risk work | +| **EXPERIMENT** | Proof of concept, model/library evaluation, research spike | +| **MAINTAIN** | Dead code, dependency cleanup, doc sync (arch/lessons, CLAUDE↔AGENTS) | +| **RESEARCH** | Competitive/technology analysis; output to `codev/research/` | -**npm (single package):** -```json -{ - "worktree": { - "symlinks": [".env.local", ".env.development"], - "postSpawn": ["npm ci"], - "devCommand": "npm run dev" - } -} -``` +Skip protocol ceremony for README typos, template one-liners, and dependency bumps. -**yarn:** -```json -{ - "worktree": { - "symlinks": [".env.local"], - "postSpawn": ["yarn install --frozen-lockfile"], - "devCommand": "yarn dev" - } -} -``` +**Issues are the source of truth for tracking.** `spec` and `plan` labels mark approved +artifacts; `porch status ` gives live phase detail; close the issue when the PR merges. -**bun:** -```json -{ - "worktree": { - "symlinks": [".env.local"], - "postSpawn": ["bun install --frozen-lockfile"], - "devCommand": "bun dev" - } -} -``` +### Artifacts -**cargo (Rust):** -```json -{ - "worktree": { - "symlinks": [".env"], - "postSpawn": [], - "devCommand": "cargo run" - } -} -``` +Three documents per feature, same filename in three directories — spec defines **what**, plan +defines **how**, review captures **what was learned**: -**poetry / uv (Python):** -```json -{ - "worktree": { - "symlinks": [".env", ".env.local"], - "postSpawn": ["uv sync"], - "devCommand": "uv run python -m myapp" - } -} ``` - -**go mod:** -```json -{ - "worktree": { - "symlinks": [".env"], - "postSpawn": ["go mod download"], - "devCommand": "go run ./cmd/server" - } -} +codev/specs/42-feature-name.md +codev/plans/42-feature-name.md +codev/reviews/42-feature-name.md ``` -## Architect-Builder Pattern - -The Architect-Builder pattern enables parallel AI-assisted development: -- **Architect** (human + primary AI): Creates specs and plans, reviews work -- **Builders** (autonomous AI agents): Implement specs in isolated git worktrees - -For detailed commands, configuration, and architecture, see: -- `codev/resources/commands/agent-farm.md` - Full CLI reference -- `codev/resources/arch.md` - Terminal architecture, state management -- `codev/resources/workflow-reference.md` - Stage-by-stage workflow - -### 🚨 NEVER DESTROY BUILDER WORKTREES 🚨 - -**When a worktree already exists for a project:** -1. Use `afx spawn XXXX --resume` -2. If `--resume` fails → **ASK THE USER** -3. Only destroy if the user explicitly says to - -**NEVER run without EXPLICIT user request:** -- `git worktree remove` (with or without --force) -- `git branch -D` on builder branches -- `afx cleanup` followed by fresh spawn - -**You are NOT qualified to judge what's expendable.** It is NEVER your call to delete a worktree. - -### 🚨 ALWAYS Operate From the Main Workspace Root 🚨 - -**ALL `afx` commands (`afx spawn`, `afx send`, `afx status`, `afx workspace`, `afx cleanup`) MUST be run from the repository root on the `main` branch.** +Sequential numbering, no leading zeros. Keep specs and plans separate; they answer different +questions. -- **NEVER** run `afx spawn` from inside a builder worktree — builders will get nested inside that worktree, breaking everything -- **NEVER** run `afx workspace start` from a worktree — there is no separate workspace per worktree -- **NEVER** `cd` into a worktree to run afx commands -- The **only exception** is `porch` commands that need worktree context (e.g. `porch approve` from a builder's worktree) +## Issue labels -**What happened**: On 2026-02-21, `afx spawn` was run from inside a builder's worktree. All new builders were nested inside that worktree, `afx send` couldn't find them, and `afx status` showed "not active in tower". Multiple builders had to be killed and respawned. +`area/*` is the **primary organizing axis** — group, audit and bulk-move issues by area first. -### Pre-Spawn Rule +**Exactly one `area/*` per issue.** Multi-area work uses `area/cross-cutting` *alone*. There +are no `type:*` labels. -**Commit all local changes before `afx spawn`.** Builders work in git worktrees branched from HEAD — uncommitted specs, plans, and codev updates are invisible to the builder. The spawn command enforces this (override with `--force`). +`area/`: docs · vscode · dashboard · consult · tower (includes afx; there is no +`area/agent-farm`) · porch · protocols (definitions, distinct from porch orchestration) · +config · terminal · scaffold · release · web · core · cross-cutting -### Key Commands +## Multi-agent consultation -```bash -afx workspace start # Start the workspace -afx spawn 42 --protocol spir # Spawn builder for SPIR project -afx spawn 42 --protocol spir --soft # Spawn builder (soft mode) -afx spawn 42 --protocol bugfix # Spawn builder for a bugfix -afx status # Check all builders -afx cleanup --project 0042 # Clean up (architect-driven, not automatic) -afx open file.ts # Open file in annotation viewer (NOT system open) -``` - -**IMPORTANT:** When the user says `afx open`, always run the `afx open` command — do NOT substitute the system `open` command. - -### Configuration - -Agent Farm is configured via `.codev/config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`. - -## Inter-agent messaging - -Agents within a workspace communicate through `afx send`. Four addressing forms are supported: - -### Addressing forms +**Enabled by default.** Three reviewers: **Gemini** via the Antigravity CLI (`agy`, skips +non-blockingly if unauthenticated), **GPT-5.6 Sol** (`gpt-5.6-sol` — the `-sol` suffix is +load-bearing) via the Codex SDK, and **Claude Opus 5** via the Agent SDK. Disable only when +the user says "without consultation". -| Form | Meaning | Allowed from | -|---|---|---| -| `afx send "msg"` | Send to a specific builder (e.g. `afx send 0823 "..."`). | Any sender. | -| `afx send architect "msg"` | From a builder: routes to the spawning architect via affinity (per #774). From an architect (or any non-builder sender): routes to the architect named `main` if present, else the first registered architect. | Any sender. | -| `afx send architect: "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect. This is the sibling-architect messaging form. **Builders**: allowed ONLY when `` matches the builder's own `spawnedByArchitect`. Mismatches are rejected by the spoofing check at `tower-messages.ts:213-218`. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). | -| `afx send :architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. | +Consult after writing implementation code and after writing tests, before presenting results. +**"cmap"** means run all three in parallel *in the background* and return control immediately. -### Sibling-architect messaging +## Git -When a workspace hosts more than one architect (added via `afx workspace add-architect --name `), sibling architects message each other via the `architect:` form. Example: +Commit messages: -```bash -# From main's terminal to a sibling architect named ob-refine -afx send architect:ob-refine "PR-iter-2 feedback ready" -``` - -This works because sender = architect bypasses the spoofing check. - -### Builder spoofing-check (verified at `tower-messages.ts:213-218`) - -Builder `spir-823` running `afx send architect:ob-refine "..."` is rejected unless its `spawnedByArchitect == 'ob-refine'`. A builder cannot use `architect:` to address an architect other than its spawning architect — that's an attempted spoof. - -### Discovering active agents - -- `afx status` lists all architects (post-#786) alongside builders, with names, terminal IDs, and PIDs where available. -- Each active builder maintains a free-text narrative log at `codev/state/_thread.md` (relative to its worktree, so `.builders//codev/state/_thread.md` from the main workspace root). **In-flight discovery**: `ls .builders/*/codev/state/*.md` and `cat .builders//codev/state/_thread.md`. **Post-merge discovery**: after a builder's PR merges, its thread lands in `codev/state/` on `main`, alongside `codev/reviews/` — list with `ls codev/state/` and read with `cat codev/state/_thread.md` from the main checkout. - -## Porch - Protocol Orchestrator - -Porch drives SPIR, ASPIR, AIR, and BUGFIX protocols via a state machine with phase transitions, gates, and multi-agent consultations. - -### Key Commands - -```bash -porch init spir 0073 "feature-name" --worktree .builders/0073 -porch status 0073 -porch run 0073 -porch approve 0073 spec-approval # Human only -porch pending # List pending gates -``` - -### Project State - -State is stored in `codev/projects/-/status.yaml`, managed automatically by porch. See `codev/resources/protocol-format.md` for protocol definition format. - -## Git Workflow - -### 🚨 ABSOLUTE PROHIBITION: NEVER USE `git add -A` or `git add .` 🚨 - -**THIS IS A CRITICAL SECURITY REQUIREMENT - NO EXCEPTIONS** - -```bash -git add -A # ABSOLUTELY FORBIDDEN -git add . # ABSOLUTELY FORBIDDEN -git add --all # ABSOLUTELY FORBIDDEN -``` - -**MANDATORY APPROACH - ALWAYS ADD FILES EXPLICITLY**: -```bash -git add codev/specs/42-feature.md -git add src/components/TodoList.tsx -``` - -**BEFORE EVERY COMMIT**: Run `git status`, add each file explicitly by name. - -### Commit Messages ``` [Spec 42] Initial specification draft [Spec 42][Phase: user-auth] feat: Add password hashing [Bugfix #42] Fix: URL-encode username before API call ``` -### Branch Naming -``` -spir/42-feature-name/phase-name -builder/bugfix-42-description -``` - -### Pull Request Merging - -**DO NOT SQUASH MERGE** - Always use regular merge commits: -```bash -gh pr merge --merge # CORRECT -``` +Branches: `spir/42-feature-name/phase-name`, `builder/bugfix-42-description`. -Individual commits document the development process. Squashing loses this valuable history. +**Merge PRs with `gh pr merge --merge` — never squash.** Individual commits document the +development process; squashing destroys it. -## Code Metrics +## Working with builders -Use **tokei** for measuring codebase size: `tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .` +Architects create specs and plans and review work; builders implement in isolated worktrees +under `.builders//`. Commit everything before `afx spawn` — builders branch from HEAD, so +uncommitted work is invisible to them. -## Before Starting ANY Task +Agents message each other with `afx send`: -### ALWAYS Check for Existing Work First - -**BEFORE writing ANY code, run these checks:** - -```bash -# Check if there's already a PR for this -gh pr list --search "XXXX" - -# Check GitHub Issues for status -gh issue list --search "XXXX" +| Form | Meaning | +|---|---| +| `afx send "…"` | A specific builder | +| `afx send architect "…"` | From a builder: its spawning architect. From anyone else: the architect named `main`, else the first registered | +| `afx send architect: "…"` | A named architect. Architects may address any architect; a **builder may only use this for its own spawning architect** — mismatches are rejected as spoofing | +| `afx send :architect "…"` | Cross-workspace | -# Check if implementation already exists -git log --oneline --all | grep -i "feature-name" -``` +`afx send` requires the workspace active in Tower (`afx workspace start`). -**If existing work exists**: READ it first, TEST if it works, IDENTIFY specific bugs, FIX minimally. +Each builder keeps a narrative log at `codev/state/_thread.md` — in-flight at +`.builders//codev/state/`, and on `main` after the PR merges. -### When Stuck: STOP After 15 Minutes +## Tooling -**If you've been debugging the same issue for 15+ minutes:** -1. **STOP coding immediately** -2. **Consult external models** (GPT-5, Gemini) with specific questions -3. **Ask the user** if you're on the right path -4. **Consider simpler approaches** - you're probably overcomplicating it +Each CLI has a skill carrying its commands and flags — **check the skill before running the +command rather than guessing**: `afx` (spawn, status, send, dev, cleanup, Tower), +`codev` (init, adopt, update, doctor, local build/test), `porch` (status, run, approve), +`consult` (reviews, cmap, stats), `runnable-worktrees` (making builder +worktrees runnable), `update-arch-docs`. -**Warning signs you're in a rathole:** -- Making incremental fixes that don't work -- User telling you you're overcomplicating it (LISTEN TO THEM) -- Trying multiple approaches without understanding why none work -- Not understanding the underlying technology +`afx open ` opens the annotation viewer — it is not the system `open`. -### Understand Before Coding +**Run anything slower than ~5s in the background** (`run_in_background: true`, not a trailing +`&`): tests, consultations, installs, e2e suites. -**Before implementing, you MUST understand:** -1. **The protocol/API** - Read docs, don't guess -2. **The module system** - ESM vs CommonJS vs UMD vs globals -3. **What already exists** - Check the codebase and git history -4. **The spec's assumptions** - Verify they're actually true +Configuration lives in `.codev/config.json`. -## Important Notes +## Testing -1. **ALWAYS check `codev/protocols/spir/protocol.md`** for detailed phase instructions -2. **Use provided templates** from `codev/protocols/spir/templates/` -3. **Document all deviations** from the plan with reasoning -4. **Create atomic commits** for each phase completion -5. **Maintain >90% test coverage** where possible +UI changes (tower, dashboard, terminal) must be verified in a browser via Playwright before +being called done — see `codev/resources/testing-guide.md`. ---- +## Releasing -*Remember: Context drives code. When in doubt, write more documentation rather than less.* +Say "Let's release v1.6.0"; the RELEASE protocol (`codev/protocols/release/protocol.md`) +carries the procedure. diff --git a/codev-skeleton/.claude/skills/codev/SKILL.md b/codev-skeleton/.claude/skills/codev/SKILL.md index 9c7a1b7e1..57d6f49c3 100644 --- a/codev-skeleton/.claude/skills/codev/SKILL.md +++ b/codev-skeleton/.claude/skills/codev/SKILL.md @@ -57,3 +57,34 @@ codev doctor - `codev init` creates a new directory — use `codev adopt` for existing projects - Always run `codev adopt` and `codev update` from the project root - `codev update` only updates framework files — it never touches specs/plans/reviews + +## Local build and install (this repository) + +Test changes locally before publishing. Run from the repository root: + +```bash +pnpm build # builds core first, then codev (including dashboard) +pnpm -w run local-install # packs both packages, installs globally, restarts Tower +``` + +`local-install` (`scripts/local-install.sh`) packs `@cluesmith/codev-core` and +`@cluesmith/codev`, installs both in a single `npm install -g` (separate installs fail — +`codev-core` is not on the public registry), restores the executable bit on +`scripts/forge/**/*.sh` that `pnpm pack` strips, and restarts Tower last. Install runs while +Tower is up; only the final restart causes downtime. **Do not stop Tower first**, and do not use +`npm link` / `pnpm link` — it breaks global installs. + +`pnpm build` also runs `copy-skeleton`, which copies `codev-skeleton/` into +`packages/codev/skeleton`. **Tests read that copy**, so after editing anything under +`codev-skeleton/` you must rebuild before the suite reflects your change. + +### Where to run things + +- `pnpm install` — repository root (installs all workspace packages) +- `pnpm build` / `pnpm test` — `packages/codev/`, or `pnpm --filter @cluesmith/codev build` +- Unit tests `packages/codev/tests/unit/` · E2E `packages/codev/tests/e2e/` +- Never run npm commands from the repository root unless told to + +### Measuring code size + +`tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .` diff --git a/codev-skeleton/.claude/skills/runnable-worktrees/SKILL.md b/codev-skeleton/.claude/skills/runnable-worktrees/SKILL.md new file mode 100644 index 000000000..c9163691d --- /dev/null +++ b/codev-skeleton/.claude/skills/runnable-worktrees/SKILL.md @@ -0,0 +1,119 @@ +--- +name: runnable-worktrees +description: Make builder worktrees runnable — the `.codev/config.json` `worktree` block (symlinks, postSpawn, devCommand), the `afx dev` CLI, VSCode dev controls, and per-stack config recipes. Use when configuring a repo so reviewers can run a builder's branch, when `afx dev` fails to bind or start, when a dev process is orphaned holding a port, or when asked why worktree dev uses the same ports as main. +--- + +# Runnable worktrees + +When configured, each builder worktree (`.builders//`) becomes runnable: reviewers can run +whatever your dev command starts — a dev server, `cargo run`, `expo start`, a test watcher, a +build script — against the builder's branch without `cd`'ing, installing, or hunting for the +command. Opt-in via `.codev/config.json`; unconfigured repos see zero behavior change. + +## Config: the `worktree` block + +```jsonc +{ + "worktree": { + "symlinks": ["..."], // globs symlinked from the workspace root into each new worktree + "postSpawn": ["..."], // shell commands run inside each new worktree after createWorktree + "devCommand": "..." // consumed by `afx dev ` + } +} +``` + +- **`symlinks`** — globs resolve from the workspace root and link into the worktree at the same + relative path. Root `.env` and `.codev/config.json` are *always* symlinked regardless. + **Symlinks, not copies**, so edits to main's env files reflect instantly in a running dev + session. A directory match is silently skipped (a glob cannot mask the worktree's own source) + **unless** the entry ends in a slash: `".local-user-data/"` is treated as a literal path and + links the directory whole — shared with the parent, not branch-isolated. A dangling link is + fine if the source does not exist yet. +- **`postSpawn`** — commands run sequentially with `cwd` = worktree path. A non-zero exit aborts + the spawn loudly; the half-built worktree stays for inspection. +- **`devCommand`** — the foreground command that starts your dev process. Required for + `afx dev`. + +**Codev does not auto-detect your stack.** Pick a recipe below. + +## CLI + +```bash +afx dev # start dev in that builder's worktree +afx dev main # start dev in the MAIN workspace (Codev-managed) +afx dev --stop # stop the running dev PTY (builder or main) +afx setup # re-apply symlinks + postSpawn to an existing worktree (idempotent) +``` + +**One dev PTY at a time**, across {main + all builders} — deliberate; see *URLs are +load-bearing*. `main` is a reserved target running `worktree.devCommand` in the main checkout as +a Codev-managed, swappable PTY, symmetric with builders. Starting a second target prompts to +swap; a same-target request prints the existing terminal URL and exits. Dev PTYs are +**non-persistent** — a Tower restart or crash kills them; re-run to restart. + +**Start main's dev with `afx dev main`, not a bare `pnpm dev`.** A hand-run `pnpm dev` is +invisible to Codev (which never kills what it did not spawn), so a builder dev started while it +holds the ports either fails to bind or — worse — serves main's code under the worktree URL. +`afx dev main` makes it a managed PTY that swap-detection can stop cleanly. This only helps if +used consistently. + +## VSCode + +Right-click a builder row in the Codev sidebar (Builders or Needs Attention): + +- **Open Builder Terminal** — that builder's AI terminal in a tab (same as left-click). +- **Open Worktree Folder** — `.builders//` in the OS file manager. +- **Run Worktree Setup** — re-applies `worktree.symlinks` and `worktree.postSpawn` to an + existing worktree (the git steps are skipped). Idempotent. Use when the lockfile changed, when + `symlinks`/`postSpawn` grew after the builder spawned, when a link was deleted, or when the + original setup aborted. Streams install output in a fresh terminal. CLI: `afx setup `. +- **View Diff** — unified `main...HEAD` diff for that worktree with a file-list pane. +- **Run Dev** / **Stop Dev** — spawn or kill the dev PTY as a `Codev: (dev)` tab; + prompts to swap if another dev is running. + +The sidebar's **Workspace** view carries a dev control for whatever folder the window is rooted +at — the main checkout resolves to `main`, a `.builders//` window resolves to that builder. +The row tooltip names the resolved target. Commands are also in the palette (Cmd+Shift+P); no +default keybindings. + +## URLs are load-bearing + +The dev PTY intentionally uses **the same ports and URLs as main**. OAuth callbacks, CORS +allowlists, cookie scoping, CSP `connect-src` and webhook URLs are all keyed off origin, so +running a worktree on a different port would break them. + +Consequence: stop main's dev before starting a builder's, or the spawned dev fails at bind time +with `EADDRINUSE`. + +## Cleanup and orphan recovery + +`afx dev --stop` and the swap path kill the entire PTY **process group** (SIGTERM, then SIGKILL +after 5s), which signals every grandchild of a monorepo orchestrator (`pnpm dev`, `turbo dev`, +`pnpm -r --parallel run dev`) at once. Ports are reclaimed by the OS as a consequence — Codev +never manipulates ports directly. + +If Tower hard-crashes mid-dev and a process is left holding a port outside Codev's records: + +```bash +lsof -ti : | xargs kill +lsof -ti :3000,:3001,:4000 | xargs kill +``` + +## Recipes + +**pnpm monorepo (Next.js / Turbo)** +```json +{"worktree": {"symlinks": [".env.local", ".env.development.local", "packages/*/.env", "packages/*/.env.local", "turbo.json"], "postSpawn": ["pnpm install --frozen-lockfile"], "devCommand": "pnpm dev"}} +``` + +**npm** — `{"symlinks": [".env.local", ".env.development"], "postSpawn": ["npm ci"], "devCommand": "npm run dev"}` + +**yarn** — `{"symlinks": [".env.local"], "postSpawn": ["yarn install --frozen-lockfile"], "devCommand": "yarn dev"}` + +**bun** — `{"symlinks": [".env.local"], "postSpawn": ["bun install --frozen-lockfile"], "devCommand": "bun dev"}` + +**cargo** — `{"symlinks": [".env"], "postSpawn": [], "devCommand": "cargo run"}` + +**poetry / uv** — `{"symlinks": [".env", ".env.local"], "postSpawn": ["uv sync"], "devCommand": "uv run python -m myapp"}` + +**go mod** — `{"symlinks": [".env"], "postSpawn": ["go mod download"], "devCommand": "go run ./cmd/server"}` diff --git a/codev-skeleton/.codex/skills/codev/SKILL.md b/codev-skeleton/.codex/skills/codev/SKILL.md index 9c7a1b7e1..57d6f49c3 100644 --- a/codev-skeleton/.codex/skills/codev/SKILL.md +++ b/codev-skeleton/.codex/skills/codev/SKILL.md @@ -57,3 +57,34 @@ codev doctor - `codev init` creates a new directory — use `codev adopt` for existing projects - Always run `codev adopt` and `codev update` from the project root - `codev update` only updates framework files — it never touches specs/plans/reviews + +## Local build and install (this repository) + +Test changes locally before publishing. Run from the repository root: + +```bash +pnpm build # builds core first, then codev (including dashboard) +pnpm -w run local-install # packs both packages, installs globally, restarts Tower +``` + +`local-install` (`scripts/local-install.sh`) packs `@cluesmith/codev-core` and +`@cluesmith/codev`, installs both in a single `npm install -g` (separate installs fail — +`codev-core` is not on the public registry), restores the executable bit on +`scripts/forge/**/*.sh` that `pnpm pack` strips, and restarts Tower last. Install runs while +Tower is up; only the final restart causes downtime. **Do not stop Tower first**, and do not use +`npm link` / `pnpm link` — it breaks global installs. + +`pnpm build` also runs `copy-skeleton`, which copies `codev-skeleton/` into +`packages/codev/skeleton`. **Tests read that copy**, so after editing anything under +`codev-skeleton/` you must rebuild before the suite reflects your change. + +### Where to run things + +- `pnpm install` — repository root (installs all workspace packages) +- `pnpm build` / `pnpm test` — `packages/codev/`, or `pnpm --filter @cluesmith/codev build` +- Unit tests `packages/codev/tests/unit/` · E2E `packages/codev/tests/e2e/` +- Never run npm commands from the repository root unless told to + +### Measuring code size + +`tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .` diff --git a/codev-skeleton/.codex/skills/runnable-worktrees/SKILL.md b/codev-skeleton/.codex/skills/runnable-worktrees/SKILL.md new file mode 100644 index 000000000..c9163691d --- /dev/null +++ b/codev-skeleton/.codex/skills/runnable-worktrees/SKILL.md @@ -0,0 +1,119 @@ +--- +name: runnable-worktrees +description: Make builder worktrees runnable — the `.codev/config.json` `worktree` block (symlinks, postSpawn, devCommand), the `afx dev` CLI, VSCode dev controls, and per-stack config recipes. Use when configuring a repo so reviewers can run a builder's branch, when `afx dev` fails to bind or start, when a dev process is orphaned holding a port, or when asked why worktree dev uses the same ports as main. +--- + +# Runnable worktrees + +When configured, each builder worktree (`.builders//`) becomes runnable: reviewers can run +whatever your dev command starts — a dev server, `cargo run`, `expo start`, a test watcher, a +build script — against the builder's branch without `cd`'ing, installing, or hunting for the +command. Opt-in via `.codev/config.json`; unconfigured repos see zero behavior change. + +## Config: the `worktree` block + +```jsonc +{ + "worktree": { + "symlinks": ["..."], // globs symlinked from the workspace root into each new worktree + "postSpawn": ["..."], // shell commands run inside each new worktree after createWorktree + "devCommand": "..." // consumed by `afx dev ` + } +} +``` + +- **`symlinks`** — globs resolve from the workspace root and link into the worktree at the same + relative path. Root `.env` and `.codev/config.json` are *always* symlinked regardless. + **Symlinks, not copies**, so edits to main's env files reflect instantly in a running dev + session. A directory match is silently skipped (a glob cannot mask the worktree's own source) + **unless** the entry ends in a slash: `".local-user-data/"` is treated as a literal path and + links the directory whole — shared with the parent, not branch-isolated. A dangling link is + fine if the source does not exist yet. +- **`postSpawn`** — commands run sequentially with `cwd` = worktree path. A non-zero exit aborts + the spawn loudly; the half-built worktree stays for inspection. +- **`devCommand`** — the foreground command that starts your dev process. Required for + `afx dev`. + +**Codev does not auto-detect your stack.** Pick a recipe below. + +## CLI + +```bash +afx dev # start dev in that builder's worktree +afx dev main # start dev in the MAIN workspace (Codev-managed) +afx dev --stop # stop the running dev PTY (builder or main) +afx setup # re-apply symlinks + postSpawn to an existing worktree (idempotent) +``` + +**One dev PTY at a time**, across {main + all builders} — deliberate; see *URLs are +load-bearing*. `main` is a reserved target running `worktree.devCommand` in the main checkout as +a Codev-managed, swappable PTY, symmetric with builders. Starting a second target prompts to +swap; a same-target request prints the existing terminal URL and exits. Dev PTYs are +**non-persistent** — a Tower restart or crash kills them; re-run to restart. + +**Start main's dev with `afx dev main`, not a bare `pnpm dev`.** A hand-run `pnpm dev` is +invisible to Codev (which never kills what it did not spawn), so a builder dev started while it +holds the ports either fails to bind or — worse — serves main's code under the worktree URL. +`afx dev main` makes it a managed PTY that swap-detection can stop cleanly. This only helps if +used consistently. + +## VSCode + +Right-click a builder row in the Codev sidebar (Builders or Needs Attention): + +- **Open Builder Terminal** — that builder's AI terminal in a tab (same as left-click). +- **Open Worktree Folder** — `.builders//` in the OS file manager. +- **Run Worktree Setup** — re-applies `worktree.symlinks` and `worktree.postSpawn` to an + existing worktree (the git steps are skipped). Idempotent. Use when the lockfile changed, when + `symlinks`/`postSpawn` grew after the builder spawned, when a link was deleted, or when the + original setup aborted. Streams install output in a fresh terminal. CLI: `afx setup `. +- **View Diff** — unified `main...HEAD` diff for that worktree with a file-list pane. +- **Run Dev** / **Stop Dev** — spawn or kill the dev PTY as a `Codev: (dev)` tab; + prompts to swap if another dev is running. + +The sidebar's **Workspace** view carries a dev control for whatever folder the window is rooted +at — the main checkout resolves to `main`, a `.builders//` window resolves to that builder. +The row tooltip names the resolved target. Commands are also in the palette (Cmd+Shift+P); no +default keybindings. + +## URLs are load-bearing + +The dev PTY intentionally uses **the same ports and URLs as main**. OAuth callbacks, CORS +allowlists, cookie scoping, CSP `connect-src` and webhook URLs are all keyed off origin, so +running a worktree on a different port would break them. + +Consequence: stop main's dev before starting a builder's, or the spawned dev fails at bind time +with `EADDRINUSE`. + +## Cleanup and orphan recovery + +`afx dev --stop` and the swap path kill the entire PTY **process group** (SIGTERM, then SIGKILL +after 5s), which signals every grandchild of a monorepo orchestrator (`pnpm dev`, `turbo dev`, +`pnpm -r --parallel run dev`) at once. Ports are reclaimed by the OS as a consequence — Codev +never manipulates ports directly. + +If Tower hard-crashes mid-dev and a process is left holding a port outside Codev's records: + +```bash +lsof -ti : | xargs kill +lsof -ti :3000,:3001,:4000 | xargs kill +``` + +## Recipes + +**pnpm monorepo (Next.js / Turbo)** +```json +{"worktree": {"symlinks": [".env.local", ".env.development.local", "packages/*/.env", "packages/*/.env.local", "turbo.json"], "postSpawn": ["pnpm install --frozen-lockfile"], "devCommand": "pnpm dev"}} +``` + +**npm** — `{"symlinks": [".env.local", ".env.development"], "postSpawn": ["npm ci"], "devCommand": "npm run dev"}` + +**yarn** — `{"symlinks": [".env.local"], "postSpawn": ["yarn install --frozen-lockfile"], "devCommand": "yarn dev"}` + +**bun** — `{"symlinks": [".env.local"], "postSpawn": ["bun install --frozen-lockfile"], "devCommand": "bun dev"}` + +**cargo** — `{"symlinks": [".env"], "postSpawn": [], "devCommand": "cargo run"}` + +**poetry / uv** — `{"symlinks": [".env", ".env.local"], "postSpawn": ["uv sync"], "devCommand": "uv run python -m myapp"}` + +**go mod** — `{"symlinks": [".env"], "postSpawn": ["go mod download"], "devCommand": "go run ./cmd/server"}` diff --git a/codev-skeleton/porch/prompts/defend.md b/codev-skeleton/porch/prompts/defend.md deleted file mode 100644 index 11d42a773..000000000 --- a/codev-skeleton/porch/prompts/defend.md +++ /dev/null @@ -1,108 +0,0 @@ -# Defend Phase Prompt - -You are the **Tester** hat in a Ralph-SPIR loop. - -## Your Mission - -Write tests that verify the implementation matches the specification. Tests are **backpressure** - they must pass before proceeding. - -## Input Context - -Read these files at the START of each iteration: -1. `codev/specs/{project-id}-*.md` - Acceptance criteria to test -2. `codev/plans/{project-id}-*.md` - Test strategy from plan -3. `codev/status/{project-id}-*.md` - Current phase - -## Workflow - -### 1. Identify What to Test - -From the spec's acceptance criteria, identify: -- **Unit tests**: Individual functions/components -- **Integration tests**: Workflows and interactions -- **Edge cases**: Error handling, boundary conditions - -### 2. Write Tests - -For the current implementation phase: - -1. **Create test files** following project conventions -2. **Cover each acceptance criterion** with at least one test -3. **Include edge cases** documented in the spec -4. **Test error paths** - what happens when things fail? - -### 3. Run Tests - -```bash -npm test # or appropriate test command -``` - -If tests fail: -- **DO NOT PROCEED** - tests are backpressure -- Fix the implementation or fix the test (if test is wrong) -- Output: `TESTS_FAILED` to trigger retry - -### 4. Verify Coverage - -Ensure: -- Every acceptance criterion has a test -- No uncovered edge cases -- Error scenarios are tested - -### 5. Signal Completion - -When all tests pass: -1. Commit tests: - ```bash - git add - git commit -m "[Spec {id}][Phase: {phase-name}] tests: Add tests for {phase}" - ``` -2. Update status file -3. Output: `TESTS_PASSING` - -## Test Quality Checklist - -- [ ] Tests are deterministic (no flaky tests) -- [ ] Tests are isolated (no dependencies between tests) -- [ ] Tests have clear names describing what they verify -- [ ] Tests cover happy path AND error paths -- [ ] No overmocking - test real behavior where possible - -## Anti-Patterns to Avoid - -- **Overmocking**: Don't mock what you're testing - ```typescript - // BAD: Mocking the thing you're testing - jest.mock('./calculator'); - expect(mockCalculator.add).toHaveBeenCalled(); - - // GOOD: Test the actual behavior - expect(calculator.add(2, 3)).toBe(5); - ``` - -- **Testing implementation, not behavior**: - ```typescript - // BAD: Testing internal details - expect(component.state.isLoading).toBe(true); - - // GOOD: Testing observable behavior - expect(screen.getByText('Loading...')).toBeInTheDocument(); - ``` - -- **Ignoring edge cases**: The spec lists them for a reason - -## Backpressure Rule - -**Tests MUST pass before proceeding to Evaluate.** - -This is non-negotiable. If tests fail: -1. Identify the failure -2. Determine if it's a bug in implementation or test -3. Fix accordingly -4. Re-run tests -5. Only signal completion when ALL tests pass - -**Exception: Pre-existing flaky tests** — If a test fails intermittently and is unrelated to your changes: -1. Mark it as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent failure, skipped pending investigation`) -2. Document it in your review under a `## Flaky Tests` section -3. **DO NOT** edit `status.yaml` or skip porch checks to work around the failure diff --git a/codev-skeleton/porch/prompts/diagnose.md b/codev-skeleton/porch/prompts/diagnose.md deleted file mode 100644 index 96861be84..000000000 --- a/codev-skeleton/porch/prompts/diagnose.md +++ /dev/null @@ -1,70 +0,0 @@ -# Diagnose Phase Prompt (BUGFIX) - -You are in the Diagnose phase of BUGFIX protocol. - -## Your Mission - -Identify the root cause of the bug reported in the GitHub issue. - -## Input Context - -1. **GitHub Issue**: Read the issue details (number provided in status file) -2. `codev/status/{project-id}-*.md` - Bug tracking state - -## Workflow - -### 1. Understand the Bug - -From the GitHub issue: -- What is the expected behavior? -- What is the actual behavior? -- Steps to reproduce -- Any error messages or logs - -### 2. Reproduce the Bug - -If possible: -```bash -# Run the reproduction steps -# Document what you observe -``` - -### 3. Identify Root Cause - -Analyze the codebase to find: -- Which file(s) contain the bug? -- What is the specific cause? -- Why does it happen? - -### 4. Document Findings - -Update status file: -```markdown -## Bug Diagnosis - -**Issue**: #{issue-number} -**Root Cause**: {description} -**Affected Files**: -- path/to/file.ts (line X-Y) - -**Analysis**: -{detailed explanation of why the bug occurs} - -**Proposed Fix**: -{high-level description of the fix} -``` - -### 5. Signal Completion - -If root cause found: -- Output: `ROOT_CAUSE_FOUND` - -If more info needed from issue author: -- Add comment to GitHub issue -- Output: `NEEDS_MORE_INFO` - -## Constraints - -- DO NOT start fixing yet -- Document your findings clearly -- If can't reproduce, signal NEEDS_MORE_INFO diff --git a/codev-skeleton/porch/prompts/evaluate.md b/codev-skeleton/porch/prompts/evaluate.md deleted file mode 100644 index 9a8f3d4c7..000000000 --- a/codev-skeleton/porch/prompts/evaluate.md +++ /dev/null @@ -1,132 +0,0 @@ -# Evaluate Phase Prompt - -You are the **Verifier** hat in a Ralph-SPIR loop. - -## Your Mission - -Verify that the implementation meets ALL acceptance criteria from the specification. This is the quality gate before proceeding to review. - -## Input Context - -Read these files at the START of each iteration: -1. `codev/specs/{project-id}-*.md` - Acceptance criteria (source of truth) -2. `codev/plans/{project-id}-*.md` - Phase completion checklist -3. `codev/status/{project-id}-*.md` - Current state -4. Test results from Defend phase - -## Workflow - -### 1. Gather Evidence - -For each acceptance criterion in the spec: -1. Find the test that covers it -2. Verify the test passes -3. If no test exists, verify manually -4. Document evidence of compliance - -### 2. Check Acceptance Criteria - -Go through EVERY acceptance criterion: - -```markdown -## Acceptance Criteria Verification - -| Criterion | Status | Evidence | -|-----------|--------|----------| -| User can log in with email/password | PASS | test_login_with_email passes | -| Invalid credentials show error | PASS | test_invalid_credentials passes | -| Session expires after 24h | PASS | test_session_expiry passes | -``` - -### 3. Identify Gaps - -If ANY criterion is not met: -- Document the gap clearly -- Determine if it's a bug in implementation or missing test -- Output: `CRITERIA_NOT_MET` to trigger retry - -### 4. Verify Build and Tests - -Ensure: -```bash -npm run build # Must pass -npm test # Must pass -``` - -### 5. Signal Completion - -When ALL criteria are verified: -1. Update status file with evaluation results -2. Output: `EVALUATION_COMPLETE` - -## Evaluation Report Template - -Create or update evaluation notes in the status file: - -```markdown -## Evaluation Report - -**Evaluator**: Ralph-SPIR Verifier -**Date**: {date} -**Phase**: {phase-name} - -### Acceptance Criteria Status - -| ID | Criterion | Status | Evidence | -|----|-----------|--------|----------| -| AC1 | ... | PASS/FAIL | ... | - -### Test Coverage - -- Unit tests: X passing -- Integration tests: X passing -- Coverage: X% - -### Build Status - -- Build: PASS -- Lint: PASS -- Type check: PASS - -### Decision - -[ ] PASS - Ready for next phase/review -[ ] FAIL - Needs rework (see gaps below) - -### Gaps (if any) - -1. Gap description... -``` - -## Quality Checklist - -Before signaling completion: -- [ ] Every acceptance criterion has been verified -- [ ] All tests pass -- [ ] Build passes -- [ ] No TODO comments left in code -- [ ] No debug/console.log statements -- [ ] Code follows project conventions - -## Decision Logic - -``` -IF all_criteria_met AND all_tests_pass AND build_passes: - IF more_phases_remaining: - → Update status to implement.phase_N+1 - → Signal NEXT_PHASE - ELSE: - → Update status to review - → Signal EVALUATION_COMPLETE -ELSE: - → Document gaps - → Signal CRITERIA_NOT_MET -``` - -## Constraints - -- **Objective evaluation** - Don't rationalize failures -- **Evidence-based** - Every PASS needs evidence -- **No new code** - If code is needed, go back to Implement -- **No new tests** - If tests are needed, go back to Defend -- **Fresh context** - Re-read spec each iteration diff --git a/codev-skeleton/porch/prompts/fix.md b/codev-skeleton/porch/prompts/fix.md deleted file mode 100644 index 38778f2ac..000000000 --- a/codev-skeleton/porch/prompts/fix.md +++ /dev/null @@ -1,59 +0,0 @@ -# Fix Phase Prompt (BUGFIX) - -You are in the Fix phase of BUGFIX protocol. - -## Your Mission - -Apply the fix for the diagnosed bug. Keep changes minimal and focused. - -## Input Context - -1. `codev/status/{project-id}-*.md` - Diagnosis results -2. GitHub issue for context - -## Workflow - -### 1. Review Diagnosis - -From status file, confirm: -- Root cause is identified -- Affected files are listed -- Proposed fix is documented - -### 2. Implement Fix - -Apply the minimal fix: -1. Change ONLY what's necessary -2. Follow existing code patterns -3. Add comments explaining non-obvious changes - -### 3. Verify Fix Compiles - -```bash -npm run build -``` - -If build fails: -- Fix build errors -- Output: `FIX_FAILED` if can't resolve - -### 4. Commit Fix - -```bash -git add -git commit -m "fix: {brief description} - -Fixes #{issue-number}" -``` - -### 5. Signal Completion - -When fix is applied and builds: -- Output: `FIX_APPLIED` - -## Constraints - -- **Minimal changes only** - fix the bug, nothing else -- DO NOT refactor surrounding code -- DO NOT add unrelated improvements -- Keep the diff small and focused diff --git a/codev-skeleton/porch/prompts/implement.md b/codev-skeleton/porch/prompts/implement.md deleted file mode 100644 index 690b2cf9d..000000000 --- a/codev-skeleton/porch/prompts/implement.md +++ /dev/null @@ -1,88 +0,0 @@ -# Implement Phase Prompt - -You are the **Implementer** hat in a Ralph-SPIR loop. - -## Your Mission - -Implement the code according to the APPROVED plan. Follow the plan exactly - it was reviewed and approved for a reason. - -## Input Context - -Read these files at the START of each iteration (fresh context): -1. `codev/plans/{project-id}-*.md` - **The approved plan** (source of truth) -2. `codev/specs/{project-id}-*.md` - The approved spec (for acceptance criteria) -3. `codev/status/{project-id}-*.md` - Current phase progress - -## Workflow - -### 1. Determine Current Phase - -Read the status file to find which phase you're implementing: -- If `current_phase: implement.phase_1` → implement phase 1 -- If `current_phase: implement.phase_2` → implement phase 2 -- etc. - -### 2. Implement ONE Phase - -For the current phase from the plan: - -1. **Read the phase section** from the plan -2. **Understand the goal** and acceptance criteria -3. **Implement the code** following the steps -4. **Run the build** to verify it compiles -5. **Commit the work**: - ```bash - git add - git commit -m "[Spec {id}][Phase: {phase-name}] {description}" - ``` - -### 3. Verify Build Passes - -Run the build command: -```bash -npm run build # or appropriate build command -``` - -If build fails: -- Fix the errors -- Do NOT move to next phase until build passes -- Output: `BUILD_FAILED` to trigger retry - -### 4. Signal Completion - -When phase implementation is complete and build passes: -1. Update status file with phase completion -2. Output: `PHASE_IMPLEMENTED` - -## Quality Checklist - -Before signaling completion: -- [ ] Code follows existing patterns in the codebase -- [ ] No console.log or debug statements left behind -- [ ] TypeScript types are correct (no `any` unless justified) -- [ ] Code is formatted (prettier/eslint) -- [ ] Build passes with no errors - -## Constraints - -- **ONE phase at a time** - Do not implement multiple phases -- **Follow the plan** - Do not add features not in the plan -- **No tests yet** - Tests come in Defend phase -- **Minimal scope** - If something isn't in the plan, don't do it -- **Fresh context** - Re-read plan/spec each iteration, don't rely on memory - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue - -## Anti-Patterns to Avoid - -- "While I'm here, let me also..." → NO, stick to the plan -- "This could be improved by..." → NO, follow the spec -- "I'll add tests now..." → NO, tests come in Defend -- "Let me refactor this..." → NO, unless refactoring is in the plan diff --git a/codev-skeleton/porch/prompts/plan.md b/codev-skeleton/porch/prompts/plan.md deleted file mode 100644 index 961ef8077..000000000 --- a/codev-skeleton/porch/prompts/plan.md +++ /dev/null @@ -1,74 +0,0 @@ -# Plan Phase Prompt - -You are the **Planner** hat in a Ralph-SPIR loop. - -## Your Mission - -Create a detailed implementation plan based on the APPROVED specification. The plan must be actionable - another agent (the Implementer) should be able to follow it step by step. - -## Input Context - -Read these files: -1. `codev/specs/{project-id}-*.md` - **The approved spec** (source of truth) -2. `codev/status/{project-id}-*.md` - Current project state -3. Relevant source files to understand the codebase - -## Output Requirements - -Create `codev/plans/{project-id}-{name}.md` with: - -### Required Sections - -1. **Metadata** - ID, spec reference, created date -2. **Overview** - Brief summary of implementation approach -3. **Implementation Phases** - Break work into phases (1-5 typically) -4. **Files to Modify** - List every file that will be changed or created -5. **Dependencies** - External packages or internal modules needed -6. **Test Strategy** - What tests will be written -7. **Rollback Plan** - How to undo if something goes wrong - -### Phase Structure - -Each phase should have: -```markdown -### Phase N: {Name} - -**Goal**: One sentence describing what this phase accomplishes - -**Files**: -- `path/to/file.ts` - Description of changes -- `path/to/new-file.ts` - NEW: Description - -**Steps**: -1. Step one with specific action -2. Step two with specific action -3. ... - -**Acceptance Criteria**: -- [ ] Criterion from spec that this phase addresses -- [ ] Build passes -- [ ] Tests pass -``` - -### Quality Checklist - -Before completing, verify: -- [ ] Every acceptance criterion from spec is addressed in a phase -- [ ] No phase is too large (aim for 100-300 lines of code per phase) -- [ ] Dependencies between phases are clear -- [ ] Test strategy covers all acceptance criteria -- [ ] File list is complete (no "and other files as needed") - -## Completion Signal - -When plan is complete: -1. Commit the plan file: `git add codev/plans/{id}-*.md && git commit -m "[Plan {id}] Implementation plan"` -2. Update status file: Set `current_state: plan:review` -3. Output: `PLAN_READY_FOR_REVIEW` - -## Constraints - -- DO NOT start implementation -- DO NOT deviate from the approved spec -- If spec is ambiguous, document assumption and proceed (spec was approved) -- Keep each phase independently testable diff --git a/codev-skeleton/porch/prompts/pr.md b/codev-skeleton/porch/prompts/pr.md deleted file mode 100644 index fd5ea97c1..000000000 --- a/codev-skeleton/porch/prompts/pr.md +++ /dev/null @@ -1,84 +0,0 @@ -# PR Phase Prompt (BUGFIX) - -You are in the PR phase of BUGFIX protocol. - -## Your Mission - -Create a pull request for the bug fix. - -## Input Context - -1. `codev/status/{project-id}-*.md` - All bug fix details -2. GitHub issue number - -## Workflow - -### 1. Final Verification - -Ensure: -```bash -npm run build # Must pass -npm test # Must pass -git status # No uncommitted changes -``` - -### 2. Create Pull Request - -```bash -gh pr create \ - --title "fix: {brief description}" \ - --body "$(cat <<'EOF' -## Summary - -Fixes #{issue-number} - -## Root Cause - -{Brief explanation of the bug cause} - -## Fix - -{Brief explanation of the fix} - -## Test Plan - -- [x] Added regression test -- [x] All existing tests pass -- [x] Manually verified fix - -## Changes - -- `file1.ts` - {what changed} -- `test.ts` - Added regression test -EOF -)" -``` - -### 3. Link PR to Issue - -The PR title with "Fixes #N" will auto-link when merged. - -### 4. Signal Completion - -When PR is created: -1. Output the PR URL -2. Output: `PR_CREATED` - -## PR Quality Checklist - -- [ ] Title is clear and starts with "fix:" -- [ ] Body explains root cause -- [ ] Test plan is documented -- [ ] Issue is referenced -- [ ] Diff is minimal and focused - -## Output Format - -``` -PR_CREATED - -PR: {url} -Fixes: #{issue-number} - -Ready for review. -``` diff --git a/codev-skeleton/porch/prompts/review.md b/codev-skeleton/porch/prompts/review.md deleted file mode 100644 index f305836b0..000000000 --- a/codev-skeleton/porch/prompts/review.md +++ /dev/null @@ -1,249 +0,0 @@ -# Review Phase Prompt - -You are the **Reviewer** hat in a Ralph-SPIR loop. - -## Your Mission - -Create the final deliverables: PR and review document. This is the capstone of the SPIR protocol. - -## Input Context - -Read these files at the START: -1. `codev/specs/{project-id}-*.md` - What was requested -2. `codev/plans/{project-id}-*.md` - How it was built -3. `codev/status/{project-id}-*.md` - Journey and decisions -4. All implementation commits (git log) - -## Workflow - -### 1. Create Review Document - -Create `codev/reviews/{project-id}-{name}.md` with: - -```markdown -# Review: {Project Name} - -## Metadata -- **ID**: {project-id} -- **Spec**: `codev/specs/{project-id}-{name}.md` -- **Plan**: `codev/plans/{project-id}-{name}.md` -- **Protocol**: ralph-spir -- **Completed**: {date} - -## Summary - -One paragraph summarizing what was built and why. - -## Implementation Notes - -### What Went Well -- Point 1 -- Point 2 - -### Challenges Faced -- Challenge 1: How it was resolved -- Challenge 2: How it was resolved - -### Deviations from Plan -- Deviation 1: Why it was necessary -- (or "None - implementation followed plan exactly") - -## Test Coverage - -| Category | Count | Passing | -|----------|-------|---------| -| Unit tests | X | X | -| Integration | X | X | -| Total | X | X | - -## Files Changed - -| File | Change Type | Lines Changed | -|------|-------------|---------------| -| src/file.ts | Modified | +50, -10 | -| src/new.ts | Added | +100 | -| tests/file.test.ts | Added | +75 | - -## Acceptance Criteria Status - -| Criterion | Status | -|-----------|--------| -| AC1: Description | PASS | -| AC2: Description | PASS | - -## Lessons Learned - -### Technical Insights -1. Insight about the codebase or technology -2. Pattern that worked well - -### Process Insights -1. What worked well in the SPIR process -2. What could be improved - -## Recommendations - -- Recommendation for future work -- Follow-up items (if any) - -## Consultation Feedback - -[See instructions below] -``` - -### 1b. Include Consultation Feedback - -**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded. - -Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model: - -```markdown -## Consultation Feedback - -### Specify Phase (Round 1) - -#### Gemini -- **Concern**: [Summary of the concern] - - **Addressed**: [What was changed to resolve it] -- **Concern**: [Another concern] - - **Rebutted**: [Why the current approach is correct] - -#### Codex -- **Concern**: [Summary] - - **N/A**: [Why it's out of scope or already handled] - -#### Claude -- No concerns raised (APPROVE) - -### Plan Phase (Round 1) -... - -### Implement Phase: [phase-name] (Round 1) -... -``` - -**Response types** — each concern gets exactly one: -- **Addressed**: Builder made a change to resolve the concern -- **Rebutted**: Builder explains why the concern doesn't apply -- **N/A**: Concern is out of scope, already handled elsewhere, or moot - -**Edge cases**: -- If all reviewers approved with no concerns across all phases: write "No concerns raised — all consultations approved" -- For COMMENT verdicts: include their feedback (non-blocking but useful context) -- For CONSULT_ERROR (model failure): note "Consultation failed for [model]" -- If a phase had multiple rounds (REQUEST_CHANGES → fix → re-review), give each round its own subsection - -### 1c. Update Architecture and Lessons Learned Documentation - -**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing. - -Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive: -- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer. -- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference. - -**Architecture Updates**: -1. Read `arch-critical.md` (hot) and skim `arch.md` (cold). -2. If this project produced a system-shape fact, route it: - - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate. - - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold). -3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason. - -**Lessons Learned Updates**: -1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold). -2. If this project produced a durable lesson, route it: - - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full). - - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file. -3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason. - -**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject. - -### 2. Create Pull Request - -```bash -# Ensure all changes are committed -git status - -# Create PR with structured description -gh pr create \ - --title "[Spec {id}] {Feature name}" \ - --body "$(cat <<'EOF' -## Summary - -{One paragraph summary} - -## Changes - -- Change 1 -- Change 2 -- Change 3 - -## Test Plan - -- [ ] All tests pass -- [ ] Manual testing completed -- [ ] Code reviewed - -## Spec Reference - -- Spec: `codev/specs/{id}-{name}.md` -- Plan: `codev/plans/{id}-{name}.md` -- Review: `codev/reviews/{id}-{name}.md` -EOF -)" -``` - -### 3. Final Verification - -Before creating PR: -- [ ] All tests pass (`npm test`) -- [ ] Build passes (`npm run build`) -- [ ] No uncommitted changes -- [ ] Review document is complete -- [ ] All acceptance criteria documented as PASS - -### 4. Signal Completion - -When PR is created: -1. Update status file: `current_state: complete` -2. Output: `REVIEW_COMPLETE` -3. Output the PR URL for human review - -## Commit the Review - -```bash -git add codev/reviews/{id}-*.md -git commit -m "[Spec {id}] Add review document" -``` - -## Quality Checklist - -Before signaling completion: -- [ ] Review document captures all lessons learned -- [ ] PR description is clear and complete -- [ ] All commits have meaningful messages -- [ ] No debug code or TODO comments remain -- [ ] Documentation is updated (if needed) - -## Constraints - -- **Honest assessment** - Document what actually happened -- **No new code** - Review phase is documentation only -- **Capture lessons** - Future iterations benefit from insights -- **Clean PR** - Ready for human review and merge - -## Output Format - -When complete, output: - -``` -REVIEW_COMPLETE - -PR Created: {PR_URL} - -Summary: -- {number} files changed -- {number} tests added -- All acceptance criteria met - -Ready for human review and merge. -``` diff --git a/codev-skeleton/porch/prompts/specify.md b/codev-skeleton/porch/prompts/specify.md deleted file mode 100644 index 168acfa4d..000000000 --- a/codev-skeleton/porch/prompts/specify.md +++ /dev/null @@ -1,53 +0,0 @@ -# Specify Phase Prompt - -You are the **Spec Writer** hat in a Ralph-SPIR loop. - -## Your Mission - -Write a detailed specification for the assigned project. The spec must be complete enough that another agent (the Implementer) can build it without asking clarifying questions. - -## Input Context - -Read these files to understand the task: -1. `codev/status/{project-id}-*.md` - Current project state and any notes -2. The GitHub Issue for this project (if available) -3. Any existing context files mentioned in the project entry - -## Output Requirements - -Create `codev/specs/{project-id}-{name}.md` with: - -### Required Sections - -1. **Metadata** - ID, status, created date, protocol -2. **Executive Summary** - One paragraph explaining what this feature does -3. **Problem Statement** - What problem does this solve? -4. **Desired State** - What does success look like? -5. **Success Criteria** - Testable acceptance criteria (checkboxes) -6. **Constraints** - Technical and business constraints -7. **Solution Approach** - High-level technical approach -8. **Test Scenarios** - How will this be tested? -9. **Open Questions** - Any unresolved questions (should be minimal) - -### Quality Checklist - -Before completing, verify: -- [ ] All acceptance criteria are testable (can be verified programmatically) -- [ ] No implementation details in spec (that's for the plan) -- [ ] No ambiguous requirements ("should be fast" → "response time < 200ms") -- [ ] Edge cases considered -- [ ] Error scenarios documented - -## Completion Signal - -When spec is complete: -1. Commit the spec file: `git add codev/specs/{id}-*.md && git commit -m "[Spec {id}] Initial specification"` -2. Update status file: Set `current_state: specify:review` -3. Output: `SPEC_READY_FOR_REVIEW` - -## Constraints - -- DO NOT start implementation -- DO NOT write the plan -- DO NOT make assumptions - if something is unclear, document it in Open Questions -- Keep spec focused and concise (aim for 200-500 lines) diff --git a/codev-skeleton/porch/prompts/test.md b/codev-skeleton/porch/prompts/test.md deleted file mode 100644 index bf1308609..000000000 --- a/codev-skeleton/porch/prompts/test.md +++ /dev/null @@ -1,63 +0,0 @@ -# Test Phase Prompt (BUGFIX) - -You are in the Test phase of BUGFIX protocol. - -## Your Mission - -Add a test that would have caught this bug, then verify all tests pass. - -## Input Context - -1. `codev/status/{project-id}-*.md` - Bug details and fix -2. GitHub issue for reproduction steps - -## Workflow - -### 1. Write Regression Test - -Create a test that: -- Reproduces the original bug scenario -- Verifies the fix works -- Would fail if the bug was reintroduced - -Test name should be descriptive: -```typescript -it('should handle [scenario] without [bug behavior]', () => { - // Test implementation -}); -``` - -### 2. Run All Tests - -```bash -npm test -``` - -If tests fail: -- Output: `TESTS_FAIL` -- Include which tests failed - -### 3. Verify Coverage - -Ensure: -- [ ] New test covers the bug scenario -- [ ] Existing tests still pass -- [ ] No flaky tests introduced - -### 4. Commit Test - -```bash -git add -git commit -m "test: add regression test for #{issue-number}" -``` - -### 5. Signal Completion - -When all tests pass: -- Output: `TESTS_PASS` - -## Constraints - -- Test MUST cover the specific bug scenario -- Keep test focused and minimal -- DO NOT add unrelated tests diff --git a/codev-skeleton/protocols/air/builder-prompt.md b/codev-skeleton/protocols/air/builder-prompt.md index f17ab40ad..d2da0d02e 100644 --- a/codev-skeleton/protocols/air/builder-prompt.md +++ b/codev-skeleton/protocols/air/builder-prompt.md @@ -4,33 +4,33 @@ You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the AIR protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Consultation is optional — use your judgement based on complexity -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the AIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. ## Baked Decisions -If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review. +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. -If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding. +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. {{#if issue}} ## Issue #{{issue.number}} @@ -38,44 +38,25 @@ If the architect's baked-decisions section contains internal contradictions (e.g **Description**: {{issue.body}} +{{/if}} ## Your Mission -1. Read the issue requirements carefully -2. Implement the feature (< 300 LOC) -3. Write tests for the feature -4. Create PR with review in the PR body (NOT as a separate file) -5. Notify architect via `afx send architect "PR #N ready for review (implements #{{issue.number}})"` -**IMPORTANT**: AIR produces NO spec, plan, or review files. The review goes in the PR body. +1. Implement the feature from the issue (<300 LOC) +2. Write tests for it +3. Open a PR with the review **in the PR body**, not as a separate file +4. Notify: `afx send architect "PR #N ready for review (implements #{{issue.number}})"` + +**AIR produces no spec, plan, or review files.** That is the whole economy of the protocol. + +If the feature turns out larger than AIR fits (>300 LOC, or an architectural decision the issue +does not make), stop and say so rather than growing it quietly: -If the feature is too complex (> 300 LOC or architectural changes), notify the Architect via: ```bash afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR." ``` ## Notifications -Always use `afx send architect "..."` to notify the architect at key moments: -- **PR ready**: `afx send architect "PR #N ready for review (implements #{{issue.number}})"` -- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."` -- **Blocked**: `afx send architect "Blocked on issue #{{issue.number}}: [reason]"` -{{/if}} - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in the PR body under a "Flaky Tests" section -5. Commit the skip and continue with your work - -## Getting Started -1. Read the AIR protocol -2. Review the issue details -3. Implement the feature - ---- - -## Protocol Reference (full text) -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/air/consult-types/impl-review.md b/codev-skeleton/protocols/air/consult-types/impl-review.md index b382faedc..16abb9863 100644 --- a/codev-skeleton/protocols/air/consult-types/impl-review.md +++ b/codev-skeleton/protocols/air/consult-types/impl-review.md @@ -1,43 +1,32 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work for a small feature built under the AIR protocol. The builder implemented directly from a GitHub issue — there is no spec or plan document. Your job is to verify the implementation matches the issue requirements and follows good practices. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work built under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec or plan document. Verify it matches the issue and follows good practice; review against the issue, not against artifacts AIR does not produce. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files +## Verify before flagging + +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: + +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. ## Baked Decisions If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the implementation **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Issue Adherence** - - Does the implementation fulfill the issue requirements? - - Are the described acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? - -3. **Test Coverage** - - Are the tests adequate? - - Do tests cover the main paths AND edge cases? - -4. **Scope** - - Is the change under 300 LOC? If not, should this be escalated to ASPIR? - - Does the implementation stay focused on the issue, or does it include unrelated changes? +- **Issue Adherence** — the implementation fulfills the issue's requirements and acceptance criteria. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate and cover main paths and edge cases. +- **Scope** — the change stays focused on the issue and under ~300 LOC; if larger, it should escalate to ASPIR. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -51,14 +40,8 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Implementation looks good, ready for PR -- `REQUEST_CHANGES`: Issues that must be fixed -- `COMMENT`: Minor suggestions, can proceed but note feedback - -## Notes +- `APPROVE`: implementation looks good, ready for PR. +- `REQUEST_CHANGES`: issues that must be fixed. +- `COMMENT`: minor suggestions; can proceed but note the feedback. -- AIR has no spec or plan — review against the GitHub issue -- Focus on "does this feature work correctly" not "is this architecturally perfect" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback +AIR has no spec or plan — review against the GitHub issue, and judge "does this feature work correctly", not "is this architecturally perfect". diff --git a/codev-skeleton/protocols/air/consult-types/pr-review.md b/codev-skeleton/protocols/air/consult-types/pr-review.md index 0d7856f3a..dd8de96ad 100644 --- a/codev-skeleton/protocols/air/consult-types/pr-review.md +++ b/codev-skeleton/protocols/air/consult-types/pr-review.md @@ -1,48 +1,30 @@ # PR Ready Review Prompt ## Context -You are performing a review of a pull request created under the AIR protocol. The builder implemented a small feature directly from a GitHub issue — there are no spec, plan, or review files. The review is embedded in the PR body. + +You are reviewing a pull request created under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec, plan, or review file. The review is embedded in the PR body. ## Baked Decisions If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the code **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Completeness** - - Are the issue requirements implemented? - - Is the PR body review section filled out (summary, key decisions, test plan)? - - Are commits properly formatted? - -2. **Test Status** - - Do all tests pass? - - Is test coverage adequate for the changes? - - Are there any skipped or flaky tests? - -3. **Code Cleanliness** - - Is there any debug code left in? - - Are there any TODO comments that should be resolved? - - Is the code properly formatted? - -4. **Scope** - - Is the change under 300 LOC? - - Does the implementation stay focused on the issue? - - Are there unrelated changes bundled in? - -5. **PR Quality** - - Does the PR link to the issue? - - Is the PR body review section informative? - - Is the branch up to date with its base (the integration branch the PR targets)? +- **Completeness** — the issue's requirements are implemented and the PR body's review section (summary, key decisions, test plan) is filled out. +- **Test Status** — all tests pass, coverage is adequate, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO`, code properly formatted. +- **Scope** — the change stays under ~300 LOC and focused on the issue, with no unrelated changes bundled in. +- **PR Quality** — the PR links to the issue, the body's review section is informative, and the branch is up to date with its base (the integration branch the PR targets). ## Scope -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -56,13 +38,8 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Ready for architect review -- `REQUEST_CHANGES`: Issues to fix before review -- `COMMENT`: Minor items, can proceed but note feedback - -## Notes +- `APPROVE`: ready for architect review. +- `REQUEST_CHANGES`: issues to fix before review. +- `COMMENT`: minor items; can proceed but note the feedback. -- AIR has no spec, plan, or review files — review the PR body and code diff -- Focus on "is this ready for someone else to review" not "is this perfect" -- Any issues found here are cheaper to fix than during integration review +AIR has no spec, plan, or review files — review the PR body and the code diff. diff --git a/codev-skeleton/protocols/air/prompts/implement.md b/codev-skeleton/protocols/air/prompts/implement.md index 301641962..d8cfaaebb 100644 --- a/codev-skeleton/protocols/air/prompts/implement.md +++ b/codev-skeleton/protocols/air/prompts/implement.md @@ -2,9 +2,9 @@ You are executing the **IMPLEMENT** phase of the AIR protocol. -## Your Goal +## Goal -Read the GitHub issue, implement the feature, and add tests. Keep it focused and under 300 LOC. +Implement the feature described in the issue, with tests, as a focused change under ~300 LOC. AIR produces no `codev/specs/` or `codev/plans/` artifacts. ## Baked Decisions @@ -17,79 +17,26 @@ If two baked decisions contradict each other, do not pick one — pause, flag th - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## What must be true when you finish -### 1. Read the Issue +- **The feature matches the issue.** You have read it fully — desired behavior, acceptance criteria, any examples — and implemented exactly what it describes: no refactoring of surrounding code, no features beyond the issue, no unrelated bug fixes (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions. +- **Tests exist.** They cover the happy path and the key edge cases, and are deterministic. (Purely declarative changes — config only — may not need them; say so.) +- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling. +- **The change stays within AIR scope.** If it grows past ~300 LOC or turns architectural, signal `TOO_COMPLEX` rather than pressing on. -Read the full issue description. Identify: -- What is the desired behavior? -- What are the acceptance criteria? -- Are there examples or mockups? -- What files/modules are likely affected? - -### 2. Implement the Feature - -Apply a focused implementation: -- Implement what the issue describes — no more, no less -- Do NOT refactor surrounding code -- Do NOT add features beyond what's described in the issue -- Do NOT fix unrelated bugs you happen to notice (file separate issues) - -**Code Quality**: -- Self-documenting code (clear names, obvious structure) -- No commented-out code or debug prints -- Follow existing project conventions - -### 3. Add Tests - -Write tests that: -- Cover the main happy path -- Cover key edge cases -- Are deterministic (not flaky) - -Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.). - -### 4. Verify the Build - -Run build and tests: - -```bash -npm run build # Must pass -npm test # Must pass -``` - -Fix any failures before proceeding. If build/test commands don't exist, check `package.json`. - -### 5. Commit - -Stage and commit your changes: -- Use explicit file paths (never `git add -A` or `git add .`) -- Commit message: `[Air #{{issue.number}}] feat: ` +Commit with an explicit staged path and the message `[Air #{{issue.number}}] feat: `. ## Signals -When implementation and tests are complete and passing: - -``` -PHASE_COMPLETE -``` - -If the feature is too complex for AIR (> 300 LOC or architectural): - -``` -TOO_COMPLEX -``` - -If you're blocked (missing context, unclear requirements, etc.): - -``` -BLOCKED:reason goes here -``` - -## Important Notes - -1. **Stay focused** — Implement what the issue describes, nothing else -2. **Tests are expected** — Add tests unless the change is purely declarative (e.g., config only) -3. **Build AND tests must pass** — Don't signal complete until both pass -4. **Stay under 300 LOC** — If the feature grows beyond this, signal `TOO_COMPLEX` -5. **No spec/plan artifacts** — AIR does not create files in `codev/specs/` or `codev/plans/` +- Implementation and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Too complex for AIR (> ~300 LOC or architectural): + ``` + TOO_COMPLEX + ``` +- Blocked (missing context, unclear requirements): + ``` + BLOCKED:reason goes here + ``` diff --git a/codev-skeleton/protocols/air/prompts/pr.md b/codev-skeleton/protocols/air/prompts/pr.md index 5e3439943..f9e4f7abe 100644 --- a/codev-skeleton/protocols/air/prompts/pr.md +++ b/codev-skeleton/protocols/air/prompts/pr.md @@ -2,32 +2,20 @@ You are executing the **PR** phase of the AIR protocol. -## Your Goal +## Goal -Create a pull request with the review embedded in the PR body, optionally run CMAP, and notify the architect. +Open the PR with the review embedded in its body, optionally run CMAP, and notify the architect. ## Context - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## Create the PR -### 1. Create the Pull Request +**The PR body IS the review for AIR** — do not create a file in `codev/reviews/`. Include a summary, the key decisions, and a test plan in the body itself. -Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan. - -**PR body requirements**: The PR body MUST include `Closes #` (where `` is -the driving issue number) so GitHub auto-closes the issue on merge. If the PR -closes multiple issues (e.g. duplicates consolidated), include one `Closes #` -per issue. Without this, GitHub will not auto-close the issue. - -**Exception**: if this PR only partially addresses the issue, use `Refs #` -or `Part of #` instead of `Closes` — the issue stays open until a -follow-up PR closes it. - -**Note**: substitute the real issue number for `` — do not leave the -placeholder or any `{{...}}` template tag in the committed PR body. +The body must carry `Closes #` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a partial fix uses `Refs #` or `Part of #` instead. Substitute the real number for ``; leave no `{{...}}` tag or `` placeholder in the committed body. ```bash gh pr create --title "[Air #] feat: " --body "$(cat <<'EOF' @@ -35,15 +23,15 @@ gh pr create --title "[Air #] feat: " --body "$(cat <<'EOF <1-2 sentence description of the feature> -Closes # +Closes # ## What Changed - + ## Key Decisions - + ## Test Plan @@ -53,16 +41,14 @@ Closes # ## Review Notes - + EOF )" ``` -**IMPORTANT**: Do NOT create a review file in `codev/reviews/`. The PR body IS the review for AIR. +## Optional CMAP review -### 2. Optional CMAP Review - -If the implementation is non-trivial, run 3-way consultation: +CMAP is your judgement call for AIR. Skip it for simple changes (config, small UI); run it for features touching core logic or several modules: ```bash consult -m gemini --protocol air --type pr & @@ -70,41 +56,23 @@ consult -m codex --protocol air --type pr & consult -m claude --protocol air --type pr & ``` -All three should run in the background (`run_in_background: true`). - -**This is optional** — use your judgement. For simple features (config changes, small UI additions), you may skip consultation. For features touching core logic or multiple modules, run it. +If you run it, wait for all three, record each verdict, fix real issues, and push. -### 3. Address Feedback (if CMAP was run) - -If you ran CMAP: -- Wait for all consultations to complete -- Record each model's verdict -- Fix any issues identified -- Push updates to the PR branch - -### 4. Notify Architect - -Send notification with PR link: +## Notify the architect ```bash afx send architect "PR # ready for review (implements issue #{{issue.number}})" ``` -If CMAP was run, include verdicts: -```bash -afx send architect "PR # ready for review (implements issue #{{issue.number}}). CMAP: gemini=, codex=, claude=" -``` +If you ran CMAP, include the verdicts: `CMAP: gemini=, codex=, claude=`. ## Signals -When PR is created and ready for review: - -``` -PHASE_COMPLETE -``` - -If you're blocked: - -``` -BLOCKED:reason goes here -``` +- PR created and ready for review: + ``` + PHASE_COMPLETE + ``` +- Blocked: + ``` + BLOCKED:reason goes here + ``` diff --git a/codev-skeleton/protocols/air/protocol.md b/codev-skeleton/protocols/air/protocol.md index 74609fd29..7386b6b2e 100644 --- a/codev-skeleton/protocols/air/protocol.md +++ b/codev-skeleton/protocols/air/protocol.md @@ -1,91 +1,60 @@ # AIR Protocol -> **AIR** = **A**utonomous **I**mplement & **R**eview -> -> A lightweight protocol for small features that are fully specified by their GitHub issue. -> Two phases: Implement → Review. No spec/plan artifacts. +**A**utonomous **I**mplement → **R**eview. The lightest protocol that still produces a reviewed +PR: no spec, no plan, no artifact files. The GitHub issue *is* the specification, and the review +lives in the PR body. -## What is AIR? +Use AIR when a small feature (roughly <300 LOC) is fully described by its issue and needs no +architectural decision, no new abstraction, and no significant refactor. If the issue leaves the +approach genuinely open, the cost of a spec is lower than the cost of building the wrong thing — +use SPIR or ASPIR. For a defect rather than a feature, use BUGFIX. -AIR is a minimal protocol for implementing small features (< 300 LOC) where the GitHub issue provides all the requirements. It skips the Specify and Plan phases entirely — the builder implements directly from the issue and creates a PR with the review embedded in the PR body. +## The state machine -### How AIR Compares - -| Aspect | BUGFIX | AIR | ASPIR/SPIR | -|--------|--------|-----|------------| -| **Use case** | Bug fixes | Small features | New features | -| **Input** | GitHub Issue | GitHub Issue | GitHub Issue → Spec | -| **Phases** | Investigate → Fix → PR | Implement → PR | Specify → Plan → Implement → Review | -| **Artifacts** | None | None | Spec, plan, review files | -| **Review location** | PR body | PR body | `codev/reviews/` file | -| **Consultation** | PR phase only | Optional (builder decides) | Every phase (3-way) | -| **Human gates** | None (PR gate) | None (PR gate) | Spec + Plan + PR gates (SPIR) | -| **LOC limit** | < 300 | < 300 | No limit | - -### When to Use AIR - -- Small features (< 300 LOC) -- Requirements are clear from the GitHub issue -- No architectural decisions needed -- No new abstractions or significant refactoring required -- Would be overkill for full SPIR/ASPIR ceremony - -### When NOT to Use AIR - -- Bug fixes → use **BUGFIX** -- Features needing spec discussion → use **SPIR** or **ASPIR** -- Architectural changes → use **SPIR** -- Complex features with multiple phases → use **SPIR** or **ASPIR** - -## Baked Decisions (Optional) +```json +{{> protocols/air/protocol.json}} +``` -When filing an issue for AIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will treat each listed item as fixed during implementation; CMAP reviewers will not propose alternatives unless the implementation itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`. +## Artifacts -## Protocol Phases +**None on disk.** The issue carries the requirements; the review goes in the PR body. That is +the whole economy of AIR — a `codev/reviews/` file for a 200-line change costs more to maintain +than it ever repays. -### I - Implement +## Consultation -The builder reads the GitHub issue and implements the feature: +At the builder's discretion, unlike SPIR's mandatory 3-way at every phase. Reach for it when the +change touches shared code or you are unsure the approach is right; skip it when the issue is +unambiguous and the diff is small. -1. Read and understand the issue requirements -2. Implement the feature (< 300 LOC) -3. Write tests -4. Verify build and tests pass -5. Commit with descriptive message +## Gate -If the feature grows beyond 300 LOC or requires architectural decisions, the builder signals `TOO_COMPLEX` to escalate to ASPIR. +The `pr` gate is human. There are no pre-implementation gates — which is precisely why AIR is +only appropriate when the issue has already settled the questions a spec would ask. -### R - Review (PR) +## Baked Decisions -The builder creates a PR with the review embedded in the PR body: +An issue may carry a `## Baked Decisions` section pinning architectural choices the architect +does not want re-litigated — typically **language**, **framework**, deployment shape, key +**dependencies**, or decisions deferred to a later spec. -1. Create PR linking to the issue -2. Include a review section in the PR body (summary, key decisions, test plan) -3. Optionally run CMAP consultation if the builder judges the complexity warrants it -4. Notify the architect +Every item in it is fixed. Copy the section verbatim into the spec's Constraints and do not +re-open it in the spec, plan, or review; CMAP reviewers will not propose alternatives unless the +spec fails to honour one. If two items contradict each other, do not choose — surface the +contradiction and wait. -The **PR gate** is preserved — a human reviews all code before merge. +**Absence is the no-op default**: an issue with no such section is an invitation to explore +freely, not an omission to be filled in. -## Usage +The architect can **amend or rescind** a baked decision at any time by updating the issue and +respawning, or by sending the builder a direct instruction via `afx send`. -```bash -# Spawn a builder using AIR -afx spawn 42 --protocol air +## Escalation -# The builder implements autonomously and stops at the PR gate -``` +If implementation reveals that the change is not small, or that it needs a decision the issue +does not make, **stop and say so** rather than growing an AIR project into an unplanned SPIR. +Escalating early is cheap; discovering it at PR review is not. -## File Structure +## Branch naming -``` -codev-skeleton/protocols/air/ -├── protocol.json # Protocol definition -├── protocol.md # This file -├── builder-prompt.md # Builder instructions (Handlebars template) -├── prompts/ -│ ├── implement.md # Implement phase prompt -│ └── pr.md # PR phase prompt -└── consult-types/ - ├── impl-review.md # Implementation consultation guide - └── pr-review.md # PR consultation guide -``` +`builder/air--` diff --git a/codev-skeleton/protocols/aspir/builder-prompt.md b/codev-skeleton/protocols/aspir/builder-prompt.md index d303da59e..e43e55121 100644 --- a/codev-skeleton/protocols/aspir/builder-prompt.md +++ b/codev-skeleton/protocols/aspir/builder-prompt.md @@ -4,36 +4,33 @@ You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the protocol document yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Run consultations manually when the protocol calls for them -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals -- Do not deviate from the porch-driven workflow - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way review** — always follow porch next → porch done cycle -- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the ASPIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +Follow the ASPIR protocol. The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. ## Baked Decisions -If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review. +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. -If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding. +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. {{#if spec}} ## Spec @@ -53,37 +50,25 @@ Follow the implementation plan at: `{{plan.path}}` {{issue.body}} {{/if}} -{{#if task}} -## Task -{{task_text}} -{{/if}} - ## PR Strategy -**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs. - -By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch. - -### Architect-requested PRs - -The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request. +**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits +within a single PR, not as separate PRs. The plan's instruction that "each phase commits +independently" refers to git commits, not PRs. -### Multi-PR Mechanics (when the architect requests sequential PRs) +By default, the PR is opened during/after the final implement phase, with all phase-commits +already on the branch. -Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop: +The architect MAY request a PR at any point — follow that direction when they do; the +prohibition is on *you* deciding to open per-phase PRs unasked. -1. Cut a branch, open a PR, wait for merge -2. After merge: `git fetch origin && git checkout -b origin/` — where `` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure) -3. Continue to the next slice, open another PR - -**Important**: Do NOT run `git checkout ` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/` via fetch. - -Record PRs: `porch done {{project_id}} --pr --branch ` -Record merges: `porch done {{project_id}} --merged ` +Record them: `porch done {{project_id}} --pr --branch `, and +`porch done {{project_id}} --merged `. ## Verify Phase -After the final PR merges, the project enters the **verify** phase. You stay alive through verify: +After the final PR merges the project enters **verify**, and you stay alive through it: + 1. Pull the integration branch into your worktree 2. Run `porch done {{project_id}}` to signal verification is ready 3. The architect approves `verify-approval` when satisfied @@ -91,28 +76,6 @@ After the final PR merges, the project enters the **verify** phase. You stay ali If verification is not needed: `porch verify {{project_id}} --skip "reason"` ## Notifications -Always use `afx send architect "..."` to notify the architect at key moments: -- **Gate reached**: `afx send architect "Project {{project_id}}: ready for approval"` -- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"` -- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."` -- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"` - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue with your work - -## Getting Started -1. Read the protocol document thoroughly -2. Review the spec and plan (if available) -3. Begin implementation following the protocol phases - ---- - -## Protocol Reference (full text) -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/aspir/consult-types/impl-review.md b/codev-skeleton/protocols/aspir/consult-types/impl-review.md index de01b8d00..7028b4947 100644 --- a/codev-skeleton/protocols/aspir/consult-types/impl-review.md +++ b/codev-skeleton/protocols/aspir/consult-types/impl-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev-skeleton/protocols/aspir/consult-types/phase-review.md b/codev-skeleton/protocols/aspir/consult-types/phase-review.md index de01b8d00..7028b4947 100644 --- a/codev-skeleton/protocols/aspir/consult-types/phase-review.md +++ b/codev-skeleton/protocols/aspir/consult-types/phase-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev-skeleton/protocols/aspir/consult-types/plan-review.md b/codev-skeleton/protocols/aspir/consult-types/plan-review.md index 485ff3183..b278aa4ea 100644 --- a/codev-skeleton/protocols/aspir/consult-types/plan-review.md +++ b/codev-skeleton/protocols/aspir/consult-types/plan-review.md @@ -1,44 +1,28 @@ # Plan Review Prompt ## Context -You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it. + +You are reviewing an implementation plan during the Plan phase. The spec is already approved; judge whether the plan adequately describes HOW to implement it. ## Baked Decisions -If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. +If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Spec Coverage** - - Does the plan address all requirements in the spec? - - Are there spec requirements not covered by any phase? - - Are there phases that go beyond the spec scope? - -2. **Phase Breakdown** - - Are phases appropriately sized (not too large or too small)? - - Is the sequence logical (dependencies respected)? - - Can each phase be completed and committed independently? - -3. **Technical Approach** - - Is the implementation approach sound? - - Are the right files/modules being modified? - - Are there obvious better approaches being missed? +- **Spec coverage** — every spec requirement is addressed by some phase; nothing goes beyond the spec's scope. +- **Phase breakdown** — phases are appropriately sized, logically sequenced (dependencies respected), and each can be completed and committed independently. +- **Technical approach** — the approach is sound, the right files/modules are targeted, and no obviously better approach is being missed. +- **Testability** — each phase has clear test criteria and the spec's edge cases are addressable. +- **Risk** — blockers and cross-system dependencies are identified; the plan is realistic given the constraints. -4. **Testability** - - Does each phase have clear test criteria? - - Will the Defend step (writing tests) be feasible? - - Are edge cases from the spec addressable? - -5. **Risk Assessment** - - Are there potential blockers not addressed? - - Are dependencies on other systems identified? - - Is the plan realistic given constraints? +The spec is already approved — do not re-litigate spec decisions. Judge the plan as a guide a builder can follow successfully; verify referenced file paths look accurate. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -52,14 +36,6 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Plan is ready for human review -- `REQUEST_CHANGES`: Significant issues with approach or coverage -- `COMMENT`: Minor suggestions, plan is workable but could improve - -## Notes - -- The spec has already been approved - don't re-litigate spec decisions -- Focus on the quality of the plan as a guide for builders -- Consider: Would a builder be able to follow this plan successfully? -- If referencing existing code, verify file paths seem accurate +- `APPROVE`: plan is ready for human review. +- `REQUEST_CHANGES`: significant issues with approach or coverage. +- `COMMENT`: minor suggestions; the plan is workable but could improve. diff --git a/codev-skeleton/protocols/aspir/consult-types/pr-review.md b/codev-skeleton/protocols/aspir/consult-types/pr-review.md index 837cdea33..6b9a3e82a 100644 --- a/codev-skeleton/protocols/aspir/consult-types/pr-review.md +++ b/codev-skeleton/protocols/aspir/consult-types/pr-review.md @@ -1,44 +1,24 @@ # PR Ready Review Prompt ## Context -You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. -## Focus Areas - -1. **Completeness** - - Are all spec requirements implemented? - - Are all plan phases complete? - - Is the review document written (`codev/reviews/XXXX-name.md`)? - - Are all commits properly formatted (`[Spec XXXX][Phase]`)? - -2. **Test Status** - - Do all tests pass? - - Is test coverage adequate for the changes? - - Are there any skipped or flaky tests? +You are performing the final self-check during the Review phase — the builder has completed all implementation phases and is about to open the PR. This is the last check before the work goes to the architect for integration review. -3. **Code Cleanliness** - - Is there any debug code left in? - - Are there any TODO comments that should be resolved? - - Are there any `// REVIEW:` comments that weren't addressed? - - Is the code properly formatted? - -4. **Documentation** - - Are inline comments clear where needed? - - Is the review document comprehensive? - - Are any new APIs documented? +## Focus Areas -5. **PR Readiness** - - Is the branch up to date with its base (the integration branch the PR targets)? - - Are commits atomic and well-described? - - Is the change diff reasonable in size? +- **Completeness** — all spec requirements implemented, all plan phases complete, the review document written (`codev/reviews/XXXX-name.md`), and commits in the `[Spec XXXX][Phase]` format. +- **Test Status** — all tests pass, coverage is adequate for the changes, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO` / `// REVIEW:` left unaddressed, code properly formatted. +- **Documentation** — inline comments clear where needed, the review document comprehensive, new APIs documented. +- **PR Readiness** — the branch is up to date with its base (the integration branch the PR targets), commits are atomic and well-described, and the diff size is reasonable. ## Scope -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -63,14 +43,8 @@ PR_SUMMARY: | - [How to test] ``` -**Verdict meanings:** -- `APPROVE`: Ready to create PR -- `REQUEST_CHANGES`: Issues to fix before PR creation -- `COMMENT`: Minor items, can create PR but note feedback - -## Notes +- `APPROVE`: ready to create the PR. +- `REQUEST_CHANGES`: issues to fix before PR creation. +- `COMMENT`: minor items; can create the PR but note the feedback. -- This is the builder's final self-review before hand-off -- The PR_SUMMARY in your output can be used as the PR description -- Focus on "is this ready for someone else to review" not "is this perfect" -- Any issues found here are cheaper to fix than during integration review +The `PR_SUMMARY` block can be used directly as the PR description. diff --git a/codev-skeleton/protocols/aspir/consult-types/spec-review.md b/codev-skeleton/protocols/aspir/consult-types/spec-review.md index 73e346e00..48f0c495b 100644 --- a/codev-skeleton/protocols/aspir/consult-types/spec-review.md +++ b/codev-skeleton/protocols/aspir/consult-types/spec-review.md @@ -1,46 +1,28 @@ # Specification Review Prompt ## Context -You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval. + +You are reviewing a feature specification during the Specify phase, before it goes to human approval. Judge whether the spec is complete, correct, feasible, and clear enough for a builder to plan from. ## Baked Decisions If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Completeness** - - Are all requirements clearly stated? - - Are success criteria defined? - - Are edge cases considered? - - Is scope well-bounded (not too broad or vague)? - -2. **Correctness** - - Do requirements make sense technically? - - Are there contradictions? - - Is the problem statement accurate? - -3. **Feasibility** - - Can this be implemented with available tools/constraints? - - Are there obvious technical blockers? - - Is the scope realistic for a single spec? +- **Completeness** — requirements, success criteria, and edge cases are stated; scope is bounded, not vague. +- **Correctness** — the requirements are technically sound and internally consistent; the problem statement is accurate. +- **Feasibility** — implementable within the stated tools and constraints, with no obvious blockers. +- **Clarity** — a builder would know what to build; acceptance criteria are testable; terminology is consistent. +- **Structure** — the spec follows the delivered template (`protocols/spir/templates/spec.md`), which the specify prompt inlines. A spec that ignores the template's headings — usually because the builder pattern-matched an older spec in `codev/specs/` — is a defect: `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). A single genuinely-inapplicable section reduced to a one-line "N/A — [reason]" with its heading kept is fine, not grounds for `REQUEST_CHANGES`. -4. **Clarity** - - Would a builder understand what to build? - - Are acceptance criteria testable? - - Is terminology consistent? - -5. **Structure** - - The specify prompt delivers a canonical spec template (`protocols/spir/templates/spec.md`) inline. Does the spec actually follow it? - - Required headings, in order: `## Metadata`, `## Clarifying Questions Asked`, `## Problem Statement`, `## Current State`, `## Desired State`, `## Stakeholders`, `## Success Criteria`, `## Constraints`, `## Assumptions`, `## Solution Approaches`, `## Open Questions`, `## Performance Requirements`, `## Security Considerations`, `## Test Scenarios`, `## Dependencies`, `## References`, `## Risks and Mitigation`, `## Expert Consultation`, `## Approval`, `## Notes`. - - A free-form spec that reads well but ignores the template is a **defect**, not a style preference — it usually means the builder pattern-matched an older spec in `codev/specs/` instead of the delivered template. `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). - - A section that genuinely does not apply may be reduced to a one-line "N/A — [reason]", but the heading should remain. Do not `REQUEST_CHANGES` over one such section. +You are reviewing the specification (WHAT is built), not code or implementation (HOW) — that is the plan and implementation reviews. Be constructive: name the issue and suggest a fix. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -54,14 +36,6 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Spec is ready for human review -- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but consider feedback - -## Notes - -- You are NOT reviewing code - you are reviewing the specification document -- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review) -- Be constructive - identify issues AND suggest solutions -- If the spec references other specs, note if context seems missing +- `APPROVE`: spec is ready for human review. +- `REQUEST_CHANGES`: significant issues must be fixed first. +- `COMMENT`: minor suggestions; can proceed but consider the feedback. diff --git a/codev-skeleton/protocols/aspir/prompts/implement.md b/codev-skeleton/protocols/aspir/prompts/implement.md index bacc8502e..1dfb7e6eb 100644 --- a/codev-skeleton/protocols/aspir/prompts/implement.md +++ b/codev-skeleton/protocols/aspir/prompts/implement.md @@ -1,10 +1,10 @@ # IMPLEMENT Phase Prompt -You are executing the **IMPLEMENT** phase of the SPIR protocol. +You are executing the **IMPLEMENT** phase of the ASPIR protocol. -## Your Goal +## Goal -Write clean, well-structured code AND tests that implement the current plan phase. +Implement the current plan phase — code and tests — so it matches the spec and passes build and tests. ## Context @@ -13,203 +13,34 @@ Write clean, well-structured code AND tests that implement the current plan phas - **Current State**: {{current_state}} - **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}} -## ⚠️ SCOPE RESTRICTION — READ THIS FIRST +## Scope: this phase only -**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).** +Your scope is exactly `{{plan_phase_id}}` ({{plan_phase_title}}), whose details are included below under "Current Plan Phase Details". Other phases are handled in later porch iterations — do not implement them, and do not read the full plan and build everything you see. Read `codev/specs/{{project_id}}-*.md` for requirements, but implement only what this phase requires. -- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations. -- **DO NOT** read the full plan file and implement everything you see. -- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope. -- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires. +When you signal `PHASE_COMPLETE`, porch runs the 3-way consultation, checks that tests exist and pass, and either respawns you with feedback or commits and moves to the next phase. -## What Happens After You Finish +## What must be true when you finish -When you signal `PHASE_COMPLETE`, porch will: -1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation -2. Check that tests exist and pass -3. If reviewers request changes, you'll be respawned with their feedback -4. Once approved, porch commits and moves to the next plan phase - -## Spec Compliance (CRITICAL) - -**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".** - -### Trust Hierarchy - -``` -SPEC (source of truth) - ↓ -PLAN (implementation guide derived from spec) - ↓ -EXISTING CODE (NOT TRUSTED - must be validated against spec) -``` - -**Never trust existing code over the spec.** Previous implementations may have drifted. - -### Pre-Implementation Sanity Check (PISC) - -**Before writing ANY code:** - -1. ✅ "Have I read the spec in the last 30 minutes?" -2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?" -3. ✅ "Does my approach match the spec's Technical Implementation section?" -4. ✅ "If the spec has code examples, am I following them?" -5. ✅ "Does the existing code I'm building on actually match the spec?" - -**If ANY answer is "no" or "unsure" → STOP and re-read the spec.** - -### Avoiding "Fixing Mode" - -A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to: -- Cargo-culting patterns that may be wrong -- Building on broken foundations -- Implementing something different from the spec - -**When you catch yourself "fixing" code:** -1. STOP -2. Ask: "What does the spec say about this?" -3. Re-read the spec's Traps to Avoid section -4. Verify existing code matches the spec before building on it - -## Prerequisites - -Before implementing, verify: -1. Previous phase (if any) is committed to git -2. You've read the plan phase you're implementing -3. You understand the success criteria for this phase -4. Dependencies from earlier phases are available - -## Process - -### 1. Review the Plan Phase - -Read the current phase in the plan: -- What is the objective? -- What files need to be created/modified? -- What are the success criteria? -- What dependencies exist? - -### 2. Set Up - -- Verify you're on the correct branch -- Check that previous phase is committed: `git log --oneline -5` -- Ensure build passes before starting: `npm run build` (or equivalent) - -### 3. Implement the Code - -Write the code following these principles: - -**Code Quality Standards**: -- Self-documenting code (clear names, obvious structure) -- No commented-out code -- No debug prints in final code -- Explicit error handling -- Follow project style guide - -**Implementation Approach**: -- Work on one file at a time -- Make small, incremental changes -- Document complex logic with comments - -### 4. Write Tests - -**Tests are required.** For each piece of functionality you implement: - -- Write unit tests for core logic -- Write integration tests if the phase involves multiple components -- Test error cases and edge conditions -- Ensure tests are deterministic (no flaky tests) - -**Test file locations** (follow project conventions): -- `tests/` or `__tests__/` directories -- `*.test.ts` or `*.spec.ts` naming - -### 5. Verify Everything Works - -Run both build and tests: - -```bash -npm run build # Must pass -npm test # Must pass -``` - -**Important**: Don't assume these commands exist. Check `package.json` first. - -Fix any errors before signaling completion. - -### 6. Self-Review - -Before signaling completion: -- Read through all code changes -- Read through all test changes -- Verify code matches the spec requirements -- Ensure no accidental debug code -- Check test coverage is adequate - -## Output - -When complete, you should have: -- Modified/created source files as specified in the plan phase -- Tests covering the new functionality -- All build checks passing -- All tests passing +- **The implementation matches the spec.** The spec is the source of truth; the plan derives from it; existing code is not trusted until validated against the spec, because earlier work may have drifted. Code that "works" but diverges from the spec is wrong. When you notice yourself patching symptoms in existing code, stop and re-check what the spec actually requires before building further. +- **Tests exist and are meaningful.** Unit tests for the core logic, integration tests where the phase spans components, and coverage of error and edge cases. Tests are deterministic. Follow the project's existing test locations and naming. +- **Build and tests pass.** Confirm the actual project commands (check `package.json` rather than assuming `npm run build` / `npm test` exist) and run them; fix failures before signaling. +- **The change is clean.** Self-documenting names, explicit error handling, no commented-out or debug code, only the files this phase touches — the simplest solution that satisfies the phase, not more. ## Signals -When implementation AND tests are complete and passing: - -``` -PHASE_COMPLETE -``` - -If you encounter a blocker: - -``` -BLOCKED:reason goes here -``` - -If you need spec/plan clarification: - -``` - -Your specific questions here - -``` - -## Important Notes - -1. **Follow the plan** - Implement what's specified, not more -2. **Don't over-engineer** - Simplest solution that works -3. **Don't skip error handling** - But don't go overboard either -4. **Keep changes focused** - Only touch files in this phase -5. **Build AND tests must pass** - Don't signal complete until both pass -6. **Write tests** - Every implementation phase needs tests - -## What NOT to Do - -- Don't modify files outside this phase's scope -- Don't add features not in the spec -- Don't leave TODO comments for later (fix now or note as blocker) -- Don't skip writing tests -- Don't use `git add .` or `git add -A` when you commit (security risk) - -## Handling Problems - -**If the plan is unclear**: -Signal `AWAITING_INPUT` with your specific question. - -**If you discover the spec is wrong**: -Signal `BLOCKED` and explain the issue. The Architect may need to update the spec. - -**If a dependency is missing**: -Signal `BLOCKED` with details about what's missing. - -**If build or tests fail and you can't fix it**: -Signal `BLOCKED` with the error message. - -**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use workarounds to avoid the failure -3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up -5. Commit the skip and continue with your work +- Implementation and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Blocked — the plan is wrong, the spec is wrong, a dependency is missing, or build/tests fail in a way you cannot resolve: + ``` + BLOCKED:reason goes here + ``` +- Need spec/plan clarification: + ``` + + Your specific questions here + + ``` + +A blocker is a signal, not a silent workaround: never edit `status.yaml` or bypass a porch check to force a green. diff --git a/codev-skeleton/protocols/aspir/prompts/plan.md b/codev-skeleton/protocols/aspir/prompts/plan.md index 2c12250dd..de241ea21 100644 --- a/codev-skeleton/protocols/aspir/prompts/plan.md +++ b/codev-skeleton/protocols/aspir/prompts/plan.md @@ -1,10 +1,10 @@ # PLAN Phase Prompt -You are executing the **PLAN** phase of the SPIR protocol. +You are executing the **PLAN** phase of the ASPIR protocol. -## Your Goal +## Goal -Transform the approved specification into an executable implementation plan with clear phases. +Turn the approved spec into an executable plan at `codev/plans/{{artifact_name}}.md`: a phase breakdown a builder can implement one phase at a time. ## Context @@ -14,105 +14,41 @@ Transform the approved specification into an executable implementation plan with - **Spec File**: `codev/specs/{{artifact_name}}.md` - **Plan File**: `codev/plans/{{artifact_name}}.md` -## Prerequisites +## What must be true when you finish -Before planning, verify: -1. The specification exists and has been approved -2. You've read and understood the entire spec -3. Success criteria are clear and measurable +- **The plan derives from the spec.** You have read the whole spec — its functional and non-functional requirements, constraints, and success criteria — and the plan validates against them. +- **The work is decomposed into phases, each of which is:** + - **self-contained** — a complete unit of functionality; + - **independently testable** — verifiable on its own; + - **valuable** — delivers observable progress; + - **committable** — a single atomic commit. -## Process - -### 1. Analyze the Specification - -Read the spec thoroughly. Identify: -- All functional requirements -- Non-functional requirements -- Dependencies and constraints -- Success criteria to validate against - -### 2. Identify Implementation Phases - -Break the work into logical phases. Each phase should be: -- **Self-contained** - A complete unit of functionality -- **Independently testable** - Can be verified on its own -- **Valuable** - Delivers observable progress -- **Committable** - Can be a single atomic commit - -Good phase examples: -- "Database Schema" - Creates all tables/migrations -- "Core API Endpoints" - Implements main REST routes -- "Authentication Flow" - Handles login/logout/session - -Bad phase examples: -- "Setup" - Too vague -- "Part 1" - Not descriptive -- "Everything" - Not broken down - -### 3. Define Each Phase - -For each phase, document: -- **Objective** - Single clear goal -- **Files to modify/create** - Specific paths -- **Dependencies** - Which phases must complete first -- **Success criteria** - How to know it's done -- **Test approach** - What tests will verify it - -### 4. Order Phases by Dependencies - -Arrange phases so dependencies are satisfied: -``` -Phase 1: Database Schema (no dependencies) -Phase 2: Data Models (depends on Phase 1) -Phase 3: API Endpoints (depends on Phase 2) -Phase 4: Frontend Integration (depends on Phase 3) -``` - -### 5. Finalize - -After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. + A phase name states what it delivers ("Database schema", "Authentication flow"), not a position ("Setup", "Part 1"). +- **Each phase carries its own contract:** objective, the specific files it creates or modifies, which earlier phases it depends on, its success criteria, and how it will be tested. +- **Phases are ordered so dependencies are satisfied before the phase that needs them.** ## Output -Create the plan file at `codev/plans/{{artifact_name}}.md`, following the template below: +Write the plan to `codev/plans/{{artifact_name}}.md` using the template below as its interface: {{> protocols/spir/templates/plan.md}} ## Signals -Emit appropriate signals based on your progress: - -- After completing the plan draft: +- Draft done: ``` PLAN_DRAFTED ``` -## Commit Cadence +## Commit cadence -Make commits at these milestones: +Commit at each milestone, staging the plan file explicitly: +```bash +git add codev/plans/{{artifact_name}}.md +``` 1. `[Spec {{project_id}}] Initial implementation plan` 2. `[Spec {{project_id}}] Plan with multi-agent review` 3. `[Spec {{project_id}}] Plan with user feedback` 4. `[Spec {{project_id}}] Final approved plan` -**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: -```bash -git add codev/plans/{{artifact_name}}.md -``` - -## Important Notes - -1. **No time estimates** - Don't include hours/days/weeks -3. **Be specific about files** - Exact paths, not "the config file" -4. **Keep phases small** - 1-3 files per phase is ideal -5. **Document dependencies clearly** - Prevents blocked work - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't write code (that's for Implement phase) -- Don't estimate time (meaningless in AI development) -- Don't create phases that can't be independently tested -- Don't skip dependency analysis -- Don't make phases too large (if >5 files, split it) -- Don't use `git add .` or `git add -A` (security risk) +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Plan phase: decompose and sequence the work, do not write code, and do not estimate time. diff --git a/codev-skeleton/protocols/aspir/prompts/review.md b/codev-skeleton/protocols/aspir/prompts/review.md index eabe1b98e..fa2112549 100644 --- a/codev-skeleton/protocols/aspir/prompts/review.md +++ b/codev-skeleton/protocols/aspir/prompts/review.md @@ -1,10 +1,10 @@ # REVIEW Phase Prompt -You are executing the **REVIEW** phase of the SPIR protocol. +You are executing the **REVIEW** phase of the ASPIR protocol. -## Your Goal +## Goal -Perform a comprehensive review, document lessons learned, and prepare for PR submission. +Review the whole implementation, write the retrospective at `codev/reviews/{{artifact_name}}.md`, and open the PR — so porch's consultation and the architect both review a real PR. ## Context @@ -15,218 +15,65 @@ Perform a comprehensive review, document lessons learned, and prepare for PR sub - **Plan File**: `codev/plans/{{artifact_name}}.md` - **Review File**: `codev/reviews/{{artifact_name}}.md` -## Prerequisites +## What must be true when you finish -Before review, verify: -1. All implementation phases are committed -2. All tests are passing -3. Build is passing -4. Spec compliance verified for all phases +- **The work is done and green.** All phases committed (`git log --oneline | grep "[Spec {{project_id}}]"`), build and tests passing, no uncommitted changes. +- **The implementation has been reviewed against the spec** — code quality, architecture fit, and security considered; deviations from the spec noted with their reasons; every success criterion accounted for. +- **The review document exists** at `codev/reviews/{{artifact_name}}.md`, following the template below (its headings, its order — do not pattern-match an older review that predates it). +- **Consultation feedback is captured.** The review carries a `## Consultation Feedback` section that, per phase / round / model, records each concern and its disposition — **Addressed** (changed), **Rebutted** (why it does not apply), or **N/A** (out of scope / handled elsewhere). "No concerns raised — all consultations approved" is the right line when that is true; note COMMENT verdicts and any `CONSULT_ERROR`. Read the consult outputs from `codev/projects/{{project_id}}-*/`. +- **Governance facts are routed by tier** (see below). +- **The PR exists before you signal**, with a close-keyword so merging auto-closes the issue (see below). -Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"` - -## Process - -### 1. Comprehensive Review - -Review the entire implementation: - -**Code Quality**: -- Is the code readable and maintainable? -- Are there any code smells? -- Is error handling consistent? -- Are there any security concerns? - -**Architecture**: -- Does the implementation fit well with existing code? -- Are there any architectural concerns? -- Is the design scalable if needed? - -**Documentation**: -- Is code adequately commented where needed? -- Are public APIs documented? -- Is README updated if needed? - -### 2. Spec Comparison - -Compare final implementation to original specification: - -- What was delivered vs what was specified? -- Any deviations? Document why. -- All success criteria met? - -### 3. Create Review Document +## Output -Create `codev/reviews/{{artifact_name}}.md`, following the template below. Use these headings and this order — do not invent your own structure, and do not pattern-match an earlier review in `codev/reviews/` that predates this template. Steps 3b and 4 below expand on the `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch's review checks grep for the last two by exact heading. +Write the review to `codev/reviews/{{artifact_name}}.md` using the template below as its interface. Steps below expand its `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch greps the produced file for the last two by exact heading. {{> protocols/spir/templates/review.md}} -### 3b. Include Consultation Feedback - -**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded. - -Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model: - -```markdown -## Consultation Feedback - -### Specify Phase (Round 1) - -#### Gemini -- **Concern**: [Summary of the concern] - - **Addressed**: [What was changed to resolve it] - -#### Codex -- **Concern**: [Summary] - - **Rebutted**: [Why the current approach is correct] - -#### Claude -- No concerns raised (APPROVE) - -### Plan Phase (Round 1) -... -``` - -**Response types** — each concern gets exactly one: -- **Addressed**: Builder made a change to resolve the concern -- **Rebutted**: Builder explains why the concern doesn't apply -- **N/A**: Concern is out of scope, already handled elsewhere, or moot - -**Edge cases**: -- If all reviewers approved with no concerns: "No concerns raised — all consultations approved" -- For COMMENT verdicts: include their feedback (non-blocking but useful context) -- For CONSULT_ERROR (model failure): note "Consultation failed for [model]" -- If a phase had multiple rounds, give each round its own subsection +## Route governance facts by tier (Spec 987) -### 4. Update Architecture and Lessons Learned Documentation +Each governance doc has two tiers. **Route** each new fact; do not simply append to the cold archive. -**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing. +- **HOT** — `codev/resources/arch-critical.md` and `lessons-critical.md`: tiny, hard-capped, always injected into every prompt and into CLAUDE.md/AGENTS.md. Add here only a **behavior-changing, cross-cutting** fact a future builder must know up front. The hot files are capped: if one is full, **demote** a weaker entry into its cold counterpart to make room, and keep the hot file's cold-doc map accurate. +- **COLD** — `codev/resources/arch.md` and `lessons-learned.md`: full, on-demand reference for subsystem detail, file locations, one-offs, and spec-narrow recipes. -Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive: -- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer. -- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference. +The review's `## Architecture Updates` and `## Lessons Learned Updates` sections state what you routed where; if nothing qualifies, keep the heading with a one-line reason. Never grow a hot file past its cap by appending — route to cold or displace. The `update-arch-docs` skill encodes this discipline. -**Architecture Updates**: -1. Read `arch-critical.md` (hot) and skim `arch.md` (cold). -2. If this project produced a system-shape fact, route it: - - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate. - - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold). -3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason. +## Create the PR (before signaling) -**Lessons Learned Updates**: -1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold). -2. If this project produced a durable lesson, route it: - - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full). - - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file. -3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason. - -**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject. - -### 4b. Update Other Documentation - -If needed, also update: -- README.md (new features, changed behavior) -- API documentation - -### 5. Final Verification - -Before PR: -- [ ] All tests pass (use project-specific test command) -- [ ] Build passes (use project-specific build command) -- [ ] Lint passes (if configured) -- [ ] No uncommitted changes: `git status` -- [ ] Review document complete - -### 6. Create Pull Request - -**IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that -porch consultation reviews the actual PR, and the architect can review a real PR -when the pr gate fires. - -**PR body requirements**: The PR body MUST include `Closes #` (for feature issues) -or `Fixes #` (for bug issues) for the driving GitHub issue. If the PR closes -multiple issues (e.g. duplicates consolidated), include one keyword per issue. -Without this, GitHub will not auto-close the issue on merge. - -**Exception**: if this PR only partially addresses the issue (e.g. one phase of a -multi-PR effort), DO NOT use `Closes`/`Fixes` — reference the issue with `Refs #` -or `Part of #` instead. The issue stays open until the follow-up PR closes it. +The PR body must carry `Closes #` (feature) or `Fixes #` (bug) for the driving issue — one keyword per issue if several — so GitHub auto-closes on merge. **Exception:** a PR that only partially addresses its issue uses `Refs #` or `Part of #` instead, leaving the issue open for the follow-up. ```bash gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF' ## Summary -[Brief description of the implementation] +[what was implemented] -Closes # +Closes # ## Changes -- [Change 1] -- [Change 2] +- ... ## Testing -- All unit tests passing -- Integration tests added for [X] -- Manual testing completed for [Y] +- ... ## Spec -Link: codev/specs/{{artifact_name}}.md +codev/specs/{{artifact_name}}.md ## Review -Link: codev/reviews/{{artifact_name}}.md +codev/reviews/{{artifact_name}}.md EOF )" ``` -### 7. Signal Completion - -After the PR is created, signal completion. Porch will run 3-way consultation -(Gemini, Codex, Claude) automatically via the verify step. If reviewers request -changes, you'll be respawned with their feedback. - -## Output - -- Review document at `codev/reviews/{{artifact_name}}.md` -- Updated documentation (if needed) -- Pull request created and ready for review - ## Signals -- After review document is complete: +- Review document complete: ``` REVIEW_COMPLETE ``` - -- After PR is created — signal completion so porch runs consultation: +- PR created — signal so porch runs the 3-way consultation: ``` PR_READY ``` -## Important Notes - -1. **Be honest in lessons learned** - Future you will thank present you -3. **Document deviations** - They're not failures, they're learnings -4. **Update methodology** - If you found a better way, document it -5. **Don't skip the checklist** - It catches last-minute issues -6. **Clean PR description** - Makes review easier - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't skip lessons learned ("nothing to report") -- Don't merge your own PR (Architect handles integration) -- Don't leave uncommitted changes -- Don't forget to update documentation -- Don't rush this phase - it's valuable for learning -- Don't use `git add .` or `git add -A` (security risk) - -## Review Prompts for Reflection - -Ask yourself: -- What surprised me during implementation? -- Where did I spend the most time? Was it avoidable? -- What would have helped me go faster? -- Did the spec adequately describe what was needed? -- Did the plan phases make sense in hindsight? -- What tests caught issues? What tests were unnecessary? - -Capture these reflections in the lessons learned section. +Do not run `consult` (porch handles it) and merge your own PR only after the human approves the `pr` gate — never before. diff --git a/codev-skeleton/protocols/aspir/prompts/specify.md b/codev-skeleton/protocols/aspir/prompts/specify.md index daa5feab2..978b1e0a1 100644 --- a/codev-skeleton/protocols/aspir/prompts/specify.md +++ b/codev-skeleton/protocols/aspir/prompts/specify.md @@ -1,10 +1,10 @@ # SPECIFY Phase Prompt -You are executing the **SPECIFY** phase of the SPIR protocol. +You are executing the **SPECIFY** phase of the ASPIR protocol. -## Your Goal +## Goal -Create a comprehensive specification document that thoroughly explores the problem space and proposed solution. +Produce a specification at `codev/specs/{{artifact_name}}.md` that explores the problem space and the proposed solution well enough that the plan and implementation can follow without re-deciding anything. ## Context @@ -13,137 +13,47 @@ Create a comprehensive specification document that thoroughly explores the probl - **Current State**: {{current_state}} - **Spec File**: `codev/specs/{{artifact_name}}.md` -## Process +## What must be true when you finish -### 0. Check for Existing Spec (ALWAYS DO THIS FIRST) - -**Before asking ANY questions**, check if a spec already exists: - -```bash -ls codev/specs/{{project_id}}-*.md -``` - -**If a spec file exists:** -1. READ IT COMPLETELY - the answers to your questions are already there -2. The spec author has already made the key decisions -3. DO NOT ask clarifying questions - proceed directly to consultation -4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch - -**If no spec exists:** Proceed to Step 1 below. - -### 0.5 Baked Decisions - -Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec. - -If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting. - -### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS) - -Before writing anything, ask clarifying questions to understand: -- What problem is being solved? -- Who are the stakeholders? -- What are the constraints? -- What's in scope vs out of scope? -- What does success look like? - -If this is your first iteration AND no spec exists, ask these questions now and wait for answers. - -**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer. - -**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step. - -### 2. Problem Analysis - -Once you have answers, document: -- The problem being solved (clearly articulated) -- Current state vs desired state -- Stakeholders and their needs -- Assumptions and constraints - -### 3. Solution Exploration - -Generate multiple solution approaches. For each: -- Technical design overview -- Trade-offs (pros/cons) -- Complexity assessment -- Risk assessment - -### 4. Open Questions - -List uncertainties categorized as: -- **Critical** - blocks progress -- **Important** - affects design -- **Nice-to-know** - optimization - -### 5. Success Criteria - -Define measurable acceptance criteria: -- Functional requirements (MUST, SHOULD, COULD) -- Non-functional requirements (performance, security) -- Test scenarios - -### 6. Finalize - -After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. +- **An existing spec is honored, not rewritten.** If `codev/specs/{{project_id}}-*.md` already exists, it carries the architect's decisions — read it fully and refine it in place. Clarifying questions are for the case where no spec exists yet; when one does, the spec is the answer. +- **Baked Decisions are fixed.** If the issue body has a "Baked Decisions" section (any heading level, case-insensitive), copy it verbatim into the spec's Constraints and treat each item as settled — **do not autonomously override** the architect's choices in Solution Exploration. Raise a genuine problem with a baked decision via `afx send architect` rather than overriding it. If two baked decisions contradict each other, do not choose — **pause**, **flag** the contradiction via `afx send`, and wait for resolution. +- **The problem is characterized before solutions are.** Current state vs desired state, stakeholders, assumptions, and constraints are explicit. +- **Solutions are explored, not assumed.** More than one approach is considered, each with its trade-offs and risks, before one is recommended. +- **Open questions are surfaced and ranked** by whether they block progress, shape the design, or are merely nice to know. +- **Success is measurable.** Acceptance criteria are concrete enough to test against. ## Output -Create or update the specification file at `codev/specs/{{artifact_name}}.md`. - -Follow the canonical spec template reproduced below. Use these headings, in this order — do not invent your own structure, and do not pattern-match an earlier spec in `codev/specs/` that predates this template. If a section genuinely does not apply, keep the heading and write a one-line "N/A — [reason]" rather than deleting it. +Write the spec to `codev/specs/{{artifact_name}}.md` using the template below as its interface — these headings, in this order. A section that genuinely does not apply keeps its heading with a one-line `N/A — [reason]` rather than being deleted. Do not pattern-match an older spec in `codev/specs/` that predates this template. {{> protocols/spir/templates/spec.md}} -**IMPORTANT**: Keep spec/plan/review filenames in sync: -- Spec: `codev/specs/{{artifact_name}}.md` -- Plan: `codev/plans/{{artifact_name}}.md` -- Review: `codev/reviews/{{artifact_name}}.md` +Keep the three artifact filenames in sync: spec `codev/specs/{{artifact_name}}.md`, plan `codev/plans/{{artifact_name}}.md`, review `codev/reviews/{{artifact_name}}.md`. ## Signals -Emit appropriate signals based on your progress: - -- When waiting for clarifying question answers, **include your questions in the signal**: +- Waiting on clarifying-question answers — **put the questions inside the signal**, which is displayed prominently to the user: ``` - Please answer these questions: - 1. What should the primary use case be - internal tooling or customer-facing? - 2. What are the key constraints we should consider? - 3. Who are the main stakeholders? + Please answer: + 1. ... + 2. ... ``` - - The content inside the signal tag is displayed prominently to the user. - -- After completing the initial spec draft: +- Initial draft done: ``` SPEC_DRAFTED ``` +## Commit cadence -## Commit Cadence - -Make commits at these milestones: +Commit at each milestone, staging the spec file explicitly: +```bash +git add codev/specs/{{artifact_name}}.md +``` 1. `[Spec {{project_id}}] Initial specification draft` 2. `[Spec {{project_id}}] Specification with multi-agent review` 3. `[Spec {{project_id}}] Specification with user feedback` 4. `[Spec {{project_id}}] Final approved specification` -**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: -```bash -git add codev/specs/{{artifact_name}}.md -``` - -## Important Notes - -1. **Be thorough** - A good spec prevents implementation problems -3. **Be specific** - Vague specs lead to wrong implementations -4. **Include examples** - Concrete examples clarify intent - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't include implementation details (that's for the Plan phase) -- Don't estimate time (AI makes time estimates meaningless) -- Don't start coding (you're in Specify, not Implement) -- Don't use `git add .` or `git add -A` (security risk) +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Specify phase: no implementation detail (that is the plan), no code, no time estimates. diff --git a/codev-skeleton/protocols/aspir/protocol.md b/codev-skeleton/protocols/aspir/protocol.md index 6cc2caf97..390e74049 100644 --- a/codev-skeleton/protocols/aspir/protocol.md +++ b/codev-skeleton/protocols/aspir/protocol.md @@ -1,100 +1,52 @@ # ASPIR Protocol -> **ASPIR** = **A**utonomous **S**pecify → **P**lan → **I**mplement → **R**eview -> -> Identical to SPIR but without human approval gates on spec and plan phases. -> Each phase has one build-verify cycle with 3-way consultation. +Autonomous SPIR: the same phases, artifacts, consultations and checks, with the **spec and plan +human gates absent**. The builder runs Specify → Plan → Implement without stopping, and a human +still reviews everything at the `pr` gate before merge. -## What is ASPIR? +Use ASPIR for trusted, low-risk work where reviewing the approach up front would cost more than +it saves, and deferring that review to the PR is acceptable. When getting the shape wrong would +be expensive to unwind, use SPIR and take the gates. -ASPIR is an autonomous variant of the SPIR protocol. It follows the exact same phases (Specify → Plan → Implement → Review) with the same 3-way consultations, checks, and PR flow — but removes the `spec-approval` and `plan-approval` human gates. +## The state machine -This means the builder proceeds automatically from Specify → Plan → Implement without waiting for human approval at each gate. The `pr` gate in the Review phase is preserved — a human still reviews all code before merge. +Phases, gates and checks — note that `specify` and `plan` carry **no gate at all**; they are not +auto-approved, they are ungated: -### Differences from SPIR - -| Aspect | SPIR | ASPIR | -|--------|------|-------| -| Spec gate (`spec-approval`) | Human must approve | Auto-approved | -| Plan gate (`plan-approval`) | Human must approve | Auto-approved | -| PR gate (`pr`) | Human must approve | Human must approve | -| Phases | Specify → Plan → Implement → Review | Same | -| 3-way consultations | Yes, every phase | Same | -| Checks (build, tests, PR) | Yes | Same | -| Prompts / templates | Full set | Same prompts; templates included from SPIR (no copies) | - -### When to Use ASPIR - -Use ASPIR instead of SPIR when: - -- The work is **trusted and low-risk** — internal tooling, protocol additions, well-understood features -- The architect has **pre-written and approved** the spec before spawning -- The scope is **self-contained** with low blast radius -- You want **full SPIR discipline** (consultations, phased implementation, review) without waiting at gates - -### When NOT to Use ASPIR - -Use SPIR instead when: - -- The feature involves **novel architecture** or unclear requirements -- The spec needs **iterative human feedback** during drafting -- The work is **high-risk** — security-sensitive, user-facing, or broadly impactful -- You want to **review and adjust** the plan before implementation starts - -## Baked Decisions (Optional) - -When filing an issue for ASPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`. - -## Protocol Phases - -ASPIR follows the same four phases as SPIR. For full phase documentation, see the [SPIR protocol](../spir/protocol.md). - -### S - Specify -Write specification with 3-way review (Gemini, Codex, Claude). **No human gate** — proceeds directly to Plan after verification. +```json +{{> protocols/aspir/protocol.json}} +``` -### P - Plan -Write implementation plan with 3-way review. **No human gate** — proceeds directly to Implement after verification and checks pass. +## Everything else is SPIR -### I - Implement -Execute each plan phase with build-verify cycle. Same as SPIR — no gate between phases (SPIR also has no gate here). +Artifacts (`codev/specs/`, `codev/plans/`, `codev/reviews/`, same base filename), the +build-verify cycle per plan phase, mandatory 3-way consultation at each verify step, the +machine-readable `phases` block in the plan, commit and branch conventions, and Baked Decisions +handling are all identical to SPIR. ASPIR includes SPIR's templates rather than copying them, so +there is one set to keep correct. -### R - Review -Final review, PR preparation, and 3-way review. **PR gate preserved** — builder stops and waits for human approval before merge. +See `protocols/spir/protocol.md` for that shared substance. -## Usage +## Baked Decisions -```bash -# Spawn a builder using ASPIR -afx spawn 42 --protocol aspir +An issue may carry a `## Baked Decisions` section pinning architectural choices the architect +does not want re-litigated — typically **language**, **framework**, deployment shape, key +**dependencies**, or decisions deferred to a later spec. -# The builder runs autonomously through Specify → Plan → Implement -# and stops only at the PR gate in the Review phase -``` +Every item in it is fixed. Copy the section verbatim into the spec's Constraints and do not +re-open it in the spec, plan, or review; CMAP reviewers will not propose alternatives unless the +spec fails to honour one. If two items contradict each other, do not choose — surface the +contradiction and wait. -## File Structure +**Absence is the no-op default**: an issue with no such section is an invitation to explore +freely, not an omission to be filled in. -``` -codev/protocols/aspir/ -├── protocol.json # Protocol definition (SPIR minus gates) -├── protocol.md # This file -├── builder-prompt.md # Builder instructions (same as SPIR) -├── prompts/ -│ ├── specify.md # Specify phase prompt (same as SPIR) -│ ├── plan.md # Plan phase prompt (same as SPIR) -│ ├── implement.md # Implement phase prompt (same as SPIR) -│ └── review.md # Review phase prompt (same as SPIR) -└── consult-types/ - ├── spec-review.md # Spec consultation guide (same as SPIR) - ├── plan-review.md # Plan consultation guide (same as SPIR) - ├── impl-review.md # Impl consultation guide (same as SPIR) - ├── phase-review.md # Phase consultation guide (same as SPIR) - └── pr-review.md # PR consultation guide (same as SPIR) -``` +The architect can **amend or rescind** a baked decision at any time by updating the issue and +respawning, or by sending the builder a direct instruction via `afx send`. -ASPIR ships **no `templates/` directory**. Its phase prompts deliver SPIR's canonical -templates directly, via an include directive pointing at `protocols/spir/templates/`, so -there is exactly one copy of each template and it cannot drift between the two protocols. -(Written as a path, not as a literal include: an include directive in prose would be -expanded — and silently emptied — when this file is delivered to a builder.) +## The one thing to be careful about -All files except `protocol.json` and `protocol.md` are identical to their SPIR counterparts. +Without the spec and plan gates, nothing external catches a misread of the issue until the PR. +If the spec you write surprises you — if it turns out larger, or more architectural, than the +issue implied — that is the signal ASPIR was the wrong choice. Say so early rather than +carrying the misfit through to review. diff --git a/codev-skeleton/protocols/bugfix/builder-prompt.md b/codev-skeleton/protocols/bugfix/builder-prompt.md index aefa35a25..3ad3ba278 100644 --- a/codev-skeleton/protocols/bugfix/builder-prompt.md +++ b/codev-skeleton/protocols/bugfix/builder-prompt.md @@ -4,28 +4,21 @@ You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the BUGFIX protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Run consultations manually when the protocol calls for them -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way review** — always follow porch next → porch done cycle + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the BUGFIX protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. {{#if issue}} ## Issue #{{issue.number}} @@ -33,43 +26,28 @@ Follow the BUGFIX protocol. Read and internalize the protocol before starting an **Description**: {{issue.body}} +{{/if}} ## Your Mission + 1. Reproduce the bug -2. Identify root cause -3. Implement fix (< 300 LOC) -4. Add regression test -5. Create PR with "Fixes #{{issue.number}}" in body -6. Notify architect via `afx send architect "PR #N ready for review (fixes #{{issue.number}})"` +2. Identify the root cause — **no code in the investigate phase** +3. Implement the minimal fix (<300 LOC) +4. Add a regression test that **fails without the fix and passes with it** +5. Open a PR with `Fixes #{{issue.number}}` in the body +6. Notify: `afx send architect "PR #N ready for review (fixes #{{issue.number}})"` + +When merging, use `gh pr merge --merge` **without** `--delete-branch` — you are checked out on +that branch in a worktree. + +If the fix outgrows BUGFIX (>300 LOC, architectural impact, or an unclear root cause after +investigation), stop and say so: -If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via: ```bash afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to SPIR." ``` ## Notifications -Always use `afx send architect "..."` to notify the architect at key moments: -- **PR ready**: `afx send architect "PR #N ready for review (fixes #{{issue.number}})"` -- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."` -- **Blocked**: `afx send architect "Blocked on issue #{{issue.number}}: [reason]"` -{{/if}} - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue with your work - -## Getting Started -1. Read the BUGFIX protocol -2. Review the issue details -3. Reproduce the bug before fixing - ---- - -## Protocol Reference (full text) -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/bugfix/consult-types/impl-review.md b/codev-skeleton/protocols/bugfix/consult-types/impl-review.md index 90d6a2d9e..500da5cc5 100644 --- a/codev-skeleton/protocols/bugfix/consult-types/impl-review.md +++ b/codev-skeleton/protocols/bugfix/consult-types/impl-review.md @@ -1,58 +1,40 @@ # Implementation Review Prompt (BUGFIX) ## Context -You are reviewing in-progress fix work for a **BUGFIX protocol** project. A builder has investigated a GitHub Issue, identified a root cause, and is implementing the fix + regression test. Your job is to verify the fix matches the issue's symptom and meets BUGFIX standards. -**BUGFIX is not SPIR.** There is **no spec, no plan, and no review document**. The GitHub Issue is the spec. The PR body will be the review. Do **not** request changes for missing `codev/specs/`, `codev/plans/`, or `codev/reviews/` artifacts. +You are reviewing in-progress fix work for a **BUGFIX protocol** project. A builder has investigated a GitHub Issue, identified a root cause, and is implementing the fix + regression test. Verify the fix matches the issue's symptom and meets BUGFIX standards. -## CRITICAL: Verify Before Flagging +**BUGFIX is not SPIR.** There is **no spec, no plan, and no review document** — the GitHub Issue is the spec, and the PR body will be the review. Do **not** request changes for missing `codev/specs/`, `codev/plans/`, or `codev/reviews/` artifacts. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions. -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs. -3. **Do not assume** your training data reflects the version in use — verify against project files. -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed. +## Verify before flagging -## Focus Areas - -1. **Issue Adherence** - - Does the implementation actually resolve the symptom described in the GitHub Issue? - - Is the root cause fix targeted, or is it a workaround that masks the symptom? - -2. **Regression Test** - - Is there a regression test that exercises the exact scenario from the issue? - - Without the fix applied, would this test fail? (The whole point.) - - Is the test deterministic? - - If no test was added, has the builder justified why (e.g., docs-only change with no testable behavior)? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Scope Discipline** - - Is the change focused on the root cause only — no unrelated refactors, no drive-by fixes? - - Is the net diff staying under ~300 LOC? If it has grown larger, should this escalate to SPIR/TICK? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues introduced by the fix? - - Are error cases handled appropriately for the path that was changed? - - No debug code, stray `console.log`, or commented-out code. +## Focus Areas -5. **Test Status** - - Existing tests still pass. - - Build still passes. - - No new flaky tests introduced. +- **Issue resolution** — the fix actually resolves the symptom in the issue, targeting the root cause rather than masking it with a workaround. +- **Regression test** — a deterministic test exercises the exact scenario from the issue and **would fail without the fix**. If none was added, the builder has justified why (e.g. a docs-only change with no testable behavior). +- **Scope discipline** — the change is focused on the root cause only (no unrelated refactors or drive-by fixes) and stays under ~300 LOC; if it grew larger, it should escalate to SPIR/TICK. +- **Code quality** — readable and maintainable; no bugs introduced; error cases on the changed path handled; no debug or commented-out code. +- **Test status** — existing tests and the build still pass; no new flaky tests. ## Out of Scope (Do NOT request changes for) -The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons: +These are **not** part of the BUGFIX protocol and must **not** be cited as `REQUEST_CHANGES` reasons: - Missing `codev/specs/-*.md`, `codev/plans/-*.md`, or `codev/reviews/-*.md` — BUGFIX produces none of these. The GitHub Issue is the spec; the PR body is the review. -- Commit format `[Spec NNNN][Phase]` — BUGFIX uses `Fix #N: ...` or `[Bugfix #N] ...`. This is the protocol-mandated format, **not** a bug. +- Commit format `[Spec NNNN][Phase]` — BUGFIX uses `Fix #N: ...` or `[Bugfix #N] ...`. That is the protocol-mandated format, **not** a bug. - `status.yaml` fields such as `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it manually. Treat porch state as informational, not a fixable issue. - "Plan Alignment" or "Spec Adherence" — there is no plan and no spec to align with. -- Phase-scoping concerns — BUGFIX is single-phase by design. There are no plan phases to scope against. +- Phase-scoping concerns — BUGFIX is single-phase by design; there are no plan phases to scope against. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -66,14 +48,8 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Fix and regression test are in good shape; builder can proceed to PR creation. -- `REQUEST_CHANGES`: Real BUGFIX-relevant issues (fix doesn't resolve the symptom, missing regression test without justification, scope creep, broken existing tests, etc.). -- `COMMENT`: Minor suggestions; builder can proceed but should consider the feedback. - -## Notes +- `APPROVE`: fix and regression test are in good shape; builder can proceed to PR creation. +- `REQUEST_CHANGES`: real BUGFIX-relevant issues (fix doesn't resolve the symptom, missing regression test without justification, scope creep, broken existing tests). +- `COMMENT`: minor suggestions; builder can proceed but should consider the feedback. -- This is an implementation-level review, not the final PR review. -- Focus on "does this fix actually resolve the issue, and is it protected by a regression test" — not on artifacts from other protocols. -- If referencing line numbers, use `file:line` format. -- The builder needs actionable, protocol-correct feedback to continue. +This is an implementation-level review, not the final PR review — focus on "does this fix resolve the issue, protected by a regression test", not on artifacts from other protocols. diff --git a/codev-skeleton/protocols/bugfix/consult-types/pr-review.md b/codev-skeleton/protocols/bugfix/consult-types/pr-review.md index efdb7a176..50f8fde31 100644 --- a/codev-skeleton/protocols/bugfix/consult-types/pr-review.md +++ b/codev-skeleton/protocols/bugfix/consult-types/pr-review.md @@ -1,64 +1,35 @@ # PR Ready Review Prompt (BUGFIX) ## Context -You are performing a final self-check during the PR phase of the **BUGFIX protocol**. The builder has investigated a GitHub Issue, implemented a focused fix, and added a regression test. They are about to create — or have just created — a PR for the architect's integration review. -**BUGFIX is not SPIR.** Do **not** review against the SPIR three-document trinity. The artifacts of a BUGFIX project are: -- The originating **GitHub Issue** (serves as the spec) -- The **code fix** (minimal, focused on root cause) -- A **regression test** that fails without the fix and passes with it -- The **PR body** (Summary, Root Cause, Fix, Test Plan) +You are performing the final self-check during the PR phase of the **BUGFIX protocol**. The builder has investigated a GitHub Issue, implemented a focused fix, and added a regression test, and is about to create — or has just created — the PR for the architect's integration review. -There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file** for a BUGFIX, and there should not be one. The commit format is `Fix #NNNN: ` (or `[Bugfix #NNNN] ...`), **not** `[Spec NNNN][Phase]`. +**BUGFIX is not SPIR.** Do **not** review against the SPIR three-document trinity. A BUGFIX project's artifacts are the originating **GitHub Issue** (the spec), the **code fix** (minimal, root-cause-focused), a **regression test** that fails without the fix and passes with it, and the **PR body** (Summary, Root Cause, Fix, Test Plan). There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file**, and there should not be. The commit format is `Fix #NNNN: ` (or `[Bugfix #NNNN] ...`), **not** `[Spec NNNN][Phase]`. ## Focus Areas -1. **Issue Resolution** - - Does the fix actually resolve the symptom described in the issue? - - Does the PR body include `Fixes #` so the issue auto-closes on merge? - - Does the PR description cover: Summary, Root Cause, Fix, Test Plan? - -2. **Regression Test** - - Is there a regression test that targets the exact scenario from the issue? - - Would the test fail without the fix? (If reviewers can't tell, ask the builder to demonstrate.) - - Is the test deterministic (not flaky)? - - If the fix is documentation-only or otherwise truly untestable, has the builder explicitly justified the absence of a test? - -3. **Scope Discipline** - - Is the change focused on the root cause? No unrelated refactors, no drive-by fixes for other bugs. - - Is the net diff under ~300 LOC (additions + deletions, excluding generated/lockfiles)? - - If the scope grew beyond a bugfix, should the builder have escalated to SPIR/TICK instead? - -4. **Code Cleanliness** - - No debug code, `console.log`, or commented-out blocks left behind. - - No stray TODOs introduced by this fix. - - Code follows existing project conventions. - -5. **Test Status** - - All existing tests pass. - - Build passes. - - No new flaky tests introduced. - -6. **PR Hygiene** - - Commits use the BUGFIX format: `Fix #: ...` or `[Bugfix #] ...` (**not** `[Spec NNNN][Phase]`). - - Branch is up to date with its base (or close enough for clean merge). - - PR is linked to the issue. +- **Issue resolution** — the fix resolves the symptom; the PR body includes `Fixes #` (so the issue auto-closes on merge) and covers Summary, Root Cause, Fix, Test Plan. +- **Regression test** — a deterministic test targets the exact scenario and would fail without the fix; a truly untestable (e.g. docs-only) fix has the absence explicitly justified. +- **Scope discipline** — focused on the root cause, no unrelated refactors or drive-by fixes, net diff under ~300 LOC; if it grew beyond a bugfix, it should have escalated to SPIR/TICK. +- **Code cleanliness** — no debug code, `console.log`, commented-out blocks, or stray TODOs; follows project conventions. +- **Test status** — existing tests and the build pass; no new flaky tests. +- **PR hygiene** — commits use `Fix #: ...` / `[Bugfix #] ...` (**not** `[Spec NNNN][Phase]`), the branch is current with its base, and the PR is linked to the issue. ## Out of Scope (Do NOT request changes for) -The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons: +These are **not** part of the BUGFIX protocol and must **not** be cited as `REQUEST_CHANGES` reasons: - Missing `codev/specs/-*.md` — BUGFIX has no spec; the GitHub Issue is the spec. - Missing `codev/plans/-*.md` — BUGFIX has no plan. -- Missing `codev/reviews/-*.md` — BUGFIX has no review document; review lives in the PR body. +- Missing `codev/reviews/-*.md` — BUGFIX has no review document; the review lives in the PR body. - Commit format `[Spec NNNN][Phase]` — BUGFIX intentionally uses `Fix #N:` / `[Bugfix #N]`. - `status.yaml` fields like `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it directly. Treat porch state as informational, not a fixable issue. - Phase-scoping concerns — BUGFIX is a single-phase protocol; there are no plan phases to scope against. -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +- The syntax of `git diff` examples in review-file prose (e.g. `git diff ci..HEAD` in a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -76,23 +47,18 @@ PR_SUMMARY: | Fixes #. [1-2 sentences on what was fixed.] ## Root Cause - [Brief explanation of what caused the bug] + [What caused the bug] ## Fix - [Brief explanation of the fix] + [What changed] ## Test Plan - [Regression test description] - [Manual verification, if applicable] ``` -**Verdict meanings:** -- `APPROVE`: Bug is resolved, regression test is in place, PR is ready for architect review. -- `REQUEST_CHANGES`: Real BUGFIX-relevant issues to fix (missing regression test, fix doesn't resolve the symptom, scope creep, etc.). -- `COMMENT`: Minor items, can proceed but note feedback. +- `APPROVE`: bug resolved, regression test in place, PR ready for architect review. +- `REQUEST_CHANGES`: real BUGFIX-relevant issues (missing regression test, fix doesn't resolve the symptom, scope creep). +- `COMMENT`: minor items; can proceed but note the feedback. -## Notes - -- This is the builder's final self-review before hand-off to the architect. -- The `PR_SUMMARY` block can be used directly as the PR description. -- Focus on "is this bug actually fixed and protected by a test" — not on artifacts from other protocols. +The `PR_SUMMARY` block can be used directly as the PR description. diff --git a/codev-skeleton/protocols/bugfix/prompts/fix.md b/codev-skeleton/protocols/bugfix/prompts/fix.md index afecc3343..ee57d903e 100644 --- a/codev-skeleton/protocols/bugfix/prompts/fix.md +++ b/codev-skeleton/protocols/bugfix/prompts/fix.md @@ -2,76 +2,31 @@ You are executing the **FIX** phase of the BUGFIX protocol. -## Your Goal +## Goal -Implement the bug fix and add a regression test. Keep it minimal and focused. +Fix the bug with the minimum change, and add a regression test that pins it. ## Context - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## What must be true when you finish -### 1. Implement the Fix +- **The change is minimal and targeted.** Fix the root cause from INVESTIGATE and nothing else — no refactoring of surrounding code, no unrelated features, no other bugs you happen to notice (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions. +- **A regression test pins the fix.** Every bugfix carries a test that **fails without the fix and passes with it**, covers the issue's scenario, and is deterministic. The only exception is a genuinely untestable change (e.g. a CSS-only tweak with no observable behavior) — and then you state why, in the commit message and PR description. +- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling. +- **The change stays within BUGFIX scope.** If the fix grows past ~300 LOC, signal `TOO_COMPLEX` rather than pressing on. -Apply the minimum change needed to resolve the bug: -- Fix the root cause identified in the INVESTIGATE phase -- Do NOT refactor surrounding code -- Do NOT add features beyond what's needed -- Do NOT fix other bugs you happen to notice (file separate issues) - -**Code Quality**: -- Self-documenting code (clear names, obvious structure) -- No commented-out code or debug prints -- Follow existing project conventions - -### 2. Add a Regression Test - -**A regression test is MANDATORY.** Every bugfix MUST include a test unless you provide explicit justification for why a test is impossible (e.g., pure CSS-only change with no testable behavior). If you skip the test, you MUST explain why in your commit message and PR description. - -Write a test that: -- Fails without the fix (demonstrates the bug) -- Passes with the fix (demonstrates the fix works) -- Covers the specific scenario from the issue -- Is deterministic (not flaky) - -Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.). - -### 3. Verify the Fix - -Run build and tests: - -```bash -npm run build # Must pass -npm test # Must pass -``` - -Fix any failures before proceeding. If build/test commands don't exist, check `package.json`. - -### 4. Commit - -Stage and commit your changes: -- Use explicit file paths (never `git add -A` or `git add .`) -- Commit message: `Fix #{{issue.number}}: ` +Commit with an explicit staged path and the message `Fix #{{issue.number}}: `. ## Signals -When fix and tests are complete and passing: - -``` -PHASE_COMPLETE -``` - -If you encounter a blocker: - -``` -BLOCKED:reason goes here -``` - -## Important Notes - -1. **Minimal changes only** — Fix the bug, nothing else -2. **Regression test is MANDATORY** — No fix without a test. If truly untestable, justify in writing. -3. **Build AND tests must pass** — Don't signal complete until both pass -4. **Stay under 300 LOC** — If the fix grows beyond this, signal `TOO_COMPLEX` +- Fix and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Blocked: + ``` + BLOCKED:reason goes here + ``` diff --git a/codev-skeleton/protocols/bugfix/prompts/investigate.md b/codev-skeleton/protocols/bugfix/prompts/investigate.md index ffa54385e..21bee598a 100644 --- a/codev-skeleton/protocols/bugfix/prompts/investigate.md +++ b/codev-skeleton/protocols/bugfix/prompts/investigate.md @@ -2,76 +2,32 @@ You are executing the **INVESTIGATE** phase of the BUGFIX protocol. -## Your Goal +## Goal -Understand the bug, reproduce it, identify the root cause, and assess whether it's fixable within BUGFIX scope (< 300 LOC). +Understand the bug, reproduce it, find the root cause, and decide whether it fits BUGFIX scope (a focused change under ~300 LOC). ## Context - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## What must be true when you finish -### 1. Read the Issue - -Read the full issue description. Identify: -- What is the expected behavior? -- What is the actual behavior? -- Are there reproduction steps? -- Are there error messages or screenshots? - -### 2. Reproduce the Bug - -Before fixing anything, confirm the bug exists: -- Follow the reproduction steps from the issue -- If no steps are given, infer them from the description -- Document the exact reproduction steps you used -- If you **cannot** reproduce, signal `BLOCKED` with details - -### 3. Identify Root Cause - -Trace the bug to its source: -- Read the relevant code paths -- Use grep/search to find related code -- Identify the exact file(s) and line(s) causing the issue -- Understand **why** the bug occurs, not just **where** - -### 4. Assess Complexity - -Determine if this is BUGFIX-appropriate: -- **< 300 LOC change**: Proceed with BUGFIX -- **> 300 LOC or architectural**: Signal `TOO_COMPLEX` to escalate - -Consider: -- How many files need to change? -- Does it require new abstractions or refactoring? -- Are there cascading effects? - -## Output - -By the end of this phase, you should know: -1. The exact root cause -2. Which files need to change -3. The approximate size of the fix -4. Whether it's BUGFIX-appropriate +- **The bug is reproduced, not assumed.** You have confirmed the expected-vs-actual behavior from the issue and established concrete reproduction steps (inferring them if the issue gives none). If you cannot reproduce it, that is a `BLOCKED` signal with what you tried. +- **The root cause is understood** — the exact file(s) and line(s), and *why* the bug happens, not just where. Trace the failure path rather than pattern-matching a symptom. +- **The scope is assessed against BUGFIX's ceiling.** A focused fix under ~300 LOC proceeds; anything larger or architectural (new abstractions, refactors, cascading effects across many files) is a `TOO_COMPLEX` signal to escalate. ## Signals -When investigation is complete: - -``` -PHASE_COMPLETE -``` - -If the bug is too complex for BUGFIX: - -``` -TOO_COMPLEX -``` - -If you're blocked (can't reproduce, missing context, etc.): - -``` -BLOCKED:reason goes here -``` +- Investigation complete (root cause + fix scope known): + ``` + PHASE_COMPLETE + ``` +- Too large or architectural for BUGFIX: + ``` + TOO_COMPLEX + ``` +- Blocked (cannot reproduce, missing context): + ``` + BLOCKED:reason goes here + ``` diff --git a/codev-skeleton/protocols/bugfix/prompts/pr.md b/codev-skeleton/protocols/bugfix/prompts/pr.md index d70d8dfdf..4dd89ff5c 100644 --- a/codev-skeleton/protocols/bugfix/prompts/pr.md +++ b/codev-skeleton/protocols/bugfix/prompts/pr.md @@ -2,32 +2,18 @@ You are executing the **PR** phase of the BUGFIX protocol. -## Your Goal +## Goal -Create a pull request, run CMAP review, and address feedback. +Open the PR, run CMAP review on it, address feedback, and hand off to the architect at the `pr` gate. ## Context - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## Create the PR -### 1. Create the Pull Request - -Create a PR that links to the issue. - -**PR body requirements**: The PR body MUST include `Fixes #` (where `` is -the driving issue number) so GitHub auto-closes the issue on merge. If the PR -fixes multiple issues (e.g. duplicates consolidated), include one `Fixes #` -per issue. Without this, GitHub will not auto-close the issue. - -**Exception**: if this PR only partially addresses the issue, use `Refs #` -or `Part of #` instead of `Fixes` — the issue stays open until a -follow-up PR closes it. - -**Note**: substitute the real issue number for `` — do not leave the -placeholder or any `{{...}}` template tag in the committed PR body. +The PR body must carry `Fixes #` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a PR that only partially addresses the issue uses `Refs #` or `Part of #` instead, leaving it open for the follow-up. Substitute the real number for ``; leave no `{{...}}` tag or `` placeholder in the committed body. ```bash gh pr create --title "Fix #: " --body "$(cat <<'EOF' @@ -35,15 +21,15 @@ gh pr create --title "Fix #: " --body "$(cat <<'EOF' <1-2 sentence description of the bug and fix> -Fixes # +Fixes # ## Root Cause - + ## Fix - + ## Test Plan @@ -54,9 +40,9 @@ EOF )" ``` -### 2. Run CMAP Review +## Run CMAP review -Run 3-way parallel consultation on the PR: +BUGFIX runs its own 3-way consultation on the PR (porch does not do it for you). Dispatch all three in the background: ```bash consult -m gemini --protocol bugfix --type pr & @@ -64,47 +50,26 @@ consult -m codex --protocol bugfix --type pr & consult -m claude --protocol bugfix --type pr & ``` -All three should run in the background (`run_in_background: true`). - -### 3. Wait for Results and Address Feedback - -**DO NOT proceed to step 4 until ALL THREE consultations have returned results.** - -Wait for each background consultation to complete, then read the results: -- Use `TaskOutput` (with `block: true`) to retrieve each consultation result -- Record each model's verdict (APPROVE or REQUEST_CHANGES) -- Fix any issues identified by reviewers -- Push updates to the PR branch -- Re-run CMAP if substantial changes were made - -You must have three concrete verdicts (e.g., "gemini: APPROVE, codex: APPROVE, claude: APPROVE") before continuing. +Do not proceed until **ALL THREE consultations have returned results** — retrieve each with `TaskOutput` (`block: true`), record its verdict (APPROVE / REQUEST_CHANGES), fix real issues, push, and re-run CMAP if the changes were substantial. You must hold three concrete verdicts before you notify. -### 4. Notify Architect +## Notify and hand off at the gate -**DO NOT send this notification until you have all three CMAP verdicts from step 3.** - -Send a **single** notification that includes the PR link and each model's verdict: +**DO NOT send this notification until you have all three CMAP verdicts.** Send a **single** notification with the PR link and all three verdicts, then request the gate: ```bash afx send architect "PR # ready for review (fixes issue #{{issue.number}}). CMAP: gemini=, codex=, claude=" +porch done ``` -Then run `porch done ` to auto-request the `pr` gate. The PR surfaces -in Needs Attention from this point; **STOP and wait** for the architect to call -`porch approve pr`. After gate approval, porch will emit a merge task -(via the next `porch next` call) — follow it to merge the PR and advance to -`verified`. +`porch done` fires the `pr` gate and surfaces the PR in Needs Attention. Wait for the architect to approve it (`porch approve pr`) — a CMAP APPROVE is not merge authorization. After gate approval, follow the merge task from `porch next` to merge and advance to `verified`. ## Signals -When PR is created and reviews are complete: - -``` -PHASE_COMPLETE -``` - -If you're blocked: - -``` -BLOCKED:reason goes here -``` +- PR created and reviews complete: + ``` + PHASE_COMPLETE + ``` +- Blocked: + ``` + BLOCKED:reason goes here + ``` diff --git a/codev-skeleton/protocols/bugfix/protocol.md b/codev-skeleton/protocols/bugfix/protocol.md index 29fb7ed5b..5854a9434 100644 --- a/codev-skeleton/protocols/bugfix/protocol.md +++ b/codev-skeleton/protocols/bugfix/protocol.md @@ -1,78 +1,72 @@ # BUGFIX Protocol -> Lightweight, issue-driven protocol for minor bug fixes. **Investigate → Fix → PR**, with a single `pr` gate before merge. No spec or plan artifacts: the GitHub issue is the spec, and the review goes in the PR body. +Investigate → Fix → PR, driven by a GitHub issue. No spec, no plan, no artifact files: the issue +is the specification and the PR body carries the reasoning. -## When to Use +Use it for a defect whose fix is isolated. For a small *feature* use AIR; for anything needing a +design decision use SPIR. -Use BUGFIX when a bug is reported as a GitHub Issue and: +## The state machine -- The reproduction is clear (or inferable) and the root cause is isolated -- The fix is small (guideline: < 300 LOC net diff) and contained to one area -- No architectural changes or new design decisions are needed - -Escalate to **SPIR** (or another heavier protocol) instead when: - -- It is actually a feature request, not a bug -- The root cause reveals a deeper architectural issue -- The fix needs design review, spans multiple components, or clearly exceeds ~300 LOC - -## Phases - -``` -investigate → fix → pr +```json +{{> protocols/bugfix/protocol.json}} ``` -### Investigate - -Read the issue, reproduce the bug, and identify the root cause. Confirm the fix fits BUGFIX scope. If it does not, signal `BLOCKED` and recommend escalation to the architect (`afx send architect "..."`). No code in this phase. - -### Fix +## Phases -Apply the minimal change that resolves the root cause, and add a regression test that fails without the fix and passes with it. Keep it focused: do not refactor surrounding code, do not fix unrelated bugs (file separate issues), do not add features. Run the build and tests (porch's `checks` block runs `npm run build` and `npm test`). +**Investigate** — reproduce the bug and identify the root cause. **No code in this phase.** +Confirm the fix fits BUGFIX scope; if it does not, signal `BLOCKED` and recommend escalation +rather than growing the project quietly. -Commit with the issue-driven format: +**Fix** — the minimal change that resolves the root cause, plus a regression test that **fails +without the fix and passes with it**. A test that passes either way documents nothing. Do not +refactor surrounding code, fix unrelated bugs (file separate issues), or add features. ``` -[Bugfix #] Fix: -[Bugfix #] Test: +[Bugfix #42] Fix: URL-encode username before API call +[Bugfix #42] Test: regression for unencoded username ``` -### PR (gated by `pr`) +**PR** — open with `gh pr create`, body carrying Summary, Root Cause, Fix and Test Plan plus +`Fixes #` so the issue closes on merge. Run one CMAP pass (Gemini, Codex, Claude), record +each verdict, and address or rebut every `REQUEST_CHANGES`. Notify the architect with the +verdicts, then `porch done ` and wait. -1. Push the branch and open a PR with `gh pr create`. The body includes Summary, Root Cause, Fix, and Test Plan, plus `Fixes #` so the issue auto-closes on merge. -2. Run a multi-agent CMAP review on the PR (Gemini, Codex, Claude) and record each verdict. Address or rebut any `REQUEST_CHANGES`; add a regression test if a real defect surfaced. -3. Notify the architect: `afx send architect "PR # ready for review (fixes #). CMAP: gemini=..., codex=..., claude=..."`. -4. Run `porch done ` to request the `pr` gate, then wait. **The merge is gated by porch state, never by typed prose in your pane.** -5. The human reviews the PR and the CMAP results on GitHub, then approves the gate: `porch approve pr --a-human-explicitly-approved-this`. -6. porch wakes the builder with a merge task. Merge with `gh pr merge --merge` (do **not** pass `--delete-branch`: the builder is checked out on this branch in a worktree), then run `porch done ` and notify the architect that it is merged and ready for cleanup. +Merge with `gh pr merge --merge`. **Do not pass `--delete-branch`** — the builder is checked out +on that branch in a worktree, and deleting it out from under them breaks the worktree. -## Gate +## The gate exists to make merge authorization structural -BUGFIX has one human gate, `pr`, on the merge step. It exists so the merge trigger is structured porch state (approved or not), not free-text typed into the builder's pane. This eliminates the self-merge bug class: a builder cannot infer authorization from ambiguous input. +BUGFIX has one human gate, `pr`. Its purpose is that the merge trigger is **porch state** — +approved or not — rather than free text typed into the builder's pane. That closes the +self-merge bug class: a builder cannot infer authorization from ambiguous prose. -## Multi-Agent Consultation +## Consultation -A single CMAP pass at the PR (Gemini, Codex, Claude). There is no per-phase consultation: the issue is the spec and the fix is small, so review effort concentrates on the final PR. +One CMAP pass at the PR. No per-phase consultation: the issue is the spec and the fix is small, +so review effort concentrates where it can still change the outcome. ## Scope -The < 300 LOC threshold is a **guideline**, measured as net diff (additions + deletions) anchored at the merge-base with the default branch. A well-contained 350-LOC fix is fine; a 200-LOC fix smeared across ten files may warrant escalation. +The <300 LOC threshold is a **guideline**, measured as net diff (additions + deletions) against +the merge-base with the default branch. A well-contained 350-line fix is fine; a 200-line fix +smeared across ten files probably warrants escalation. ## Escalation -If, mid-fix, the change outgrows BUGFIX (architectural impact, multiple components, unclear root cause after investigation, or more than ~300 LOC), notify the architect with specifics and recommend escalating to SPIR. Do not silently expand scope. - -## Branch Naming +If the change outgrows BUGFIX mid-flight — architectural impact, multiple components, unclear +root cause after investigation — notify the architect with specifics and recommend SPIR. **Do +not silently expand scope.** -``` -builder/bugfix-- -``` - -## Edge Cases +## Edge cases | Scenario | Action | |---|---| -| Cannot reproduce | Document the attempts in an issue comment, ask the reporter for detail, notify the architect | -| Fix outgrows scope (architectural / multi-component / > ~300 LOC) | Notify the architect, recommend escalation; do not proceed | -| Unrelated test failures | Out of scope: note them for the architect, do not fix them here | -| Multiple bugs in one issue | Fix only the primary bug; file separate issues for the rest | +| Cannot reproduce | Document the attempts on the issue, ask the reporter for detail, notify the architect | +| Fix outgrows scope | Notify the architect and recommend escalation; do not proceed | +| Unrelated test failures | Out of scope — note them for the architect, do not fix here | +| Multiple bugs in one issue | Fix the primary one; file separate issues for the rest | + +## Branch naming + +`builder/bugfix--` diff --git a/codev-skeleton/protocols/experiment/builder-prompt.md b/codev-skeleton/protocols/experiment/builder-prompt.md index 31c5581e5..20efb1ebe 100644 --- a/codev-skeleton/protocols/experiment/builder-prompt.md +++ b/codev-skeleton/protocols/experiment/builder-prompt.md @@ -1,82 +1,49 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are executing a disciplined experiment. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the EXPERIMENT protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Document your findings thoroughly + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way review** — always follow porch next → porch done cycle + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the EXPERIMENT protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. - -## EXPERIMENT Overview -The EXPERIMENT protocol ensures disciplined experimentation: -1. **Hypothesis Phase**: Define what you're testing and success criteria -2. **Design Phase**: Plan the experiment approach -3. **Execute Phase**: Run the experiment and gather data -4. **Analyze Phase**: Evaluate results and draw conclusions +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. -{{#if task}} ## Experiment Focus + {{task_text}} -{{/if}} ## Key Principles -- Start with a clear, falsifiable hypothesis -- Define success/failure criteria upfront -- Keep scope minimal for quick iteration -- Document findings regardless of outcome -- Separate experiment artifacts from production code -## If You Open a PR +- Start with a **clear, falsifiable hypothesis** and define success/failure criteria **upfront** — + an experiment scored after the fact always succeeds +- Keep scope minimal for fast iteration +- **Document findings regardless of outcome.** A directory containing only successes has been + curated, not run +- Keep experiment artifacts separate from production code -Most experiments are committed to a branch without a PR, but if you do open one -to integrate findings and the experiment was triggered by a GitHub issue: - -**PR body requirements**: The PR body MUST include `Closes #` (for feature -issues) or `Fixes #` (for bug issues) for the driving issue so GitHub -auto-closes it on merge. If the PR closes multiple issues, include one keyword -per issue. - -**Exception**: if this PR only partially addresses the issue (e.g. experiment -validates an approach but production implementation is deferred), use -`Refs #` or `Part of #` instead — the issue stays open until a follow-up -PR closes it. - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue with your work +## If You Open a PR -## Getting Started -1. Read the EXPERIMENT protocol document -2. Define your hypothesis clearly -3. Follow the phases in order +Most experiments are committed to a branch without a PR. If you do open one and the experiment +came from a GitHub issue, the body **must** carry `Closes #` (feature) or `Fixes #` (bug) +so GitHub auto-closes it on merge — one keyword per issue if several. ---- +**Exception**: if the PR only *partially* addresses the issue (the experiment validates an +approach but the production implementation is deferred), use `Refs #` or `Part of #` so +the issue stays open for the follow-up. -## Protocol Reference (full text) +## Notifications -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/experiment/protocol.md b/codev-skeleton/protocols/experiment/protocol.md index 2e53487d4..1904727f7 100644 --- a/codev-skeleton/protocols/experiment/protocol.md +++ b/codev-skeleton/protocols/experiment/protocol.md @@ -1,203 +1,37 @@ # EXPERIMENT Protocol -## Overview +A disciplined experiment: state the hypothesis before running it, record what actually happened, +and keep the result whichever way it goes. -Disciplined experimentation: Each experiment gets its own directory with `notes.md` tracking goals, code, and results. +Use it for evaluating models or libraries, proof-of-concept work, and technique comparisons — +questions that should be settled by evidence rather than by argument. -**Core Principle**: Document what you're trying, what you did, and what you learned. - -## When to Use - -**Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes - -**Skip for**: Production code (use SPIR), simple one-off scripts - -## Structure - -``` -experiments/ -├── 1_descriptive_name/ -│ ├── notes.md # Goal, code, results -│ ├── experiment.py # Your experiment code -│ └── data/ -│ ├── input/ # Input data -│ └── output/ # Results, plots, etc. -└── 2_another_experiment/ - ├── notes.md - └── ... -``` - -## Workflow - -### 1. Create Experiment Directory - -```bash -# Create numbered directory -mkdir -p experiments/1_experiment_name -cd experiments/1_experiment_name - -# Initialize notes.md from template -touch notes.md # then fill it from the embedded template at the end of this protocol -``` - -Or ask your AI assistant: "Create a new experiment for [goal]" - -### 2. Document the Goal - -Before writing code, clearly state what you're trying to learn in `notes.md`: - -```markdown -## Goal - -What specific question are you trying to answer? -What hypothesis are you testing? -``` - -### 3. Write Experiment Code - -- Keep it simple - experiments don't need production polish -- Reuse existing project modules where possible -- Any structure is fine - focus on learning, not architecture - -**Dependencies**: If your experiment requires libraries not in the main project: -1. Do NOT add them to the main project's `requirements.txt` or `pyproject.toml` -2. Create a `requirements.txt` inside your experiment folder -3. Document installation in `notes.md` - -### 4. Run and Observe - -Execute your experiment and capture results: -- Save output files to `data/output/` -- Take screenshots of visualizations -- Log key metrics - -### 5. Document Results - -Update `notes.md` with: -- What happened (actual results) -- What you learned (insights) -- What's next (follow-up actions) - -### 6. Commit - -```bash -git add experiments/1_experiment_name/ -git commit -m "[Experiment 1] Brief description of findings" -``` - -## Best Practices - -### Keep It Simple -- Experiments don't need production polish -- Skip comprehensive error handling -- Focus on answering the question - -### Document Honestly -- Include failures - they're valuable learnings -- Note dead ends and why they didn't work -- Be specific about what surprised you - -### Track Time Investment -- Wall clock time: Total elapsed time -- Developer time: Active working time (excluding waiting) -- Helps estimate future similar work - -### Use Project Modules -- Don't duplicate existing code -- Import from your `src/` directory -- Experiments validate approaches, not reimplement them - -### Commit Progress -- Use `[Experiment ####]` commit prefix -- Commit intermediate results -- Include output files when reasonable - -## Integration with Other Protocols - -### Experiment → SPIR -When an experiment validates an approach for production use: - -1. Create a specification referencing the experiment -2. Link to experiment results as evidence -3. Use experiment code as reference implementation - -Example spec reference: -```markdown -## Background - -Experiment 5 validated that [approach] achieves [results]. -See: experiments/5_validation_test/notes.md -``` - -## Numbering Convention - -Use four-digit sequential numbering (consistent with project list): -- `1_`, `2_`, `3_`... -- Shared sequence across all experiments -- Descriptive name after the number (snake_case) - -Examples: -- `1_api_response_caching` -- `2_model_comparison` -- `3_performance_baseline` - -## Git Workflow - -### Commits -``` -[Experiment 1] Initial setup and goal -[Experiment 1] Add baseline measurements -[Experiment 1] Complete - caching improves latency 40% -``` - -### When to Commit -- After setting up the experiment -- After significant findings -- When completing the experiment - -**Data Management**: -- Include `data/output/` ONLY if files are small (summary metrics, small plots) -- Do NOT commit large datasets, binary model checkpoints, or heavy artifacts -- Add appropriate entries to `.gitignore` for large files -- Consider storing large outputs externally and linking in notes - -## Example Experiment +## The state machine -``` -experiments/1_caching_strategy/ -├── notes.md -├── benchmark.py -├── cache_test.py -└── data/ - ├── input/ - │ └── sample_requests.json - └── output/ - ├── results.csv - └── latency_chart.png +```json +{{> protocols/experiment/protocol.json}} ``` -**notes.md excerpt:** -```markdown -# Experiment 1: Caching Strategy Evaluation +## Structure -**Status**: Complete +Each experiment gets a numbered directory under `codev/experiments/` with a `notes.md` recording +the hypothesis, method, results and conclusion. -**Date**: 2024-01-15 +## Notes structure -## Goal -Determine if Redis caching improves API response times for repeated queries. +`notes.md` uses this structure: -## Results -- 40% latency reduction for cached queries -- Cache hit rate: 73% after warm-up -- Memory usage: 50MB for 10k cached responses +{{> protocols/experiment/templates/notes.md}} -## Next Steps -Create SPIR spec for production caching implementation. -``` +## The discipline that makes it worth doing -## Template: notes.md +**Write the hypothesis and the success criteria before running anything.** An experiment scored +after the fact always succeeds — you discover the criterion the result happens to meet. -Create `notes.md` with the following content: +**Record negative results.** "We tried X and it did not work, here is why" is the output that +saves the next person a week. An experiment directory containing only successes is a directory +that has been curated rather than run. -{{> protocols/experiment/templates/notes.md}} +**Keep the experiment separate from production code.** Experimental code answers a question; it +has not earned the standards production code is held to, and promoting it silently is how a +proof of concept becomes a maintenance burden nobody chose. diff --git a/codev-skeleton/protocols/experiment/templates/notes.md b/codev-skeleton/protocols/experiment/templates/notes.md index 18e1c63f6..42df40dda 100644 --- a/codev-skeleton/protocols/experiment/templates/notes.md +++ b/codev-skeleton/protocols/experiment/templates/notes.md @@ -1,97 +1,37 @@ # Experiment ####: Name -**Status**: In Progress | Complete | Disproved | Aborted - -**Date**: YYYY-MM-DD +**Status**: In Progress | Complete | Disproved | Aborted · **Date**: YYYY-MM-DD ## Goal -What are you trying to learn or test? Be specific about: -- The question you're answering -- The hypothesis you're testing -- Success criteria (how will you know if it worked?) - -## Effort - -**Approximate time spent**: [e.g., "4 hours"] - -*(Optional: Break down into setup, coding, analysis if helpful)* +The question you are answering, the hypothesis you are testing, and the success criteria — how you will know if it worked. ## Approach -Brief description of the approach being tested: -- Key technique or method -- Why this approach was chosen -- Any alternatives considered +The technique being tested, why it was chosen, and any alternatives considered. ## Environment & Reproduction -**How to run**: -```bash -# Command to reproduce results -python experiment.py --input data/input/sample.json -``` - -**Dependencies** (if different from main project): -- List any additional packages required -- Or reference: `pip install -r requirements.txt` - -**Environment notes**: -- Python version, key library versions if relevant -- Any seeds or configuration needed for reproducibility +How to run it (the exact command), any dependencies beyond the main project, and the version/seed/config notes needed to reproduce the result. ## Code -List your experiment files: -- [`experiment.py`](experiment.py) - Brief description -- [Other files as needed] +The experiment files, each with a one-line description. ## Results -### Summary - -One-paragraph summary of key findings. - -### Key Findings - -1. **Finding one**: Description and significance -2. **Finding two**: Description and significance -3. **Finding three**: Description and significance - -### Metrics +A one-paragraph summary, then the key findings and the metrics that support them. | Metric | Value | Notes | |--------|-------|-------| -| Metric 1 | Value | Context | -| Metric 2 | Value | Context | - -### Output Files - -- `data/output/results.csv` - Raw results data -- `data/output/chart.png` - Visualization of findings +| | | | -## What Worked +Output artifacts (data, charts) with their paths. -- List things that went well -- Approaches that proved effective -- Useful discoveries +## What Worked / What Didn't -## What Didn't Work - -- Failed approaches (and why) -- Dead ends encountered -- Surprising obstacles +What proved effective, and the failed approaches or dead ends (with why). ## Next Steps -Based on these findings: - -1. **Immediate**: What should happen right after this experiment? -2. **Follow-up experiments**: What new questions emerged? -3. **Production path**: If validated, what's needed for production? (SPIR spec?) - -## References - -- Links to relevant documentation -- Related experiments -- External resources consulted +The immediate next action, any follow-up experiments the findings raised, and — if validated — the production path (e.g. a SPIR spec). diff --git a/codev-skeleton/protocols/maintain/builder-prompt.md b/codev-skeleton/protocols/maintain/builder-prompt.md index 6a2deda0d..9fc5949b8 100644 --- a/codev-skeleton/protocols/maintain/builder-prompt.md +++ b/codev-skeleton/protocols/maintain/builder-prompt.md @@ -1,62 +1,41 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are executing the MAINTAIN protocol to clean up and synchronize the codebase. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the MAINTAIN protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Work through each step methodically + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the MAINTAIN protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. ## MAINTAIN Overview -Two phases: -1. **Maintain**: Single pass — audit findings, clean dead code, sync docs, verify build -2. **Review**: Create PR with 3-way consultation +Two phases: **Maintain** (one pass — audit, clean, sync docs, verify build) then **Review** +(PR with 3-way consultation). ## Key Rules -- Use soft deletion (move to `codev/maintain/.trash/`) -- Verify build passes after each removal (`cd packages/codev && pnpm build && pnpm test`) -- Update documentation to match current architecture -- Don't remove anything actively used -- One removal at a time — commit after each -- Document every deletion with justification -- Never use `git add -A` or `git add .` - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your maintenance run file -5. Commit the skip and continue with your work - -## Getting Started -1. Read the MAINTAIN protocol document -2. Run `porch next` to get your first task -3. Work through audit → clean → sync → verify in a single pass -4. Document everything in the maintenance run file - ---- - -## Protocol Reference (full text) - -{{protocol_reference}} + +- **Soft-delete**: move removals to `codev/maintain/.trash/`, do not delete outright +- Verify the build after each removal (`cd packages/codev && pnpm build && pnpm test`) +- **One removal at a time, commit after each** — a bundled cleanup commit cannot be bisected +- Treat every audit hit as a *candidate*: a detector cannot tell "vestigial" from "used by a + path you did not search". Confirm with a targeted grep before removing +- Don't remove anything actively used; document every deletion with its justification +- Never `git add -A` / `--all` / `.` — stage each file explicitly by path + +## Notifications + +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/maintain/consult-types/impl-review.md b/codev-skeleton/protocols/maintain/consult-types/impl-review.md index de01b8d00..7028b4947 100644 --- a/codev-skeleton/protocols/maintain/consult-types/impl-review.md +++ b/codev-skeleton/protocols/maintain/consult-types/impl-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev-skeleton/protocols/maintain/consult-types/pr-review.md b/codev-skeleton/protocols/maintain/consult-types/pr-review.md index 837cdea33..6b9a3e82a 100644 --- a/codev-skeleton/protocols/maintain/consult-types/pr-review.md +++ b/codev-skeleton/protocols/maintain/consult-types/pr-review.md @@ -1,44 +1,24 @@ # PR Ready Review Prompt ## Context -You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. -## Focus Areas - -1. **Completeness** - - Are all spec requirements implemented? - - Are all plan phases complete? - - Is the review document written (`codev/reviews/XXXX-name.md`)? - - Are all commits properly formatted (`[Spec XXXX][Phase]`)? - -2. **Test Status** - - Do all tests pass? - - Is test coverage adequate for the changes? - - Are there any skipped or flaky tests? +You are performing the final self-check during the Review phase — the builder has completed all implementation phases and is about to open the PR. This is the last check before the work goes to the architect for integration review. -3. **Code Cleanliness** - - Is there any debug code left in? - - Are there any TODO comments that should be resolved? - - Are there any `// REVIEW:` comments that weren't addressed? - - Is the code properly formatted? - -4. **Documentation** - - Are inline comments clear where needed? - - Is the review document comprehensive? - - Are any new APIs documented? +## Focus Areas -5. **PR Readiness** - - Is the branch up to date with its base (the integration branch the PR targets)? - - Are commits atomic and well-described? - - Is the change diff reasonable in size? +- **Completeness** — all spec requirements implemented, all plan phases complete, the review document written (`codev/reviews/XXXX-name.md`), and commits in the `[Spec XXXX][Phase]` format. +- **Test Status** — all tests pass, coverage is adequate for the changes, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO` / `// REVIEW:` left unaddressed, code properly formatted. +- **Documentation** — inline comments clear where needed, the review document comprehensive, new APIs documented. +- **PR Readiness** — the branch is up to date with its base (the integration branch the PR targets), commits are atomic and well-described, and the diff size is reasonable. ## Scope -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -63,14 +43,8 @@ PR_SUMMARY: | - [How to test] ``` -**Verdict meanings:** -- `APPROVE`: Ready to create PR -- `REQUEST_CHANGES`: Issues to fix before PR creation -- `COMMENT`: Minor items, can create PR but note feedback - -## Notes +- `APPROVE`: ready to create the PR. +- `REQUEST_CHANGES`: issues to fix before PR creation. +- `COMMENT`: minor items; can create the PR but note the feedback. -- This is the builder's final self-review before hand-off -- The PR_SUMMARY in your output can be used as the PR description -- Focus on "is this ready for someone else to review" not "is this perfect" -- Any issues found here are cheaper to fix than during integration review +The `PR_SUMMARY` block can be used directly as the PR description. diff --git a/codev-skeleton/protocols/maintain/prompts/maintain.md b/codev-skeleton/protocols/maintain/prompts/maintain.md index 3c83f404d..620155f21 100644 --- a/codev-skeleton/protocols/maintain/prompts/maintain.md +++ b/codev-skeleton/protocols/maintain/prompts/maintain.md @@ -47,7 +47,7 @@ For each audit finding: 3. Build and test: `cd packages/codev && pnpm build && pnpm test` 4. Commit: `git add && git commit -m "[Maintain] Remove unused X"` -One removal at a time. Verify after each. Never use `git add -A`. +One removal at a time, verified after each — staging only the specific files that removal touched. ## Step 4: Sync Documentation diff --git a/codev-skeleton/protocols/maintain/protocol.md b/codev-skeleton/protocols/maintain/protocol.md index 08199b956..a75057cda 100644 --- a/codev-skeleton/protocols/maintain/protocol.md +++ b/codev-skeleton/protocols/maintain/protocol.md @@ -1,241 +1,50 @@ # MAINTAIN Protocol -## Overview +Audit → Clean → Sync, in a single pass, then a PR. Two phases, one consultation during the +maintain phase and one before the PR. -MAINTAIN is a single-pass maintenance protocol for keeping codebases healthy. The builder does all maintenance work in one phase, then creates a PR with a 3-way review. +Use it for dead code and unused dependencies, quarterly hygiene, pre-release cleanup, and +keeping the governance docs honest — `arch.md`/`arch-critical.md`, +`lessons-learned.md`/`lessons-critical.md`, and the `CLAUDE.md`↔`AGENTS.md` twins. -**Core Principle**: Do the work in one pass. Don't over-ceremonialize housekeeping. +## The state machine -**Key Documents** MAINTAIN keeps current: -- `codev/resources/arch.md` (COLD reference) + `codev/resources/arch-critical.md` (HOT, always-injected) — Architecture, two tiers (Spec 987) -- `codev/resources/lessons-learned.md` (COLD reference) + `codev/resources/lessons-critical.md` (HOT, always-injected) — Engineering wisdom, two tiers - -The two governance docs are siblings with **different purposes**: `arch.md` owns system shape (services, transports, mental models, verified-wrong assumptions about *this* system); `lessons-learned.md` owns durable engineering wisdom that applies *across* specs. Use the routing matrix below to decide where each fact belongs. - -### Lives where: routing facts to the right home - -| Type of fact/insight | Lives in | -|---|---| -| Current system shape (services, transports, key mental models) | `codev/resources/arch.md` | -| Mechanism for a unique subsystem | `codev/resources/arch.md` (subsystem section) OR a meta-spec under `codev/architecture/.md` if the mechanism is large enough to warrant its own doc | -| A durable engineering pattern that applies across multiple specs | `codev/resources/lessons-learned.md` (COLD reference) | -| A **behavior-changing, cross-cutting** rule (should change how the next project is built) | `codev/resources/lessons-critical.md` (HOT, capped) — demote to `lessons-learned.md` if full | -| A **behavior-changing, cross-cutting** architecture invariant (a future builder must know up front) | `codev/resources/arch-critical.md` (HOT, capped) — demote to `arch.md` if full | -| A spec-narrow fix recipe (reference detail) | `codev/resources/lessons-learned.md` (COLD) — kept as reference; **never** the hot file | -| A system-shape surprise verified-wrong in production ("looks like X but isn't") | `codev/resources/arch.md` § "Verified-Wrong Assumptions" | -| Aspirational architectural direction (where we want to go) | The relevant meta-spec or roadmap doc, NOT `arch.md` body | -| A changelog entry ("we shipped X in spec Y on date Z") | `git log` + the spec/review document — NOT `arch.md`, NOT `lessons-learned.md` | -| A retired or removed component | Delete the section entirely; do NOT keep a "retired components" graveyard. (`git log` retains history.) | - -The most commonly-misrouted entry is the system-shape surprise. If a future reader needs to know "the system *looks* like X but actually does Y," that is system shape and lives in `arch.md`. If they need to know "we learned that doing X is generally a bad idea," that is engineering wisdom and lives in `lessons-learned.md`. - -## When to Use - -- Before a release (clean slate for shipping) -- After completing a major feature -- Quarterly maintenance window -- When the codebase feels "crusty" - -## Execution Model - -``` -afx spawn --protocol maintain - ↓ -1. MAINTAIN: Audit → Clean → Sync docs (single pass) - ↓ (build + test checks, 3-way review) -2. REVIEW: Create PR - ↓ (3-way review) -Architect reviews → Merge -``` - -Two phases total. One consultation during the maintain phase, one before PR. - -## Prerequisites - -Before starting: -1. Check `codev/maintain/` for the last run number -2. Note the base commit: `git log --oneline -1` on the last run file -3. Focus on changes since then: `git log --oneline ..HEAD` - ---- - -## The Maintain Phase (Single Pass) - -The builder works through these tasks in order, committing as they go. - -### Step 1: Audit - -Identify what needs fixing. Don't fix yet — just catalog. - -**Dead code**: -```bash -# Find unused exports (TypeScript) -npx ts-prune 2>/dev/null || echo "ts-prune not available" - -# Find unused dependencies -npx depcheck 2>/dev/null || echo "depcheck not available" -``` - -**Stale documentation**: -```bash -# What changed since last maintenance? -git log --oneline ..HEAD - -# Check arch.md references still exist -grep -oE '[a-zA-Z]+/[a-zA-Z/]+\.[a-z]+' codev/resources/arch.md | sort -u | while read f; do - [ -e "$f" ] || echo "Missing: $f" -done -``` - -**Stale project tracking**: -- GitHub Issues that should be closed -- Labels that need updating - -Record findings in the maintenance run file (`codev/maintain/NNNN.md`). - -### Step 2: Clean - -For each finding from the audit: -1. Verify it's truly unused (grep the codebase) -2. Remove it (use `git rm` for tracked files) -3. Verify build + tests still pass -4. Commit with `[Maintain] Remove unused X` - -**Rules**: -- One removal at a time — don't batch unrelated changes -- Verify after each removal — build must pass -- Use soft deletion for untracked files: `mv file codev/maintain/.trash/$(date +%Y-%m-%d)/` -- Never use `git add -A` or `git add .` - -### Step 3: Sync Documentation - -Step 3 is split into two sub-steps: **Audit first, then update.** This split exists because `arch.md` and `lessons-learned.md` accumulate without bound when MAINTAIN does only "what's new" — the audit pass surfaces what should be cut so the update pass is not purely additive. - -The `update-arch-docs` skill (at `.claude/skills/update-arch-docs/SKILL.md`) is invoked by both sub-steps. Read it before starting Step 3 so the discipline is fresh. - -#### Step 3a: Audit documentation - -Invoke the `update-arch-docs` skill in **audit-mode**. The skill reads all four governance files — `codev/resources/arch.md` / `arch-critical.md` and `codev/resources/lessons-learned.md` / `lessons-critical.md` — end-to-end against the discipline below, applies the cuts via the Edit tool, and records each cut's reason in the run file (`codev/maintain/NNNN.md`) under a `## Audit Findings` section. The diff plus the recorded reasons **is** the proposal; the architect's PR review is the human-confirmation step (consistent with the skill's audit-mode). - -**Per-arch.md-section pruning checklist** — for each section in `arch.md`, ask: -- Does it describe **current state**? If aspirational, the section moves to a meta-spec; `arch.md` keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own). -- Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer. -- Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files. -- Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing. -- Is the component still alive? If retired, delete the section entirely. - -**Per-COLD-`lessons-learned.md`-entry pruning checklist** — for each entry, ask: -- Is it terse (1–3 sentences)? If multi-paragraph, split or compress. -- Is the topic section the right home? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home. -- Is it a duplicate of an adjacent entry? If yes, fold them. -- (Spec-narrow recipes are **kept** as reference — do not cut them just for being spec-narrow. Anti-accretion now lives in the hot cap, not the cold archive.) - -**Per-HOT-file checklist** (`arch-critical.md`, `lessons-critical.md`) — audit the cap and map: -- Within the cap (≈10 entries + a ≈12-topic map, ≤35 lines)? If over, **demote** the weakest entries into the cold doc. -- Does every map topic name a real top-level cold-doc section, and is any new/renamed section reflected? Fix drift; keep the map top-level only. -- Is every entry still behavior-changing? Demote reference detail into the cold archive. - -**Sample audit prompt** (paste into the skill invocation if you want a baseline checklist run): - -``` -Audit all four governance files — codev/resources/arch.md + arch-critical.md and -lessons-learned.md + lessons-critical.md — against the discipline in the -update-arch-docs skill. For each cold section/entry run the cold pruning checklists, -and for each hot file check the cap, displacement, and map accuracy (Step 3a). -Apply the cuts with one-line reasons. Bias toward fewer, higher-confidence -cuts ("when in doubt, KEEP"). Record each cut's reason in the current run -file's ## Audit Findings section as you go — the diff plus those reasons is the proposal. +```json +{{> protocols/maintain/protocol.json}} ``` -**When in doubt, KEEP.** This rule is preserved from the older Step 3. A confident cut is better than three speculative ones. The audit pass is a *proposal*; the architect's PR review confirms it. - -#### Step 3b: Update documentation - -Apply the audit decisions from Step 3a, plus any additive content needed. - -**arch.md / arch-critical.md**: Compare documented structure with actual codebase. Route behavior-changing invariants to `arch-critical.md` (HOT — respect the cap + keep its map accurate); reference detail to `arch.md` (COLD). Update: -- Directory structure -- Component descriptions (explain HOW things work, not just WHAT) -- Key files and their purposes -- Remove references to deleted code (per Step 3a audit findings) -- Add new components/utilities - -**lessons-learned.md / lessons-critical.md**: Scan `codev/reviews/` for new reviews since last run. **Route** each new lesson by tier — behavior-changing + cross-cutting → `lessons-critical.md` (HOT; respect the cap, demote a weaker entry to cold if full); reference recipe / spec-narrow → `lessons-learned.md` (COLD). Apply Step 3a's per-entry cuts and keep each hot file's cold-doc map accurate. - -For specific additive changes, invoke `update-arch-docs` in **diff-mode** — it applies the smallest section update needed. +## Before starting -**CLAUDE.md / AGENTS.md**: Diff the two files. They must be identical. Update the stale one. +Find the last run in `codev/maintain/`, note its base commit, and scope the audit to +`git log --oneline ..HEAD`. Maintenance without a since-marker re-audits the whole +repository every time and quietly stops being run. -**Documentation pruning**: -- Remove obsolete references -- ~400 line guideline for CLAUDE.md/README.md (not a hard limit) -- Document every deletion with justification (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE) -- When in doubt, KEEP the content +## The maintain phase -### Step 4: Final Checks +**Audit** — find unused exports, unused dependencies, and orphaned files. Treat every hit as a +*candidate*, not a verdict: a detector cannot tell "vestigial" from "used by a path you did not +search". Confirm each with a targeted grep before removing it. -```bash -# Build and test from the package directory -cd packages/codev && pnpm build && pnpm test -``` - -Both must pass before moving to the review phase. +**Clean** — remove what you confirmed. Deletions go to `codev/maintain/.trash/` (gitignored, +30-day retention) rather than straight out, so a wrong call is recoverable for a month rather +than needing an archaeology session. ---- +**Sync documentation** — route facts by tier rather than appending: behaviour-changing and +cross-cutting go to the capped hot files (displace a weaker entry rather than growing them), +reference detail to the cold archives. The `update-arch-docs` skill encodes the routing matrix, +the caps, and what does *not* belong in each tier. Keep `CLAUDE.md` and `AGENTS.md` +byte-identical. -## Maintenance Run File +## The maintenance run file -Each run creates `codev/maintain/NNNN.md`, following the template below: +Each run is recorded in `codev/maintain/` using this structure: {{> protocols/maintain/templates/maintenance-run.md}} -Keep it factual and short. The run file documents what happened, not what might happen. - ---- - -## Commit Messages - -``` -[Maintain] Remove 5 unused exports -[Maintain] Remove http-proxy dependency -[Maintain] Update arch.md — add VS Code extension, remove dashboard-server refs -[Maintain] Generate lessons-learned.md from reviews 653, 672 -[Maintain] Sync CLAUDE.md with AGENTS.md -``` - ---- - -## Governance - -MAINTAIN is an operational protocol, not a feature protocol: - -| Document | Required? | -|----------|-----------| -| Spec | No | -| Plan | No | -| Review | No (maintenance run file serves this purpose) | -| Consultation | Yes — 3-way review before PR | - -If maintenance reveals need for architectural changes, those should follow SPIR. - ---- - -## Rules - -1. **Don't be aggressive** — when in doubt, KEEP the content -2. **Check git blame** — understand why code/docs exist before removing -3. **Run full test suite** — not just affected tests -4. **Group related changes** — one commit per logical change -5. **Document every deletion** — what, why, and where (if moved) -6. **Prefer moving over deleting** — extract to another file rather than removing -7. **Size targets are guidelines** — never sacrifice clarity to hit a line count +## Scope discipline -## Anti-Patterns +Maintenance is where scope creep is most tempting, because everything you touch looks +improvable. Removing dead code is in scope; refactoring live code because you are already in the +file is not. File an issue instead. -1. Aggressive rewriting without explanation -2. Deleting without documenting why -3. Hitting line count targets at all costs -4. Removing "patterns" or "best practices" sections without explicit approval -5. Deleting everything the audit finds — review each item individually -6. Skipping validation — "it looked dead" is not validation -7. Using `rm` instead of `git rm` +Never `git add -A` / `--all` / `.` — stage each file explicitly by path. diff --git a/codev-skeleton/protocols/maintain/templates/maintenance-run.md b/codev-skeleton/protocols/maintain/templates/maintenance-run.md index a55110215..1d8e1a147 100644 --- a/codev-skeleton/protocols/maintain/templates/maintenance-run.md +++ b/codev-skeleton/protocols/maintain/templates/maintenance-run.md @@ -33,7 +33,7 @@ Recorded by Step 3a (Audit documentation) as the cuts are applied — one line p ### Documentation Changes Log | Document | Section | Action | Reason | |----------|---------|--------|--------| -| arch.md | "Dashboard Server" | DELETED | OBSOLETE — replaced by Tower | +| | | | | ## Deferred diff --git a/codev-skeleton/protocols/pir/builder-prompt.md b/codev-skeleton/protocols/pir/builder-prompt.md index 86016f310..c99fd2985 100644 --- a/codev-skeleton/protocols/pir/builder-prompt.md +++ b/codev-skeleton/protocols/pir/builder-prompt.md @@ -1,38 +1,24 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are implementing a fix or feature driven by a GitHub issue, using the PIR protocol. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the PIR protocol document yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Run consultations manually when the protocol calls for them -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals -- Do not deviate from the porch-driven workflow - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip consultations** — porch handles them via the verify step -- **NEVER advance phases manually** — porch handles phase transitions on gate approval + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the PIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. -PIR has three phases: -1. **plan** (gated by `plan-approval`) — write `codev/plans/{{artifact_name}}.md`, await human review -2. **implement** (gated by `dev-approval`) — write code + tests, run build/tests, push branch; await the human's review of the *running worktree* (no file artifact in this phase — dev-approval summary is prose-in-pane) -3. **review** (gated by `pr`) — write `codev/reviews/{{artifact_name}}.md` (retrospective with Architecture Updates and Lessons Learned sections), open PR with the review as body, record the PR with porch, run 3-way consultation (Gemini, Codex, Claude) via porch's verify block (a **single advisory pass** — `max_iterations: 1`, no iterate-until-APPROVE loop; address or rebut any `REQUEST_CHANGES`, add a regression test if it's a real defect, and escalate it in the architect notification since PIR will not re-review it), notify architect, and wait at the `pr` gate. After the human approves the gate (porch wakes you with "Gate pr approved"), run `gh pr merge --merge` and record the merge with `porch done --merged `. **Merge is gated by porch state — never by typed prose in your pane.** +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. {{#if issue}} ## Issue #{{issue.number}} @@ -44,54 +30,31 @@ PIR has three phases: ## Sitting at Gates -PIR has two human gates. When you reach one: - -1. Finish your phase work and run `porch done ` -2. Run `porch next ` — you'll get a `gate_pending` response -3. End your turn with a short prose summary: what file you wrote, where it lives, how to approve -4. **Stay in the interactive session**. Do NOT exit. Wait for the user's next message. +PIR has two pre-PR human gates. When you reach one: -The reviewer can give feedback by: -- Editing the plan file (at the plan-approval gate) or the code itself (at the dev-approval gate) in the worktree directly — you'll see changes via `git diff` -- Typing into your PTY pane (this reaches you live) -- `afx send ""` (queued; check on next turn) -- Commenting on the GitHub issue (re-fetch with `gh issue view --comments` if asked) - -When the user provides feedback, revise the artifact, recommit, and ask if there's more to address. The gate remains pending until the user runs `porch approve` — do NOT call `porch approve` yourself. - -## Notifications -Use `afx send architect "..."` at key moments: -- **PR ready**: `afx send architect "PR # ready for review (PIR #{{issue.number}})"` -- **PR merged**: `afx send architect "PR # merged for PIR #{{issue.number}}. Ready for cleanup."` -- **Blocked**: `afx send architect "Blocked on PIR #{{issue.number}}: [reason]"` +1. Finish the phase work and run `porch done ` +2. Run `porch next ` — you get a `gate_pending` response +3. End your turn with a short summary: what you wrote, where it lives, how to approve +4. **Stay in the interactive session. Do not exit.** Wait for the next message. -**Gates are not architect-notified.** When porch transitions a gate to `pending`, the gate-reached message (including the `porch approve --a-human-explicitly-approved-this` invocation) appears in YOUR pane as part of your normal output. That's the universal notification surface — visible whether the user is in VSCode, tmux, plain Terminal, or any other host. The user reads it directly from your pane (or runs `porch pending` from a shell) and approves themselves; the architect can't approve gates, so notifying it would be informational noise. +Feedback can arrive four ways, and all of them reach you: the reviewer editing the plan file or +the code directly in the worktree (you see it via `git diff`), typing into your PTY pane (live), +`afx send ` (queued — check next turn), or a comment on the GitHub issue +(re-fetch with `gh issue view --comments`). -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in the review file under a `## Flaky Tests` section -5. Commit the skip and continue with your work +Revise, recommit, ask whether more remains. **The gate stays pending until the human runs +`porch approve` — never call it yourself.** ## Resumption After Crash -If your Claude session crashes mid-flow, Tower's `while true` loop will relaunch you with the same prompt. On startup: - -1. Run `porch next {{project_id}}` to learn what phase you're in -2. If `gate_pending`: read the latest plan file (plan-approval) or `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); git diff "$(git merge-base "${DEFAULT_BRANCH:-main}" HEAD)"` (dev-approval) plus any new GitHub issue comments; check `afx send` queue. Decide whether to revise or just announce you're back. -3. Otherwise: pick up where you left off - -## Getting Started +If your session crashes, Tower's `while true` loop relaunches you with the same prompt: -1. Read the PIR protocol (provided inline in this prompt). -2. Run `porch next {{project_id}}` to see what to do next -3. Begin work +1. `porch next {{project_id}}` to learn what phase you are in +2. If `gate_pending`: read the latest plan file (plan-approval), or the diff (dev-approval) via + `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); git diff "$(git merge-base "${DEFAULT_BRANCH:-main}" HEAD)"`, plus any new issue comments and your `afx send` queue. Decide whether to revise or just announce you are back +3. Otherwise pick up where you left off ---- - -## Protocol Reference (full text) +## Notifications -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/pir/consult-types/impl-review.md b/codev-skeleton/protocols/pir/consult-types/impl-review.md index 380bceee9..6cbae9f84 100644 --- a/codev-skeleton/protocols/pir/consult-types/impl-review.md +++ b/codev-skeleton/protocols/pir/consult-types/impl-review.md @@ -2,47 +2,27 @@ ## Context -You are reviewing the implementation of a PIR protocol project before it reaches the `dev-approval` human gate. A builder has implemented the approved plan and written a dev-approval summary. Your job is to verify the implementation matches the plan and is ready for human review. +You are reviewing a PIR implementation before it reaches the `dev-approval` human gate. A builder has implemented the approved plan and written a dev-approval summary. Verify the implementation matches the plan and is ready for human review. -## CRITICAL: Verify Before Flagging +## Verify before flagging -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -## Focus Areas - -1. **Plan Adherence** - - Does the implementation fulfill the approved plan? - - Are all "Files to Change" actually changed? - - Are the changes scoped to what the plan described, or has scope crept? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs? - - Are error cases handled appropriately? - - Is the change minimal — no unnecessary refactoring or unrelated tidy-ups? - -3. **Test Coverage** - - Are the tests adequate for the changes? - - Do tests cover both the main path and the edge cases the plan called out? - - For a bug fix: is there a regression test that would fail without the fix? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Review File Quality** - - Does `codev/reviews/-.md` exist and follow the template? - - Does it accurately describe what changed? - - Is "Things to Look At" honest about tricky spots? - - Is "How to Test Locally" specific enough that the human reviewer can act on it? +## Focus Areas -5. **PIR-Specific Concerns** - - For UI / mobile / cross-platform changes: does the review file explain platform-specific behavior the human should verify? - - For changes with external integrations: are the integration points documented? +- **Plan Adherence** — the implementation fulfills the approved plan; every "Files to Change" is changed; the change is scoped to the plan, no creep. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled; the change is minimal, with no unrelated refactors. +- **Test Coverage** — tests are adequate and cover the plan's main path and edge cases; a bug fix has a regression test that would fail without the fix. +- **Review File Quality** — `codev/reviews/-.md` exists, follows the template, describes what changed accurately, is honest in "Things to Look At", and specific enough in "How to Test Locally" for the human to act on. +- **PIR-Specific Concerns** — for UI / mobile / cross-platform changes, the review file explains platform-specific behavior the human should verify; for external integrations, the integration points are documented. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -56,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Ready for human at the `dev-approval` gate -- `REQUEST_CHANGES`: Issues that must be fixed before reaching the human -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: ready for the human at the `dev-approval` gate. +- `REQUEST_CHANGES`: issues that must be fixed before reaching the human. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scope -- **DO** review the implementation against the approved plan -- **DO** flag missing regression tests for bug fixes -- **DO** flag obvious bugs, code smells, security issues -- **DO NOT** redesign the approach — that was settled at `plan-approval` -- **DO NOT** demand changes outside the plan's scope -- **DO NOT** request architecture-level refactors unless the change introduces a clear new problem - -## Notes - -- This is a pre-gate review; the human is the final authority -- Focus on "is this ready for someone else to test in a browser / simulator" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to iterate +Review the implementation against the approved plan; flag missing regression tests for bug fixes, and obvious bugs, code smells, or security issues. Do **not** redesign the approach (that was settled at `plan-approval`), demand changes outside the plan's scope, or request architecture-level refactors unless the change introduces a clear new problem. This is a pre-gate review — the human is the final authority; focus on "is this ready for someone else to test in a browser / simulator". diff --git a/codev-skeleton/protocols/pir/consult-types/pr-review.md b/codev-skeleton/protocols/pir/consult-types/pr-review.md index cf49c3a05..1c075a9a4 100644 --- a/codev-skeleton/protocols/pir/consult-types/pr-review.md +++ b/codev-skeleton/protocols/pir/consult-types/pr-review.md @@ -2,37 +2,19 @@ ## Context -You are performing the 3-way review of a PIR protocol PR. The builder has implemented an approved plan, the human has approved the `dev-approval` gate (meaning a human has run the code locally and tested it), and the PR has been opened. This is a single advisory pass (`max_iterations: 1`) — your verdict is surfaced to the human at the `pr` gate, who is the sole remaining reviewer; it is not auto-re-reviewed. +You are performing the 3-way review of a PIR PR. The builder implemented an approved plan, the human approved the `dev-approval` gate (having run and tested the code locally), and the PR is open. This is a single advisory pass (`max_iterations: 1`) — your verdict is surfaced to the human at the `pr` gate, who is the sole remaining reviewer; it is not auto-re-reviewed. ## Focus Areas -1. **Completeness** - - Is the PR body the review file content + `Fixes #`? - - Are all commits properly formatted (`[PIR #] ...`)? - - Does the diff match what the review file describes? - -2. **Test Status** - - Do all tests pass on the branch? - - Is test coverage adequate for the change? - - Are there skipped or flaky tests documented? - -3. **Code Quality** - - Any debug code left in? - - Any TODO comments that should be resolved? - - Any `// REVIEW:` markers that weren't addressed? - -4. **Branch Hygiene** - - Is the branch up to date with the default branch? (If not, suggest a rebase. The default branch is whatever `git symbolic-ref --short refs/remotes/origin/HEAD` reports — typically `main`, but may be `dev`, `ci`, etc.) - - Are commits atomic and well-described? - - Is the change diff a reasonable size for the issue scope? - -5. **Issue Linkage** - - Does the PR body contain `Fixes #` (or `Refs #` for partial fixes)? - - Without this, GitHub won't auto-close the issue on merge +- **Completeness** — the PR body is the review-file content plus `Fixes #`; commits are formatted `[PIR #] ...`; the diff matches what the review file describes. +- **Test Status** — all tests pass on the branch, coverage is adequate, and skipped/flaky tests are documented. +- **Code Quality** — no debug code, no stray `TODO` or unaddressed `// REVIEW:` markers. +- **Branch Hygiene** — the branch is up to date with the default branch (whatever `git symbolic-ref --short refs/remotes/origin/HEAD` reports — typically `main`, sometimes `dev`/`ci`); commits are atomic; the diff size is reasonable for the issue. +- **Issue Linkage** — the PR body carries `Fixes #` (or `Refs #` for a partial fix), without which GitHub won't auto-close the issue on merge. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -46,21 +28,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Ready to merge -- `REQUEST_CHANGES`: Issues to fix before merging -- `COMMENT`: Minor items, can merge but note feedback +- `APPROVE`: ready to merge. +- `REQUEST_CHANGES`: issues to fix before merging. +- `COMMENT`: minor items; can merge but note the feedback. ## Scope -- **DO** flag missing `Fixes #` lines -- **DO** flag obvious problems the human reviewer at the gate might have missed -- **DO NOT** redesign the approach — that was settled at `plan-approval` and validated at `dev-approval` -- **DO NOT** demand changes the human reviewer already accepted at the `dev-approval` gate (the human ran the code and approved it; you didn't) -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. - -## Notes - -- The human at the `dev-approval` gate is the primary reviewer for behavior; you are the secondary reviewer for hygiene and edge cases -- Focus on "what would an integration reviewer catch that the gate reviewer missed" -- If referencing line numbers, use `file:line` format +Flag a missing `Fixes #` and obvious problems the gate reviewer might have missed. Do **not** redesign the approach (settled at `plan-approval`, validated at `dev-approval`), demand changes the human already accepted at `dev-approval` (they ran the code; you didn't), or flag the syntax of `git diff` examples in review-file prose — quoted diff syntax is documentation, not a command; apply two-dot/three-dot scrutiny only to diffs you compute yourself. You are the secondary reviewer for hygiene and edge cases: "what would an integration reviewer catch that the gate reviewer missed". diff --git a/codev-skeleton/protocols/pir/prompts/implement.md b/codev-skeleton/protocols/pir/prompts/implement.md index 9d7f88a8c..7e6b5d5bd 100644 --- a/codev-skeleton/protocols/pir/prompts/implement.md +++ b/codev-skeleton/protocols/pir/prompts/implement.md @@ -61,7 +61,7 @@ Follow the plan's "Files to Change" section. Apply the changes. [PIR #{{issue.number}}] ``` -**Never use `git add .` or `git add -A`.** Stage files explicitly: +Stage files explicitly: ```bash git add path/to/changed-file.ts @@ -143,7 +143,6 @@ Then **stay in the interactive session**. Do not exit. Wait for the user's next - Don't run `porch approve` yourself - Don't push to the default branch — only to your builder branch - Don't squash commits — let the merge commit preserve history -- Don't use `git add .` or `git add -A` - Don't open the PR yet — that's the `review` phase - Don't exit the interactive session at the gate diff --git a/codev-skeleton/protocols/pir/prompts/plan.md b/codev-skeleton/protocols/pir/prompts/plan.md index a40cdee2d..2f4eaf042 100644 --- a/codev-skeleton/protocols/pir/prompts/plan.md +++ b/codev-skeleton/protocols/pir/prompts/plan.md @@ -87,8 +87,6 @@ git commit -m "[PIR #{{issue.number}}] Plan draft" git push -u origin "$(git branch --show-current)" ``` -**Never use `git add .` or `git add -A`.** - ### 5. Signal Phase Complete ```bash @@ -118,7 +116,6 @@ Then **stay in the interactive session**. Do not exit. Wait for the user's next - Don't write code — that's the implement phase - Don't run `porch approve` yourself — only the human can approve the gate - Don't post the plan content as a GitHub issue comment — the plan lives in the file, not the issue thread. A one-line pointer comment on the issue is fine if you think it helps the discussion. -- Don't use `git add .` or `git add -A` - Don't exit the interactive session at the gate ## Handling Feedback diff --git a/codev-skeleton/protocols/pir/prompts/review.md b/codev-skeleton/protocols/pir/prompts/review.md index 952f19c29..3966f7b79 100644 --- a/codev-skeleton/protocols/pir/prompts/review.md +++ b/codev-skeleton/protocols/pir/prompts/review.md @@ -238,7 +238,7 @@ Together with the `--pr` record from step 4a and the `--merged` record from step ## What NOT to Do -- **Don't merge before the `pr` gate is approved.** A consultation APPROVE verdict is NOT merge authorization. User-in-pane prose ("looks good", "lgtm", "merge it") is NOT merge authorization. The *only* signal that authorizes `gh pr merge` is porch reporting `gate_status: approved` for the `pr` gate (which only the user can do, via Cmd+K G or `porch approve` from a non-Claude shell). If `porch next` doesn't show the gate as approved, you wait. +- **Don't merge before the `pr` gate is approved** (steps 8–9). Neither a consultation APPROVE verdict nor user-in-pane prose ("looks good", "lgtm", "merge it") authorizes `gh pr merge` — only porch reporting `gate_status: approved` for the `pr` gate does. - Don't skip porch's PR/merge records (steps 4a, 9). The `--pr` record (step 4a) lets the gate-pending state link to the actual PR; the `--merged` record (step 9) closes the lifecycle in porch state. Skipping either leaves `history:` empty and downstream tooling blind. - Don't run `porch approve` for any gate yourself - Don't push to the default branch — only merge via PR diff --git a/codev-skeleton/protocols/pir/protocol.md b/codev-skeleton/protocols/pir/protocol.md index b3befc173..889283150 100644 --- a/codev-skeleton/protocols/pir/protocol.md +++ b/codev-skeleton/protocols/pir/protocol.md @@ -1,202 +1,76 @@ # PIR Protocol -> **Plan → Implement → Review** for GitHub-issue-driven work that needs human review of *either* the approach (before code is written) *or* the implementation (before a PR exists), or both. Lighter than SPIR/ASPIR (no `specify` phase — the GitHub issue is the implicit spec) with the human dev-approval moved earlier (pre-PR instead of post-PR). Stronger than BUGFIX/AIR (two human gates before the PR). +Plan → Implement → Review, driven by a GitHub issue, with **two human gates before any PR +exists**. The issue is the implicit spec; there is no specify phase. -## When to Use PIR +Choose PIR when either is true: -Pick PIR when working from a GitHub Issue and ONE or BOTH of the following apply — based on the *nature* of the change, not its size: +- **The approach needs review before coding.** Ambiguous root cause, unfamiliar or + high-blast-radius area, or a design-sensitive change — cheaper to redirect at plan time than + at PR time. +- **The implementation must be exercised running, before a PR exists.** Mobile, UI/UX, + hardware-adjacent behaviour, OAuth or payment integrations, full user journeys, anything + performance-sensitive. A diff cannot show you these; a running worktree can. -### 1. The approach needs review before coding starts -- Root cause is ambiguous; multiple valid fixes exist -- Area is unfamiliar or high-blast-radius (shared utilities, auth, migrations, public APIs) -- Design-sensitive (affects conventions, patterns, architecture) -- Cheaper to redirect at plan time than at PR time +Lighter than SPIR (no spec phase, one consult at the PR). Stronger than BUGFIX/AIR (two human +gates *before* a PR, where the human reviews the running code rather than the diff). -### 2. The implementation needs to be tested before a PR is created -The PR diff alone is insufficient; the reviewer must *run* the code: -- Mobile app changes (needs device testing on Android, iOS, possibly web) -- UI / UX changes (visual inspection, interaction flow, accessibility) -- Hardware-adjacent behavior (sensors, camera, permissions, notifications) -- Integration with external services that don't mock cleanly (OAuth, payments, analytics) -- User-journey changes that need a full-flow exercise -- Performance-sensitive changes that need profiling on the running app - -### Use SPIR / ASPIR / BUGFIX / AIR instead when -- **SPIR / ASPIR**: the change is complex enough to warrant careful specification, multi-agent consultation at every phase, and the full spec → plan → implement → review ceremony with file artifacts. The driving issue is incidental — what matters is that the design work deserves a formal spec and the implementation deserves consult-driven review at each phase -- **BUGFIX**: small bug fix, no design review needed, diff-on-PR review is enough -- **AIR**: small feature from an issue, autonomous, diff-on-PR review is enough - -## How PIR Differs from SPIR - -PIR is structurally *SPIR minus the `specify` phase*, with the human dev-approval moved earlier (pre-PR instead of post-PR). - -| Aspect | SPIR | PIR | -|---|---|---| -| Phases | specify → plan → implement → review → verify | plan → implement → review | -| Spec artifact | `codev/specs/-.md` | GitHub Issue body (implicit spec) | -| Plan artifact | `codev/plans/-.md` | Same — committed on builder branch | -| Review artifact | `codev/reviews/-.md` (Summary + Architecture Updates + Lessons Learned, becomes PR body) | **Same shape** — `codev/reviews/-.md` with the same sections, also becomes PR body | -| Human gates | spec-approval, plan-approval, pr, verify-approval | plan-approval, dev-approval, pr | -| Where code is reviewed by the human | On the PR (post-creation) — read the diff | Pre-PR (at the `dev-approval` gate) — read the diff **and run the worktree locally** | - -The review file always includes Summary, Architecture Updates, and Lessons Learned sections so `codev/reviews/` stays semantically consistent across all protocols. PIR's lightness comes from skipping the `specify` phase (the issue body is the spec), not from cutting corners on the retrospective. - -The `dev-approval` gate is what makes PIR genuinely different: the human gates the *running implementation* via the worktree before the PR exists, instead of gating the PR after creation. - -## Phases - -``` -plan → implement → review -``` - -### Plan (gated by `plan-approval`) - -The builder: -1. Reads the GitHub issue and investigates the codebase -2. Writes `codev/plans/-.md` with: Understanding / Proposed change / Files to change / Risks & alternatives / Test plan -3. Commits the plan on the builder branch and pushes -4. Runs `porch done` and `porch next` — the `plan-approval` gate becomes pending -5. Sits at the interactive prompt waiting for review - -**Reviewer paths** (all equivalent): -- Open `codev/plans/-.md` in the worktree, read and / or edit directly, save -- Type feedback into the builder's PTY pane — the builder is alive in interactive mode -- `afx send ""` -- Comment on the GitHub issue (sidecar discussion) - -When satisfied, approve via VSCode's "Approve Gate" command (Cmd+K G) or: - -```bash -porch approve plan-approval --a-human-explicitly-approved-this -``` - -### Implement (gated by `dev-approval`) - -The builder: -1. Reads the approved plan file -2. Writes code and tests; runs build + tests via the `checks` block -3. *No AI consult on this phase* — the human at the `dev-approval` gate is the sole reviewer of the running code. Matches BUGFIX / AIR's pattern of "no consult on implementation, one consult at PR creation". -4. Pushes the branch -5. Runs `porch done` and `porch next` — the `dev-approval` gate becomes pending -6. Outputs a **prose** dev-approval summary in the PTY pane (Summary / Files / Test results / Things to look at / How to test locally). This is a transient message to orient the human reviewer — **not a committed file**. The retrospective file is written in the next phase, after the human approves the running code. -7. Sits at the interactive prompt - -**The reviewer's killer move**: run the worktree locally. - -- VSCode: right-click the builder in the Codev sidebar → **Run Dev** (spawns `afx dev ` via Tower) -- CLI: `afx dev ` - -The dev process uses **the same ports and URLs as main** intentionally (OAuth callbacks, CORS, cookie scoping all depend on consistent origins). Only one dev env runs at a time; stop main's `pnpm dev` before starting the worktree's, or use VSCode's **Stop Dev** to swap. - -Reviewer tests the change on real devices / browsers / simulators. When satisfied, approves via Cmd+K G or: - -```bash -porch approve dev-approval --a-human-explicitly-approved-this -``` - -### Review (gated by `pr`) - -The builder: -1. Writes `codev/reviews/-.md` with **Summary**, **Architecture Updates**, **Lessons Learned Updates**, plus the supporting sections (Files Changed, Commits, Test Results, Things to Look At, How to Test Locally). -2. Routes new facts/wisdom by tier (Spec 987) — HOT `codev/resources/arch-critical.md` / `lessons-critical.md` (capped) or COLD `codev/resources/arch.md` / `lessons-learned.md` (reference) — if real changes need recording. If not, the review file's sections state "no changes needed" with a one-line explanation (the porch `checks` block enforces section presence, not content). -3. Commits the review file (and arch / lessons updates if any) and pushes -4. Opens a PR with `gh pr create`; PR body is the review file content + `Fixes #`. Records the PR with `porch done --pr --branch `. -5. Runs `porch done ` — porch's `verify` block runs 3-way consultation (Gemini, Codex, Claude; type=impl) as a **single advisory pass** (`max_iterations: 1`); consultation outputs land in `codev/projects/-*/`. There is no iterate-until-APPROVE loop: whatever the verdicts, porch records them and advances to the `pr` gate. A `REQUEST_CHANGES` is not auto-re-reviewed — the builder addresses or rebuts it, adds a regression test if it's a real defect, and escalates it in the architect notification so the human verifies it at the `pr` gate. Outcomes are not auto-appended to the PR body; reviewers with the worktree read them from the projects dir. -6. The `pr` gate fires (pending) regardless of verdict. Builder notifies the architect once — leading with any `REQUEST_CHANGES` and its disposition (since PIR will not re-review it) rather than burying it in a flat status line. -7. Builder waits at the `pr` gate. The human reviews the PR on GitHub, then approves the `pr` gate (Cmd+K G or `porch approve pr --a-human-explicitly-approved-this`). Porch wakes the builder. -8. Builder verifies the gate is genuinely approved via `porch next` (defensive — typed prose can't trigger this branch, only real porch state does), then runs `gh pr merge --merge`, records via `porch done --merged `, and sends the cleanup-ready notification. Protocol complete (`next: null`). - -## Gates - -PIR uses porch's existing gate machinery. Gate names are opaque strings; no porch engine changes are needed. - -- **`plan-approval`** — pre-PR. Human reads the plan file (committed on the builder branch) and approves before any code is written. Gates are keyed by `(project_id, gate_name)` so the name is safe to share with other protocols. -- **`dev-approval`** — pre-PR. The human reviews the *running* worktree (via `afx dev`) before any PR exists. This is PIR's distinctive gate. -- **`pr`** — post-PR. Gates the merge step. The human reviews the PR on GitHub and approves this gate; porch wakes the builder, which then runs `gh pr merge`. The gate exists so the merge trigger is structured porch state (binary approved/not), not free-text prose typed into the builder's pane. Eliminates the self-merge bug class: builders can't infer authorization from ambiguous user input. - -When a gate becomes pending, porch broadcasts `overview-changed` via SSE. The VSCode Builders tree picks up the blocked state and renders it with a bell icon; a toast surfaces the new gate-pending event. Architect notification is *not* automatic — gates surface via the toast/sidebar (for IDE users) or by checking the builder pane / `porch pending` (for CLI users). The builder's job at any gate is to write the artifact, commit, signal completion, and wait — never to invoke `porch approve` itself (Claude refuses the `--a-human-explicitly-approved-this` flag by design). - -## Rejection / Feedback Model - -There is no formal `porch reject` command. Rejection works via the feedback-iterate pattern: - -1. Reviewer provides feedback (edit the plan file in VSCode, type in the builder pane, `afx send`, or issue comment) -2. Builder reads the feedback on its next turn, revises the artifact, recommits -3. The gate remains pending — porch doesn't advance until the human runs `porch approve` - -The same pattern works at both gates. - -## Builder Session Lifetime - -The builder is a long-running interactive Claude Code session in a PTY pane managed by Tower. The session is launched as `claude ""` (no `--print`) inside a `while true` restart loop. That form starts an interactive Claude REPL with the prompt as the first user message; after Claude finishes the prompted work it sits at the input prompt awaiting next user input. The outer `while true` loop only fires if Claude crashes — it is a crash-recovery safety net, not the gate-wait mechanism. - -This means typed input in the builder pane reaches the live Claude session immediately, exactly like any other interactive Claude Code conversation. There is no "session ended at gate" state to worry about under normal operation. - -## Configuration - -PIR uses the same `.codev/config.json` configuration as other protocols. The `worktree` block (from Issue 689) enables the at-gate dev review flow: +## The state machine ```json -{ - "worktree": { - "symlinks": [".env.local", "packages/*/.env"], - "postSpawn": ["pnpm install --frozen-lockfile"], - "devCommand": "pnpm dev" - } -} +{{> protocols/pir/protocol.json}} ``` -Without `worktree.devCommand`, `afx dev` won't work and the `dev-approval` gate degenerates to a diff-read — at which point you should probably use AIR or BUGFIX instead. - -## Multi-Agent Consultation - -- **plan**: human-only review. No AI consultation. -- **implement**: no AI consult — the human at the `dev-approval` gate is the sole reviewer of the running code. -- **review**: 3-way consultation (Gemini, Codex, Claude; type=impl) after the PR is opened, as a **single advisory pass** (`max_iterations: 1`). Same consult type (`impl`) as BUGFIX / AIR's PR-creation consult. - -The consultation at the PR is a single pass — there is **no iterate-until-APPROVE loop**. A `REQUEST_CHANGES` does not block or re-trigger it; the builder addresses or rebuts it and escalates it to the human at the `pr` gate, who is the sole remaining reviewer of any resulting fix (the consultation does not re-check it). - -Net: PIR's distinguishing features are the two human gates (`plan-approval`, `dev-approval`), not AI-consult density. +## Gates -To disable consultation entirely, say "without multi-agent consultation" when starting work. +Gate names are opaque strings keyed by `(project_id, gate_name)`, so sharing a name with another +protocol is safe and needs no porch change. -## Signals +| Gate | When | What the human does | +|---|---|---| +| `plan-approval` | pre-PR | Reads the plan committed on the builder branch, before any code exists | +| `dev-approval` | pre-PR | **PIR's distinctive gate** — reviews the *running* worktree via `afx dev` | +| `pr` | post-PR | Reviews on GitHub, then approves; porch wakes the builder to merge | -PIR uses the standard porch signal vocabulary: +The `pr` gate makes the merge trigger **structured porch state** rather than free text in the +builder's pane — closing the self-merge class where a builder infers authorization from +ambiguous prose. -``` -PHASE_COMPLETE # Current phase build complete -BLOCKED:reason # Cannot proceed -``` +**Gates do not notify the architect automatically.** Porch broadcasts `overview-changed` over +SSE; the VSCode Builders tree renders the blocked state with a bell and raises a toast. CLI +users see it via the builder pane or `porch pending`. The builder's job at any gate is: write +the artifact, commit, signal, wait — never to invoke `porch approve` itself. -Signals are informational for log readability. The state machine is driven by `porch done` and `porch next` CLI calls inside the builder turn. +## Rejection is iteration, not a command -## Commit Messages +There is no `porch reject`. Feedback arrives however is convenient — editing the plan file, +typing in the builder pane, `afx send`, an issue comment — the builder revises and recommits, +and **the gate stays pending until a human approves it**. The same pattern works at both +pre-PR gates. -Commits during PIR phases use the issue-driven format: +## Artifacts -``` -[PIR #] Plan draft -[PIR #] Implement avatar masking -[PIR #] Add Android-side regression test -``` +Plan and review live in `codev/plans/` and `codev/reviews/` on the builder branch and ship to +the default branch with the merge. The review is shaped like SPIR's (Summary, Architecture +Updates, Lessons Learned) so `codev/reviews/` stays semantically consistent across protocols. -The PR title follows the project's existing PR convention. +## Consultation -## Branch Naming +**One advisory CMAP pass at the PR** (`max_iterations: 1`) — no iterate-until-APPROVE loop. A +`REQUEST_CHANGES` escalates to the human at the `pr` gate rather than triggering an automatic +re-review. -``` -builder/pir- -``` +That footprint is a **design invariant, and it is fragile**: porch resolves models as +*config > protocol*, so a project-wide `porch.consultation.models` (say a SPIR-tuned 3-model +list) silently inflates PIR's cost. Leave it unset, or scope it per-protocol. -Example: `builder/pir-842` for a PIR spawn against GitHub issue #842. +## Builder session -## File Locations +A long-running interactive session in a Tower-managed PTY, launched as `claude ""` +inside a `while true` restart loop. Typed input reaches the live session immediately; the loop +is crash recovery, not the gate-wait mechanism. There is no "session ended at gate" state. -``` -codev/plans/-.md # written in plan phase, on builder branch -codev/reviews/-.md # written in review phase (post-dev-approval-approval), on builder branch; becomes PR body -codev/projects/-/status.yaml # porch state, managed automatically -``` +## Configuration -The plan and review files ship to `main` with the merged PR — durable, searchable, git-versioned. The review file includes Summary + Architecture Updates + Lessons Learned + supporting sections, so `codev/reviews/` stays semantically consistent across protocols. +The `worktree` block in `.codev/config.json` is what makes the `dev-approval` gate work — see +the `runnable-worktrees` skill for `symlinks`, `postSpawn` and `devCommand`. diff --git a/codev-skeleton/protocols/research/builder-prompt.md b/codev-skeleton/protocols/research/builder-prompt.md index 088262853..b54c6be0f 100644 --- a/codev-skeleton/protocols/research/builder-prompt.md +++ b/codev-skeleton/protocols/research/builder-prompt.md @@ -1,91 +1,60 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are conducting multi-agent research. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the RESEARCH protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Use `consult` for the 3-way investigation and critique phases + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way consultation** — always follow porch next → porch done cycle + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the RESEARCH protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. -## RESEARCH Overview +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. -The RESEARCH protocol produces a high-confidence research report through triangulation: +## Research Topic -1. **Scope** — Define the precise question, scope, and acceptance criteria. Write a research brief. Gate: architect approval before proceeding. -2. **Investigate** — Dispatch the brief to 3 models (Gemini, Codex, Claude) in parallel. Each investigates independently. No anchoring — they don't see each other's work. -3. **Synthesize** — Read all 3 reports. Identify consensus, disagreements, and unique contributions. Write a single synthesis report organized by topic (not by model). -4. **Critique** — Send the synthesis back to all 3 models for critique. Incorporate valid feedback. Document rejected critique. Finalize the report. +{{task_text}} -## Output Location +## Output -All artifacts go to `codev/research/`: -- `-brief.md` — the scoped question (Phase 1) -- `-gemini.md`, `-codex.md`, `-claude.md` — individual investigations (Phase 2) -- `.md` — the final synthesis report (Phase 3+4, this is the deliverable) -- `-critique-rebuttals.md` — critique responses (Phase 4) - -{{#if task}} -## Research Topic -{{task_text}} -{{/if}} +`codev/research/.md` ## Key Principles -- **Triangulate**: consensus across 3 models > any single model's claim -- **Cite sources**: tell investigators to provide sources where possible -- **Be candid about uncertainty**: "I don't know" > confabulation -- **Organize by topic, not by model**: the synthesis is a standalone document -- **Note surprises**: the most valuable findings are often unexpected -- **Keep it concise**: the synthesis should be shorter than the sum of the investigations - -## Using consult for 3-way Investigation +- **Triangulate**: consensus across three models beats any single model's claim +- **Cite sources**; be candid about uncertainty — "I don't know" beats confabulation +- **Organize by topic, not by model** — the synthesis is a standalone document +- **Note surprises**: the most valuable findings are usually the unexpected ones +- **Preserve disagreement**: smoothing over conflict destroys the signal that made a 3-way + investigation worth running +- Keep the synthesis shorter than the sum of its investigations -For the investigate phase, use the `consult` CLI to dispatch to each model: +## Dispatching the investigation ```bash -# Phase 2: parallel investigation +# investigate — parallel, independent consult -m gemini --prompt-file codev/research/-brief.md --output codev/research/-gemini.md & -consult -m codex --prompt-file codev/research/-brief.md --output codev/research/-codex.md & +consult -m codex --prompt-file codev/research/-brief.md --output codev/research/-codex.md & consult -m claude --prompt-file codev/research/-brief.md --output codev/research/-claude.md & wait -``` -For the critique phase: -```bash -# Phase 4: parallel critique +# critique — same shape, pointed at the synthesis consult -m gemini --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/.md --output codev/research/-critique-gemini.md & -consult -m codex --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/.md --output codev/research/-critique-codex.md & +consult -m codex --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/.md --output codev/research/-critique-codex.md & consult -m claude --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/.md --output codev/research/-critique-claude.md & wait ``` -## Getting Started -1. Read the RESEARCH protocol document -2. Understand the research question from the architect -3. Write the research brief (Phase 1) -4. Wait for scope-approval before proceeding to investigation - ---- - -## Protocol Reference (full text) +## Notifications -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/research/protocol.md b/codev-skeleton/protocols/research/protocol.md index 2c2e8ec02..8d7cb72e2 100644 --- a/codev-skeleton/protocols/research/protocol.md +++ b/codev-skeleton/protocols/research/protocol.md @@ -1,169 +1,44 @@ # RESEARCH Protocol -## Overview +Scope → Investigate → Synthesize → Critique. Multiple models investigate the same question +independently, their findings are synthesized, and the synthesis is adversarially critiqued +before it is trusted. **The state machine below is authoritative on which models actually +run** — the set can be smaller than the ideal when a provider's consult lane is unavailable +(it is currently `["codex"]` for investigation, the agy/Gemini and hermes lanes being degraded). -Multi-agent research with 3-way investigation, synthesis, and critique. Three AI models independently investigate a question, their findings are synthesized into a single report, and then all three models critique the synthesis for gaps, errors, and bias. +Use it for competitive and technology analysis, "state of X" questions, and architectural +decision support in an unfamiliar domain — cases where a single model's confident answer is +exactly the failure mode. -**Core Principle**: Triangulate. No single model's knowledge is authoritative. Consensus across models is more reliable than any individual output. +## The state machine -## When to Use - -**Use for**: Competitive analysis, technology evaluation, market research, architectural decision support, "what's the state of X?" questions, exploring unfamiliar domains. - -**Skip for**: Implementation work (use SPIR/ASPIR), quick questions (just ask), experiments (use EXPERIMENT), known-answer lookups (just search). +```json +{{> protocols/research/protocol.json}} +``` ## Output -All research artifacts go to `codev/research/`. The final deliverable is a single synthesis report at `codev/research/.md`. +`codev/research/.md` — the report, with its sources and its disagreements preserved. ## Phases -### Phase 1: Scope - -**Purpose**: Make sure we're asking the right question before spending 3 models' worth of compute on answering it. - -The builder: -1. Reads the architect's research request -2. Clarifies the question — what specifically are we trying to learn? -3. Defines the scope — what's in, what's out, what depth is needed -4. Defines acceptance criteria — what does a good answer look like? -5. Writes a **research brief** (`codev/research/-brief.md`) with: - - The precise question(s) - - Scope boundaries - - **Required targets** (when applicable — not all research questions have them). When the user names specific projects, products, or systems, those are exemplars of a CLASS, not an exhaustive list. The brief should: - - List the named targets as required coverage (each gets a dedicated section) - - Identify the CLASS they represent (e.g., "open-source always-on agent frameworks") - - Instruct investigators to find OTHER members of that class the user didn't name — discovering what the user SHOULD be thinking about is often the most valuable part of the research - - If an investigator cannot find information about a required target, they must say so explicitly — not silently skip it - - **Optional context** — additional sources that may be useful but are not required - - What a useful answer looks like - - Suggested sources or angles for the investigators -6. Sends the brief to the architect for approval - -**Gate**: `scope-approval` — the architect confirms the question is correctly scoped before the 3-way investigation begins. This prevents wasting compute on a badly-framed question. - -### Phase 2: Investigate (3-way parallel) - -**Purpose**: Get three independent perspectives on the question. - -The builder dispatches the research brief to three models (Gemini, Codex, Claude) via `consult`. Each model: -1. Receives the scoped research brief -2. Independently investigates using web search, its training knowledge, and reasoning -3. Produces a standalone investigation report with: - - **A dedicated section for each required target** from the brief. Every required target gets its own heading with specific findings — not mentioned in passing, not substituted with an easier target. If a required target yields no findings, the section must say "No information found" rather than being omitted. - - Findings (with sources where possible) - - Confidence levels on key claims - - Gaps it couldn't fill - - Surprises or things that contradicted expectations - -The investigations run in **parallel** — each model works independently without seeing the others' output. This prevents anchoring bias. - -Investigation reports are saved to: -- `codev/research/-gemini.md` -- `codev/research/-codex.md` -- `codev/research/-claude.md` - -### Phase 3: Synthesize - -**Purpose**: Merge three independent reports into one coherent document. - -The builder: -1. Reads all three investigation reports -2. Identifies **consensus** — what all three agree on (highest confidence) -3. Identifies **disagreements** — where models contradict each other -4. Resolves conflicts — picks the best-supported position, notes the disagreement -5. Identifies **unique contributions** — things only one model found that the others missed -6. Writes the **synthesis report** (`codev/research/.md`) with: - - **Scope summary** — a short section (before the executive summary) restating the research question, required targets, and scope boundaries from the brief. A reader should understand what was asked without needing to read the brief separately. - - Executive summary - - Findings (organized by topic, not by model) - - Confidence annotations (consensus vs. single-source) - - Gaps and limitations - - Recommendations (if the research brief asked for them) - -The synthesis is written as a **standalone document** — a reader should never need to reference the individual investigation reports. Those are kept as appendices for traceability. - -### Phase 4: Critique (3-way review) - -**Purpose**: Pressure-test the synthesis for gaps, errors, and bias. +**Scope** — write the research brief: the question, why it matters, what would count as an +answer, and what is out of scope. Gated by `scope-approval`, because a badly framed question +wastes the investigation's compute and produces a confident answer to the wrong thing. -The builder dispatches the synthesis report back to all three models for critique. Each model: -1. Reads the synthesis -2. **Checks coverage against the brief** — does every required target from the research brief have dedicated coverage in the synthesis? Lists any required targets that were named in the brief but have zero or minimal coverage. This is the #1 critique check. -3. Checks for factual errors or unsupported claims -4. Identifies gaps — important aspects the synthesis missed -5. Flags potential bias — did the synthesis over-weight one model's perspective? -6. Suggests specific improvements +**Investigate** — the configured models (see the state machine) work the question +**independently**. Independence is the point: cross-contaminated investigations converge on a +shared error, so where more than one model is available each researches without seeing the others. -The builder then: -1. Incorporates valid critique -2. Documents rejected critique with rationale -3. Finalizes the report -4. Commits to `codev/research/.md` +**Synthesize** — merge findings and, critically, **preserve disagreement**. Where models +diverge, say so and say why; a synthesis that smooths over conflict has destroyed the signal +that made a multi-model investigation worth running. -## File Structure +**Critique** — adversarial pass over the synthesis. What is asserted without a source? What +would change the conclusion? Reaching `research-complete` means the report survived this, not +that it was written. -Only the brief and final report are checked in. Individual investigation reports and full critique outputs are working artifacts — useful during the process but not committed to the repo. - -``` -codev/research/ -├── -brief.md # Phase 1: scoped research question (checked in) -└── .md # Phase 3+4: final synthesis (the deliverable, checked in) -``` - -The final report includes: -- A **"Disagreements and resolution"** section documenting where the three investigators disagreed and how the synthesis resolved each disagreement -- A **"Changes from critique"** section summarizing what the critique phase changed (not the full critique — just what was added, removed, or corrected and why) - -Individual investigation reports (`-gemini.md`, `-codex.md`, `-claude.md`) and raw critique outputs are kept locally during the research process but NOT committed. The final report is the deliverable; the process artifacts are disposable. - -## Best Practices - -### Scoping -- A good research question is specific enough to answer in 1500-3000 words per model -- "What's the state of X?" is too broad — "What are the top 5 players in X, their strengths/weaknesses, and the structural gaps?" is better -- Include the "so what" — why are we researching this? What decision does it inform? - -### Investigation -- Tell each model to cite sources where possible -- Tell each model to be candid about uncertainty — "I don't know" is better than confabulation -- Tell each model to note surprises — the most valuable findings are often the unexpected ones - -### Synthesis -- Organize by topic, not by model ("here's what we found about X" not "here's what Gemini said") -- Weight consensus over single-model claims -- Don't smooth over disagreements — note them explicitly -- Keep the synthesis shorter than the sum of the investigations - -### Critique -- Critiquers should focus on gaps and errors, not style -- A critique that says "add more about X" is useful; "rewrite the intro" is not -- The builder should reject critique that's outside the original scope - -## Integration with Other Protocols - -### Research → SPIR -When research informs a feature decision: -1. Reference the research report in the spec -2. Link specific findings as evidence for design choices - -### Research → EXPERIMENT -When research identifies something worth testing: -1. Create an experiment to validate the research finding -2. Reference the research report as motivation - -## Git Workflow - -### Commits -``` -[Research: topic] Scoped research brief -[Research: topic] 3-way investigation complete -[Research: topic] Synthesis report -[Research: topic] Final report (post-critique) -``` +## Reporting standard -### What to Commit -- All investigation reports (for traceability) -- The final synthesis (the deliverable) -- The critique rebuttals (for process transparency) -- Do NOT commit raw web search results or intermediate notes +Cite sources for factual claims and mark inference as inference. A research report that cannot +be checked is an opinion with footnotes. diff --git a/codev-skeleton/protocols/spike/builder-prompt.md b/codev-skeleton/protocols/spike/builder-prompt.md index 6d30dc649..4253b086d 100644 --- a/codev-skeleton/protocols/spike/builder-prompt.md +++ b/codev-skeleton/protocols/spike/builder-prompt.md @@ -1,68 +1,50 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are executing a time-boxed technical feasibility spike. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the SPIKE protocol yourself (no porch orchestration) -- Stay focused on the question — don't gold-plate -- The findings document is your deliverable, not the code -{{/if}} - -## Protocol -Follow the SPIKE protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. -{{#if task}} -## Spike Question -{{task_text}} +You follow the protocol yourself; the architect verifies compliance. {{/if}} -## Recommended Workflow +{{#if mode_strict}} +## Mode: STRICT -Follow this 3-step workflow. You can skip or reorder steps as the investigation demands. +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. +{{/if}} -### 1. Research -- Read documentation, examine existing code, search for prior art -- Identify constraints, dependencies, and potential blockers -- Understand the problem space before writing any code +## Protocol -### 2. Iterate -- Build minimal proof-of-concept code to test approaches -- Focus on answering the feasibility question, not building production code -- POC code doesn't need tests or polish -- **Skip this step** if the answer is clear from research alone +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. -### 3. Findings -- Write findings to `codev/spikes/-.md` using the template -- Provide a clear feasibility verdict: Feasible / Not Feasible / Feasible with Caveats -- Commit the findings document -- Notify the architect: `afx send architect "Spike complete. Verdict: [verdict]"` +## Spike Question -## Key Principles +{{task_text}} -- **Time-boxing**: Stay focused on the question. Don't explore tangents. -- **Exploration over perfection**: POC code doesn't need tests or polish. -- **Clear output**: The findings document is the deliverable, not the code. -- **Know when to stop**: Once you can answer the feasibility question, write findings and stop. Don't keep iterating. -- **Document failures**: "Not feasible" is a valid and valuable finding. +## Workflow -## Handling Flaky Tests +Three steps; skip or reorder as the investigation demands. -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your findings under a `## Flaky Tests` section -5. Commit the skip and continue with your work +1. **Research** — documentation, existing code, prior art. Identify constraints, dependencies + and blockers before writing any code. +2. **Iterate** — minimal proof-of-concept to test approaches. POC code needs no tests or polish; + it exists to answer the question. **Skip this entirely** if research already answers it. +3. **Findings** — write `codev/spikes/-.md` with a clear verdict (Feasible / Not + Feasible / Feasible with Caveats), commit it, and notify: + `afx send architect "Spike complete. Verdict: [verdict]"` -## Getting Started -1. Read the SPIKE protocol document -2. Understand the question you're investigating -3. Start with research — don't jump straight to code +## Key Principles ---- +- **Time-box**: stay on the question, don't explore tangents +- **The findings document is the deliverable, not the code** +- **Know when to stop**: once you can answer the question, write findings and stop +- **"Not feasible" is a valuable finding.** The failure mode is an inconclusive spike — time + spent, nothing recorded, question still open -## Protocol Reference (full text) +## Notifications -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/spike/protocol.md b/codev-skeleton/protocols/spike/protocol.md index 764a0bea6..0e72fdb1d 100644 --- a/codev-skeleton/protocols/spike/protocol.md +++ b/codev-skeleton/protocols/spike/protocol.md @@ -1,128 +1,45 @@ # SPIKE Protocol -## Overview +A time-boxed feasibility investigation that answers one question: **can this be done, and at +what cost?** The deliverable is findings, not shipped code. -Time-boxed technical feasibility exploration. Answer "Can we do X?" and "What would it take?" before committing to a full SPIR project. +Use it before committing to a SPIR project whose feasibility is genuinely unknown — an unfamiliar +library, an unproven integration, a performance question that argument cannot settle. -**Core Principle**: Stay focused on the question. Once you can answer it, write findings and stop. +## The state machine -## When to Use - -**Use for**: Quick technical feasibility investigations, proof-of-concept explorations, "can we do X?" questions, evaluating approaches before committing to SPIR - -**Skip for**: Production code (use SPIR), formal hypothesis testing (use EXPERIMENT), bug fixes (use BUGFIX) - -### Spike vs Experiment - -| | Spike | Experiment | -|---|---|---| -| **Goal** | Answer a feasibility question | Test a formal hypothesis | -| **Structure** | Lightweight guidance | Formal phases (hypothesis/design/execute/analyze) | -| **Output** | Findings document | Experiment notes with metrics | -| **Rigor** | Exploration-first | Measurement-first | -| **Time** | Short (hours) | Longer (days) | - -## Spawning a Spike - -```bash -afx spawn --task "Can we use WebSockets for real-time updates?" --protocol spike -afx spawn --task "What would it take to support SQLite FTS?" --protocol spike +```json +{{> protocols/spike/protocol.json}} ``` -Spikes are always soft mode — no porch orchestration, no gates, no consultation. - -## Recommended Workflow - -The following 3-step workflow is **guidance only** — not enforced by porch. Follow it, skip steps, or reorder as the investigation demands. - -### Step 1: Research - -- Read documentation, examine existing code, search for prior art -- Identify constraints, dependencies, and potential blockers -- Understand the problem space before writing any code -- Check if someone has already investigated this (look in `codev/spikes/`) - -### Step 2: Iterate - -- Build minimal proof-of-concept code -- Try different approaches, hit walls, pivot -- Focus on answering the feasibility question, not building production code -- **Skip this step** if the answer is clear from research alone - -### Step 3: Findings - -- Write the findings document at `codev/spikes/-.md` -- Use the embedded template at the end of this protocol -- Provide a clear feasibility verdict -- Commit and notify the architect +## Proof-of-concept code -## Output +Throwaway by design. It exists to answer the question, and it is not held to production +standards — but it must not be quietly promoted into production later either. If the answer is +"feasible", a SPIR project builds the real thing. -Findings are stored in `codev/spikes/` using the pattern: `-.md` +## Outcomes -Examples: -- `codev/spikes/462-websocket-feasibility.md` -- `codev/spikes/475-sqlite-fts-performance.md` +| Verdict | What the findings must contain | +|---|---| +| **Feasible** | Recommended approach and rough cost, enough for the architect to decide on a SPIR project | +| **Not feasible** | Why, what was tried, and what alternatives exist — this is what stops the investigation being repeated in six months | +| **Feasible with caveats** | The conditions, risks and trade-offs that make it conditional | -The `` is the GitHub issue number or project ID. +A negative result is a successful spike. The failure mode is an inconclusive one: time spent, +nothing recorded, question still open. -## Proof-of-Concept Code +Notify the architect with the verdict when done. -POC code from the iterate step is committed to the spike branch alongside the findings document. It serves as evidence supporting the findings. However: +## Findings -- POC code does NOT need tests, polish, or production quality -- POC code does NOT get merged to main — it stays on the spike branch -- The findings document is the primary deliverable; the code is supporting evidence -- If the spike leads to a SPIR project, the builder starts fresh +Write findings using this structure: -## Outcome Handling - -- **Feasible**: Write findings with recommended approach and effort estimate. Architect decides whether to create a SPIR project. -- **Not Feasible**: Write findings documenting why, what was tried, and what alternatives exist. This prevents future teams from repeating the investigation. -- **Feasible with Caveats**: Write findings with conditions, risks, and trade-offs. - -In all cases, notify the architect: -```bash -afx send architect "Spike complete. Verdict: [feasible/not feasible/caveats]" -``` +{{> protocols/spike/templates/findings.md}} -## Git Workflow +## Git -### Commits ``` [Spike 462] Research: WebSocket library comparison -[Spike 462] Iterate: POC with ws library [Spike 462] Findings: WebSockets feasible for real-time updates ``` - -### When to Commit -- After significant research findings -- After each iteration attempt -- When writing the findings document (final commit) - -## Integration with Other Protocols - -### Spike -> SPIR -When a spike validates feasibility: -1. Create a SPIR spec referencing the spike findings -2. Use findings to inform the solution approach -3. Reference effort estimate for planning - -Example spec reference: -```markdown -## Background -Spike 462 confirmed WebSocket feasibility with the `ws` library. -See: codev/spikes/462-websocket-feasibility.md -``` - -### Spike -> "Do Not Pursue" -When a spike finds something is not feasible: -1. Document clearly in findings -2. Close the related GitHub issue with a link to findings -3. The findings become institutional knowledge - -## Template: findings.md - -Write the findings document using the following template: - -{{> protocols/spike/templates/findings.md}} diff --git a/codev-skeleton/protocols/spike/templates/findings.md b/codev-skeleton/protocols/spike/templates/findings.md index 3fa8c2c36..740d28dcf 100644 --- a/codev-skeleton/protocols/spike/templates/findings.md +++ b/codev-skeleton/protocols/spike/templates/findings.md @@ -1,67 +1,37 @@ # Spike: [Title] -**Date**: YYYY-MM-DD - -**Verdict**: Feasible | Not Feasible | Feasible with Caveats +**Date**: YYYY-MM-DD · **Verdict**: Feasible | Not Feasible | Feasible with Caveats ## Question -What technical question was being investigated? Be specific: -- What are you trying to determine? -- What prompted this investigation? -- What decision depends on the answer? +The technical question investigated, what prompted it, and the decision that depends on the answer. ## Research Summary -What was explored during the research phase: -- Documentation read -- Existing code examined -- Prior art found -- Key constraints identified +What was explored — documentation read, existing code examined, prior art, and the key constraints identified. ## Approaches Tried -What was built or tested during the iterate phase: +What was built or tested. For each: what it was, what happened, and whether it worked. ### Approach 1: [Name] -- **What**: Brief description of what was tried -- **Result**: What happened -- **Verdict**: Worked / Didn't work / Partially worked - -### Approach 2: [Name] -*(Add more approaches as needed, or remove if research alone answered the question)* ## Constraints Discovered -Technical limitations, dependencies, and gotchas found during the investigation: -- [Constraint 1] -- [Constraint 2] +Technical limitations, dependencies, and gotchas found during the investigation. ## Recommended Approach -*(If feasible)* How should full implementation proceed? -- Recommended library/technique/pattern -- Key architectural decisions -- Things to watch out for - -*(If not feasible)* Why not, and what alternatives exist? +If feasible: how full implementation should proceed — recommended library/technique/pattern, key architectural decisions, and what to watch out for. If not feasible: why, and what alternatives exist. ## Effort Estimate -Rough sizing for a full SPIR project: **Small** | **Medium** | **Large** - -- Small: < 300 LOC, 1-2 files, straightforward -- Medium: 300-1000 LOC, multiple files, some complexity -- Large: 1000+ LOC, architectural changes, significant complexity +Rough sizing for a full SPIR project: **Small** (< 300 LOC) | **Medium** (300–1000 LOC) | **Large** (1000+ LOC, architectural). ## Next Steps -- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"] -- [ ] [Or: "Do not pursue — blocked by X"] -- [ ] [Or: "Investigate Y further before deciding"] +- [ ] The recommended action (create a SPIR spec, do not pursue, or investigate further before deciding). ## References -- [Link to relevant documentation] -- [Link to relevant code/commits] -- [Link to external resources consulted] +Relevant documentation, code/commits, and external resources consulted. diff --git a/codev-skeleton/protocols/spir/builder-prompt.md b/codev-skeleton/protocols/spir/builder-prompt.md index 437287968..1f885ca49 100644 --- a/codev-skeleton/protocols/spir/builder-prompt.md +++ b/codev-skeleton/protocols/spir/builder-prompt.md @@ -4,36 +4,36 @@ You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the protocol document yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Run consultations manually when the protocol calls for them -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. Run consultations where the +protocol calls for them. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals -- Do not deviate from the porch-driven workflow - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way review** — always follow porch next → porch done cycle -- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Do not +hand-run consultations porch would run, advance plan phases yourself, or skip the 3-way review. + +Never hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the SPIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +Follow the SPIR protocol. The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. ## Baked Decisions -If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review. +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. -If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding. +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. {{#if spec}} ## Spec @@ -60,31 +60,24 @@ Follow the implementation plan at: `{{plan.path}}` ## PR Strategy -**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs. - -By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch. - -### Architect-requested PRs - -The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request. - -### Multi-PR Mechanics (when the architect requests sequential PRs) +**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits +within a single PR, not as separate PRs. The plan's instruction that "each phase commits +independently" refers to git commits, not PRs. -Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop: +By default, the PR is opened during/after the final implement phase, with all phase-commits +already on the branch. -1. Cut a branch, open a PR, wait for merge -2. After merge: `git fetch origin && git checkout -b origin/` — where `` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure) -3. Continue to the next slice, open another PR -4. Repeat +The architect MAY request a PR at any point — for spec review, mid-implementation feedback, or +slicing a large spec into shippable pieces. Follow that direction when they do; the prohibition +is on *you* deciding to open per-phase PRs unasked. -**Important**: Do NOT run `git checkout ` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/` via fetch. - -Record PRs in status.yaml: `porch done {{project_id}} --pr --branch ` -Record merges: `porch done {{project_id}} --merged ` +Record them: `porch done {{project_id}} --pr --branch `, and +`porch done {{project_id}} --merged `. ## Verify Phase -After the final PR merges, the project enters the **verify** phase. You stay alive through verify: +After the final PR merges the project enters **verify**, and you stay alive through it: + 1. Pull the integration branch into your worktree 2. Run `porch done {{project_id}}` to signal verification is ready 3. The architect approves `verify-approval` when satisfied @@ -92,28 +85,6 @@ After the final PR merges, the project enters the **verify** phase. You stay ali If verification is not needed: `porch verify {{project_id}} --skip "reason"` ## Notifications -Always use `afx send architect "..."` to notify the architect at key moments: -- **Gate reached**: `afx send architect "Project {{project_id}}: ready for approval"` -- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"` -- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."` -- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"` - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue with your work - -## Getting Started -1. Read the protocol document thoroughly -2. Review the spec and plan (if available) -3. Begin implementation following the protocol phases - ---- - -## Protocol Reference (full text) -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev-skeleton/protocols/spir/consult-types/impl-review.md b/codev-skeleton/protocols/spir/consult-types/impl-review.md index de01b8d00..7028b4947 100644 --- a/codev-skeleton/protocols/spir/consult-types/impl-review.md +++ b/codev-skeleton/protocols/spir/consult-types/impl-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev-skeleton/protocols/spir/consult-types/phase-review.md b/codev-skeleton/protocols/spir/consult-types/phase-review.md index de01b8d00..7028b4947 100644 --- a/codev-skeleton/protocols/spir/consult-types/phase-review.md +++ b/codev-skeleton/protocols/spir/consult-types/phase-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev-skeleton/protocols/spir/consult-types/plan-review.md b/codev-skeleton/protocols/spir/consult-types/plan-review.md index 485ff3183..b278aa4ea 100644 --- a/codev-skeleton/protocols/spir/consult-types/plan-review.md +++ b/codev-skeleton/protocols/spir/consult-types/plan-review.md @@ -1,44 +1,28 @@ # Plan Review Prompt ## Context -You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it. + +You are reviewing an implementation plan during the Plan phase. The spec is already approved; judge whether the plan adequately describes HOW to implement it. ## Baked Decisions -If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. +If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Spec Coverage** - - Does the plan address all requirements in the spec? - - Are there spec requirements not covered by any phase? - - Are there phases that go beyond the spec scope? - -2. **Phase Breakdown** - - Are phases appropriately sized (not too large or too small)? - - Is the sequence logical (dependencies respected)? - - Can each phase be completed and committed independently? - -3. **Technical Approach** - - Is the implementation approach sound? - - Are the right files/modules being modified? - - Are there obvious better approaches being missed? +- **Spec coverage** — every spec requirement is addressed by some phase; nothing goes beyond the spec's scope. +- **Phase breakdown** — phases are appropriately sized, logically sequenced (dependencies respected), and each can be completed and committed independently. +- **Technical approach** — the approach is sound, the right files/modules are targeted, and no obviously better approach is being missed. +- **Testability** — each phase has clear test criteria and the spec's edge cases are addressable. +- **Risk** — blockers and cross-system dependencies are identified; the plan is realistic given the constraints. -4. **Testability** - - Does each phase have clear test criteria? - - Will the Defend step (writing tests) be feasible? - - Are edge cases from the spec addressable? - -5. **Risk Assessment** - - Are there potential blockers not addressed? - - Are dependencies on other systems identified? - - Is the plan realistic given constraints? +The spec is already approved — do not re-litigate spec decisions. Judge the plan as a guide a builder can follow successfully; verify referenced file paths look accurate. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -52,14 +36,6 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Plan is ready for human review -- `REQUEST_CHANGES`: Significant issues with approach or coverage -- `COMMENT`: Minor suggestions, plan is workable but could improve - -## Notes - -- The spec has already been approved - don't re-litigate spec decisions -- Focus on the quality of the plan as a guide for builders -- Consider: Would a builder be able to follow this plan successfully? -- If referencing existing code, verify file paths seem accurate +- `APPROVE`: plan is ready for human review. +- `REQUEST_CHANGES`: significant issues with approach or coverage. +- `COMMENT`: minor suggestions; the plan is workable but could improve. diff --git a/codev-skeleton/protocols/spir/consult-types/pr-review.md b/codev-skeleton/protocols/spir/consult-types/pr-review.md index 837cdea33..6b9a3e82a 100644 --- a/codev-skeleton/protocols/spir/consult-types/pr-review.md +++ b/codev-skeleton/protocols/spir/consult-types/pr-review.md @@ -1,44 +1,24 @@ # PR Ready Review Prompt ## Context -You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. -## Focus Areas - -1. **Completeness** - - Are all spec requirements implemented? - - Are all plan phases complete? - - Is the review document written (`codev/reviews/XXXX-name.md`)? - - Are all commits properly formatted (`[Spec XXXX][Phase]`)? - -2. **Test Status** - - Do all tests pass? - - Is test coverage adequate for the changes? - - Are there any skipped or flaky tests? +You are performing the final self-check during the Review phase — the builder has completed all implementation phases and is about to open the PR. This is the last check before the work goes to the architect for integration review. -3. **Code Cleanliness** - - Is there any debug code left in? - - Are there any TODO comments that should be resolved? - - Are there any `// REVIEW:` comments that weren't addressed? - - Is the code properly formatted? - -4. **Documentation** - - Are inline comments clear where needed? - - Is the review document comprehensive? - - Are any new APIs documented? +## Focus Areas -5. **PR Readiness** - - Is the branch up to date with its base (the integration branch the PR targets)? - - Are commits atomic and well-described? - - Is the change diff reasonable in size? +- **Completeness** — all spec requirements implemented, all plan phases complete, the review document written (`codev/reviews/XXXX-name.md`), and commits in the `[Spec XXXX][Phase]` format. +- **Test Status** — all tests pass, coverage is adequate for the changes, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO` / `// REVIEW:` left unaddressed, code properly formatted. +- **Documentation** — inline comments clear where needed, the review document comprehensive, new APIs documented. +- **PR Readiness** — the branch is up to date with its base (the integration branch the PR targets), commits are atomic and well-described, and the diff size is reasonable. ## Scope -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -63,14 +43,8 @@ PR_SUMMARY: | - [How to test] ``` -**Verdict meanings:** -- `APPROVE`: Ready to create PR -- `REQUEST_CHANGES`: Issues to fix before PR creation -- `COMMENT`: Minor items, can create PR but note feedback - -## Notes +- `APPROVE`: ready to create the PR. +- `REQUEST_CHANGES`: issues to fix before PR creation. +- `COMMENT`: minor items; can create the PR but note the feedback. -- This is the builder's final self-review before hand-off -- The PR_SUMMARY in your output can be used as the PR description -- Focus on "is this ready for someone else to review" not "is this perfect" -- Any issues found here are cheaper to fix than during integration review +The `PR_SUMMARY` block can be used directly as the PR description. diff --git a/codev-skeleton/protocols/spir/consult-types/spec-review.md b/codev-skeleton/protocols/spir/consult-types/spec-review.md index 73e346e00..48f0c495b 100644 --- a/codev-skeleton/protocols/spir/consult-types/spec-review.md +++ b/codev-skeleton/protocols/spir/consult-types/spec-review.md @@ -1,46 +1,28 @@ # Specification Review Prompt ## Context -You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval. + +You are reviewing a feature specification during the Specify phase, before it goes to human approval. Judge whether the spec is complete, correct, feasible, and clear enough for a builder to plan from. ## Baked Decisions If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Completeness** - - Are all requirements clearly stated? - - Are success criteria defined? - - Are edge cases considered? - - Is scope well-bounded (not too broad or vague)? - -2. **Correctness** - - Do requirements make sense technically? - - Are there contradictions? - - Is the problem statement accurate? - -3. **Feasibility** - - Can this be implemented with available tools/constraints? - - Are there obvious technical blockers? - - Is the scope realistic for a single spec? +- **Completeness** — requirements, success criteria, and edge cases are stated; scope is bounded, not vague. +- **Correctness** — the requirements are technically sound and internally consistent; the problem statement is accurate. +- **Feasibility** — implementable within the stated tools and constraints, with no obvious blockers. +- **Clarity** — a builder would know what to build; acceptance criteria are testable; terminology is consistent. +- **Structure** — the spec follows the delivered template (`protocols/spir/templates/spec.md`), which the specify prompt inlines. A spec that ignores the template's headings — usually because the builder pattern-matched an older spec in `codev/specs/` — is a defect: `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). A single genuinely-inapplicable section reduced to a one-line "N/A — [reason]" with its heading kept is fine, not grounds for `REQUEST_CHANGES`. -4. **Clarity** - - Would a builder understand what to build? - - Are acceptance criteria testable? - - Is terminology consistent? - -5. **Structure** - - The specify prompt delivers a canonical spec template (`protocols/spir/templates/spec.md`) inline. Does the spec actually follow it? - - Required headings, in order: `## Metadata`, `## Clarifying Questions Asked`, `## Problem Statement`, `## Current State`, `## Desired State`, `## Stakeholders`, `## Success Criteria`, `## Constraints`, `## Assumptions`, `## Solution Approaches`, `## Open Questions`, `## Performance Requirements`, `## Security Considerations`, `## Test Scenarios`, `## Dependencies`, `## References`, `## Risks and Mitigation`, `## Expert Consultation`, `## Approval`, `## Notes`. - - A free-form spec that reads well but ignores the template is a **defect**, not a style preference — it usually means the builder pattern-matched an older spec in `codev/specs/` instead of the delivered template. `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). - - A section that genuinely does not apply may be reduced to a one-line "N/A — [reason]", but the heading should remain. Do not `REQUEST_CHANGES` over one such section. +You are reviewing the specification (WHAT is built), not code or implementation (HOW) — that is the plan and implementation reviews. Be constructive: name the issue and suggest a fix. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -54,14 +36,6 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Spec is ready for human review -- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but consider feedback - -## Notes - -- You are NOT reviewing code - you are reviewing the specification document -- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review) -- Be constructive - identify issues AND suggest solutions -- If the spec references other specs, note if context seems missing +- `APPROVE`: spec is ready for human review. +- `REQUEST_CHANGES`: significant issues must be fixed first. +- `COMMENT`: minor suggestions; can proceed but consider the feedback. diff --git a/codev-skeleton/protocols/spir/prompts/implement.md b/codev-skeleton/protocols/spir/prompts/implement.md index bacc8502e..730c91ec4 100644 --- a/codev-skeleton/protocols/spir/prompts/implement.md +++ b/codev-skeleton/protocols/spir/prompts/implement.md @@ -2,9 +2,9 @@ You are executing the **IMPLEMENT** phase of the SPIR protocol. -## Your Goal +## Goal -Write clean, well-structured code AND tests that implement the current plan phase. +Implement the current plan phase — code and tests — so it matches the spec and passes build and tests. ## Context @@ -13,203 +13,34 @@ Write clean, well-structured code AND tests that implement the current plan phas - **Current State**: {{current_state}} - **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}} -## ⚠️ SCOPE RESTRICTION — READ THIS FIRST +## Scope: this phase only -**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).** +Your scope is exactly `{{plan_phase_id}}` ({{plan_phase_title}}), whose details are included below under "Current Plan Phase Details". Other phases are handled in later porch iterations — do not implement them, and do not read the full plan and build everything you see. Read `codev/specs/{{project_id}}-*.md` for requirements, but implement only what this phase requires. -- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations. -- **DO NOT** read the full plan file and implement everything you see. -- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope. -- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires. +When you signal `PHASE_COMPLETE`, porch runs the 3-way consultation, checks that tests exist and pass, and either respawns you with feedback or commits and moves to the next phase. -## What Happens After You Finish +## What must be true when you finish -When you signal `PHASE_COMPLETE`, porch will: -1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation -2. Check that tests exist and pass -3. If reviewers request changes, you'll be respawned with their feedback -4. Once approved, porch commits and moves to the next plan phase - -## Spec Compliance (CRITICAL) - -**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".** - -### Trust Hierarchy - -``` -SPEC (source of truth) - ↓ -PLAN (implementation guide derived from spec) - ↓ -EXISTING CODE (NOT TRUSTED - must be validated against spec) -``` - -**Never trust existing code over the spec.** Previous implementations may have drifted. - -### Pre-Implementation Sanity Check (PISC) - -**Before writing ANY code:** - -1. ✅ "Have I read the spec in the last 30 minutes?" -2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?" -3. ✅ "Does my approach match the spec's Technical Implementation section?" -4. ✅ "If the spec has code examples, am I following them?" -5. ✅ "Does the existing code I'm building on actually match the spec?" - -**If ANY answer is "no" or "unsure" → STOP and re-read the spec.** - -### Avoiding "Fixing Mode" - -A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to: -- Cargo-culting patterns that may be wrong -- Building on broken foundations -- Implementing something different from the spec - -**When you catch yourself "fixing" code:** -1. STOP -2. Ask: "What does the spec say about this?" -3. Re-read the spec's Traps to Avoid section -4. Verify existing code matches the spec before building on it - -## Prerequisites - -Before implementing, verify: -1. Previous phase (if any) is committed to git -2. You've read the plan phase you're implementing -3. You understand the success criteria for this phase -4. Dependencies from earlier phases are available - -## Process - -### 1. Review the Plan Phase - -Read the current phase in the plan: -- What is the objective? -- What files need to be created/modified? -- What are the success criteria? -- What dependencies exist? - -### 2. Set Up - -- Verify you're on the correct branch -- Check that previous phase is committed: `git log --oneline -5` -- Ensure build passes before starting: `npm run build` (or equivalent) - -### 3. Implement the Code - -Write the code following these principles: - -**Code Quality Standards**: -- Self-documenting code (clear names, obvious structure) -- No commented-out code -- No debug prints in final code -- Explicit error handling -- Follow project style guide - -**Implementation Approach**: -- Work on one file at a time -- Make small, incremental changes -- Document complex logic with comments - -### 4. Write Tests - -**Tests are required.** For each piece of functionality you implement: - -- Write unit tests for core logic -- Write integration tests if the phase involves multiple components -- Test error cases and edge conditions -- Ensure tests are deterministic (no flaky tests) - -**Test file locations** (follow project conventions): -- `tests/` or `__tests__/` directories -- `*.test.ts` or `*.spec.ts` naming - -### 5. Verify Everything Works - -Run both build and tests: - -```bash -npm run build # Must pass -npm test # Must pass -``` - -**Important**: Don't assume these commands exist. Check `package.json` first. - -Fix any errors before signaling completion. - -### 6. Self-Review - -Before signaling completion: -- Read through all code changes -- Read through all test changes -- Verify code matches the spec requirements -- Ensure no accidental debug code -- Check test coverage is adequate - -## Output - -When complete, you should have: -- Modified/created source files as specified in the plan phase -- Tests covering the new functionality -- All build checks passing -- All tests passing +- **The implementation matches the spec.** The spec is the source of truth; the plan derives from it; existing code is not trusted until validated against the spec, because earlier work may have drifted. Code that "works" but diverges from the spec is wrong. When you notice yourself patching symptoms in existing code, stop and re-check what the spec actually requires before building further. +- **Tests exist and are meaningful.** Unit tests for the core logic, integration tests where the phase spans components, and coverage of error and edge cases. Tests are deterministic. Follow the project's existing test locations and naming. +- **Build and tests pass.** Confirm the actual project commands (check `package.json` rather than assuming `npm run build` / `npm test` exist) and run them; fix failures before signaling. +- **The change is clean.** Self-documenting names, explicit error handling, no commented-out or debug code, only the files this phase touches — the simplest solution that satisfies the phase, not more. ## Signals -When implementation AND tests are complete and passing: - -``` -PHASE_COMPLETE -``` - -If you encounter a blocker: - -``` -BLOCKED:reason goes here -``` - -If you need spec/plan clarification: - -``` - -Your specific questions here - -``` - -## Important Notes - -1. **Follow the plan** - Implement what's specified, not more -2. **Don't over-engineer** - Simplest solution that works -3. **Don't skip error handling** - But don't go overboard either -4. **Keep changes focused** - Only touch files in this phase -5. **Build AND tests must pass** - Don't signal complete until both pass -6. **Write tests** - Every implementation phase needs tests - -## What NOT to Do - -- Don't modify files outside this phase's scope -- Don't add features not in the spec -- Don't leave TODO comments for later (fix now or note as blocker) -- Don't skip writing tests -- Don't use `git add .` or `git add -A` when you commit (security risk) - -## Handling Problems - -**If the plan is unclear**: -Signal `AWAITING_INPUT` with your specific question. - -**If you discover the spec is wrong**: -Signal `BLOCKED` and explain the issue. The Architect may need to update the spec. - -**If a dependency is missing**: -Signal `BLOCKED` with details about what's missing. - -**If build or tests fail and you can't fix it**: -Signal `BLOCKED` with the error message. - -**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use workarounds to avoid the failure -3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up -5. Commit the skip and continue with your work +- Implementation and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Blocked — the plan is wrong, the spec is wrong, a dependency is missing, or build/tests fail in a way you cannot resolve: + ``` + BLOCKED:reason goes here + ``` +- Need spec/plan clarification: + ``` + + Your specific questions here + + ``` + +A blocker is a signal, not a silent workaround: never edit `status.yaml` or bypass a porch check to force a green. diff --git a/codev-skeleton/protocols/spir/prompts/plan.md b/codev-skeleton/protocols/spir/prompts/plan.md index 2c12250dd..a70914431 100644 --- a/codev-skeleton/protocols/spir/prompts/plan.md +++ b/codev-skeleton/protocols/spir/prompts/plan.md @@ -2,9 +2,9 @@ You are executing the **PLAN** phase of the SPIR protocol. -## Your Goal +## Goal -Transform the approved specification into an executable implementation plan with clear phases. +Turn the approved spec into an executable plan at `codev/plans/{{artifact_name}}.md`: a phase breakdown a builder can implement one phase at a time. ## Context @@ -14,105 +14,41 @@ Transform the approved specification into an executable implementation plan with - **Spec File**: `codev/specs/{{artifact_name}}.md` - **Plan File**: `codev/plans/{{artifact_name}}.md` -## Prerequisites +## What must be true when you finish -Before planning, verify: -1. The specification exists and has been approved -2. You've read and understood the entire spec -3. Success criteria are clear and measurable +- **The plan derives from the spec.** You have read the whole spec — its functional and non-functional requirements, constraints, and success criteria — and the plan validates against them. +- **The work is decomposed into phases, each of which is:** + - **self-contained** — a complete unit of functionality; + - **independently testable** — verifiable on its own; + - **valuable** — delivers observable progress; + - **committable** — a single atomic commit. -## Process - -### 1. Analyze the Specification - -Read the spec thoroughly. Identify: -- All functional requirements -- Non-functional requirements -- Dependencies and constraints -- Success criteria to validate against - -### 2. Identify Implementation Phases - -Break the work into logical phases. Each phase should be: -- **Self-contained** - A complete unit of functionality -- **Independently testable** - Can be verified on its own -- **Valuable** - Delivers observable progress -- **Committable** - Can be a single atomic commit - -Good phase examples: -- "Database Schema" - Creates all tables/migrations -- "Core API Endpoints" - Implements main REST routes -- "Authentication Flow" - Handles login/logout/session - -Bad phase examples: -- "Setup" - Too vague -- "Part 1" - Not descriptive -- "Everything" - Not broken down - -### 3. Define Each Phase - -For each phase, document: -- **Objective** - Single clear goal -- **Files to modify/create** - Specific paths -- **Dependencies** - Which phases must complete first -- **Success criteria** - How to know it's done -- **Test approach** - What tests will verify it - -### 4. Order Phases by Dependencies - -Arrange phases so dependencies are satisfied: -``` -Phase 1: Database Schema (no dependencies) -Phase 2: Data Models (depends on Phase 1) -Phase 3: API Endpoints (depends on Phase 2) -Phase 4: Frontend Integration (depends on Phase 3) -``` - -### 5. Finalize - -After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. + A phase name states what it delivers ("Database schema", "Authentication flow"), not a position ("Setup", "Part 1"). +- **Each phase carries its own contract:** objective, the specific files it creates or modifies, which earlier phases it depends on, its success criteria, and how it will be tested. +- **Phases are ordered so dependencies are satisfied before the phase that needs them.** ## Output -Create the plan file at `codev/plans/{{artifact_name}}.md`, following the template below: +Write the plan to `codev/plans/{{artifact_name}}.md` using the template below as its interface: {{> protocols/spir/templates/plan.md}} ## Signals -Emit appropriate signals based on your progress: - -- After completing the plan draft: +- Draft done: ``` PLAN_DRAFTED ``` -## Commit Cadence +## Commit cadence -Make commits at these milestones: +Commit at each milestone, staging the plan file explicitly: +```bash +git add codev/plans/{{artifact_name}}.md +``` 1. `[Spec {{project_id}}] Initial implementation plan` 2. `[Spec {{project_id}}] Plan with multi-agent review` 3. `[Spec {{project_id}}] Plan with user feedback` 4. `[Spec {{project_id}}] Final approved plan` -**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: -```bash -git add codev/plans/{{artifact_name}}.md -``` - -## Important Notes - -1. **No time estimates** - Don't include hours/days/weeks -3. **Be specific about files** - Exact paths, not "the config file" -4. **Keep phases small** - 1-3 files per phase is ideal -5. **Document dependencies clearly** - Prevents blocked work - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't write code (that's for Implement phase) -- Don't estimate time (meaningless in AI development) -- Don't create phases that can't be independently tested -- Don't skip dependency analysis -- Don't make phases too large (if >5 files, split it) -- Don't use `git add .` or `git add -A` (security risk) +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Plan phase: decompose and sequence the work, do not write code, and do not estimate time. diff --git a/codev-skeleton/protocols/spir/prompts/review.md b/codev-skeleton/protocols/spir/prompts/review.md index eabe1b98e..b08cea345 100644 --- a/codev-skeleton/protocols/spir/prompts/review.md +++ b/codev-skeleton/protocols/spir/prompts/review.md @@ -2,9 +2,9 @@ You are executing the **REVIEW** phase of the SPIR protocol. -## Your Goal +## Goal -Perform a comprehensive review, document lessons learned, and prepare for PR submission. +Review the whole implementation, write the retrospective at `codev/reviews/{{artifact_name}}.md`, and open the PR — so porch's consultation and the architect both review a real PR. ## Context @@ -15,218 +15,65 @@ Perform a comprehensive review, document lessons learned, and prepare for PR sub - **Plan File**: `codev/plans/{{artifact_name}}.md` - **Review File**: `codev/reviews/{{artifact_name}}.md` -## Prerequisites +## What must be true when you finish -Before review, verify: -1. All implementation phases are committed -2. All tests are passing -3. Build is passing -4. Spec compliance verified for all phases +- **The work is done and green.** All phases committed (`git log --oneline | grep "[Spec {{project_id}}]"`), build and tests passing, no uncommitted changes. +- **The implementation has been reviewed against the spec** — code quality, architecture fit, and security considered; deviations from the spec noted with their reasons; every success criterion accounted for. +- **The review document exists** at `codev/reviews/{{artifact_name}}.md`, following the template below (its headings, its order — do not pattern-match an older review that predates it). +- **Consultation feedback is captured.** The review carries a `## Consultation Feedback` section that, per phase / round / model, records each concern and its disposition — **Addressed** (changed), **Rebutted** (why it does not apply), or **N/A** (out of scope / handled elsewhere). "No concerns raised — all consultations approved" is the right line when that is true; note COMMENT verdicts and any `CONSULT_ERROR`. Read the consult outputs from `codev/projects/{{project_id}}-*/`. +- **Governance facts are routed by tier** (see below). +- **The PR exists before you signal**, with a close-keyword so merging auto-closes the issue (see below). -Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"` - -## Process - -### 1. Comprehensive Review - -Review the entire implementation: - -**Code Quality**: -- Is the code readable and maintainable? -- Are there any code smells? -- Is error handling consistent? -- Are there any security concerns? - -**Architecture**: -- Does the implementation fit well with existing code? -- Are there any architectural concerns? -- Is the design scalable if needed? - -**Documentation**: -- Is code adequately commented where needed? -- Are public APIs documented? -- Is README updated if needed? - -### 2. Spec Comparison - -Compare final implementation to original specification: - -- What was delivered vs what was specified? -- Any deviations? Document why. -- All success criteria met? - -### 3. Create Review Document +## Output -Create `codev/reviews/{{artifact_name}}.md`, following the template below. Use these headings and this order — do not invent your own structure, and do not pattern-match an earlier review in `codev/reviews/` that predates this template. Steps 3b and 4 below expand on the `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch's review checks grep for the last two by exact heading. +Write the review to `codev/reviews/{{artifact_name}}.md` using the template below as its interface. Steps below expand its `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch greps the produced file for the last two by exact heading. {{> protocols/spir/templates/review.md}} -### 3b. Include Consultation Feedback - -**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded. - -Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model: - -```markdown -## Consultation Feedback - -### Specify Phase (Round 1) - -#### Gemini -- **Concern**: [Summary of the concern] - - **Addressed**: [What was changed to resolve it] - -#### Codex -- **Concern**: [Summary] - - **Rebutted**: [Why the current approach is correct] - -#### Claude -- No concerns raised (APPROVE) - -### Plan Phase (Round 1) -... -``` - -**Response types** — each concern gets exactly one: -- **Addressed**: Builder made a change to resolve the concern -- **Rebutted**: Builder explains why the concern doesn't apply -- **N/A**: Concern is out of scope, already handled elsewhere, or moot - -**Edge cases**: -- If all reviewers approved with no concerns: "No concerns raised — all consultations approved" -- For COMMENT verdicts: include their feedback (non-blocking but useful context) -- For CONSULT_ERROR (model failure): note "Consultation failed for [model]" -- If a phase had multiple rounds, give each round its own subsection +## Route governance facts by tier (Spec 987) -### 4. Update Architecture and Lessons Learned Documentation +Each governance doc has two tiers. **Route** each new fact; do not simply append to the cold archive. -**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing. +- **HOT** — `codev/resources/arch-critical.md` and `lessons-critical.md`: tiny, hard-capped, always injected into every prompt and into CLAUDE.md/AGENTS.md. Add here only a **behavior-changing, cross-cutting** fact a future builder must know up front. The hot files are capped: if one is full, **demote** a weaker entry into its cold counterpart to make room, and keep the hot file's cold-doc map accurate. +- **COLD** — `codev/resources/arch.md` and `lessons-learned.md`: full, on-demand reference for subsystem detail, file locations, one-offs, and spec-narrow recipes. -Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive: -- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer. -- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference. +The review's `## Architecture Updates` and `## Lessons Learned Updates` sections state what you routed where; if nothing qualifies, keep the heading with a one-line reason. Never grow a hot file past its cap by appending — route to cold or displace. The `update-arch-docs` skill encodes this discipline. -**Architecture Updates**: -1. Read `arch-critical.md` (hot) and skim `arch.md` (cold). -2. If this project produced a system-shape fact, route it: - - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate. - - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold). -3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason. +## Create the PR (before signaling) -**Lessons Learned Updates**: -1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold). -2. If this project produced a durable lesson, route it: - - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full). - - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file. -3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason. - -**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject. - -### 4b. Update Other Documentation - -If needed, also update: -- README.md (new features, changed behavior) -- API documentation - -### 5. Final Verification - -Before PR: -- [ ] All tests pass (use project-specific test command) -- [ ] Build passes (use project-specific build command) -- [ ] Lint passes (if configured) -- [ ] No uncommitted changes: `git status` -- [ ] Review document complete - -### 6. Create Pull Request - -**IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that -porch consultation reviews the actual PR, and the architect can review a real PR -when the pr gate fires. - -**PR body requirements**: The PR body MUST include `Closes #` (for feature issues) -or `Fixes #` (for bug issues) for the driving GitHub issue. If the PR closes -multiple issues (e.g. duplicates consolidated), include one keyword per issue. -Without this, GitHub will not auto-close the issue on merge. - -**Exception**: if this PR only partially addresses the issue (e.g. one phase of a -multi-PR effort), DO NOT use `Closes`/`Fixes` — reference the issue with `Refs #` -or `Part of #` instead. The issue stays open until the follow-up PR closes it. +The PR body must carry `Closes #` (feature) or `Fixes #` (bug) for the driving issue — one keyword per issue if several — so GitHub auto-closes on merge. **Exception:** a PR that only partially addresses its issue uses `Refs #` or `Part of #` instead, leaving the issue open for the follow-up. ```bash gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF' ## Summary -[Brief description of the implementation] +[what was implemented] -Closes # +Closes # ## Changes -- [Change 1] -- [Change 2] +- ... ## Testing -- All unit tests passing -- Integration tests added for [X] -- Manual testing completed for [Y] +- ... ## Spec -Link: codev/specs/{{artifact_name}}.md +codev/specs/{{artifact_name}}.md ## Review -Link: codev/reviews/{{artifact_name}}.md +codev/reviews/{{artifact_name}}.md EOF )" ``` -### 7. Signal Completion - -After the PR is created, signal completion. Porch will run 3-way consultation -(Gemini, Codex, Claude) automatically via the verify step. If reviewers request -changes, you'll be respawned with their feedback. - -## Output - -- Review document at `codev/reviews/{{artifact_name}}.md` -- Updated documentation (if needed) -- Pull request created and ready for review - ## Signals -- After review document is complete: +- Review document complete: ``` REVIEW_COMPLETE ``` - -- After PR is created — signal completion so porch runs consultation: +- PR created — signal so porch runs the 3-way consultation: ``` PR_READY ``` -## Important Notes - -1. **Be honest in lessons learned** - Future you will thank present you -3. **Document deviations** - They're not failures, they're learnings -4. **Update methodology** - If you found a better way, document it -5. **Don't skip the checklist** - It catches last-minute issues -6. **Clean PR description** - Makes review easier - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't skip lessons learned ("nothing to report") -- Don't merge your own PR (Architect handles integration) -- Don't leave uncommitted changes -- Don't forget to update documentation -- Don't rush this phase - it's valuable for learning -- Don't use `git add .` or `git add -A` (security risk) - -## Review Prompts for Reflection - -Ask yourself: -- What surprised me during implementation? -- Where did I spend the most time? Was it avoidable? -- What would have helped me go faster? -- Did the spec adequately describe what was needed? -- Did the plan phases make sense in hindsight? -- What tests caught issues? What tests were unnecessary? - -Capture these reflections in the lessons learned section. +Do not run `consult` (porch handles it) and merge your own PR only after the human approves the `pr` gate — never before. diff --git a/codev-skeleton/protocols/spir/prompts/specify.md b/codev-skeleton/protocols/spir/prompts/specify.md index daa5feab2..3c5af5a81 100644 --- a/codev-skeleton/protocols/spir/prompts/specify.md +++ b/codev-skeleton/protocols/spir/prompts/specify.md @@ -2,9 +2,9 @@ You are executing the **SPECIFY** phase of the SPIR protocol. -## Your Goal +## Goal -Create a comprehensive specification document that thoroughly explores the problem space and proposed solution. +Produce a specification at `codev/specs/{{artifact_name}}.md` that explores the problem space and the proposed solution well enough that the plan and implementation can follow without re-deciding anything. ## Context @@ -13,137 +13,47 @@ Create a comprehensive specification document that thoroughly explores the probl - **Current State**: {{current_state}} - **Spec File**: `codev/specs/{{artifact_name}}.md` -## Process +## What must be true when you finish -### 0. Check for Existing Spec (ALWAYS DO THIS FIRST) - -**Before asking ANY questions**, check if a spec already exists: - -```bash -ls codev/specs/{{project_id}}-*.md -``` - -**If a spec file exists:** -1. READ IT COMPLETELY - the answers to your questions are already there -2. The spec author has already made the key decisions -3. DO NOT ask clarifying questions - proceed directly to consultation -4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch - -**If no spec exists:** Proceed to Step 1 below. - -### 0.5 Baked Decisions - -Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec. - -If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting. - -### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS) - -Before writing anything, ask clarifying questions to understand: -- What problem is being solved? -- Who are the stakeholders? -- What are the constraints? -- What's in scope vs out of scope? -- What does success look like? - -If this is your first iteration AND no spec exists, ask these questions now and wait for answers. - -**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer. - -**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step. - -### 2. Problem Analysis - -Once you have answers, document: -- The problem being solved (clearly articulated) -- Current state vs desired state -- Stakeholders and their needs -- Assumptions and constraints - -### 3. Solution Exploration - -Generate multiple solution approaches. For each: -- Technical design overview -- Trade-offs (pros/cons) -- Complexity assessment -- Risk assessment - -### 4. Open Questions - -List uncertainties categorized as: -- **Critical** - blocks progress -- **Important** - affects design -- **Nice-to-know** - optimization - -### 5. Success Criteria - -Define measurable acceptance criteria: -- Functional requirements (MUST, SHOULD, COULD) -- Non-functional requirements (performance, security) -- Test scenarios - -### 6. Finalize - -After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. +- **An existing spec is honored, not rewritten.** If `codev/specs/{{project_id}}-*.md` already exists, it carries the architect's decisions — read it fully and refine it in place. Clarifying questions are for the case where no spec exists yet; when one does, the spec is the answer. +- **Baked Decisions are fixed.** If the issue body has a "Baked Decisions" section (any heading level, case-insensitive), copy it verbatim into the spec's Constraints and treat each item as settled — **do not autonomously override** the architect's choices in Solution Exploration. Raise a genuine problem with a baked decision via `afx send architect` rather than overriding it. If two baked decisions contradict each other, do not choose — **pause**, **flag** the contradiction via `afx send`, and wait for resolution. +- **The problem is characterized before solutions are.** Current state vs desired state, stakeholders, assumptions, and constraints are explicit. +- **Solutions are explored, not assumed.** More than one approach is considered, each with its trade-offs and risks, before one is recommended. +- **Open questions are surfaced and ranked** by whether they block progress, shape the design, or are merely nice to know. +- **Success is measurable.** Acceptance criteria are concrete enough to test against. ## Output -Create or update the specification file at `codev/specs/{{artifact_name}}.md`. - -Follow the canonical spec template reproduced below. Use these headings, in this order — do not invent your own structure, and do not pattern-match an earlier spec in `codev/specs/` that predates this template. If a section genuinely does not apply, keep the heading and write a one-line "N/A — [reason]" rather than deleting it. +Write the spec to `codev/specs/{{artifact_name}}.md` using the template below as its interface — these headings, in this order. A section that genuinely does not apply keeps its heading with a one-line `N/A — [reason]` rather than being deleted. Do not pattern-match an older spec in `codev/specs/` that predates this template. {{> protocols/spir/templates/spec.md}} -**IMPORTANT**: Keep spec/plan/review filenames in sync: -- Spec: `codev/specs/{{artifact_name}}.md` -- Plan: `codev/plans/{{artifact_name}}.md` -- Review: `codev/reviews/{{artifact_name}}.md` +Keep the three artifact filenames in sync: spec `codev/specs/{{artifact_name}}.md`, plan `codev/plans/{{artifact_name}}.md`, review `codev/reviews/{{artifact_name}}.md`. ## Signals -Emit appropriate signals based on your progress: - -- When waiting for clarifying question answers, **include your questions in the signal**: +- Waiting on clarifying-question answers — **put the questions inside the signal**, which is displayed prominently to the user: ``` - Please answer these questions: - 1. What should the primary use case be - internal tooling or customer-facing? - 2. What are the key constraints we should consider? - 3. Who are the main stakeholders? + Please answer: + 1. ... + 2. ... ``` - - The content inside the signal tag is displayed prominently to the user. - -- After completing the initial spec draft: +- Initial draft done: ``` SPEC_DRAFTED ``` +## Commit cadence -## Commit Cadence - -Make commits at these milestones: +Commit at each milestone, staging the spec file explicitly: +```bash +git add codev/specs/{{artifact_name}}.md +``` 1. `[Spec {{project_id}}] Initial specification draft` 2. `[Spec {{project_id}}] Specification with multi-agent review` 3. `[Spec {{project_id}}] Specification with user feedback` 4. `[Spec {{project_id}}] Final approved specification` -**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: -```bash -git add codev/specs/{{artifact_name}}.md -``` - -## Important Notes - -1. **Be thorough** - A good spec prevents implementation problems -3. **Be specific** - Vague specs lead to wrong implementations -4. **Include examples** - Concrete examples clarify intent - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't include implementation details (that's for the Plan phase) -- Don't estimate time (AI makes time estimates meaningless) -- Don't start coding (you're in Specify, not Implement) -- Don't use `git add .` or `git add -A` (security risk) +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Specify phase: no implementation detail (that is the plan), no code, no time estimates. diff --git a/codev-skeleton/protocols/spir/protocol.md b/codev-skeleton/protocols/spir/protocol.md index 5922d9883..d7aef53b0 100644 --- a/codev-skeleton/protocols/spir/protocol.md +++ b/codev-skeleton/protocols/spir/protocol.md @@ -1,657 +1,108 @@ # SPIR Protocol -> **SPIR** = **S**pecify → **P**lan → **I**mplement → **R**eview -> -> Each phase has one build-verify cycle with 3-way consultation. +**S**pecify → **P**lan → **I**mplement → **R**eview. Each phase is a build-verify cycle with +3-way consultation, and two human gates stand before implementation begins. +Use SPIR for new features, new protocols, architecture changes, and complex refactors — work +where getting the shape wrong is expensive to discover late. For an isolated bug fix or a small +feature fully described in an issue, a lighter protocol costs less and loses nothing. -## Prerequisites +## The state machine -**Clean Worktree Before Spawning Builders**: -- All specs, plans, and local changes **MUST be committed** before `afx spawn` -- Builders work in git worktrees branched from HEAD — uncommitted files are invisible -- This includes `codev update` results, spec drafts, and plan approvals -- The `afx spawn` command enforces this (use `--force` to override) - -**Required for Multi-Agent Consultation**: -- The `consult` CLI must be available (installed with `npm install -g @cluesmith/codev`) -- At least one consultation backend: `claude`, `gemini-cli`, or `codex` -- Check with: `codev doctor` or `consult --help` - -## Protocol Configuration - -### Multi-Agent Consultation (ENABLED BY DEFAULT) - -**DEFAULT BEHAVIOR:** -Multi-agent consultation is **ENABLED BY DEFAULT** when using SPIR protocol. - -**DEFAULT AGENTS:** -- **GPT-5 Codex**: Primary reviewer for architecture, feasibility, and code quality -- **Gemini Pro**: Secondary reviewer for completeness, edge cases, and alternative approaches - -**DISABLING CONSULTATION:** -To run SPIR without consultation, say "without consultation" when starting work. - -**CUSTOM AGENTS:** -The user can specify different agents by saying: "use SPIR with consultation from [agent1] and [agent2]" - -**CONSULTATION BEHAVIOR:** -- DEFAULT: MANDATORY consultation with GPT-5 and Gemini Pro at EVERY checkpoint -- When explicitly disabled: Skip all consultation steps -- The protocol is BLOCKED until all required consultations are complete - -**Consultation Checkpoints**: -- **Specification**: After initial draft, after human comments -- **Planning**: After initial plan, after human review -- **Implementation**: After code implementation -- **Defending**: After test creation -- **Evaluation**: Before marking phase complete -- **Review**: After review document - -## Overview -SPIR is a structured development protocol that emphasizes specification-driven development with iterative implementation and continuous review. It builds upon the DAPPER methodology with a focus on context-first development and multi-agent collaboration. - -**The SPIR Model**: -- **S - Specify**: Write specification with 3-way review → Gate: `spec-approval` -- **P - Plan**: Write implementation plan with 3-way review → Gate: `plan-approval` -- **I - Implement**: Execute each plan phase with build-verify cycle (one cycle per phase) -- **R - Review**: Final review and PR preparation with 3-way review - -Each phase follows a build-verify loop: build the artifact, then verify with 3-way consultation (Gemini, Codex, Claude). - -**Core Principle**: Each feature is tracked through exactly THREE documents - a specification, a plan, and a review with lessons learned - all sharing the same filename and sequential identifier. - -## When to Use SPIR - -### Use SPIR for: -- New feature development -- Architecture changes -- Complex refactoring -- System design decisions -- API design and implementation -- Performance optimization initiatives - -### Skip SPIR for: -- Simple bug fixes (< 10 lines) -- Documentation updates -- Configuration changes -- Dependency updates -- Emergency hotfixes (but do a lightweight retrospective after) - -## Baked Decisions (Optional) - -When filing an issue for SPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`. - -## Protocol Phases - -### S - Specify (Collaborative Design Exploration) - -**Purpose**: Thoroughly explore the problem space and solution options before committing to an approach. - -**Workflow Overview**: -1. User provides a prompt describing what they want built -2. Agent generates initial specification document -3. **COMMIT**: "Initial specification draft" -4. Multi-agent review (GPT-5 and Gemini Pro) -5. Agent updates spec with multi-agent feedback -6. **COMMIT**: "Specification with multi-agent review" -7. Human reviews and provides comments for changes -8. Agent makes changes and lists what was modified -9. **COMMIT**: "Specification with user feedback" -10. Multi-agent review of updated document -11. Final updates based on second review -12. **COMMIT**: "Final approved specification" -13. Iterate steps 7-12 until user approves and says to proceed to planning - -**Important**: Keep documentation minimal - use only THREE core files with the same name: -- `specs/####-descriptive-name.md` - The specification -- `plans/####-descriptive-name.md` - The implementation plan -- `reviews/####-descriptive-name.md` - Review and lessons learned (created during Review phase) - -**Process**: -1. **Clarifying Questions** (ALWAYS START HERE) - - Ask the user/stakeholder questions to understand the problem - - Probe for hidden requirements and constraints - - Understand the business context and goals - - Identify what's in scope and out of scope - - Continue asking until the problem is crystal clear - -2. **Problem Analysis** - - Clearly articulate the problem being solved - - Identify stakeholders and their needs - - Document current state and desired state - - List assumptions and constraints - -3. **Solution Exploration** - - Generate multiple solution approaches (as many as appropriate) - - For each approach, document: - - Technical design - - Trade-offs (pros/cons) - - Estimated complexity - - Risk assessment - -4. **Open Questions** - - List all uncertainties that need resolution - - Categorize as: - - Critical (blocks progress) - - Important (affects design) - - Nice-to-know (optimization) - -5. **Success Criteria** - - Define measurable acceptance criteria - - Include performance requirements - - Specify quality metrics - - Document test scenarios - -6. **Expert Consultation (DEFAULT - MANDATORY)** - - **First Consultation** (after initial draft): - - MUST consult GPT-5 AND Gemini Pro - - Focus: Problem clarity, solution completeness, missing requirements - - Update specification with ALL feedback from both models - - Document changes in "Consultation Log" section of the spec - - **Second Consultation** (after human comments): - - MUST consult GPT-5 AND Gemini Pro again - - Focus: Validate changes, ensure alignment - - Final specification update with both models' input - - Update "Consultation Log" with new feedback - - **Note**: Only skip if user explicitly requested "without multi-agent consultation" - -**⚠️ BLOCKING**: Cannot proceed without BOTH consultations (unless explicitly disabled) - -**Output**: Single specification document in `codev/specs/####-descriptive-name.md` -- All consultation feedback incorporated directly into this document -- Include a "Consultation Log" section summarizing key feedback and changes -- Version control captures evolution through commits -**Structure**: developed through the specify phase -**Review Required**: Yes - Human approval AFTER consultations - -### P - Plan (Structured Decomposition) - -**Purpose**: Transform the approved specification into an executable roadmap with clear phases. - -**⚠️ CRITICAL: No Time Estimates in the AI Age** -- **NEVER include time estimates** (hours, days, weeks, story points) -- AI-driven development makes traditional time estimates meaningless -- Delivery speed depends on iteration cycles, not calendar time -- Focus on logical dependencies and phase ordering instead -- Measure progress by completed phases, not elapsed time -- The only valid metrics are: "done" or "not done" - -**Workflow Overview**: -1. Agent creates initial plan document -2. **COMMIT**: "Initial plan draft" -3. Multi-agent review (GPT-5 and Gemini Pro) -4. Agent updates plan with multi-agent feedback -5. **COMMIT**: "Plan with multi-agent review" -6. User reviews and requests modifications -7. Agent updates plan based on user feedback -8. **COMMIT**: "Plan with user feedback" -9. Multi-agent review of updated plan -10. Final updates based on second review -11. **COMMIT**: "Final approved plan" -12. Iterate steps 6-11 until agreement is reached - -**Phase Design Goals**: -Each phase should be: -- A separate piece of work that can be checked in as a unit -- A complete set of functionality -- Self-contained and independently valuable - -**Process**: -1. **Phase Definition** - - Break work into logical phases - - Each phase must: - - Have a clear, single objective - - Be independently testable - - Deliver observable value - - Be a complete unit that can be committed - - End with evaluation discussion and single commit - - Note dependencies inline, for example: - ```markdown - Phase 2: API Endpoints - - Depends on: Phase 1 (Database Schema) - - Objective: Create /users and /todos endpoints - - Evaluation: Test coverage, API design review, performance check - - Commit: Will create single commit after user approval - ``` - -2. **Success Metrics** - - Define "done" for each phase - - Include test coverage requirements - - Specify performance benchmarks - - Document acceptance tests - -3. **Expert Review (DEFAULT - MANDATORY)** - - **First Consultation** (after plan creation): - - MUST consult GPT-5 AND Gemini Pro - - Focus: Feasibility, phase breakdown, completeness - - Update plan with ALL feedback from both models - - **Second Consultation** (after human review): - - MUST consult GPT-5 AND Gemini Pro again - - Focus: Validate adjustments, confirm approach - - Final plan refinement with both models' input - - **Note**: Only skip if user explicitly requested "without multi-agent consultation" - -**⚠️ BLOCKING**: Cannot proceed without BOTH consultations (unless explicitly disabled) - -**Output**: Single plan document in `codev/plans/####-descriptive-name.md` -- Same filename as specification, different directory -- All consultation feedback incorporated directly -- Include phase status tracking within this document -- **DO NOT include time estimates** - Focus on deliverables and dependencies, not hours/days -- Version control captures evolution through commits -**Structure**: follows the plan template provided by the plan phase -**Review Required**: Yes - Technical lead approval AFTER consultations - -### I - Implement (Per Plan Phase) - -Execute for each phase in the plan. Each phase follows a build-verify cycle. - -**CRITICAL PRECONDITION**: Before starting any phase, verify the previous phase was committed to git. No phase can begin without the prior phase's commit. - -**Build-Verify Cycle Per Phase**: -1. **Build** - Implement code and tests for this phase -2. **Verify** - 3-way consultation (Gemini, Codex, Claude) -3. **Iterate** - Address feedback until verification passes -4. **Commit** - Single atomic commit for the phase (MANDATORY before next phase) -5. **Proceed** - Move to next phase only after commit - -**Handling Failures**: -- If verification reveals gaps → iterate and fix -- If fundamental plan flaws found → mark phase as `blocked` and revise plan - -**Commit Requirements**: -- Each phase MUST end with a git commit before proceeding -- Commit message format: `[Spec ####][Phase: name] type: Description` -- No work on the next phase until current phase is committed -- If changes are needed after commit, create a new commit with fixes - -#### I - Implement (Build with Discipline) - -**Purpose**: Transform the plan into working code with high quality standards. - -**Precondition**: Previous phase must be committed (verify with `git log`) - -**Requirements**: -1. **Pre-Implementation** - - Verify previous phase is committed to git - - Review the phase plan and success criteria - - Set up the development environment - - Create feature branch following naming convention - - Document any plan deviations immediately - -2. **During Implementation** - - Write self-documenting code - - Follow project style guide strictly - - Implement incrementally with frequent commits - - Each commit must: - - Be atomic (single logical change) - - Include descriptive message - - Reference the phase - - Pass basic syntax checks - -3. **Code Quality Standards** - - No commented-out code - - No debug prints in final code - - Handle all error cases explicitly - - Include necessary logging - - Follow security best practices - -4. **Documentation Requirements** - - Update API documentation - - Add inline comments for complex logic - - Update README if needed - - Document configuration changes - -**Evidence Required**: -- Link to commits -- Code review approval (if applicable) -- No linting errors -- CI pipeline pass link (build/test/lint) - -**Expert Consultation (DEFAULT - MANDATORY)**: -- MUST consult BOTH GPT-5 AND Gemini Pro after implementation -- Focus: Code quality, patterns, security, best practices -- Update code based on feedback from BOTH models before proceeding -- Only skip if user explicitly disabled multi-agent consultation - -#### D - Defend (Write Comprehensive Tests) - -**Purpose**: Create comprehensive automated tests that safeguard intended behavior and prevent regressions. - -**CRITICAL**: Tests must be written IMMEDIATELY after implementation, NOT retroactively at the end of all phases. This is MANDATORY. - -**Requirements**: -1. **Defensive Test Creation** - - Write unit tests for all new functions - - Create integration tests for feature flows - - Develop edge case coverage - - Build error condition tests - - Establish performance benchmarks - -2. **Test Validation** (ALL MANDATORY) - - All new tests must pass - - All existing tests must pass - - No reduction in overall coverage - - Performance benchmarks met - - Security scans pass - - **Avoid Overmocking**: - - Test behavior, not implementation details - - Prefer integration tests over unit tests with heavy mocking - - Only mock external dependencies (APIs, databases, file systems) - - Never mock the system under test itself - - Use real implementations for internal module boundaries - -3. **Test Suite Documentation** - - Document test scenarios - - Explain complex test setups - - Note any flaky tests - - Record performance baselines - -**Evidence Required**: -- Test execution logs -- Coverage report (show no reduction) -- Performance test results (if applicable per spec) -- Security scan results (if configured) -- CI test run link with artifacts - -**Expert Consultation (DEFAULT - MANDATORY)**: -- MUST consult BOTH GPT-5 AND Gemini Pro for test defense review -- Focus: Test coverage completeness, edge cases, defensive patterns, test strategy -- Write additional defensive tests based on feedback from BOTH models -- Share their feedback during the Evaluation discussion -- Only skip if user explicitly disabled multi-agent consultation - -#### E - Evaluate (Assess Objectively) - -**Purpose**: Verify the implementation fully satisfies the phase requirements and maintains system quality. This is where the critical discussion happens before committing the phase. - -**Requirements**: -1. **Functional Evaluation** - - All acceptance criteria met - - User scenarios work as expected - - Edge cases handled properly - - Error messages are helpful - -2. **Non-Functional Evaluation** - - Performance requirements satisfied - - Security standards maintained - - Code maintainability assessed - - Technical debt documented - -3. **Deviation Analysis** - - Document any changes from plan - - Explain reasoning for changes - - Assess impact on other phases - - Update future phases if needed - - **Overmocking Check** (MANDATORY): - - Verify tests focus on behavior, not implementation - - Ensure at least one integration test per critical path - - Check that internal module boundaries use real implementations - - Confirm mocks are only used for external dependencies - - Tests should survive refactoring that preserves behavior - -4. **Expert Consultation Before User Evaluation** (MANDATORY - NO EXCEPTIONS) - - Get initial feedback from experts - - Make ALL necessary fixes based on feedback - - **CRITICAL**: Get FINAL approval from ALL consulted experts on the FIXED version - - Only proceed to user evaluation after ALL experts approve - - If any expert says "not quite" or has concerns, fix them FIRST - -5. **Evaluation Discussion with User** (ONLY AFTER EXPERT APPROVAL) - - Present to user: "Phase X complete. Here's what was built: [summary]" - - Share test results and coverage metrics - - Share that ALL experts have given final approval - - Ask: "Any changes needed before I commit this phase?" - - Incorporate user feedback if requested - - Get explicit approval to proceed - -6. **Phase Commit** (MANDATORY - NO EXCEPTIONS) - - Create single atomic commit for the entire phase - - Commit message: `[Spec ####][Phase: name] type: Description` - - Update the plan document marking this phase as complete - - Push all changes to version control - - Document any deviations or decisions in the plan - - **CRITICAL**: Next phase CANNOT begin until this commit is complete - - Verify commit with `git log` before proceeding - -7. **Final Verification** - - Confirm all expert feedback was addressed - - Verify all tests pass - - Check that documentation is updated - - Ensure no outstanding concerns from experts or user - -**Evidence Required**: -- Evaluation checklist completed -- Test results and coverage report -- Expert review notes from GPT-5 and Gemini Pro -- User approval from evaluation discussion -- Updated plan document with: - - Phase marked complete - - Evaluation discussion summary - - Any deviations noted -- Git commit for this phase -- Final CI run link after all fixes - -## 📋 PHASE COMPLETION CHECKLIST (MANDATORY BEFORE NEXT PHASE) - -**⚠️ STOP: DO NOT PROCEED TO NEXT PHASE UNTIL ALL ITEMS ARE ✅** - -### Before Starting ANY Phase: -- [ ] Previous phase is committed to git (verify with `git log`) -- [ ] Plan document shows previous phase as `completed` -- [ ] No outstanding issues from previous phase - -### After Implement Phase: -- [ ] All code for this phase is complete -- [ ] Code follows project style guide -- [ ] No commented-out code or debug prints -- [ ] Error handling is implemented -- [ ] Documentation is updated (if needed) -- [ ] Expert consultation completed (GPT-5 + Gemini Pro) -- [ ] Expert feedback has been addressed - -### After Defend Phase: -- [ ] Unit tests written for all new functions -- [ ] Integration tests written for critical paths -- [ ] Edge cases have test coverage -- [ ] All new tests are passing -- [ ] All existing tests still pass -- [ ] No reduction in code coverage -- [ ] Overmocking check completed (tests focus on behavior) -- [ ] Expert consultation on tests completed -- [ ] Test feedback has been addressed - -### After Evaluate Phase: -- [ ] All acceptance criteria from spec are met -- [ ] Performance requirements satisfied -- [ ] Security standards maintained -- [ ] Expert consultation shows FINAL approval -- [ ] User evaluation discussion completed -- [ ] User has given explicit approval to proceed -- [ ] Plan document updated with phase status -- [ ] Phase commit created with proper message format -- [ ] Commit pushed to version control -- [ ] Commit verified with `git log` - -### ❌ PHASE BLOCKERS (Fix Before Proceeding): -- Any failing tests -- Unaddressed expert feedback -- Missing user approval -- Uncommitted changes -- Incomplete documentation -- Coverage reduction - -**REMINDER**: Each phase is atomic. You cannot start the next phase until the current phase is fully complete, tested, evaluated, and committed. - -### R - Review/Refine/Revise (Continuous Improvement) - -**Purpose**: Ensure overall coherence, capture learnings, improve the methodology, and perform systematic review. - -**Precondition**: All implementation phases must be committed (verify with `git log --oneline | grep "\[Phase"`) - -**Process**: -1. **Comprehensive Review** - - Verify all phases have been committed to git - - Compare final implementation to original specification - - Assess overall architecture impact - - Review code quality across all changes - - Validate documentation completeness - -2. **Refinement Actions** - - Refactor code for clarity if needed - - Optimize performance bottlenecks - - Improve test coverage gaps - - Enhance documentation - -3. **Update Architecture Documentation** - - Route new system-shape facts and durable wisdom by tier (Spec 987): behavior-changing + cross-cutting → the HOT `codev/resources/arch-critical.md` / `lessons-critical.md` (capped, always-injected; demote a weaker entry to cold if full); reference detail → the COLD `codev/resources/arch.md` / `lessons-learned.md` - - Use the **`update-arch-docs` skill** (at `.claude/skills/update-arch-docs/SKILL.md`) to apply changes — it encodes the hot/cold two-tier discipline (caps + cold-doc maps for the hot files; reference archive for the cold files) and what NOT to include - - Follow guidance in the MAINTAIN protocol's Step 3 ("Sync Documentation") for structure, the "Lives where" routing matrix, and pruning checklists - - Ensure both docs reflect current state - -4. **Revision Requirements** (MANDATORY) - - Update README.md with any new features or changes - - Update AGENTS.md and CLAUDE.md with protocol improvements from lessons learned - - Update specification and plan documents with final status - - Revise architectural diagrams if needed - - Update API documentation - - Modify deployment guides as necessary - - **CRITICAL**: Update this protocol document based on lessons learned - -5. **Systematic Issue Review** (MANDATORY) - - Review entire project for systematic issues: - - Repeated problems across phases - - Process bottlenecks or inefficiencies - - Missing documentation patterns - - Technical debt accumulation - - Testing gaps or quality issues - - Document systematic findings in lessons learned - - Create action items for addressing systematic issues - -6. **Lessons Learned** (MANDATORY) - - What went well? - - What was challenging? - - What would you do differently? - - What methodology improvements are needed? - - What systematic issues were identified? - -7. **Methodology Evolution** - - Propose process improvements based on lessons - - Update protocol documents with improvements - - Update templates if needed - - Share learnings with team - - Document in `codev/reviews/` - - **Important**: This protocol should evolve based on each project's learnings - -**Output**: -- Single review document in `codev/reviews/####-descriptive-name.md` -- Same filename as spec/plan, captures review and learnings from this feature -- Methodology improvement proposals (update protocol if needed) - -**Review Required**: Yes - Team retrospective recommended - -## File Naming Conventions - -### Specifications and Plans -Format: `####-descriptive-name.md` -- Use sequential numbering (1, 2, etc.) -- Same filename in both `specs/` and `plans/` directories -- Example: `1-user-authentication.md` - -## Status Tracking - -Status is tracked at the **phase level** within plan documents, not at the document level. - -Each phase in a plan should have a status: -- `pending`: Not started -- `in-progress`: Currently being worked on -- `completed`: Phase finished and tested -- `blocked`: Cannot proceed due to external factors - -## Git Integration - -### Commit Message Format - -For specification/plan documents: -``` -[Spec ####] : -``` +Phases, gates, checks and their order are defined here. This is the authoritative source; the +prose below is only what the JSON cannot express. -Examples: -``` -[Spec 1] Initial specification draft -[Spec 1] Specification with multi-agent review -[Spec 1] Specification with user feedback -[Spec 1] Final approved specification +```json +{{> protocols/spir/protocol.json}} ``` -For implementation: -``` -[Spec ####][Phase: ] : +## Artifacts - -``` +Three documents per feature, **same base filename** in three directories: -Example: -``` -[Spec 1][Phase: user-auth] feat: Add password hashing service +| Document | Answers | Written during | +|---|---|---| +| `codev/specs/-.md` | what and why | Specify | +| `codev/plans/-.md` | how, and in what order | Plan | +| `codev/reviews/-.md` | what was learned | Review | -Implements bcrypt-based password hashing with configurable rounds -``` +Sequential numbering, no leading zeros: `42-user-authentication.md`. -### Branch Naming -``` -spir/####-/ -``` +Specs and plans stay separate. A spec that has acquired file paths and step ordering has become +a plan — and the gate meant to catch a wrong approach is now reviewing an implementation. -Example: -``` -spir/1-user-authentication/database-schema -``` +The plan carries a machine-readable `phases` JSON block. Porch parses it to track progress, so +it is a contract, not an illustration. + +## Phases +**Specify** — explore the problem before committing to an approach. Ask clarifying questions +first; they are cheapest before anything is written. Capture the problem, current and desired +state, several solution approaches with their trade-offs, open questions ranked by whether they +block, and measurable success criteria. -## Best Practices +**Plan** — decompose into phases that are each independently testable, independently valuable, +and committable as a unit. Note dependencies inline. **No time estimates.** Delivery speed +depends on iteration cycles, not calendar time, and an estimate in an AI-driven project is noise +that later gets quoted back as a commitment. -### During Specification -- Use clear, unambiguous language -- Include concrete examples -- Define measurable success criteria -- Link to relevant references +**Implement** — one build-verify cycle per plan phase: build, verify by 3-way consultation, +address what reviewers find, commit. The commit is what makes the next phase safe to begin; a +phase that is "done but uncommitted" can vanish. If verification exposes a flaw in the *plan* +rather than the code, mark the phase blocked and revise the plan — implementing around a +known-wrong plan is how a project ships the wrong thing carefully. -### During Planning -- Keep phases small and focused -- Ensure each phase delivers value -- Note phase dependencies inline (no formal dependency mapping needed) -- Include rollback strategies +Tests belong to the phase that creates the behaviour, not to a cleanup pass at the end. +Retroactive tests document what was built; tests written alongside constrain what gets built. +Mock external dependencies only — mocking the system under test proves the mock works. -### During Implementation -- Follow the plan but document deviations -- Maintain test coverage -- Keep commits atomic and well-described -- Update documentation as you go +**Review** — compare the implementation against the specification, record lessons, and route new +facts by tier: behaviour-changing and cross-cutting to `arch-critical.md` / +`lessons-critical.md` (capped — displace a weaker entry rather than growing them), reference +detail to `arch.md` / `lessons-learned.md`. The `update-arch-docs` skill encodes that routing. -### During Review -- Check against original specification -- Document lessons learned -- Propose methodology improvements -- Update estimates for future work +## Consultation -## Templates +3-way consultation (Gemini, Codex, Claude) is **on by default** and runs at each phase's verify +step. Disable it only when the human explicitly asks. + +It is not a formality: it reliably catches security, design and protocol problems that solo +review misses, and the cost of skipping it is paid later by someone with less context. + +## Gates + +`spec-approval`, `plan-approval` and `pr` are **human** decisions. Stop and wait. A gate message +is a notification to a human, not authorization to proceed. + +## Baked Decisions + +An issue may carry a `## Baked Decisions` section pinning architectural choices the architect +does not want re-litigated — typically **language**, **framework**, deployment shape, key +**dependencies**, or decisions deferred to a later spec. + +Every item in it is fixed. Copy the section verbatim into the spec's Constraints and do not +re-open it in the spec, plan, or review; CMAP reviewers will not propose alternatives unless the +spec fails to honour one. If two items contradict each other, do not choose — surface the +contradiction and wait. + +**Absence is the no-op default**: an issue with no such section is an invitation to explore +freely, not an omission to be filled in. + +The architect can **amend or rescind** a baked decision at any time by updating the issue and +respawning, or by sending the builder a direct instruction via `afx send`. + +## Git + +``` +[Spec 42] Initial specification draft +[Spec 42][Phase: user-auth] feat: Add password hashing service +``` -Each phase has a template that ships in the package skeleton; the phase prompts deliver the structure you need, so you do not fetch these files directly: -- `spec.md` - Specification template -- `plan.md` - Planning template (includes phase status tracking) -- `review.md` - Review and lessons learned template +Branches: `spir/42-feature-name/phase-name`. -**Remember**: Only create THREE documents per feature - spec, plan, and review with the same filename in different directories. +Each implement phase ends in one atomic commit before the next begins. -## Protocol Evolution +## Phase status -This protocol can be customized per project: -1. Fork the protocol directory -2. Modify templates and processes -3. Document changes in `protocol-changes.md` -4. Share improvements back to the community \ No newline at end of file +Tracked per phase inside the plan document, not per document: `pending`, `in-progress`, +`completed`, `blocked`. diff --git a/codev-skeleton/protocols/spir/templates/plan.md b/codev-skeleton/protocols/spir/templates/plan.md index 9da106498..13c35e916 100644 --- a/codev-skeleton/protocols/spir/templates/plan.md +++ b/codev-skeleton/protocols/spir/templates/plan.md @@ -1,184 +1,65 @@ # Plan: [Title] -## Metadata -- **ID**: plan-[YYYY-MM-DD]-[short-name] -- **Status**: draft -- **Specification**: [Link to codev/specs/spec-file.md] -- **Created**: [YYYY-MM-DD] +**Specification**: [Link to codev/specs/XXXX-*.md] ## Executive Summary -[Brief overview of the implementation approach chosen and why. Reference the specification's selected approach.] -## Success Metrics -[Copy from specification and add implementation-specific metrics] -- [ ] All specification criteria met -- [ ] Test coverage >90% -- [ ] Performance benchmarks achieved -- [ ] Zero critical security issues -- [ ] Documentation complete +The implementation approach chosen and why, referencing the spec's selected approach. ## Phases (Machine Readable) - + ```json { "phases": [ {"id": "phase_1", "title": "Phase 1 Title Here"}, - {"id": "phase_2", "title": "Phase 2 Title Here"}, - {"id": "phase_3", "title": "Phase 3 Title Here"} + {"id": "phase_2", "title": "Phase 2 Title Here"} ] } ``` ## Phase Breakdown +Repeat this block per phase. Each phase is self-contained, independently testable, valuable, and a single atomic commit. + ### Phase 1: [Descriptive Name] + **Dependencies**: None -#### Objectives -- [Clear, single objective for this phase] -- [What value does this phase deliver?] +#### Objective + +The single goal of this phase and the value it delivers. + +#### Files to Create / Modify + +Specific paths. #### Deliverables -- [ ] [Specific deliverable 1] -- [ ] [Specific deliverable 2] -- [ ] [Tests for this phase] -- [ ] [Documentation updates] - -#### Implementation Details -[Specific technical approach for this phase. Include: -- Key files/modules to create or modify -- Architectural decisions -- API contracts -- Data models] -#### Acceptance Criteria -- [ ] [Testable criterion 1] -- [ ] [Testable criterion 2] -- [ ] All tests pass -- [ ] Code review completed +- [ ] … +- [ ] Tests for this phase -#### Test Plan -- **Unit Tests**: [What to test] -- **Integration Tests**: [What to test] -- **Manual Testing**: [Scenarios to verify] +#### Acceptance Criteria -#### Rollback Strategy -[How to revert this phase if issues arise] +- [ ] Testable criterion(s), plus build and tests passing. -#### Risks -- **Risk**: [Specific risk for this phase] - - **Mitigation**: [How to address] +#### Test Plan ---- +Unit / integration / manual scenarios that verify this phase. ### Phase 2: [Descriptive Name] -**Dependencies**: Phase 1 - -[Repeat structure for each phase] ---- +**Dependencies**: Phase 1 -### Phase 3: [Descriptive Name] -**Dependencies**: Phase 2 +[Same structure.] -[Continue for all phases] +## Risks and Mitigation -## Dependency Map -``` -Phase 1 ──→ Phase 2 ──→ Phase 3 - ↓ - Phase 4 (optional) -``` +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| … | | | | -## Resource Requirements -### Development Resources -- **Engineers**: [Expertise needed] -- **Environment**: [Dev/staging requirements] - -### Infrastructure -- [Database changes] -- [New services] -- [Configuration updates] -- [Monitoring additions] - -## Integration Points -### External Systems -- **System**: [Name] - - **Integration Type**: [API/Database/Message Queue] - - **Phase**: [Which phase needs this] - - **Fallback**: [What if unavailable] - -### Internal Systems -[Repeat structure] - -## Risk Analysis -### Technical Risks -| Risk | Probability | Impact | Mitigation | Owner | -|------|------------|--------|------------|-------| -| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] | - -### Schedule Risks -| Risk | Probability | Impact | Mitigation | Owner | -|------|------------|--------|------------|-------| -| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] | - -## Validation Checkpoints -1. **After Phase 1**: [What to validate] -2. **After Phase 2**: [What to validate] -3. **Before Production**: [Final checks] - -## Monitoring and Observability -### Metrics to Track -- [Metric 1: Description and threshold] -- [Metric 2: Description and threshold] - -### Logging Requirements -- [What to log and at what level] -- [Retention requirements] - -### Alerting -- [Alert condition and severity] -- [Who to notify] - -## Documentation Updates Required -- [ ] API documentation -- [ ] Architecture diagrams -- [ ] Runbooks -- [ ] User guides -- [ ] Configuration guides - -## Post-Implementation Tasks -- [ ] Performance validation -- [ ] Security audit -- [ ] Load testing -- [ ] User acceptance testing -- [ ] Monitoring validation - -## Expert Review -**Date**: [YYYY-MM-DD] -**Model**: [Model consulted] -**Key Feedback**: -- [Feasibility assessment] -- [Missing considerations] -- [Risk identification] -- [Alternative suggestions] - -**Plan Adjustments**: -- [How the plan was modified based on feedback] - -## Approval -- [ ] Technical Lead Review -- [ ] Engineering Manager Approval -- [ ] Resource Allocation Confirmed -- [ ] Expert AI Consultation Complete - -## Change Log -| Date | Change | Reason | Author | -|------|--------|--------|--------| -| [Date] | [What changed] | [Why] | [Who] | - -## Notes -[Additional context, assumptions, or considerations] +## Documentation Updates +Which docs change (README, API docs, arch/lessons) — or none. diff --git a/codev-skeleton/protocols/spir/templates/review.md b/codev-skeleton/protocols/spir/templates/review.md index 668055637..2dc574789 100644 --- a/codev-skeleton/protocols/spir/templates/review.md +++ b/codev-skeleton/protocols/spir/templates/review.md @@ -2,128 +2,60 @@ ## Summary -[1-3 sentences: what was built, how many phases, net outcome.] +1–3 sentences: what was built, how many phases, the net outcome. ## Spec Compliance +Each acceptance criterion and whether it was met, with the phase that delivered it. + - [x] AC1: [Description] (Phase N) -- [x] AC2: [Description] (Phase N) - [ ] ACn: [Not met — reason] ## Deviations from Plan -- **Phase N**: [What changed and why] - -## Key Metrics - -- **Commits**: [N] on the branch -- **Tests**: [N] passing ([N] existing + [N] new) -- **Files created**: [list] -- **Files deleted**: [list] -- **Net LOC impact**: [+/-N lines] - -## Timelog - -All times [timezone], [date range]. - -| Time | Event | -|------|-------| -| HH:MM | First commit: [description] | -| HH:MM | [Phase/milestone] | -| — | **GATE: [gate-name]** (human approval required) | -| HH:MM | Implementation begins | -| HH:MM | Phase N complete after N iterations | -| HH:MM | **GATE: pr** | - -### Autonomous Operation - -| Period | Duration | Activity | -|--------|----------|----------| -| Spec + Plan | ~Nm | [Summary] | -| Human gate wait | ~Nh Nm | Idle — waiting for approval | -| Implementation → PR | ~Nh Nm | N phases, N consultation rounds | - -**Total wall clock** (first commit to pr): **Xh Ym** -**Total autonomous work time** (excluding gate waits): **~Xh Ym** -**Context window resets**: [N] (resumed automatically / required manual restart) - -## Consultation Iteration Summary - -[N] consultation files produced ([N] rounds x [N] models). [N] APPROVE, [N] REQUEST_CHANGES, [N] COMMENT. - -| Phase | Iters | Who Blocked | What They Caught | -|-------|-------|-------------|------------------| -| Specify | N | [Model] | [Brief description] | -| Plan | N | [Model] | [Brief description] | -| Phase 1 | N | [Model] | [Brief description] | -| Phase N | N | [Model] | [Brief description] | -| Review | N | [Model] | [Brief description] | - -**Most frequent blocker**: [Model] — blocked in N of N rounds, focused on: [pattern]. - -### Avoidable Iterations - -Iterations that could have been prevented with better builder behavior: - -1. **[Pattern]**: [Specific thing the builder should have done without needing reviewer feedback. E.g., "Run exhaustive grep before claiming all instances fixed."] - -2. **[Pattern]**: [Another avoidable iteration pattern.] +What changed from the plan, per phase, and why. "None" if the plan held. ## Consultation Feedback -[For each phase that had consultation, summarize every reviewer's concerns and how the builder responded. Use **Addressed** (fixed), **Rebutted** (disagreed with reasoning), or **N/A** (out of scope/moot) for each concern. If all reviewers approved with no concerns: "No concerns raised — all consultations approved."] +Per phase that had consultation, each reviewer's concerns and how you responded — **Addressed** (changed), **Rebutted** (why it does not apply), or **N/A** (out of scope / moot). "No concerns raised — all consultations approved" when that is true; note COMMENT verdicts and any `CONSULT_ERROR`. ### [Phase] Phase (Round N) #### Gemini -- **Concern**: [Summary of concern] - - **Addressed**: [What was changed] - -#### Codex -- **Concern**: [Summary of concern] - - **Rebutted**: [Why current approach is correct] - -#### Claude -- No concerns raised (APPROVE) +- **Concern**: … → **Addressed** / **Rebutted** / **N/A**: … ## Lessons Learned ### What Went Well -- [Specific positive observation — what worked and why] ### Challenges Encountered -- **[Challenge]**: [How it was resolved. How many iterations it cost.] + +What was hard and how it resolved. ### What Would Be Done Differently -- [Actionable improvement for future builders] ### Methodology Improvements -- [Suggested improvement to the SPIR protocol] -- [Suggested improvement to tooling] + +Suggested improvements to the SPIR protocol or the tooling. ## Architecture Updates -[What you routed where — HOT `codev/resources/arch-critical.md` (tiny, capped, always-injected) vs COLD `codev/resources/arch.md` (reference) — or why no changes were needed.] +What you routed where — HOT `codev/resources/arch-critical.md` (tiny, capped, always-injected) vs COLD `codev/resources/arch.md` (reference) — or why no change was needed. Note any hot-tier demotion made to respect the cap. -- Routed: [hot | cold] — [fact/section] — [what was added/changed; note any demotion if the hot file was full] -- Or: "No architecture updates needed — [brief reason]" +- Routed: [hot | cold] — [fact] — [what changed] +- Or: "No architecture updates needed — [reason]" ## Lessons Learned Updates -[What you routed where — HOT `codev/resources/lessons-critical.md` (capped) vs COLD `codev/resources/lessons-learned.md` (reference) — or why no changes were needed.] - -- Routed: [hot | cold] — [category] — [lesson summary] -- Or: "No lessons learned updates needed — [brief reason]" - -## Technical Debt +What you routed where — HOT `codev/resources/lessons-critical.md` (capped) vs COLD `codev/resources/lessons-learned.md` (reference) — or why no change was needed. -- [Any shortcuts taken or inconsistencies introduced] +- Routed: [hot | cold] — [category] — [lesson] +- Or: "No lessons learned updates needed — [reason]" ## Flaky Tests -- [Pre-existing tests skipped as flaky during this project — test name, file path, observed failure mode] -- [If none: "No flaky tests encountered"] +Pre-existing tests skipped as flaky during this project — name, file path, observed failure mode. "No flaky tests encountered" if none. ## Follow-up Items -- [Items identified for future work, outside this spec's scope] +Work identified for later, outside this spec's scope. diff --git a/codev-skeleton/protocols/spir/templates/spec.md b/codev-skeleton/protocols/spir/templates/spec.md index 4cca2177f..676afe79a 100644 --- a/codev-skeleton/protocols/spir/templates/spec.md +++ b/codev-skeleton/protocols/spir/templates/spec.md @@ -3,152 +3,58 @@ -## Metadata -- **ID**: spec-[YYYY-MM-DD]-[short-name] -- **Status**: draft -- **Created**: [YYYY-MM-DD] - -## Clarifying Questions Asked - -[List the questions you asked to understand the problem better and the responses received. This shows the discovery process.] - ## Problem Statement -[Clearly articulate the problem being solved. Include context about why this is important, who is affected, and what the current pain points are.] + +What problem is being solved, why it matters, who is affected, and the current pain points. ## Current State -[Describe how things work today. What are the limitations? What workarounds exist? Include specific examples.] + +How things work today, and the limitations or workarounds that motivate the change. Concrete examples. ## Desired State -[Describe the ideal solution. How should things work after implementation? What specific improvements will users see?] -## Stakeholders -- **Primary Users**: [Who will directly use this feature?] -- **Secondary Users**: [Who else is affected?] -- **Technical Team**: [Who will implement and maintain this?] -- **Business Owners**: [Who has decision authority?] +How things should work after implementation, and the specific improvements users will see. ## Success Criteria -- [ ] [Specific, measurable criterion 1] -- [ ] [Specific, measurable criterion 2] -- [ ] [Specific, measurable criterion 3] -- [ ] All tests pass with >90% coverage -- [ ] Performance benchmarks met (specify below) -- [ ] Documentation updated + +Measurable, testable acceptance criteria — the conditions under which this spec is satisfied. + +- [ ] … ## Constraints -### Technical Constraints -- [Existing system limitations] -- [Technology stack requirements] -- [Integration points] -### Business Constraints -- [Timeline requirements] -- [Budget considerations] -- [Compliance requirements] +Technical and business constraints that bound the solution: existing-system limits, required stack, integration points, compliance. ## Assumptions -- [List assumptions being made] -- [Include dependencies on other work] -- [Note any prerequisites] -## Solution Approaches - -### Approach 1: [Name] -**Description**: [Brief overview of this approach] +Assumptions being made and dependencies on other work. -**Pros**: -- [Advantage 1] -- [Advantage 2] +## Solution Approaches -**Cons**: -- [Disadvantage 1] -- [Disadvantage 2] +More than one approach where the space is open. For each: a short description, its trade-offs (pros/cons), and its risk/complexity. Name the recommended one and why. -**Estimated Complexity**: [Low/Medium/High] -**Risk Level**: [Low/Medium/High] +### Approach 1: [Name] ### Approach 2: [Name] -[Repeat structure for additional approaches] - -[Add as many approaches as appropriate for the problem] ## Open Questions -### Critical (Blocks Progress) -- [ ] [Question that must be answered before proceeding] - -### Important (Affects Design) -- [ ] [Question that influences technical decisions] - -### Nice-to-Know (Optimization) -- [ ] [Question that could improve the solution] - -## Performance Requirements -- **Response Time**: [e.g., <200ms p95] -- **Throughput**: [e.g., 1000 requests/second] -- **Resource Usage**: [e.g., <500MB memory] -- **Availability**: [e.g., 99.9% uptime] - -## Security Considerations -- [Authentication requirements] -- [Authorization model] -- [Data privacy concerns] -- [Audit requirements] +Ranked by how much they block: **Critical** (blocks progress) · **Important** (shapes design) · **Nice-to-know** (optimization). ## Test Scenarios -### Functional Tests -1. [Scenario 1: Happy path] -2. [Scenario 2: Edge case] -3. [Scenario 3: Error condition] -### Non-Functional Tests -1. [Performance test scenario] -2. [Security test scenario] -3. [Load test scenario] +The functional and non-functional scenarios that verify the success criteria — happy paths, edge cases, error conditions. -## Dependencies -- **External Services**: [List any external APIs or services] -- **Internal Systems**: [List internal dependencies] -- **Libraries/Frameworks**: [List required libraries] +## Risks and Mitigation -## References -- [Link to relevant documentation in codev/ref/] -- [Link to related specifications] -- [Link to architectural diagrams] -- [Link to research materials] +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| … | | | | -## Risks and Mitigation -| Risk | Probability | Impact | Mitigation Strategy | -|------|------------|--------|-------------------| -| [Risk 1] | Low/Med/High | Low/Med/High | [How to address] | -| [Risk 2] | Low/Med/High | Low/Med/High | [How to address] | - -## Expert Consultation - -**Date**: [YYYY-MM-DD] -**Models Consulted**: [e.g., GPT-5 and Gemini Pro] -**Sections Updated**: -- [Section name]: [Brief description of change based on consultation] -- [Section name]: [Brief description of change based on consultation] - -Note: All consultation feedback has been incorporated directly into the relevant sections above. - -## Approval -- [ ] Technical Lead Review -- [ ] Product Owner Review -- [ ] Stakeholder Sign-off -- [ ] Expert AI Consultation Complete - -## Notes -[Any additional context or considerations not covered above] +## References +Related specs, research, or documentation. diff --git a/codev-skeleton/roles/architect.md b/codev-skeleton/roles/architect.md index 56cac231d..41dc0d17f 100644 --- a/codev-skeleton/roles/architect.md +++ b/codev-skeleton/roles/architect.md @@ -1,348 +1,98 @@ # Role: Architect -The Architect is the **project manager and gatekeeper** who decides what to build, spawns builders, approves gates, and ensures integration quality. +You decide what gets built, spawn builders, approve gates, and own integration quality. You do +not implement — builders do that in isolated worktrees. -> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands. +## What you own -## Key Concept: Spawning Builders +1. **What to build** — features, priorities, GitHub Issues as the project registry. +2. **Spawning** — one builder per project, in a worktree branched from HEAD. +3. **Gates** — in strict mode, reviewing the spec and plan before the builder proceeds. +4. **Integration review** — whether a PR fits the architecture, at a depth matched to its risk. +5. **Closing the loop** — closing the issue when the PR merges, and cleaning up the worktree. -Builders work autonomously in isolated git worktrees. The Architect: -1. **Decides** what to build -2. **Spawns** builders via `afx spawn` -3. **Approves** gates (spec-approval, plan-approval) when in strict mode -4. **Reviews** PRs for integration concerns +## Spawning -### Two Builder Modes +| Mode | Flag | What it means | +|---|---|---| +| **Strict** (default) | none | Porch orchestrates: automated gates, 3-way consultation, enforced phase transitions. Most likely to finish without intervention. | +| **Soft** | `--soft` | The builder follows the protocol itself; you verify compliance. Use when you want closer oversight. | -| Mode | Command | Use When | -|------|---------|----------| -| **Strict** (default) | `afx spawn XXXX --protocol spir` | Porch orchestrates - runs autonomously to completion | -| **Soft** | `afx spawn XXXX --protocol spir --soft` | AI follows protocol - you verify compliance | +`--protocol` is **required** for numbered spawns (`--task`, `--shell` and `--worktree` spawns +are the exceptions). -**Strict mode** (default): Porch orchestrates the builder with automated gates, 3-way consultations, and enforced phase transitions. More likely to complete autonomously without intervention. +**Builders branch from HEAD, so commit first.** Uncommitted specs, plans and framework updates +are invisible to the builder. `afx spawn` refuses a dirty worktree; `--force` overrides it and +gives the builder a tree missing your uncommitted work. -**Soft mode**: Builder reads and follows the protocol document, but you monitor progress and verify the AI is adhering to the protocol correctly. Use when you want more hands-on oversight. +Commands and flags live in the `afx` skill — check it rather than guessing. -### Pre-Spawn Checklist +## Gates -**Before every `afx spawn`, complete these steps:** +The builder stops and waits. Read the artifact in its worktree with an absolute path, decide — +then **relay the decision; the builder runs the command.** -1. **`git status`** — Ensure worktree is clean (no uncommitted changes) -2. **Commit if needed** — Builders branch from HEAD; uncommitted specs/plans are invisible -3. **`afx spawn N --protocol `** — `--protocol` is **REQUIRED** (spir, aspir, air, bugfix, etc.) - -The spawn command will refuse if the worktree is dirty (override with `--force`, but your builder won't see uncommitted files). - -## Key Tools - -### Agent Farm CLI (`afx`) - -```bash -afx spawn 1 --protocol spir # Strict mode (default) - porch-driven -afx spawn 1 --protocol spir -t "feature" # Strict mode with title (no spec yet) -afx spawn 1 --resume # Resume existing porch state -afx spawn 1 --protocol spir --soft # Soft mode - protocol-guided -afx spawn --task "fix the bug" # Ad-hoc task builder (soft mode) -afx spawn --worktree # Worktree with no initial prompt -afx status # Check all builders -afx cleanup -p 0001 # Remove completed builder -afx workspace start/stop # Workspace management -afx send 0001 "message" # Short message to builder -``` - -> **Note:** `--protocol` is REQUIRED for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip it. - -**Note:** `afx`, `consult`, `porch`, and `codev` are global commands. They work from any directory. - -### Porch CLI (for strict mode) - -```bash -porch status 0001 # Check project state -porch approve 0001 spec-approval # Approve a gate -porch pending # List pending gates -``` - -### Consult Tool (for integration reviews) - -```bash -# Single-model review (medium risk) -consult -m claude --type integration pr 35 - -# 3-way parallel review (high risk) -consult -m gemini --type integration pr 35 & -consult -m codex --type integration pr 35 & -consult -m claude --type integration pr 35 & -wait -``` - -## Responsibilities - -1. **Decide what to build** - Identify features, prioritize work -2. **Track projects** - Use GitHub Issues as the project registry -3. **Spawn builders** - Choose soft or strict mode based on needs -4. **Approve gates** - (Strict mode) Review specs and plans, approve to continue -5. **Monitor progress** - Track builder status, unblock when stuck -6. **Integration review** - Review PRs for architectural fit -7. **Manage releases** - Group projects into releases - -## Workflow - -### 1. Starting a New Feature - -```bash -# 1. Create a GitHub Issue for the feature -# 2. Ensure worktree is clean: git status → commit if needed -# 3. Spawn the builder (--protocol is REQUIRED) - -# Default: Strict mode (porch-driven with gates) -afx spawn 42 --protocol spir - -# With project title (if no spec exists yet) -afx spawn 42 --protocol spir -t "user-authentication" - -# Or: Soft mode (builder follows protocol independently) -afx spawn 42 --protocol spir --soft - -# For bugfixes -afx spawn 42 --protocol bugfix -``` - -### 2. Approving Gates (Strict Mode Only) - -The builder stops at gates requiring approval: - -**spec-approval** - After builder writes the spec ```bash -# Review the spec in the builder's worktree -cat .builders/spir-0042-feature-name/codev/specs/0042-feature-name.md - -# Approve if satisfactory (run from builder's worktree context) -(cd .builders/spir-0042-feature-name && porch approve 0042 spec-approval --a-human-explicitly-approved-this) - -# IMPORTANT: Always message the builder after approving a gate -afx send 0042 "Spec approved. Continue to plan phase." +afx send "Spec approved by the human. Run porch approve and continue to plan." ``` -**plan-approval** - After builder writes the plan -```bash -# Review the plan -cat .builders/spir-0042-feature-name/codev/plans/0042-feature-name.md +You do not run `porch approve` on the builder's behalf. The gate is the human's decision, you +are the channel that carries it, and the builder executes against its own porch state. Approval +the builder never hears about is approval that didn't happen. -# Approve if satisfactory (run from builder's worktree context) -(cd .builders/spir-0042-feature-name && porch approve 0042 plan-approval --a-human-explicitly-approved-this) +The command the builder runs requires `--a-human-explicitly-approved-this`, and that flag is +load-bearing: a gate message is a notification *to* a human, never a token an agent may spend on +its own authority. -# IMPORTANT: Always message the builder after approving a gate -afx send 0042 "Plan approved. Continue to implement phase." -``` +## Integration review — depth matched to risk -### 3. Monitoring Progress +Assess before choosing depth. **Highest single factor wins**: if lines, file count, subsystem +or cross-cutting scope puts it in a tier, the whole PR is in that tier. -```bash -afx status # Overview of all builders -porch status 0042 # Detailed state for one project (strict mode) -``` +| Risk | Shape | Review | +|---|---|---| +| **Low** | <100 lines, 1–3 files, isolated — docs, tests, cosmetic, most bugfixes | Read it yourself | +| **Medium** | 100–500 lines, 4–10 files, shared code — features, new commands | One model: `consult -m claude --type integration pr ` | +| **High** | >500 lines, >10 files, or core subsystems — porch, Tower, protocols, security model | 3-way CMAP in parallel | -### 4. Integration Review (Risk-Based Triage) +Subsystem mappings and worked examples: `codev/resources/risk-triage.md`. -When the builder creates a PR, **assess risk first** before deciding review depth. +Post findings as a PR comment, not a terminal message. Then tell the builder to merge — you +don't merge their work. -> **Full reference**: See `codev/resources/risk-triage.md` for subsystem mappings and examples. +### Presenting a decision to the human (PRFT) -#### Step 1: Assess Risk +Whenever you bring something to the human for a decision — a merge word, a `pr` gate, a +dev-approval — lead with **Problem · Root Cause · Fix · Testing**, unprompted, at every risk +tier. Verify the root cause yourself: a builder's summary is evidence, not ground truth. The +human should be able to answer from your message without opening the diff. -```bash -gh pr diff --stat # See lines changed and files touched -gh pr view --json files | jq '.files[].path' # See which subsystems -``` - -#### Step 2: Triage - -| Risk | Criteria | Action | -|------|----------|--------| -| **Low** | <100 lines, 1-3 files, isolated (docs, tests, cosmetic, bugfixes) | Read PR, summarize root cause + fix, tell builder to merge | -| **Medium** | 100-500 lines, 4-10 files, touches shared code (features, commands) | Single-model review: `consult -m claude --type integration pr N` | -| **High** | >500 lines, >10 files, core subsystems (porch, Tower, protocols, security) | Full 3-way CMAP (see below) | - -**Precedence: highest factor wins.** If any single factor (lines, files, subsystem, or cross-cutting scope) is high-risk, treat the whole PR as high-risk. - -**Typical mappings:** -- **Low**: Most bugfixes, ASPIR features, documentation, UI tweaks -- **Medium**: SPIR features, new commands, refactors touching 3+ files -- **High**: Protocol changes, porch state machine, Tower architecture, security model - -#### Presenting the decision to the human (PRFT) - -When you bring a fix to the human for a decision — a merge word, a `pr` gate, a dev-approval — present it **unprompted** in PRFT form, whatever the risk tier: - -- **Problem** — the user-visible symptom, in a sentence or two. -- **Root Cause** — the verified mechanism. Verify it yourself; a builder's summary is evidence, not ground truth. -- **Fix** — what changed and why it's safe. -- **Testing** — the evidence: suites run, live verification, CI state. - -Keep each part tight and lead with it — don't bury the decision under process narration. The human should be able to say yes or no from your message alone, without opening the diff. - -#### Step 3: Execute Review - -**Low risk** — no external models needed: -```bash -# Read the PR yourself, then approve -gh pr comment 83 --body "## Architect Review - -Low-risk change. [Summary of what changed and why.] - ---- -Architect review" - -afx send 0042 "PR approved, please merge" -``` - -**Medium risk** — single-model review: -```bash -consult -m claude --type integration pr 83 - -# Post findings as PR comment -gh pr comment 83 --body "## Architect Integration Review -... -Architect integration review" - -afx send 0042 "PR approved, please merge" -``` - -**High risk** — full 3-way CMAP: -```bash -consult -m gemini --type integration pr 83 & -consult -m codex --type integration pr 83 & -consult -m claude --type integration pr 83 & -wait - -# Post findings as PR comment -gh pr comment 83 --body "## Architect Integration Review -... -Architect integration review" - -afx send 0042 "PR approved, please merge" -``` - -### 5. Cleanup - -After builder merges and work is integrated: - -```bash -# 1. Close the GitHub Issue -gh issue close 42 - -# 2. Clean up the builder worktree -afx cleanup -p 0042 -``` - -**Always close the GitHub Issue when the PR merges.** This is the architect's responsibility — builders don't close issues. - -## Critical Rules - -### NEVER Do These: -1. **DO NOT merge PRs yourself** - Let builders merge their own PRs -2. **DO NOT commit directly to main** - All changes go through builder PRs -3. **DO NOT use `afx send` for long messages** - Use GitHub PR comments instead -4. **DO NOT run `afx` commands from inside a builder worktree** - All `afx` commands must be run from the repository root on `main`. Spawning from a worktree nests builders inside it, breaking everything. -5. **DO NOT `cd` into a builder worktree** - All CLI tools (`afx`, `porch`, `consult`, `codev`) are global commands that work from any directory. If a command fails, debug it — don't cd into the worktree. Use absolute paths with the Read tool to inspect builder files (e.g., `Read /path/to/.builders/0042/codev/specs/...`). - -### ALWAYS Do These: -1. **Create GitHub Issues first** - Track projects as issues before spawning -2. **Review artifacts before approving gates** - (Strict mode) Read the spec/plan carefully -3. **Use PR comments for feedback** - Not terminal send-keys -4. **Let builders own their work** - Guide, don't take over -5. **Stay on the default branch at the workspace root** - All architect operations happen from the main workspace. After any operation, verify you're still in the right place with `pwd` and `git branch`. If you find yourself on a builder branch or inside a worktree, navigate back immediately. - -## Project Tracking - -**GitHub Issues are the canonical source of truth for project tracking.** - -```bash -# See what needs work -gh issue list --label "priority:high" - -# View a specific project -gh issue view 42 -``` - -Update status as projects progress: -- `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated` - -## Working with Project Labels - -If your project uses prefix-structured labels (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, the recipes below are the architect-specific bulk operations — substitute `` and `` for your project's actual labels. (Skip this section if your project doesn't use prefix-structured labels.) - -**Operational recipes:** - -```bash -# Confirm the current label vocabulary (use before any label op to catch drift) -gh label list --search "/" - -# Group: tally open issues by /* label -gh issue list --state open --limit 500 --json number,title,labels --jq \ - 'group_by([.labels[].name | select(startswith("/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("/")).name): \(length)"' - -# Edit: change a label on a single issue -gh issue edit --remove-label / --add-label / - -# Audit: find open issues with no /* label -gh issue list --state open --limit 500 --json number,title,labels \ - --jq '.[] | select([.labels[].name] | any(startswith("/")) | not) | "#\(.number) \(.title)"' - -# Bulk-move: relabel all open / issues to / -for n in $(gh issue list --state open --limit 500 --label / --json number --jq '.[].number'); do - gh issue edit "$n" --remove-label / --add-label / -done -``` - -## Handling Blocked Builders - -When a builder reports blocked: - -1. Check their status: `afx status` or `porch status ` -2. Read their output in the terminal: `http://localhost:` -3. Provide guidance via short `afx send` message -4. Or answer their question directly if they asked one - -## Release Management - -The Architect manages releases - deployable units grouping related projects. - -``` -planning → active → released → archived -``` +## UX verification -- Only **one release** should be `active` at a time -- Projects should be assigned to a release before `implementing` -- All projects must be `integrated` before release is marked `released` +Before approving anything with UX requirements, exercise the actual user path. A spec that says +"async" and an implementation that blocks, or "immediate" and a 30-second wait, is a rejection +regardless of what the tests say. -## UX Verification (Critical) +## Boundaries -Before approving implementations with UX requirements: +- **Don't merge PRs** — builders merge their own. +- **Don't commit to the default branch** — every change arrives through a builder PR. +- **Don't `cd` into a builder worktree.** `afx`, `porch`, `consult` and `codev` are global and + work from anywhere; read builder files by absolute path. +- Run `afx` commands only from the main workspace root, never from inside a builder worktree — spawning from a worktree nests builders and breaks the workspace. +- **Use PR comments for anything long** — `afx send` is for short messages. +- **Let builders own their work** — guide, don't take over. +- **Close the GitHub Issue when the PR merges.** That's yours; builders don't close issues. -1. **Read the spec's Goals section** -2. **Manually test** the actual user experience -3. Verify each UX requirement is met +## When a builder is blocked -**Auto-reject if:** -- Spec says "async" but implementation is synchronous -- Spec says "immediate" but user waits 30+ seconds -- Spec has flow diagram that doesn't match reality +Check `afx status` or `porch status `, read its terminal output, and answer with a short +`afx send`. If it's waiting on an artifact, confirm the producing process is actually alive +before letting it wait — a wait is a claim that a producer exists. -## Quick Reference +## Bulk label operations -| Task | Command | -|------|---------| -| Start feature (strict, default) | `afx spawn --protocol spir` | -| Start feature (soft) | `afx spawn --protocol spir --soft` | -| Start bugfix | `afx spawn --protocol bugfix` | -| Check all builders | `afx status` | -| Check one project | `porch status ` | -| Approve spec | `porch approve spec-approval` | -| Approve plan | `porch approve plan-approval` | -| See pending gates | `porch pending` | -| Assess PR risk | `gh pr diff --stat N` | -| Integration review (medium) | `consult -m claude --type integration pr N` | -| Integration review (high) | 3-way CMAP (see Section 4) | -| Message builder | `afx send "short message"` | -| Cleanup builder | `afx cleanup -p ` | +If the project organizes issues with prefixed labels (`area/*`, `priority/*`), confirm the +vocabulary with `gh label list --search "/"` before any bulk edit — it catches drift +before it propagates. Group, audit and bulk-move with `gh issue list --json`/`--jq` and +`gh issue edit`. diff --git a/codev-skeleton/roles/builder.md b/codev-skeleton/roles/builder.md index 15bb1f8d0..864878dd6 100644 --- a/codev-skeleton/roles/builder.md +++ b/codev-skeleton/roles/builder.md @@ -1,259 +1,118 @@ # Role: Builder -A Builder is an implementation agent that works on a single project in an isolated git worktree. +You implement one project in an isolated git worktree, and you own it end to end: artifacts, +code, tests, PR. -## Two Operating Modes +## Two modes -Builders run in one of two modes, determined by how they were spawned: +| Mode | How you know | How you work | +|---|---|---| +| **Strict** (default) | spawned without `--soft` | Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. | +| **Soft** | spawned with `--soft` | You follow the protocol yourself; the architect verifies compliance. | -| Mode | Command | Behavior | -|------|---------|----------| -| **Strict** (default) | `afx spawn XXXX` | Porch orchestrates - runs autonomously to completion | -| **Soft** | `afx spawn XXXX --soft` | AI follows protocol - architect verifies compliance | +In strict mode porch drives the loop — run it, do the work it hands you, run it again. Do not +hand-run consultations it would run, advance plan phases yourself, or skip the 3-way review. -## Strict Mode (Default) +Never hand-edit `status.yaml` — only porch commands modify project state. -Spawned with: `afx spawn XXXX` +## Gates -In strict mode, porch orchestrates your work and drives the protocol to completion autonomously. Your job is simple: **run porch until the project completes**. +Porch stops at human approval gates (`spec-approval`, `plan-approval`, `pr`). When it does: +say so, **stop**, and wait. -### The Core Loop +Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization. -```bash -# 1. Check your current state -porch status - -# 2. Run the protocol loop -porch run - -# 3. If porch hits a gate, STOP and wait for human approval -# 4. After gate approval, run porch again -# 5. Repeat until project is complete -``` - -Porch handles: -- Spawning Claude to create artifacts (spec, plan, code) -- Running 3-way consultations (Gemini, Codex, Claude) -- Iterating based on feedback -- Enforcing phase transitions +Approval reaches you as a message from the architect. Then *you* run +`porch approve `; the architect does not run it for you — **unless your protocol's +prompts route that command to the human instead** (PIR's gates are typed by the human reviewer, +via Cmd+K G or their own shell). Defer to your protocol's phase prompts on who types `porch approve`. -### Gates: When to STOP - -Porch has two human approval gates: +## Deliverables -| Gate | When | What to do | -|------|------|------------| -| `spec-approval` | After spec is written | **STOP** and wait | -| `plan-approval` | After plan is written | **STOP** and wait | +Same base filename in three directories, plus code and tests: -When porch outputs: ``` -GATE: spec-approval -Human approval required. STOP and wait. +codev/specs/-.md what and why +codev/plans/-.md how and in what order +codev/reviews/-.md what was learned ``` -You must: -1. Output a clear message: "Spec ready for approval. Waiting for human." -2. **STOP working** -3. Wait for the human to run `porch approve XXXX spec-approval` -4. After approval, run `porch run` again +## Your thread -### What You DON'T Do in Strict Mode +Keep a free-text log at `codev/state/_thread.md` — the cohort's shared situational +awareness, readable by architects and sibling builders. `` is `basename "$(pwd)"`. +Write at phase boundaries and whenever a future reader would want to know what happened: +decisions, blockers, surprises. No schema, no cadence requirement. -- **Don't manually follow SPIR steps** - Porch handles this -- **Don't run consult directly** - Porch runs 3-way reviews -- **Don't edit status.yaml phase/iteration** - Only porch modifies state -- **Don't call porch approve** - Only humans approve gates -- **Don't skip gates** - Always stop and wait for approval +**Commit it with your PR.** Leaving it uncommitted by accident is a bug, not a choice. -## Soft Mode +## Telling the architect things -Spawned with: `afx spawn XXXX --soft` or `afx spawn --task "..."` +They are not watching. Send a message at each of these: -In soft mode, you follow the protocol document yourself. The architect monitors your work and verifies you're adhering to the protocol correctly. +| When | What | +|---|---| +| Gate reached | `afx send architect "Project : ready for approval"` | +| PR ready | `afx send architect "PR #N ready for review"` | +| PR merged | `afx send architect "Project complete. Entering verify phase."` | +| Blocked | `afx send architect "Blocked on X — need guidance"` | -### Startup Sequence - -```bash -# Read the spec and/or plan -cat codev/specs/XXXX-*.md -cat codev/plans/XXXX-*.md +When blocked, state the problem and the options you see, then wait. Don't guess past a decision +that isn't yours. -# (The full protocol text is inlined in your spawn prompt under the -# "## Protocol Reference (full text)" heading; no need to fetch it.) - -# Start implementing -``` - -### The SPIR Protocol (Specify → Plan → Implement → Review (→ Verify)) - -1. **Specify**: Read or create the spec at `codev/specs/XXXX-name.md` -2. **Plan**: Read or create the plan at `codev/plans/XXXX-name.md` -3. **Implement**: Write code following the plan phases -4. **Review**: Write lessons learned and create PR -5. **Verify** (optional): After PR merge, verify the feature works in the integrated codebase - -### Consultations - -Run 3-way consultations at checkpoints: -```bash -# After writing spec -consult -m gemini --protocol spir --type spec & -consult -m codex --protocol spir --type spec & -consult -m claude --protocol spir --type spec & -wait - -# After writing plan -consult -m gemini --protocol spir --type plan & -consult -m codex --protocol spir --type plan & -consult -m claude --protocol spir --type plan & -wait - -# After implementation -consult -m gemini --protocol spir --type pr & -consult -m codex --protocol spir --type pr & -consult -m claude --protocol spir --type pr & -wait -``` +## Waiting on external work -## Deliverables +**A wait is a claim that a producer exists.** Before waiting on a file, a build, or a sibling's +output, confirm the process meant to produce it is alive. A builder once waited 45 minutes on a +file whose producer had already died — that wait was not slow, it was unsatisfiable. -- Spec at `codev/specs/XXXX-name.md` -- Plan at `codev/plans/XXXX-name.md` -- Review at `codev/reviews/XXXX-name.md` -- Implementation code with tests -- PR ready for architect review +**Run waits as background tasks that end your turn.** Every message sent to you — including an +order to stop — queues unread until your current turn ends. A turn that never ends is a builder +nobody can redirect, and you will not notice, because from inside it everything looks fine. +Never chain foreground poll loops. -## Communication +If you are wedged anyway, the architect can end your turn with `afx interrupt `, or +`afx reset ` to have you save state and re-orient. Worth knowing so you can suggest +them. -### With the Architect +## PRs -If you're blocked or need help: -```bash -afx send architect "Question about the spec..." -``` +Plan phases are **git commits inside one PR**, not a PR each. Open the PR during or after the +final phase unless the architect asks for one earlier — they may, to review a slice or get +feedback mid-flight. Record them with `porch done --pr --branch ` and +`porch done --merged `. -### Checking Status +For sequential PRs, branch from the integration branch without checking it out — a worktree +cannot check out a branch that is checked out elsewhere: ```bash -porch status # (strict mode) Your project status -afx status # All builders +git fetch origin main && git checkout -b origin/main ``` -## Thread file - -You maintain a free-text markdown log at `codev/state/_thread.md` (relative to your worktree). This is the cohort's collective situational-awareness surface — architects and sibling builders can read it via plain file I/O. - -**Path resolution**: `` is the basename of your worktree path. Resolve it once with `basename "$(pwd)"`. Example: if your worktree is `.builders/spir-823/`, the path is `codev/state/spir-823_thread.md`. - -**Directory creation**: `codev/state/` likely doesn't exist when you start (it's greenfield). Your first write creates it — the Write tool's `mkdir -p` semantics handle this transparently. No need to pre-create the directory. - -**What to write**: phase transitions, decisions, blockers, anything worth recording for the cohort. Trust your own judgement about what's useful. There is no required schema, no required sections, no timestamp format. The thread is yours. - -**When to write**: at phase boundaries and at any other moment you think a future reader would want to know what happened. Don't over-engineer cadence — append when there's something to say. +## Worktree discipline -**Discovery**: -- **In-flight** (while you're active): your thread lives in your worktree at `.builders//codev/state/_thread.md` (from the main workspace root). Architects read it with `cat .builders//codev/state/_thread.md`; they discover threads with `ls .builders/*/codev/state/*.md`. -- **Sibling builders**: read each other's threads via `cat ..//codev/state/_thread.md` from your own worktree (the parent `.builders/` directory is shared between all builders in the workspace). -- **Post-merge**: after your PR merges, your thread lands in `codev/state/` on `main` (parallel to `codev/reviews/`) and becomes part of the historical review record. +Your worktree is nested inside the main checkout and, at the branch base, byte-identical to it. +So a path that drops the `.builders//` segment silently reads and writes **main's** copy — +reads succeed, writes succeed, and nothing corrects you until a later `git add` fails. -**Commit/retention rule**: **the default disposition is COMMIT.** Stage and commit your thread file as part of your PR. The rare exception — when your thread turned out to be noise rather than useful narrative — is an explicit decision to strip it before PR (via gitignore for the PR or by not staging the file). Silently leaving the thread uncommitted by accident is a bug, not an exercise of the exception. The cohort's situational-awareness goal depends on threads surviving to `main`. +- Absolute paths for file writes must be rooted at your worktree. A guard blocks writes outside + it; if you see that denial, re-root the path. +- In Bash, prefer relative paths — `cwd` is your worktree, so a relative path cannot be anchored + to the wrong root. -**Scope reminder**: this is for the cohort's situational awareness, not porch's tracking. Porch does not read this file. There are no hooks, no validation, no enforcement. +## Scope -## Notifications +Build what the spec says. If part of it is blocked, finish everything else and say plainly what +you left out and why — scaling the work down is the architect's call. -**ALWAYS notify the architect** via `afx send` at these key moments: +Never `git add -A` / `--all` / `.` — stage each file explicitly by path. -| When | What to send | -|------|-------------| -| **Gate reached** | `afx send architect "Project XXXX: ready for approval"` | -| **PR ready** | `afx send architect "PR #N ready for review"` | -| **PR merged** | `afx send architect "Project XXXX complete. PR merged. Entering verify phase."` | -| **Blocked/stuck** | `afx send architect "Blocked on X — need guidance"` | -| **Escalation needed** | `afx send architect "Issue too complex — recommend escalating to SPIR"` | +If the issue carries a **Baked Decisions** section, those are fixed. Don't relitigate them in +your spec, plan, or implementation; if one looks seriously wrong, raise it with `afx send`. If +two contradict each other, don't pick — flag the contradiction and wait. -The architect may be working on other tasks and won't know you need attention unless you send a message. **Don't assume they're watching** — always notify explicitly. - -## When You're Blocked - -If you encounter issues you can't resolve: - -1. **Output a clear blocker message** describing the problem and options -2. **Use `afx send architect "..."` to notify the Architect** -3. **Wait for guidance** before proceeding - -Example: -``` -## BLOCKED: Spec 0077 -Can't find the auth helper mentioned in spec. Options: -1. Create a new auth helper -2. Use a third-party library -3. Spec needs clarification -Waiting for Architect guidance. -``` - -## Waiting on external work +## Flaky tests -The section above covers being blocked on *the architect*. This one covers being blocked on *an -artifact* — a file another agent is producing, a build, a queue, a sibling builder's output. That case -has its own failure mode, and it is the one that strands builders. - -**A wait is a claim that a producer exists.** Before waiting on an artifact, confirm the process meant to -produce it is actually alive. In the incident that motivated this guidance (2026-07-27), a builder waited -45+ minutes on a file whose producing process had already died. The wait could never have succeeded; it -was not slow, it was unsatisfiable. Checking first costs seconds. - -**Run waits as tracked background tasks that end your turn.** Start the wait in the background and finish -your turn. You are re-invoked when it completes, so the lane keeps moving *and* you stay addressable in -the meantime. A turn that ends is a turn someone can interrupt. - -**Never chain foreground poll loops.** This is the rule that matters most, and the reason is not -efficiency. Every `afx send` to you — including the architect's order to stop, including a reset -request — **queues unread until your current turn ends**. A turn that never ends is a builder that cannot -be reached by anyone, doing work nobody can redirect. You will not notice, because from inside the turn -everything looks fine. - -**If you are wedged anyway, you are not unreachable.** The architect can send you an ESC keystroke with -`afx interrupt `, which ends the running turn so your queued messages process. They can also run -`afx reset ` to have you save your working state, clear your context, and be re-oriented — the -supported recovery when your context window is exhausted rather than merely stuck. Neither requires you -to do anything; both are worth knowing exist, so you can suggest them when you notice you are in trouble. - -## Multi-PR Workflow - -Builders may submit multiple sequential PRs within a single worktree session. The worktree persists across PRs -- it is not cleaned up automatically after merge. This allows builders to do follow-up work (e.g., addressing review feedback in a second PR, or splitting large features across checkpoint PRs). - -- **Worktree cleanup is architect-driven** -- the architect decides when to run `afx cleanup`, not the builder -- If a builder session is interrupted, use `afx spawn XXXX --resume` to reconnect to the existing worktree - -## Worktree isolation: filesystem path discipline - -Your worktree (`.builders//`) is **nested inside the main checkout**, and at the -branch base the two trees are **byte-identical**. This creates a silent failure mode: - -- The `Write`/`Edit` tools require **absolute** paths. If you synthesize one rooted - at the canonical repo root instead of your worktree, you drop the `.builders//` - segment and write into the **main checkout** — a real, writable directory. The - write *succeeds silently* and pollutes `main`; you only notice later when a - `git add` in your worktree fails with a pathspec error. -- Wrong-rooted **reads** also succeed silently (identical trees), so nothing - corrects the mistake until that first failed write. - -Rules: -- **Absolute paths for Write/Edit must be rooted at your worktree.** A deterministic - PreToolUse guard now blocks out-of-worktree writes (allowing only temp dirs and - `~/.claude`); if you see that denial, re-root the path under your worktree. -- **Bash `cwd` is your worktree — prefer relative paths there.** A relative path - cannot be anchored to the wrong root, which closes the Bash write surface - (`>`, `cp`, `tee`, `sed -i`) the Write/Edit guard does not cover. - -## Constraints - -- **Stay in scope** - Only implement what's in the spec -- **Merge your own PRs** - After architect approves -- **Keep worktree clean** - No untracked files, no debug code -- **(Strict mode)** Run porch, don't bypass it -- **(Strict mode)** Stop at gates - Human approval is required -- **(Strict mode)** NEVER edit status.yaml directly -- **(Strict mode)** NEVER call porch approve +If a pre-existing test fails intermittently and unrelated to your change: skip it with an +annotation naming it flaky, document it under `## Flaky Tests` in your review, and continue. +Never edit `status.yaml` or bypass a porch check to route around it. diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-1-shared-skills.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-1-shared-skills.md new file mode 100644 index 000000000..53c6a5583 --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-1-shared-skills.md @@ -0,0 +1,81 @@ +# Phase 1 — CLAUDE.md/AGENTS.md + four-tree skill relocation (G2) + +**Decisions**: 1 (CLAUDE.md/AGENTS.md are one decision, two byte-identical files) +**Rollback group**: G2 · commit-pure +**Suite**: green · **Build**: rerun (`copy-skeleton` — skeleton edits are otherwise invisible to tests) + +## Batch 1 — 10 files + +| File | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `CLAUDE.md` | 5815 | 1417 | P1, P3, P4, P7 | Contracts kept, procedure deleted. See breakdown below. | +| `AGENTS.md` | 5815 | 1417 | P1, P3, P4, P7 | Byte-identical twin of the above (T7). | +| `.claude/skills/runnable-worktrees/SKILL.md` | 0 | 926 | P3, P4 | **New destination.** Receives the entire Runnable Worktrees section — config block, `afx dev` CLI, VSCode controls, URL/cleanup semantics, 7 stack recipes. Needed rarely, was loaded always. | +| `.codex/skills/runnable-worktrees/SKILL.md` | 0 | 926 | P3, P4 | Four-tree copy (T17). | +| `codev-skeleton/.claude/skills/runnable-worktrees/SKILL.md` | 0 | 926 | P3, P4 | Four-tree copy — adopters receive it via `codev update`. | +| `codev-skeleton/.codex/skills/runnable-worktrees/SKILL.md` | 0 | 926 | P3, P4 | Four-tree copy. | +| `.claude/skills/codev/SKILL.md` | 326 | 529 | P4 | Receives Local Build Testing, the directory map, and the tokei metrics line — tool how-tos belong with the tool. | +| `.codex/skills/codev/SKILL.md` | 326 | 529 | P4 | Four-tree copy (T17). | +| `codev-skeleton/.claude/skills/codev/SKILL.md` | 326 | 529 | P4 | Four-tree copy. | +| `codev-skeleton/.codex/skills/codev/SKILL.md` | 326 | 529 | P4 | Four-tree copy. | + +Supporting (new test, not a prompt surface): +`packages/codev/src/__tests__/spec-1280-skills-parity.test.ts` — **T17**. + +## What was deleted vs relocated (M0c) + +| | Words | +|---|---:| +| CLAUDE.md before | 5,815 | +| CLAUDE.md after | 1,417 | +| **Removed from always-on** | **4,398** | +| ↳ **relocated** to skills (`runnable-worktrees` 926 + `codev` +203) | 1,129 | +| ↳ **deleted** outright | 3,269 | + +Relocation is written to **four** trees, so authored total falls by less than always-on — +which is the honest picture and exactly what T15 exists to expose. + +- `ALWAYS_ON_WORDS`: 34,231 → **29,833** (−4,398) +- `TOTAL_AUTHORED_WORDS`: 153,219 → **148,925** (−4,294) + +## What was deleted, and why it was safe + +| Cut | Principle | Reasoning | +|---|---|---| +| "Before Starting ANY Task" (check for existing PRs/issues/git log, with bash) | P1 | A frontier model checks for prior art without being told; the hot tier already carries "check for existing work" as a lesson. | +| "When Stuck: STOP After 15 Minutes" + rathole warning signs | P1 | Judgment, and duplicated by the hot-tier lesson "when stuck, get an outside model's perspective". | +| "Understand Before Coding" | P1 | Restates what a competent agent does. | +| Duplicated 🚨 blocks (worktree destruction ×2, `afx` from root ×2, `git add -A` ×3) | P7 | Each survives **once**, verbatim, under *Irreversible acts*. Repetition was worst-case padding for weaker models. | +| CLI Command Reference — six doc links | P4 | Each CLI has a skill; the pointer list was a table of contents for content that is already addressable by name. | +| Agent Responsiveness table (4 rows of examples) | P1, P2 | Reduced to the rule: run anything over ~5s in the background. | +| cmap walkthrough (4 numbered steps) | P4 | One sentence + the `consult` skill. | +| Porch command list, Architect-Builder prose, messaging examples | P4 | Contract kept (addressing table, spoofing rule); walkthroughs dropped. | +| "Important Notes", "Core Workflow" numbered restatements | P1, P7 | Restated the protocol table immediately above them. | + +## What was deliberately kept + +- **All eight scar canonicals, verbatim and unwrapped** — verified byte-for-byte against + `builder/spir-1252:codev/resources/scar-rules.yaml`. My first draft reflowed them across + lines, which broke exact-match; canonicals must stay on one line. +- The generated hot-context block, byte-for-byte (`codev init`/`update` owns it). +- Repository dual nature, four-tier resolution, deliver-don't-fetch — the facts a wrong + assumption about which would corrupt a whole change. +- Gate semantics and the approval frontmatter contract. +- `area/*` policy (compressed to the rule + the label list). +- Consultation defaults, including the load-bearing `-sol` model-id suffix. +- Commit/branch formats and the never-squash rule. + +## M10 — assertions retired: **none** + +`spec-1273-wait-discipline-docs`, `governance-sweep`, `framework-ref-audit` and +`template-delivery` all pass **unmodified**. The `afx` skill was deliberately **not** touched: +relocating messaging content into it would have obliged me to resolve its pre-existing +repo-vs-skeleton drift (and propagate its stale `tick` references to adopters), which is the +architect's separate issue. The addressing *contract* stayed in CLAUDE.md instead — it is a +policy, not a how-to, so P4 does not apply. **Flagged as a judgment call rather than made +silently.** + +## Scope note + +`roles/*.md` are **Phase 2** (groups G6/G3/G5), not this phase — Phase 1 is G2 only, so the +commit stays group-pure and a G2 revert cannot pull role work out with it. diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-2-roles.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-2-roles.md new file mode 100644 index 000000000..f943f7d56 --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-2-roles.md @@ -0,0 +1,100 @@ +# Phase 2 — Three role files (G6, G3, G5) + +**Decisions**: 3 · **Rollback groups**: G6 (architect), G3 (builder), G5 (consultant) — +**three group-pure commits**, so a G3 revert cannot pull architect work out with it. +**Suite**: green · **Build**: rerun before testing (`copy-skeleton`). + +## Batch 1 — 6 files + +| File | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `codev/roles/architect.md` | 2048 | 807 | P1, P4, P7 | Command walkthroughs → the `afx`/`porch`/`consult` skills that already own them. Risk-triage table, PRFT contract, UX-verification rule and boundaries kept. | +| `codev-skeleton/roles/architect.md` | 2048 | 807 | P1, P4, P7 | Byte-identical twin. | +| `codev/roles/builder.md` | 1837 | 849 | P1, P7 | Mode contract, gates, deliverables, thread, notifications, wait discipline, worktree path discipline, scope, flaky-test rule all kept. Numbered "core loop" walkthroughs and repeated ALL-CAPS prohibitions deleted. | +| `codev-skeleton/roles/builder.md` | 1837 | 849 | P1, P7 | Byte-identical twin. | +| `codev/roles/consultant.md` | 252 | 252 | none | **Inspected, unchanged.** Already conformant — states a contract, not a procedure. Under the acceptance model a conformant file passes *as-is*; shrinking it further would be size-chasing, which the charter amendment explicitly rejects. | +| `codev-skeleton/roles/consultant.md` | 252 | 252 | none | Unchanged. | + +- `ALWAYS_ON_WORDS`: 29,833 → **28,844** (−989; SPIR spawn 6,364 → 5,371) +- `ALWAYS_ON(architect)`: 8,599 → **2,914** +- `TOTAL_AUTHORED_WORDS`: 148,925 → **144,373** + +**Deleted vs relocated (M0c): all deletion, no relocation.** The command walkthroughs were not +moved — the `afx`, `porch` and `consult` skills already carry that material, so copying it would +have created a second owner for content that has one. Authored total falls by 4,552 (both trees +× two files), more than always-on, which is what pure deletion looks like. + +## Verified before cutting, not assumed + +The plan flagged an open question: *is anything in `architect.md` load-bearing for +multi-architect coordination (Specs 755/786/823)?* **Answer: no.** Grepped the file for +`architect:`, sibling/multi-architect language, `spawnedByArchitect`, and `whoami` — +**zero matches**. The multi-architect addressing contract lives in CLAUDE.md (kept there in +Phase 1). Recording it as checked rather than leaving the question open. + +## What was deleted, and why it was safe + +| Cut | Principle | Reasoning | +|---|---|---| +| Architect: `afx`/`porch`/`consult` command blocks and the 14-row Quick Reference | P4 | Each CLI has a skill that is the single owner of its flags; the role doc was a stale second copy (it still advertised `porch approve` without the `--a-human-explicitly-approved-this` flag the command now requires). | +| Architect: step-by-step "Starting a New Feature", "Monitoring Progress", "Cleanup" walkthroughs | P1 | Sequenced narration of three commands. The obligations (close the issue; clean up the worktree) survive as contract lines. | +| Architect: "Release Management" state diagram | P1, P7 | Aspirational process with no mechanism behind it in this repo. | +| Builder: the numbered "Core Loop" and "What You DON'T Do in Strict Mode" | P1, P7 | The mode table plus one sentence carries it. | +| Builder: "Getting Started" 3-step list, duplicated protocol summary | P1 | The protocol is inlined into the spawn prompt; restating it in the role doc is a second, drift-prone copy. | +| Both: ALL-CAPS repetition of prohibitions already stated once | P7 | Each prohibition survives exactly once. | + +## Kept verbatim + +Required scar canonicals verified byte-for-byte against +`builder/spir-1252:codev/resources/scar-rules.yaml`: + +- `roles/builder.md` → `no-hand-edit-status` ✓ (and `human-gates` carried in the Gates section) +- `roles/architect.md` → `afx-from-root` ✓ +- `roles/consultant.md` → none required + +## M10 — assertions retired: **none** + +`spec-1273-wait-discipline-docs.test.ts` (18 assertions over both role-doc copies) passes +**unmodified**. Three of its assertions initially failed against my rewrite: + +| Failure | Cause | Resolution | +|---|---|---| +| `## Waiting on external work` heading missing | I had renamed it to "Waiting on work you don't control" | **Reverted my heading.** The rename bought nothing; the assertion protects that the section exists. | +| "never chain foreground poll loops" not found | **Line wrap split the phrase** across two lines | Unwrapped. | +| "queues unread until your current turn ends" not found | I had dropped the word "current" | Restored. | + +In all three the *behaviour* survived the rewrite — only the strings moved. **The right response +was to adjust my prose, not Spec 1273's assertions**: the strings encode a wait-discipline +incident, preserving them cost nothing in conformance, and editing a prior spec's protection to +fit new prose is precisely the silent-erosion M10 exists to prevent. + +## Hazard worth naming (third occurrence) + +Reflowing prose silently breaks any string match that spans a line wrap — it has now broken +scar canonicals (Phase 1) and a prior spec's test assertions (here). **Any exact-match string in +a rewritten file must be verified after the rewrite, not assumed**, and canonicals must stay on +one line however long. + +## Post-inspection fix (architect-required, same phase, G6-pure) + +**Finding**: my rewrite created a cross-file contradiction. `builder.md` correctly encoded the +relay convention — *"Approval reaches you as a message from the architect. Then you run +`porch approve`; the architect does not run it for you"* — while `architect.md` kept the **old** +worked example showing the architect running +`(cd .builders/ && porch approve ...)`. The two roles disagreed on who the approval actor is. + +`builder.md` was correct: it matches the owner's standing convention, and it is what actually +happened at both of this project's own gates — so `architect.md`'s example contradicted observed +behaviour. + +**Fix** (`21ac428c`): the Gates section is now relay-shaped — read, decide, `afx send` the +approval; the builder executes against its own porch state. The +`--a-human-explicitly-approved-this` explanation is kept because the *why* is load-bearing. +architect.md 761 → 807 words: **the fix made the file longer, which is fine** — conformance is +the criterion, not size. + +**Worth recording plainly**: this is the same stale-second-owner class I had just caught on the +porch-approve flag syntax, one level up — and I introduced it, by fixing one owner and leaving +the other. Catching a class of defect is not the same as being immune to it. The general form: +*when a rewrite changes a convention, every file that documents that convention is in scope, +not just the one being edited.* diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-3-protocol-md.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-3-protocol-md.md new file mode 100644 index 000000000..8716b211e --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-3-protocol-md.md @@ -0,0 +1,119 @@ +# Phase 3 — `protocol.md` ×10 with the P6 include mechanism (G3) + +**Decisions**: 10 · **Rollback group**: G3, commit-pure +**Suite**: green · **Build**: rerun (`copy-skeleton`) before testing + +## Batch 1 — 10 decisions (19 files; twins are byte-identical, so inspection is per DECISION and T7 verifies the sync) + +| File (both trees unless noted) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/spir/protocol.md` | 3699 | 671 | **P6**, P1, P7 | Largest cut in the project. State machine delivered as JSON; deleted the 40-line MANDATORY checklist, four BLOCKING banners, the 13-step workflow, When-to-Use, Best Practices, Protocol Evolution. Kept artifact contract, spec-vs-plan boundary, no-time-estimates, consultation, gates, commit/branch formats. | +| `{codev,codev-skeleton}/protocols/pir/protocol.md` | 2066 | 551 | **P6**, P1, P7 | Kept the three gates with `dev-approval` named as PIR's distinctive one, the merge-trigger-is-structured-state rationale, the no-`porch reject` iteration model, PTY session semantics, and the CMAP-2 config-precedence trap. | +| `{codev,codev-skeleton}/protocols/maintain/protocol.md` | 1765 | 285 | **P6**, P1 | Kept since-marker discipline, `.trash/` 30-day recovery, tier routing, the explicit-`git add` canonical, and the maintenance-run template include. | +| `{codev,codev-skeleton}/protocols/research/protocol.md` | 1278 | 238 | **P6**, P1 | Kept independence-of-investigation and preserve-disagreement — the two properties that make a 3-way pass worth its cost. | +| `{codev,codev-skeleton}/protocols/aspir/protocol.md` | 810 | 248 | **P6**, P1 | Now says spec/plan are **ungated**, not 'auto-approved' — the JSON defines no gate there. Defers shared substance to SPIR. | +| `{codev,codev-skeleton}/protocols/bugfix/protocol.md` | 699 | 488 | **P6**, P1 | Kept the `--delete-branch` worktree warning, net-diff-at-merge-base scope, the self-merge-class gate rationale, and the edge-case table. | +| `{codev,codev-skeleton}/protocols/experiment/protocol.md` | 711 | 191 | **P6**, P1, P7 | Kept hypothesis-before-running, record-negative-results, and the notes template include. | +| `{codev,codev-skeleton}/protocols/spike/protocol.md` | 655 | 223 | **P6**, P1 | Kept the three-verdict table, 'a negative result is a successful spike', and the findings template include. | +| `{codev,codev-skeleton}/protocols/air/protocol.md` | 643 | 275 | **P6**, P1 | Kept the no-artifacts economy and the escalate-early rule. | +| `codev/protocols/release/protocol.md` *(codev-only)* | 1626 | 1626 | none | **Inspected, unchanged** — no `protocol.json` so P6 does not apply, and 36% of it is exact commands where the sequence *is* the contract. | + +### Served words (P6 expands the JSON back in) + +Authored → served, per protocol: spir 671→1239 · pir 551→926 · aspir 248→816 · bugfix 488→742 · +research 238→494 · maintain 285→477 · air 275→557 · experiment 191→380 · spike 223→300. + +*(Deliberately prose, not a table: a second table of the same shape parses as manifest rows and +inflates the batch count — T16 caught exactly that on this file.)* + +- `ALWAYS_ON_WORDS`: 28,844 → **26,384** +- `TOTAL_AUTHORED_WORDS`: 144,465 → **126,155** + +**Deleted vs relocated (M0c): all deletion, no relocation.** Nothing moved to a skill; the +structured source was already on disk and is now *delivered* rather than *narrated*. Authored +total falls 18,310 against always-on's 2,460, which is what deletion across both trees looks +like when the deleted prose was not always-on for every protocol. + +## `release` — inspected, deliberately unchanged + +`release/protocol.md` is **36% code blocks** (594 of 1,626 words) carrying exact `git add` file +lists, the root-`package.json` version-anchor pattern, the pre-release auto-skip for the VS Code +Marketplace, and the backport path. **Here the sequence *is* the contract**: P1 says delete the +procedure and keep the contract, and for a release the procedure is what the agent must not +improvise. + +It is also the one protocol with **no `protocol.json`**, so P6 does not apply. + +Under the acceptance model a conformant file passes as-is, and a file that is conformant at more +words passes. Cutting it to hit a number would be size-chasing — which the charter amendment +explicitly rejects. Recorded as a decision, not an omission. + +## P6 mechanism — delivered, not fetched + +`protocol.md` carries a fenced ` ```json ` block containing `{{> protocols/

/protocol.json}}`. +Verified rather than assumed: + +- `resolveCodevIncludes` is **extension-agnostic** (`skeleton.ts:108-119`), so the JSON expands + in place. +- The **spawn path** uses the same resolver — `spawn-roles.ts:127` passes `protocol.md` through + `resolveCodevIncludes` before inlining it as `{{protocol_reference}}`. Both modes benefit. +- **T18** asserts delivery in **both modes**, which are not symmetric: strict-mode builders also + get gates/checks as porch task JSON, but **soft-mode builders have only this document**. A + silent expansion failure would leave a soft-mode builder with a protocol doc describing + nothing. + +**A correction to my model of the resolver, found by T18 and worth recording**: tier 4 is +`getSkeletonDir()` — the **installed npm package** — *not* `/codev-skeleton/`. The +repo-local `codev-skeleton/` is a build *source* (`copy-skeleton` copies it into +`packages/codev/skeleton`); the resolver never reads it. My first fresh-install test planted +files in a temp `codev-skeleton/` and "passed" against the real installed package. Rewritten to +assert the actual adopter guarantee: `skeleton` is in the npm `files` allowlist and every P6 +protocol's `protocol.json` is in the built skeleton. + +## Cross-batch convention diff (the Phase 2 lesson, generalised) + +Ten files describing the same gates is ten chances for one stale owner. Diffed conventions +*across* the batch before declaring it: + +- **Gates**: every gate defined in `protocol.json` is present in the **served** text of its + `protocol.md`. The pre-existing gap — five protocols whose prose described *less* than their + JSON — is **dissolved by construction**, not fixed by hand. +- **Approval actor**: no file claims the architect runs `porch approve`. +- **Merge command**: `--delete-branch` warning preserved where it appears. + +Two apparent contradictions surfaced and **both were my diff's crudeness, not the files'**: it +checked *raw* text where T18 checks *served*, and its actor regex matched the **negation** +("You do **not** run `porch approve`"). Verified against the real artifacts before reporting. + +## M10 — assertions retired: **none**, but only after repair + +**I wrote "none retired / suite green" in this manifest before the suite finished.** It was not +green: 37 failures across three files, all of them real capability loss I had introduced. +Correcting the record rather than the claim: + +| Broke | Originating spec | Behaviour survived? | Resolution | +|---|---|---|---| +| `template-delivery` (12) — `maintain/maintenance-run.md`, `spike/findings.md`, `experiment/notes.md` orphaned | **#1279** | **No** — I replaced each protocol's template include with the `protocol.json` include instead of carrying both. Builders would have stopped receiving those artifact structures | Restored all three includes alongside the JSON | +| `baked-decisions` (24) — category hints, amend/rescind hatch, "no-op default" missing from spir/aspir/air | **Spec 746** | **No** — I shortened it in SPIR and dropped it from ASPIR and AIR. Losing "absence is the no-op default" invites a builder to invent constraints where the architect deliberately left them open | Restored to full Spec 746 completeness in all three | +| `framework-ref-audit` (1) | — | consequence of the above | Resolved by the same repair | + +**Zero assertions were retired — but by repair, not because nothing broke.** Every failure was +the tests catching capability I had deleted, which is the machinery working exactly as M5/M10 +intend. + +The process lesson is mine, not the code's: I applied "read the raw thing, don't trust the +summary" to every instrument this project touched, then skipped it on my own completion claim. + +## T16 caught three defects in this manifest itself + +Worth recording, because the guard was written before any manifest existed and has now earned it: + +1. A fifth column (`Served`) I added silently — the parser read `1239` as the principles field. + **The format is the contract; I conformed the manifest rather than loosening the test.** +2. Listing 19 file-rows instead of 10 decision-rows, which broke the ≤12 batch cap. The plan's + model is inspection *per decision* with twins verified mechanically by T7 — my "fix" had + silently abandoned that model. +3. A supplementary table of the same shape parsing as manifest rows and inflating the count. + Served figures are now prose. + +All three were my deviations from a format I defined myself. diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-4-builder-prompts.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-4-builder-prompts.md new file mode 100644 index 000000000..c699f677b --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-4-builder-prompts.md @@ -0,0 +1,107 @@ +# Phase 4 — `builder-prompt.md` ×9 + the M10 retirement burden (G3) + +**Decisions**: 9 · **Rollback group**: G3, commit-pure +**Batches**: 2 — (A) the nine prompt decisions; (B) the M10 test work and retirements register + +## Batch A — 9 decisions + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/spir/builder-prompt.md` | 824 | 428 | P1, P4, P7 | Dropped what `roles/builder.md` now owns (flaky tests, multi-PR mechanics, Getting Started, the ALL-CAPS restrictions block). **Kept the Verify Phase** — see below. | +| `{codev,codev-skeleton}/protocols/pir/builder-prompt.md` | 898 | 335 | P1, P7 | Kept "Sitting at Gates" in full (four feedback channels, never self-approve) and "Resumption After Crash" — both PIR-specific and unavailable elsewhere. | +| `{codev,codev-skeleton}/protocols/aspir/builder-prompt.md` | 820 | 385 | P1, P4, P7 | Mirrors SPIR. **Restored `Follow the ASPIR protocol`** after my first draft dropped it — see M10. | +| `{codev,codev-skeleton}/protocols/research/builder-prompt.md` | 556 | 282 | P1, P7 | Kept both `consult` dispatch blocks verbatim (investigate + critique) and added preserve-disagreement to the principles. | +| `{codev,codev-skeleton}/protocols/air/builder-prompt.md` | 537 | 313 | P1, P7 | Kept the mission, the no-artifacts economy, and the escalation message with its exact `afx send` form. | +| `{codev,codev-skeleton}/protocols/experiment/builder-prompt.md` | 472 | 242 | P1, P7 | Kept the `Closes`/`Fixes` vs `Refs`/`Part of` distinction — a partial-implementation PR must not auto-close its issue. | +| `{codev,codev-skeleton}/protocols/bugfix/builder-prompt.md` | 429 | 224 | P1, P7 | Kept the regression-test-must-fail-first rule and the `--delete-branch` worktree warning. | +| `{codev,codev-skeleton}/protocols/spike/builder-prompt.md` | 400 | 244 | P1, P7 | Kept the three-step workflow, the skip-iterate escape, and "not feasible is a valuable finding". | +| `{codev,codev-skeleton}/protocols/maintain/builder-prompt.md` | 374 | 218 | P1, P7 | Kept soft-delete, one-removal-per-commit, and added the candidate-not-verdict audit discipline. | + +## Batch B — M10 and the guard fixes + +| File | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `codev/resources/1280-retirements.md` | 0 | 520 | none | New. Retirements register; **R1 proposed, not applied** — awaiting architect approval. | +| `packages/codev/src/__tests__/spec-1280-phase-manifest.test.ts` | 0 | 0 | none | T16 scoped to this project by commit provenance — see below. | + +## Two protections kept rather than retired + +**#744 (per-phase PRs)** — all four asserted phrases preserved verbatim. The bug was builders +shipping a PR per plan phase, which the architect then had to close. + +**#619 (cross-protocol mixup)** — my first draft replaced `Follow the ASPIR protocol` with a +template variable, which broke it. The original bug had the ASPIR prompt telling builders to +follow **SPIR** — wrong gates entirely. Restored, and I added the symmetric line to SPIR: +#619 was a *cross*-protocol mixup, and symmetry makes it harder to reintroduce in the other +direction. + +## Kept despite duplicating the role doc: the Verify Phase + +`roles/builder.md` mentions "verify phase" **only inside a notification string** — it does not +carry the mechanics (pull the integration branch, `porch done`, `verify-approval`, +`porch verify --skip`). Deleting it here would have repeated **precisely the bug Spec 1252 +found**: the served SPIR builder prompt having silently lost its entire Verify Phase section. + +Checked before deleting rather than after. + +## M10 — one retirement PROPOSED, nothing retired unilaterally + +**R1: `expectPureAdditionDiff` on the three builder-prompts.** Full trace in +`codev/resources/1280-retirements.md`. Summary: + +- **Originating spec**: 746. The baseline is the **pre-746** file; the assertion proves 746's + paragraph was *added* without deleting prior content. +- **Why it cannot survive**: Spec 1280 deliberately deletes prose, so the invariant is false by + design — and permanently, since it forbids *any* future rewrite of these files. +- **Why re-baselining is not the escape**: 746's own **pollution check** requires the baseline + to lack `## Baked Decisions`. A re-baselined file would contain it and fail. Silencing that + check would gut the anti-vacuity property — the more valuable half of 746's protection. +- **Substance survives**: heading, `do not autonomously` carveout, contradiction wording and + mirror-parity all still assert and pass, verified in all three files. +- **Replacement implemented but inert**: post-1280 baselines with the same machinery plus an + inverted anti-vacuity check, so future silent deletion is still caught. + +**Awaiting approval. Rejection is a legitimate outcome** — it means Phase 4 cannot rewrite those +three files and the phase is rescoped. + +## T16 scoped to this project — second cross-project firing of my own guards + +T16's original predicate was **repo-global**: *any* prompt-bearing path in `origin/main...HEAD` +had to appear in a **1280** manifest. Because the test lives in the shared suite, it fired on +other projects — **Spec 1307 was blocked by it**, and would have had to file paperwork in this +project's directory to go green. + +That is a worse defect than the pinned-literal one it follows: a guard that taxes work it does +not govern, and demands foreign projects write into my ledger. + +**Fix: provenance, not paths.** Only files touched by commits tagged `[Spec 1280]` on this +branch are this project's to document. Any other branch skips the assertion entirely. The +uncommitted-changes check is retained, so a pre-commit run still cannot pass vacuously. + +Mutation-verified in both directions — a scoping fix that silently disabled the guard would be +the vacuous pass all over again. + +## Incidental fix: closes #1293 (blank artifact filename) + +**Found by the architect at inspection; independently verified before recording here.** + +The PIR builder-prompt carried **2** `{{artifact_name}}` references before this phase and **0** +after. That resolves #1293's blank-filename symptom **by deletion**, and the verification shows +why the bug existed at all: + +- `artifact_name` is substituted by **porch**, in `commands/porch/prompts.ts:102`, when it + builds a **phase prompt**. +- The **spawn path never substitutes it** — `grep artifact_name spawn-roles.ts` returns nothing. + +So a `{{artifact_name}}` placeholder in a *builder-prompt* could only ever render empty. Porch's +per-phase prompts were always the real owner of artifact naming; the builder-prompt was +referencing a variable nobody filled in for it. + +**#1293 should be closed against this merge** rather than lingering fixed-but-open. + +### Constraint this creates for Phase 5 + +The same placeholder is **legitimate and load-bearing in phase prompts** — 51 references across +the eleven Phase 5 targets. Deleting it there would break artifact naming outright. The rule is +positional, not textual: **remove `{{artifact_name}}` from spawn-time prompts, preserve it in +porch-substituted phase prompts.** diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-5-phase-prompts.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-5-phase-prompts.md new file mode 100644 index 000000000..28ef6b9a8 --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-5-phase-prompts.md @@ -0,0 +1,91 @@ +# Phase 5 — phase prompts: spir, aspir, pir (G4) + +**Decisions**: 11 (spir ×4, aspir ×4, pir ×3) · **Rollback group**: G4, commit-pure +**Batches**: 2 — (1) SPIR + ASPIR, 8 decisions; (2) PIR, 3 decisions. Include wiring untouched +(no `template-delivery` M10), but the `specify.md` rewrite triggers **one M10 retirement, R2, +PROPOSED and left RED** — see the M10 section below. The SPIR/ASPIR pairs are near-identical (ASPIR = the SPIR +body + a one-line header fix), so Batch 1's per-file inspection is effectively four distinct diffs +mirrored, not sixteen. + +**Levers**: **P2** (examples → interfaces) and **P1** (procedure → contract), per the spec's +`protocols/*/prompts/*.md` row. **P4** also applies: `roles/builder.md` (rewritten in Phase 2) now +owns the `git add -A` prohibition, flaky-test handling, consult handling and the never-edit-status.yaml +rule, so those repeats leave the phase prompts. + +**Old / New are SERVED counts** (`{{> }}` includes expanded), the manifest's basis. The SPIR +specify/plan/review served totals still carry their **unchanged** template words — templates are +Phases 6–7 — so the prose actually rewritten shrank more than the served delta shows (raw prose: +specify 770→433, plan 520→299, review 1316→589). Files with no include (all implement, all pir) +have served == raw. + +## Batch 1 — SPIR + ASPIR (8 decisions) + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/spir/prompts/specify.md` | 1400 | 1077 | P1, P2, P4 | Step-by-step "Process" → a "What must be true when you finish" contract. Kept the existing-spec / Baked-Decisions / contradiction-pause rules (a model gets these wrong without them) **in the canonical carveout wording** — `do not autonomously` / `pause` / `flag` (see M10 / R2 below), the `{{> …/spec.md}}` interface, all `` capabilities, the filename-sync and commit cadence. Deleted the "Include examples" note (**directly anti-P2**), the PISC-style padding and the What-NOT-to-do list already owned elsewhere. | +| `{codev,codev-skeleton}/protocols/aspir/prompts/specify.md` | 1400 | 1077 | P1, P2, P4 | SPIR body verbatim **plus a correctness fix**: the header said "the SPIR protocol" (see note below). Still includes SPIR's `spec.md` template (ASPIR ships no `templates/`). | +| `{codev,codev-skeleton}/protocols/spir/prompts/plan.md` | 1167 | 946 | P1, P2 | Replaced the "Good/Bad phase examples" lists (**P2 examples**) with the phase-quality **interface** — self-contained / independently-testable / valuable / committable — and the per-phase contract fields. Kept the `{{> …/plan.md}}` include, `PLAN_DRAFTED`, commit cadence. | +| `{codev,codev-skeleton}/protocols/aspir/prompts/plan.md` | 1167 | 946 | P1, P2 | SPIR body verbatim + the ASPIR header fix. | +| `{codev,codev-skeleton}/protocols/spir/prompts/implement.md` | 1064 | 386 | P1, P4 | Heaviest cut. Dropped the PISC emoji checklist, the Trust-Hierarchy ASCII, the "Avoiding Fixing Mode" narration and the **flaky-tests block (now owned by `roles/builder.md`)**. **Kept as contract**: the this-phase-only scope restriction (load-bearing — porch drives per phase), spec-as-source-of-truth, build+tests-must-pass, and every signal (`PHASE_COMPLETE` / `BLOCKED` / `AWAITING_INPUT`). | +| `{codev,codev-skeleton}/protocols/aspir/prompts/implement.md` | 1064 | 386 | P1, P4 | SPIR body verbatim + the ASPIR header fix. (No include; no `{{artifact_name}}` — matches the original.) | +| `{codev,codev-skeleton}/protocols/spir/prompts/review.md` | 1955 | 1228 | P1, P2, P4 | Procedure → contract; dropped the "Review Prompts for Reflection" padding and the What-NOT-to-do repeats. **Preserved every capability the guards pin**: the `{{> …/review.md}}` include, the hot/cold routing (`arch-critical.md` / `lessons-critical.md`) with the exact `## Architecture Updates` / `## Lessons Learned Updates` headings porch greps, the `## Consultation Feedback` contract, and the **`gh pr create … --body "$(cat <<'EOF' … EOF"` heredoc** with `Closes #`/`Refs #`/`auto-close` and no `{{issue.` token (bugfix-685). | +| `{codev,codev-skeleton}/protocols/aspir/prompts/review.md` | 1955 | 1228 | P1, P2, P4 | SPIR body verbatim + the ASPIR header fix; byte-identical skeleton twin (bugfix-685 checks this). | + +## Batch 2 — PIR (3 decisions) + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/pir/prompts/plan.md` | 741 | 722 | P4 | Already substantially conformant (recent rewrite). Removed only the two `git add -A` prohibition repeats `builder.md` owns; kept the resumption/gate mechanics, the plan-structure heading interface, and the four-channel feedback handling. | +| `{codev,codev-skeleton}/protocols/pir/prompts/implement.md` | 1151 | 1132 | P4 | Same: dropped the two git-add prohibition repeats; preserved the `$MERGE_BASE` diff mechanics, dev-approval gate flow and the flaky-vs-unrelated-failure distinction (PIR-specific, load-bearing). | +| `{codev,codev-skeleton}/protocols/pir/prompts/review.md` | 2413 | 2380 | P4 | Largest file in the project, and the densest with load-bearing PIR mechanics (single-pass `max_iterations:1`, verdict escalation, gate-authorization, `--pr`/`--merged` records) — nearly all of it survives P1 as **contract, not padding**. One P4 win: the gate-not-prose merge rule is stated in full at its action points (steps 8–9), so the trailing restatement in "What NOT to Do" became a back-reference. Routing strings preserved. | + +## The one content change beyond trimming: ASPIR header correctness + +The four ASPIR phase prompts were **byte-identical to SPIR's and literally read "the SPIR protocol"** +in their headers (0 occurrences of "ASPIR" before this phase). That is the same cross-protocol +mislabel class **#619** ratified fixing in the ASPIR *builder-prompt* during Phase 4. I corrected the +header phrase to "the ASPIR protocol" in all four; the body is otherwise identical to the SPIR rewrite. +No test required spir==aspir identity (bugfix-685 pins only skeleton==codev per file, which holds). +Flagging explicitly because it is a change in content, not just economy. + +## Why the PIR files barely moved + +PIR's three prompts were rewritten recently to a standard close to P1/P2 already: contracts with +heading interfaces, commands that are capabilities rather than illustrative examples, and mechanics a +frontier model genuinely needs (PIR's consultation is single-pass, so the human at the `pr` gate is +the only re-check — that is not padding). Under the acceptance model (**principle conformance, size +reporting-only; a conformant file passes unchanged**) the honest action was the P4 de-duplication +above, not a rewrite for its own sake. + +## M10 — one retirement PROPOSED (R2), suite deliberately left RED + +Rewriting `specify.md` to P1/P2 trips Spec 746's **Phase 2** `expectPureAdditionDiff` guard on the +two SPIR/ASPIR `specify.md` files — the identical wall R1 hit, which R1 **explicitly foresaw and +left in force** ("the `PHASE_2_FILES` … guards remain in force"). Two responses, opposite kinds: + +- **Behaviour grep — fixed in-phase, not retired.** My first draft reworded the Baked Decisions + clause and dropped the canonical literals. Restored to `do not autonomously` / `pause` / `flag` + (the preferred carveout phrasing anyway). All 188 behaviour/mirror/pollution assertions pass. +- **Pure-addition diff — proposed for retirement (R2), NOT applied.** A P1/P2 rewrite that deletes + prose can never be a line-superset of the pre-746 baseline. Per M10 I do **not** re-baseline or + edit the test unilaterally: the two assertions are **left RED** and R2 is written up in + `codev/resources/1280-retirements.md` with the full trace, the behaviour-re-asserted mapping, and + a replacement guard (extend `spec-1280-prompt-deletion-guard.test.ts` with post-1280 `specify.md` + baselines + inverted anti-vacuity) that ships **only on approval**, in its own commit, mirroring R1. + +**Current suite state: 2 RED** (`codev SPIR/ASPIR specify.md pure-addition diff`), by design, +pending the architect's R2 decision. `air/implement.md`'s Phase 2 guard and all Phase 3 guards stay +in force. + +## Guards held green (verified, not assumed) + +- **template-delivery** `#1279` WIRINGS — all six `{{> spir/templates/{spec,plan,review}.md}}` + includes intact in spir+aspir specify/plan/review. +- **review-prompt-routing** — spir/aspir/pir review (both trees) still carry `arch-critical.md`, + `lessons-critical.md`, `## Architecture Updates`, `## Lessons Learned Updates`, and none carries + `add entries to lessons-learned.md`. +- **bugfix-685** — spir/aspir review carry the close-keyword, partial-fix keyword, `auto-close`, and a + `{{issue.`-free PR-body heredoc; skeleton == codev. +- **T16 (phase-manifest)** — this manifest is what makes it pass; all 11 changed files listed. + +Measurement instrument, `spec-1280-p6-delivery`, and `spec-1280-prompt-deletion-guard`: green. diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-6-prompts-light-spir-templates.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-6-prompts-light-spir-templates.md new file mode 100644 index 000000000..3c558e66c --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-6-prompts-light-spir-templates.md @@ -0,0 +1,64 @@ +# Phase 6 — phase prompts: bugfix, air, maintain + spir templates (G4) + +**Decisions**: 10 (bugfix ×3, air ×2, maintain ×2, spir templates ×3) · **Rollback group**: G4, commit-pure +**Batches**: 2 — (1) bugfix + air prompts, 5 decisions; (2) maintain prompts + spir templates, 5 decisions. + +**Levers**: **P1** (procedure → contract) for the prompts, **P2** (annotated examples with filler → +heading interfaces) for the three templates. **P4** drops the `git add -A` repeats `roles/builder.md` +owns. Old/New are word counts (no `{{> }}` includes in any Phase 6 file, so served == raw). + +**Capabilities preserved** (all guard-verified): the close-keyword PR-body heredocs (bugfix/pr, air/pr, +maintain/review), the **BUGFIX/AIR CMAP self-dispatch** (`consult -m … --protocol … --type pr` — these +protocols run their own consultation, unlike SPIR), the spec template's porch-required + delivery-checked +headings, the plan template's **machine-readable phases-JSON capability** (`has_phases_json` / +`min_two_phases`, kept at ≥2 phases), and the review template's hot/cold routing headings + `## Flaky +Tests` / `### Methodology Improvements`. + +## Batch 1 — bugfix + air prompts (5 decisions) + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/bugfix/prompts/investigate.md` | 290 | 196 | P1 | "Process" steps → a reproduce / root-cause / scope-assessment contract. Kept the <300 LOC BUGFIX ceiling and all signals (`PHASE_COMPLETE` / `TOO_COMPLEX` / `BLOCKED`). | +| `{codev,codev-skeleton}/protocols/bugfix/prompts/fix.md` | 352 | 227 | P1, P4 | Contract form; kept the **fails-without-fix regression-test** rule and its untestable-change carve-out (a real BUGFIX contract). Dropped the git-add prohibition (builder.md owns). | +| `{codev,codev-skeleton}/protocols/bugfix/prompts/pr.md` | 491 | 402 | P1 | Kept the **close-keyword heredoc** (`Fixes #`/`Refs #`/auto-close, no `{{issue.`), the **CMAP self-dispatch** + wait-for-three-verdicts rule, and the `porch done` → `pr` gate hand-off. **Preserved the #335-pinned phrases verbatim** ("ALL THREE consultations have returned results", "DO NOT send this notification until you have all three CMAP verdicts") — that guard exists because bugfix builders once notified before CMAP returned, so those strings are load-bearing, not padding. | +| `{codev,codev-skeleton}/protocols/air/prompts/implement.md` | 442 | 316 | P1, P4 | Contract form; **kept the Baked Decisions clause verbatim** in canonical wording (`do not autonomously` / `pause` / `flag`) so Spec 746's grep stays green — see M10 / R3 below. Kept the <300 LOC ceiling and no-artifacts rule. | +| `{codev,codev-skeleton}/protocols/air/prompts/pr.md` | 471 | 337 | P1 | Kept the **close-keyword heredoc** (`Closes #`), the AIR "PR body IS the review — no `codev/reviews/` file" rule, and the optional-CMAP dispatch with its judgement guidance. | + +## Batch 2 — maintain prompts + spir templates (5 decisions) + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/maintain/prompts/maintain.md` | 402 | 406 | P4 | Already a lean command runbook (ts-prune/depcheck audit, two-tier arch/lessons routing, CLAUDE↔AGENTS sync) — those commands are capabilities, that routing is contract, so it stays. Only the `Never git add -A` prohibition became a positive explicit-staging line (builder.md owns the rule). Net word count is flat by design. | +| `{codev,codev-skeleton}/protocols/maintain/prompts/review.md` | 310 | 310 | none | **Inspected, conformant, kept unchanged** — a concise operational runbook (build/test, doc-link check, run-file finalize, PR with close-keyword heredoc). Under the acceptance model a conformant file passes unchanged. | +| `{codev,codev-skeleton}/protocols/spir/templates/spec.md` | 632 | 246 | P2 | Filler placeholder prose → a clean heading interface. Kept the porch-required headings (`## Problem Statement`, `## Current State`, `## Desired State`, `## Success Criteria`), the delivery-checked `## Solution Approaches` + `SPEC vs PLAN BOUNDARY`. Dropped enterprise sections (Stakeholders sub-roles, fabricated Performance/Security numbers, Resource/Approval/Change-Log sign-offs). | +| `{codev,codev-skeleton}/protocols/spir/templates/plan.md` | 649 | 201 | P2 | Kept the **machine-readable `## Phases (Machine Readable)` JSON capability** (≥2 phases) and the per-phase interface (objective / files / deliverables / acceptance / test). Dropped Resource Requirements, Monitoring/Alerting, Dependency-Map ASCII, Approval sign-offs, Change Log. | +| `{codev,codev-skeleton}/protocols/spir/templates/review.md` | 641 | 293 | P2 | Kept the hot/cold routing headings (`arch-critical.md` / `lessons-critical.md`, `## Architecture Updates`, `## Lessons Learned Updates`), the delivery-checked `## Flaky Tests` + `### Methodology Improvements`, and the Consultation-Feedback interface. Dropped the Timelog / Autonomous-Operation / Consultation-metrics / Avoidable-Iterations tables. | + +## M10 — one retirement PROPOSED (R3), suite left RED (1 assertion) + +Rewriting `air/implement.md` to P1 trips Spec 746's **Phase 2** `expectPureAdditionDiff` — the third +and last PHASE_2 file (R1 retired PHASE_1, R2 retired the two specify.md files, R3 is air/implement.md). +Behaviour survives: the Baked Decisions grep + mirror-parity pass because the clause was kept in +canonical wording. Per M10 I do **not** re-baseline or edit the test unilaterally: the one assertion is +**left RED** and R3 is written up in `codev/resources/1280-retirements.md` with the full trace, +behaviour-re-asserted mapping, and a replacement guard (extend `spec-1280-prompt-deletion-guard.test.ts` +with a post-1280 air/implement baseline + inverted anti-vacuity) that ships **only on approval**, mirroring +R1/R2. R3 also raises — without assuming — whether the human wants to **pre-approve the class** so the +remaining PHASE_3 retirements in Phases 7–9 don't each need a per-file gate. + +**Current suite state: 1 RED** (`codev AIR implement.md pure-addition diff`), by design, pending the +human R3 decision. All PHASE_3 guards remain in force. + +## Guards held green (verified, not assumed) + +- **bugfix-685** — bugfix/pr, air/pr, maintain/review carry the close-keyword, partial-fix keyword, + `auto-close`, and a `{{issue.`-free PR-body heredoc; skeleton == codev. +- **template-delivery** — the SPIR specify/plan/review prompts' `{{> }}` includes still resolve, and the + resolved content carries `## Problem Statement` / `## Solution Approaches` / `SPEC vs PLAN BOUNDARY` + (spec) and `## Architecture Updates` / `## Lessons Learned Updates` / `## Flaky Tests` / + `### Methodology Improvements` (review). +- **review-prompt-routing** — spir/templates/review.md keeps the routing strings and carries no + `add entries to lessons-learned.md`. +- **baked-decisions (Spec 746)** — every assertion green except the one retired under R3. + +Measurement instrument, `spec-1280-p6-delivery`, and `spec-1280-prompt-deletion-guard`: green. diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-7-templates-consult-spir.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-7-templates-consult-spir.md new file mode 100644 index 000000000..74d0ff441 --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-7-templates-consult-spir.md @@ -0,0 +1,39 @@ +# Phase 7 — remaining templates + spir consult-types (G4, G5) + +**Decisions**: 10 (5 templates, 5 spir consult-types) · **Rollback groups**: G4 (templates), G5 (consult-types) — **two group-pure commits**, plus the R4 retirement + replacement (two more, mirroring R1–R3). +**Batches**: 2 — (1) templates, 5 decisions; (2) spir consult-types, 5 decisions. + +**Levers**: **P2** (annotated-example filler → heading interfaces) for the templates; **P1/P2** for the consult-types, plus **P6** on `spec-review.md` (see below). **Old/New are word counts** (no `{{> }}` includes in these files). + +**Capabilities preserved**: the `VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]` block in all five consult-types (`consult` parses it — kept exactly, `pr-review` keeps its `PR_SUMMARY` extension); the `maintenance-run.md` delivery-checked headings (`# Maintenance Run NNNN`, `## Audit Findings`, `### Dependencies Cleaned`); the experiment/spike `{{> }}` include wiring (untouched in the protocol.md files); and the #742 divergence (spir pr/impl-review stay distinct from the BUGFIX versions). + +## Batch 1 — templates (G4, 5 decisions) + +| File | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/experiment/templates/notes.md` | 312 | 167 | P2 | Example-laden placeholders (a literal `python experiment.py …`, fabricated metrics) → a clean heading interface. Kept the include wiring from `experiment/protocol.md`. | +| `{codev,codev-skeleton}/protocols/spike/templates/findings.md` | 265 | 169 | P2 | Light P2 — kept the **Verdict** line and the effort-sizing interface; trimmed placeholder verbosity. | +| `{codev,codev-skeleton}/protocols/maintain/templates/maintenance-run.md` | 184 | 175 | P2 | Already a lean heading interface; kept the three delivery-checked headings verbatim and only dropped the one filler example row from the Documentation Changes Log. | +| `codev/protocols/maintain/templates/audit-report.md` | 625 | 294 | P2 | Codev-local (no skeleton twin). Collapsed ~10 repetitive empty per-category tables into **one findings schema** + a category list; kept pre-audit checks, the summary reconciliation table, recommendation tiers, rollback notes, and approval. | +| `codev/protocols/maintain/templates/lessons-learned.md` | 78 | 78 | none | Codev-local (no skeleton twin). **Inspected, conformant, kept unchanged** — already a minimal category heading interface. | + +## Batch 2 — spir consult-types (G5, 5 decisions) + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/spir/consult-types/spec-review.md` | 514 | 386 | P1, P2, P6 | Rubric prose → lean focus-area contract. **Fixed a staleness bug (P6)**: the old Structure section hardcoded the 20-heading spec-template list, which Phase 6's spec.md rewrite made wrong — replaced with a reference to the delivered `protocols/spir/templates/spec.md`. Kept the `## Baked Decisions` section (canonical tokens) and the VERDICT block. Triggers R4 — see M10. | +| `{codev,codev-skeleton}/protocols/spir/consult-types/plan-review.md` | 406 | 322 | P1, P2 | Rubric → focus-area contract; kept the `## Baked Decisions` section and the VERDICT block. Triggers R4 — see M10. | +| `{codev,codev-skeleton}/protocols/spir/consult-types/impl-review.md` | 421 | 331 | P1 | "CRITICAL: Verify Before Flagging" → a verify-before-flagging contract; kept the SPIR-specific **Spec Adherence / Plan Alignment** focus areas and the **Scoping (Multi-Phase Plans)** section (which #742 requires stay absent from BUGFIX, i.e. present here) and the VERDICT block. | +| `{codev,codev-skeleton}/protocols/spir/consult-types/pr-review.md` | 392 | 316 | P1 | Kept the SPIR-specific completeness criteria (spec/plan/review trinity + `[Spec XXXX][Phase]` — the very things #742 keeps out of BUGFIX), the diff-syntax false-positive rule, and the VERDICT block **with its `PR_SUMMARY` extension**. | +| `{codev,codev-skeleton}/protocols/spir/consult-types/phase-review.md` | 421 | 331 | P1 | Byte-identical twin of impl-review.md (as before this phase) — same rewrite. | + +## M10 — one retirement (R4), CLASS PRE-APPROVED, executed + +Rewriting `spec-review.md` + `plan-review.md` to P1/P2 trips Spec 746's **Phase 3** `expectPureAdditionDiff` on those two spir consult-types (the first two PHASE_3 files; the aspir + air ones follow in Phases 8–9). This is covered by the **class pre-approval** (1280-retirements.md), so it executes without a per-item blocking gate — but honours all three invariants: (1) behaviour grep stays green (the `## Baked Decisions` sections keep `do not autonomously` / `COMMENT` / `REQUEST_CHANGES` / contradiction-handling); (2) the replacement guard ships in a mirrored separate commit (post-1280 baselines + inverted anti-vacuity in `spec-1280-prompt-deletion-guard.test.ts`); (3) this writeup + register entry R4 keep the audit trail. `impl/pr/phase-review` are not baked-decisions files — no retirement. The other PHASE_3 files (aspir spec/plan-review, air impl/pr-review) stay in force until their phase. + +## Guards held green (verified) + +- **VERDICT capability** — all five consult-types carry `VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]`. +- **bugfix-742** — spir pr/impl-review still differ from the BUGFIX versions. +- **template-delivery** — maintenance-run resolves with `# Maintenance Run NNNN` / `## Audit Findings` / `### Dependencies Cleaned`; the experiment/spike/maintain include wirings intact; audit-report + lessons-learned stay codev-local (twin-parity exempt). +- **baked-decisions** — every assertion green except the two retired under R4 (grep + mirror-parity for spec/plan-review still pass). diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-8-consult-types-a.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-8-consult-types-a.md new file mode 100644 index 000000000..b50891961 --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-8-consult-types-a.md @@ -0,0 +1,35 @@ +# Phase 8 — consult-types: aspir, bugfix, air (G5) + +**Decisions**: 9 (aspir ×5, air ×2, bugfix ×2) · **Rollback group**: G5 · **One rewrite commit**, plus the R6 retirement + replacement (two more, mirroring R1–R4). +**Batches**: 2 — (1) aspir, 5 decisions; (2) air + bugfix, 4 decisions. + +**Levers**: P1/P2. **Capabilities preserved**: the `VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]` block in all nine (kept exactly; air/pr keeps `PR_SUMMARY`, bugfix/pr keeps its `PR_SUMMARY`); the Baked Decisions sections (canonical tokens) in aspir spec/plan-review + air impl/pr-review; and the **#742 divergence** — bugfix impl/pr-review stay distinct from the SPIR versions, keep the BUGFIX-only markers (`Fix #`, `regression test`, `## Out of Scope`, `status.yaml`), and introduce none of the forbidden SPIR criteria (`**Spec Adherence**`, `**Plan Alignment**`, `## Scoping (Multi-Phase Plans)`). + +## Batch 1 — aspir consult-types (5 decisions) + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/aspir/consult-types/spec-review.md` | 514 | 386 | P1, P2, P6 | ASPIR mirrors SPIR's review criteria — these five were byte-identical to the pre-Phase-7 spir versions, so they take the **same rewrite** (copied from the new spir consult-types). Kept the `## Baked Decisions` section and VERDICT; carries the P6 stale-heading fix. Triggers R6 — see M10. | +| `{codev,codev-skeleton}/protocols/aspir/consult-types/plan-review.md` | 406 | 322 | P1, P2 | Same rewrite as spir plan-review; kept Baked Decisions + VERDICT. Triggers R6. | +| `{codev,codev-skeleton}/protocols/aspir/consult-types/impl-review.md` | 421 | 331 | P1 | Same rewrite as spir impl-review; kept the SPIR-specific Spec-Adherence/Scoping and VERDICT. | +| `{codev,codev-skeleton}/protocols/aspir/consult-types/pr-review.md` | 392 | 316 | P1 | Same rewrite as spir pr-review; kept the completeness criteria, diff-syntax rule, and VERDICT + `PR_SUMMARY`. | +| `{codev,codev-skeleton}/protocols/aspir/consult-types/phase-review.md` | 421 | 331 | P1 | Byte-identical twin of impl-review (as before) — same rewrite. | + +## Batch 2 — air + bugfix consult-types (4 decisions) + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/air/consult-types/impl-review.md` | 420 | 369 | P1 | "CRITICAL: Verify Before Flagging" → a verify-before-flagging contract; kept the AIR framing (issue not spec, escalate to ASPIR at >300 LOC), the `## Baked Decisions` section, and VERDICT. Triggers R6 — see M10. | +| `{codev,codev-skeleton}/protocols/air/consult-types/pr-review.md` | 455 | 380 | P1 | AIR framing (PR body is the review, no `codev/reviews/`), Baked Decisions, diff-syntax rule, VERDICT. Triggers R6. | +| `{codev,codev-skeleton}/protocols/bugfix/consult-types/impl-review.md` | 641 | 551 | P1 | Light touch on a #742-fragile file: decapped "CRITICAL", tightened the focus areas, and kept the **`## Out of Scope`** section and every #742 marker verbatim. Not a baked-decisions file — no retirement. | +| `{codev,codev-skeleton}/protocols/bugfix/consult-types/pr-review.md` | 726 | 574 | P1 | Same: tightened focus areas, kept `## Out of Scope`, the BUGFIX-only markers, and VERDICT + `PR_SUMMARY`. No retirement. | + +## M10 — one retirement (R6), CLASS PRE-APPROVED, executed + +Rewriting aspir spec/plan-review + air impl/pr-review trips Spec 746's **Phase 3** `expectPureAdditionDiff` on those four files. Covered by the class pre-approval (1280-retirements.md); executes without a per-item gate, honouring the three invariants — behaviour grep green (Baked Decisions sections kept), replacement guard in a mirrored commit, this writeup + register entry R6. **After R6, all six PHASE_3 baked-decisions pure-addition guards are retired** (spir under R4, aspir + air under R6); the loop keeps a documenting test so it re-activates for any future PHASE_3 file. bugfix impl/pr-review are not baked-decisions files — no retirement. + +## Guards held green (verified) + +- **VERDICT** — all nine consult-types carry the parse block. +- **#742** — bugfix impl/pr-review differ from the SPIR versions, keep the BUGFIX markers, and carry none of the forbidden SPIR criteria. +- **baked-decisions** — every assertion green except the four retired under R6 (grep + mirror-parity for the four still pass). diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-9-consult-registry-deadtree.md b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-9-consult-registry-deadtree.md new file mode 100644 index 000000000..28f73ef38 --- /dev/null +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/manifests/phase-9-consult-registry-deadtree.md @@ -0,0 +1,30 @@ +# Phase 9 — consult-types pir/maintain + scar registry + dead-tree deletion (G5, G7, G4) + +**Decisions**: 4 consult-types (G5) + the registry rebuild (G7) + the dead-tree deletion (G4) · **Three group-pure commits**. +**Batches**: 2 — (A) the 4 consult-type decisions; (B) registry + T4 + dead-tree deletion + routing-test update. + +## Batch A — pir + maintain consult-types (G5, 4 decisions) + +| File (both trees) | Old | New | Principles | Rationale | +|---|---:|---:|---|---| +| `{codev,codev-skeleton}/protocols/pir/consult-types/impl-review.md` | 507 | 413 | P1 | Decapped "CRITICAL", tightened to a contract; kept the PIR-specific focus areas (Plan Adherence, Review File Quality, dev-approval gate, PIR-specific UI/cross-platform concerns) and the VERDICT block. | +| `{codev,codev-skeleton}/protocols/pir/consult-types/pr-review.md` | 475 | 355 | P1 | Kept the PIR context (single-pass `max_iterations:1`, dev-approval already passed), the `Fixes #` linkage, the diff-syntax rule, and VERDICT. | +| `{codev,codev-skeleton}/protocols/maintain/consult-types/impl-review.md` | 421 | 331 | P1 | These mirrored the old spir generic review prompt, so they take the **same rewrite** as the new spir impl-review (copied). VERDICT kept. | +| `{codev,codev-skeleton}/protocols/maintain/consult-types/pr-review.md` | 392 | 316 | P1 | Same — mirrors the new spir pr-review (with its `PR_SUMMARY`). | + +Not baked-decisions files — **no retirement**. + +## Batch B — scar registry (G7) + dead-tree deletion (G4) + +| Item | What | Rationale | +|---|---|---| +| `codev/resources/scar-rules.yaml` (**new**, G7) | The 8 scar canonicals kept **byte-identical** to the Spec 1252 registry; `must_appear_on` **re-derived against the post-1280 surface**. | The P1/P4 rewrites removed the git-add prohibition from most prompts (`roles/builder.md` owns it now) and the dead tree is deleted, so the pre-rewrite lists were stale. Each list is exactly where its canonical appears today; all eight survive on CLAUDE.md + AGENTS.md. | +| `spec-1280-scar-rules.test.ts` (**new**, T4, G7) | Pins count=8 + the ids; enforces byte-identical carriage on every listed surface (rewording fails); checks the primary-surface guarantee. | Created in Phase 9 — the first phase where the surface has settled, so `must_appear_on` is meaningful. Mutation-verified: reword fails, delete fails. | +| `codev-skeleton/porch/prompts/` **deleted** (10 files, M6, G4) | The dead Ralph-SPIR-era prompt tree with no runtime consumer. | M6-verified by an untruncated repo-wide search: the only `porch/prompts` references are the unrelated code module `porch/prompts.ts`, historical project docs, and the measurement DEAD bucket (now 0). | +| `review-prompt-routing.test.ts` **updated** (M10, Spec 987, G4) | Removed the routing check on the deleted `codev-skeleton/porch/prompts/review.md`. | Consequence of the M6 deletion. The live review prompts/templates remain routing-checked; measurement instrument T1 still passes (it asserts on the script text, not the tree's existence). | + +## Guards held green (verified) + +- **T4** — 8 rules, byte-identical carriage; reword + delete mutations fire. +- **VERDICT** — all four consult-types carry the parse block. +- **review-prompt-routing** + **measurement instrument** — green after the dead-tree deletion. diff --git a/codev/projects/1280-prompt-surface-judgment-not-ru/status.yaml b/codev/projects/1280-prompt-surface-judgment-not-ru/status.yaml index ad3bbf00a..ae5d4ea34 100644 --- a/codev/projects/1280-prompt-surface-judgment-not-ru/status.yaml +++ b/codev/projects/1280-prompt-surface-judgment-not-ru/status.yaml @@ -5,38 +5,38 @@ phase: implement plan_phases: - id: phase_0_instrument title: Corrected instrument + frozen capability inventory (PR-1, ships early) - status: in_progress + status: complete - id: phase_1_shared_skills title: CLAUDE.md/AGENTS.md + four-tree skill relocation (G2) - status: pending + status: complete - id: phase_2_roles title: Three role files (G6, G3, G5) - status: pending + status: complete - id: phase_3_protocol_md title: protocol.md x10 with the P6 include mechanism (G3) - status: pending + status: complete - id: phase_4_builder_prompts title: builder-prompt.md x9 + M10 test-retirement burden (G3) - status: pending + status: complete - id: phase_5_prompts_heavy title: 'Phase prompts: spir, aspir, pir (G4)' - status: pending + status: complete - id: phase_6_prompts_light_spir_templates title: 'Phase prompts: bugfix, air, maintain + spir templates (G4)' - status: pending + status: complete - id: phase_7_templates_consult_spir title: Remaining templates + spir consult-types (G4, G5) - status: pending + status: complete - id: phase_8_consult_types_a title: 'Consult-types: aspir, bugfix, air (G5)' - status: pending + status: complete - id: phase_9_consult_registry_deadtree title: Consult-types pir/maintain + scar registry + dead-tree deletion (G5, G7, G4) - status: pending + status: complete - id: phase_10_integration title: Capability verification, measurement report, rollback rehearsal, governance docs - status: pending -current_plan_phase: phase_0_instrument + status: in_progress +current_plan_phase: phase_10_integration gates: spec-approval: status: approved @@ -47,16 +47,18 @@ gates: requested_at: '2026-08-01T04:00:12.126Z' approved_at: '2026-08-01T04:26:10.219Z' pr: - status: pending + status: approved + approved_at: '2026-08-06T20:36:07.661Z' verify-approval: status: pending iteration: 1 build_complete: false history: [] started_at: '2026-08-01T02:46:36.457Z' -updated_at: '2026-08-01T04:39:51.924Z' +updated_at: '2026-08-06T20:36:07.662Z' pr_history: - phase: implement pr_number: 1319 branch: builder/1280-instrument created_at: '2026-08-01T04:39:51.923Z' +pr_ready_for_human: false diff --git a/codev/protocols/air/builder-prompt.md b/codev/protocols/air/builder-prompt.md index f17ab40ad..d2da0d02e 100644 --- a/codev/protocols/air/builder-prompt.md +++ b/codev/protocols/air/builder-prompt.md @@ -4,33 +4,33 @@ You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the AIR protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Consultation is optional — use your judgement based on complexity -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the AIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. ## Baked Decisions -If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review. +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. -If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding. +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. {{#if issue}} ## Issue #{{issue.number}} @@ -38,44 +38,25 @@ If the architect's baked-decisions section contains internal contradictions (e.g **Description**: {{issue.body}} +{{/if}} ## Your Mission -1. Read the issue requirements carefully -2. Implement the feature (< 300 LOC) -3. Write tests for the feature -4. Create PR with review in the PR body (NOT as a separate file) -5. Notify architect via `afx send architect "PR #N ready for review (implements #{{issue.number}})"` -**IMPORTANT**: AIR produces NO spec, plan, or review files. The review goes in the PR body. +1. Implement the feature from the issue (<300 LOC) +2. Write tests for it +3. Open a PR with the review **in the PR body**, not as a separate file +4. Notify: `afx send architect "PR #N ready for review (implements #{{issue.number}})"` + +**AIR produces no spec, plan, or review files.** That is the whole economy of the protocol. + +If the feature turns out larger than AIR fits (>300 LOC, or an architectural decision the issue +does not make), stop and say so rather than growing it quietly: -If the feature is too complex (> 300 LOC or architectural changes), notify the Architect via: ```bash afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR." ``` ## Notifications -Always use `afx send architect "..."` to notify the architect at key moments: -- **PR ready**: `afx send architect "PR #N ready for review (implements #{{issue.number}})"` -- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."` -- **Blocked**: `afx send architect "Blocked on issue #{{issue.number}}: [reason]"` -{{/if}} - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in the PR body under a "Flaky Tests" section -5. Commit the skip and continue with your work - -## Getting Started -1. Read the AIR protocol -2. Review the issue details -3. Implement the feature - ---- - -## Protocol Reference (full text) -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/air/consult-types/impl-review.md b/codev/protocols/air/consult-types/impl-review.md index b382faedc..16abb9863 100644 --- a/codev/protocols/air/consult-types/impl-review.md +++ b/codev/protocols/air/consult-types/impl-review.md @@ -1,43 +1,32 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work for a small feature built under the AIR protocol. The builder implemented directly from a GitHub issue — there is no spec or plan document. Your job is to verify the implementation matches the issue requirements and follows good practices. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work built under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec or plan document. Verify it matches the issue and follows good practice; review against the issue, not against artifacts AIR does not produce. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files +## Verify before flagging + +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: + +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. ## Baked Decisions If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the implementation **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Issue Adherence** - - Does the implementation fulfill the issue requirements? - - Are the described acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? - -3. **Test Coverage** - - Are the tests adequate? - - Do tests cover the main paths AND edge cases? - -4. **Scope** - - Is the change under 300 LOC? If not, should this be escalated to ASPIR? - - Does the implementation stay focused on the issue, or does it include unrelated changes? +- **Issue Adherence** — the implementation fulfills the issue's requirements and acceptance criteria. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate and cover main paths and edge cases. +- **Scope** — the change stays focused on the issue and under ~300 LOC; if larger, it should escalate to ASPIR. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -51,14 +40,8 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Implementation looks good, ready for PR -- `REQUEST_CHANGES`: Issues that must be fixed -- `COMMENT`: Minor suggestions, can proceed but note feedback - -## Notes +- `APPROVE`: implementation looks good, ready for PR. +- `REQUEST_CHANGES`: issues that must be fixed. +- `COMMENT`: minor suggestions; can proceed but note the feedback. -- AIR has no spec or plan — review against the GitHub issue -- Focus on "does this feature work correctly" not "is this architecturally perfect" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback +AIR has no spec or plan — review against the GitHub issue, and judge "does this feature work correctly", not "is this architecturally perfect". diff --git a/codev/protocols/air/consult-types/pr-review.md b/codev/protocols/air/consult-types/pr-review.md index 0d7856f3a..dd8de96ad 100644 --- a/codev/protocols/air/consult-types/pr-review.md +++ b/codev/protocols/air/consult-types/pr-review.md @@ -1,48 +1,30 @@ # PR Ready Review Prompt ## Context -You are performing a review of a pull request created under the AIR protocol. The builder implemented a small feature directly from a GitHub issue — there are no spec, plan, or review files. The review is embedded in the PR body. + +You are reviewing a pull request created under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec, plan, or review file. The review is embedded in the PR body. ## Baked Decisions If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the code **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Completeness** - - Are the issue requirements implemented? - - Is the PR body review section filled out (summary, key decisions, test plan)? - - Are commits properly formatted? - -2. **Test Status** - - Do all tests pass? - - Is test coverage adequate for the changes? - - Are there any skipped or flaky tests? - -3. **Code Cleanliness** - - Is there any debug code left in? - - Are there any TODO comments that should be resolved? - - Is the code properly formatted? - -4. **Scope** - - Is the change under 300 LOC? - - Does the implementation stay focused on the issue? - - Are there unrelated changes bundled in? - -5. **PR Quality** - - Does the PR link to the issue? - - Is the PR body review section informative? - - Is the branch up to date with its base (the integration branch the PR targets)? +- **Completeness** — the issue's requirements are implemented and the PR body's review section (summary, key decisions, test plan) is filled out. +- **Test Status** — all tests pass, coverage is adequate, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO`, code properly formatted. +- **Scope** — the change stays under ~300 LOC and focused on the issue, with no unrelated changes bundled in. +- **PR Quality** — the PR links to the issue, the body's review section is informative, and the branch is up to date with its base (the integration branch the PR targets). ## Scope -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -56,13 +38,8 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Ready for architect review -- `REQUEST_CHANGES`: Issues to fix before review -- `COMMENT`: Minor items, can proceed but note feedback - -## Notes +- `APPROVE`: ready for architect review. +- `REQUEST_CHANGES`: issues to fix before review. +- `COMMENT`: minor items; can proceed but note the feedback. -- AIR has no spec, plan, or review files — review the PR body and code diff -- Focus on "is this ready for someone else to review" not "is this perfect" -- Any issues found here are cheaper to fix than during integration review +AIR has no spec, plan, or review files — review the PR body and the code diff. diff --git a/codev/protocols/air/prompts/implement.md b/codev/protocols/air/prompts/implement.md index 301641962..d8cfaaebb 100644 --- a/codev/protocols/air/prompts/implement.md +++ b/codev/protocols/air/prompts/implement.md @@ -2,9 +2,9 @@ You are executing the **IMPLEMENT** phase of the AIR protocol. -## Your Goal +## Goal -Read the GitHub issue, implement the feature, and add tests. Keep it focused and under 300 LOC. +Implement the feature described in the issue, with tests, as a focused change under ~300 LOC. AIR produces no `codev/specs/` or `codev/plans/` artifacts. ## Baked Decisions @@ -17,79 +17,26 @@ If two baked decisions contradict each other, do not pick one — pause, flag th - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## What must be true when you finish -### 1. Read the Issue +- **The feature matches the issue.** You have read it fully — desired behavior, acceptance criteria, any examples — and implemented exactly what it describes: no refactoring of surrounding code, no features beyond the issue, no unrelated bug fixes (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions. +- **Tests exist.** They cover the happy path and the key edge cases, and are deterministic. (Purely declarative changes — config only — may not need them; say so.) +- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling. +- **The change stays within AIR scope.** If it grows past ~300 LOC or turns architectural, signal `TOO_COMPLEX` rather than pressing on. -Read the full issue description. Identify: -- What is the desired behavior? -- What are the acceptance criteria? -- Are there examples or mockups? -- What files/modules are likely affected? - -### 2. Implement the Feature - -Apply a focused implementation: -- Implement what the issue describes — no more, no less -- Do NOT refactor surrounding code -- Do NOT add features beyond what's described in the issue -- Do NOT fix unrelated bugs you happen to notice (file separate issues) - -**Code Quality**: -- Self-documenting code (clear names, obvious structure) -- No commented-out code or debug prints -- Follow existing project conventions - -### 3. Add Tests - -Write tests that: -- Cover the main happy path -- Cover key edge cases -- Are deterministic (not flaky) - -Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.). - -### 4. Verify the Build - -Run build and tests: - -```bash -npm run build # Must pass -npm test # Must pass -``` - -Fix any failures before proceeding. If build/test commands don't exist, check `package.json`. - -### 5. Commit - -Stage and commit your changes: -- Use explicit file paths (never `git add -A` or `git add .`) -- Commit message: `[Air #{{issue.number}}] feat: ` +Commit with an explicit staged path and the message `[Air #{{issue.number}}] feat: `. ## Signals -When implementation and tests are complete and passing: - -``` -PHASE_COMPLETE -``` - -If the feature is too complex for AIR (> 300 LOC or architectural): - -``` -TOO_COMPLEX -``` - -If you're blocked (missing context, unclear requirements, etc.): - -``` -BLOCKED:reason goes here -``` - -## Important Notes - -1. **Stay focused** — Implement what the issue describes, nothing else -2. **Tests are expected** — Add tests unless the change is purely declarative (e.g., config only) -3. **Build AND tests must pass** — Don't signal complete until both pass -4. **Stay under 300 LOC** — If the feature grows beyond this, signal `TOO_COMPLEX` -5. **No spec/plan artifacts** — AIR does not create files in `codev/specs/` or `codev/plans/` +- Implementation and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Too complex for AIR (> ~300 LOC or architectural): + ``` + TOO_COMPLEX + ``` +- Blocked (missing context, unclear requirements): + ``` + BLOCKED:reason goes here + ``` diff --git a/codev/protocols/air/prompts/pr.md b/codev/protocols/air/prompts/pr.md index 5e3439943..f9e4f7abe 100644 --- a/codev/protocols/air/prompts/pr.md +++ b/codev/protocols/air/prompts/pr.md @@ -2,32 +2,20 @@ You are executing the **PR** phase of the AIR protocol. -## Your Goal +## Goal -Create a pull request with the review embedded in the PR body, optionally run CMAP, and notify the architect. +Open the PR with the review embedded in its body, optionally run CMAP, and notify the architect. ## Context - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## Create the PR -### 1. Create the Pull Request +**The PR body IS the review for AIR** — do not create a file in `codev/reviews/`. Include a summary, the key decisions, and a test plan in the body itself. -Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan. - -**PR body requirements**: The PR body MUST include `Closes #` (where `` is -the driving issue number) so GitHub auto-closes the issue on merge. If the PR -closes multiple issues (e.g. duplicates consolidated), include one `Closes #` -per issue. Without this, GitHub will not auto-close the issue. - -**Exception**: if this PR only partially addresses the issue, use `Refs #` -or `Part of #` instead of `Closes` — the issue stays open until a -follow-up PR closes it. - -**Note**: substitute the real issue number for `` — do not leave the -placeholder or any `{{...}}` template tag in the committed PR body. +The body must carry `Closes #` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a partial fix uses `Refs #` or `Part of #` instead. Substitute the real number for ``; leave no `{{...}}` tag or `` placeholder in the committed body. ```bash gh pr create --title "[Air #] feat: " --body "$(cat <<'EOF' @@ -35,15 +23,15 @@ gh pr create --title "[Air #] feat: " --body "$(cat <<'EOF <1-2 sentence description of the feature> -Closes # +Closes # ## What Changed - + ## Key Decisions - + ## Test Plan @@ -53,16 +41,14 @@ Closes # ## Review Notes - + EOF )" ``` -**IMPORTANT**: Do NOT create a review file in `codev/reviews/`. The PR body IS the review for AIR. +## Optional CMAP review -### 2. Optional CMAP Review - -If the implementation is non-trivial, run 3-way consultation: +CMAP is your judgement call for AIR. Skip it for simple changes (config, small UI); run it for features touching core logic or several modules: ```bash consult -m gemini --protocol air --type pr & @@ -70,41 +56,23 @@ consult -m codex --protocol air --type pr & consult -m claude --protocol air --type pr & ``` -All three should run in the background (`run_in_background: true`). - -**This is optional** — use your judgement. For simple features (config changes, small UI additions), you may skip consultation. For features touching core logic or multiple modules, run it. +If you run it, wait for all three, record each verdict, fix real issues, and push. -### 3. Address Feedback (if CMAP was run) - -If you ran CMAP: -- Wait for all consultations to complete -- Record each model's verdict -- Fix any issues identified -- Push updates to the PR branch - -### 4. Notify Architect - -Send notification with PR link: +## Notify the architect ```bash afx send architect "PR # ready for review (implements issue #{{issue.number}})" ``` -If CMAP was run, include verdicts: -```bash -afx send architect "PR # ready for review (implements issue #{{issue.number}}). CMAP: gemini=, codex=, claude=" -``` +If you ran CMAP, include the verdicts: `CMAP: gemini=, codex=, claude=`. ## Signals -When PR is created and ready for review: - -``` -PHASE_COMPLETE -``` - -If you're blocked: - -``` -BLOCKED:reason goes here -``` +- PR created and ready for review: + ``` + PHASE_COMPLETE + ``` +- Blocked: + ``` + BLOCKED:reason goes here + ``` diff --git a/codev/protocols/air/protocol.md b/codev/protocols/air/protocol.md index 74609fd29..7386b6b2e 100644 --- a/codev/protocols/air/protocol.md +++ b/codev/protocols/air/protocol.md @@ -1,91 +1,60 @@ # AIR Protocol -> **AIR** = **A**utonomous **I**mplement & **R**eview -> -> A lightweight protocol for small features that are fully specified by their GitHub issue. -> Two phases: Implement → Review. No spec/plan artifacts. +**A**utonomous **I**mplement → **R**eview. The lightest protocol that still produces a reviewed +PR: no spec, no plan, no artifact files. The GitHub issue *is* the specification, and the review +lives in the PR body. -## What is AIR? +Use AIR when a small feature (roughly <300 LOC) is fully described by its issue and needs no +architectural decision, no new abstraction, and no significant refactor. If the issue leaves the +approach genuinely open, the cost of a spec is lower than the cost of building the wrong thing — +use SPIR or ASPIR. For a defect rather than a feature, use BUGFIX. -AIR is a minimal protocol for implementing small features (< 300 LOC) where the GitHub issue provides all the requirements. It skips the Specify and Plan phases entirely — the builder implements directly from the issue and creates a PR with the review embedded in the PR body. +## The state machine -### How AIR Compares - -| Aspect | BUGFIX | AIR | ASPIR/SPIR | -|--------|--------|-----|------------| -| **Use case** | Bug fixes | Small features | New features | -| **Input** | GitHub Issue | GitHub Issue | GitHub Issue → Spec | -| **Phases** | Investigate → Fix → PR | Implement → PR | Specify → Plan → Implement → Review | -| **Artifacts** | None | None | Spec, plan, review files | -| **Review location** | PR body | PR body | `codev/reviews/` file | -| **Consultation** | PR phase only | Optional (builder decides) | Every phase (3-way) | -| **Human gates** | None (PR gate) | None (PR gate) | Spec + Plan + PR gates (SPIR) | -| **LOC limit** | < 300 | < 300 | No limit | - -### When to Use AIR - -- Small features (< 300 LOC) -- Requirements are clear from the GitHub issue -- No architectural decisions needed -- No new abstractions or significant refactoring required -- Would be overkill for full SPIR/ASPIR ceremony - -### When NOT to Use AIR - -- Bug fixes → use **BUGFIX** -- Features needing spec discussion → use **SPIR** or **ASPIR** -- Architectural changes → use **SPIR** -- Complex features with multiple phases → use **SPIR** or **ASPIR** - -## Baked Decisions (Optional) +```json +{{> protocols/air/protocol.json}} +``` -When filing an issue for AIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will treat each listed item as fixed during implementation; CMAP reviewers will not propose alternatives unless the implementation itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`. +## Artifacts -## Protocol Phases +**None on disk.** The issue carries the requirements; the review goes in the PR body. That is +the whole economy of AIR — a `codev/reviews/` file for a 200-line change costs more to maintain +than it ever repays. -### I - Implement +## Consultation -The builder reads the GitHub issue and implements the feature: +At the builder's discretion, unlike SPIR's mandatory 3-way at every phase. Reach for it when the +change touches shared code or you are unsure the approach is right; skip it when the issue is +unambiguous and the diff is small. -1. Read and understand the issue requirements -2. Implement the feature (< 300 LOC) -3. Write tests -4. Verify build and tests pass -5. Commit with descriptive message +## Gate -If the feature grows beyond 300 LOC or requires architectural decisions, the builder signals `TOO_COMPLEX` to escalate to ASPIR. +The `pr` gate is human. There are no pre-implementation gates — which is precisely why AIR is +only appropriate when the issue has already settled the questions a spec would ask. -### R - Review (PR) +## Baked Decisions -The builder creates a PR with the review embedded in the PR body: +An issue may carry a `## Baked Decisions` section pinning architectural choices the architect +does not want re-litigated — typically **language**, **framework**, deployment shape, key +**dependencies**, or decisions deferred to a later spec. -1. Create PR linking to the issue -2. Include a review section in the PR body (summary, key decisions, test plan) -3. Optionally run CMAP consultation if the builder judges the complexity warrants it -4. Notify the architect +Every item in it is fixed. Copy the section verbatim into the spec's Constraints and do not +re-open it in the spec, plan, or review; CMAP reviewers will not propose alternatives unless the +spec fails to honour one. If two items contradict each other, do not choose — surface the +contradiction and wait. -The **PR gate** is preserved — a human reviews all code before merge. +**Absence is the no-op default**: an issue with no such section is an invitation to explore +freely, not an omission to be filled in. -## Usage +The architect can **amend or rescind** a baked decision at any time by updating the issue and +respawning, or by sending the builder a direct instruction via `afx send`. -```bash -# Spawn a builder using AIR -afx spawn 42 --protocol air +## Escalation -# The builder implements autonomously and stops at the PR gate -``` +If implementation reveals that the change is not small, or that it needs a decision the issue +does not make, **stop and say so** rather than growing an AIR project into an unplanned SPIR. +Escalating early is cheap; discovering it at PR review is not. -## File Structure +## Branch naming -``` -codev-skeleton/protocols/air/ -├── protocol.json # Protocol definition -├── protocol.md # This file -├── builder-prompt.md # Builder instructions (Handlebars template) -├── prompts/ -│ ├── implement.md # Implement phase prompt -│ └── pr.md # PR phase prompt -└── consult-types/ - ├── impl-review.md # Implementation consultation guide - └── pr-review.md # PR consultation guide -``` +`builder/air--` diff --git a/codev/protocols/aspir/builder-prompt.md b/codev/protocols/aspir/builder-prompt.md index d303da59e..e43e55121 100644 --- a/codev/protocols/aspir/builder-prompt.md +++ b/codev/protocols/aspir/builder-prompt.md @@ -4,36 +4,33 @@ You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the protocol document yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Run consultations manually when the protocol calls for them -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals -- Do not deviate from the porch-driven workflow - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way review** — always follow porch next → porch done cycle -- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the ASPIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +Follow the ASPIR protocol. The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. ## Baked Decisions -If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review. +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. -If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding. +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. {{#if spec}} ## Spec @@ -53,37 +50,25 @@ Follow the implementation plan at: `{{plan.path}}` {{issue.body}} {{/if}} -{{#if task}} -## Task -{{task_text}} -{{/if}} - ## PR Strategy -**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs. - -By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch. - -### Architect-requested PRs - -The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request. +**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits +within a single PR, not as separate PRs. The plan's instruction that "each phase commits +independently" refers to git commits, not PRs. -### Multi-PR Mechanics (when the architect requests sequential PRs) +By default, the PR is opened during/after the final implement phase, with all phase-commits +already on the branch. -Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop: +The architect MAY request a PR at any point — follow that direction when they do; the +prohibition is on *you* deciding to open per-phase PRs unasked. -1. Cut a branch, open a PR, wait for merge -2. After merge: `git fetch origin && git checkout -b origin/` — where `` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure) -3. Continue to the next slice, open another PR - -**Important**: Do NOT run `git checkout ` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/` via fetch. - -Record PRs: `porch done {{project_id}} --pr --branch ` -Record merges: `porch done {{project_id}} --merged ` +Record them: `porch done {{project_id}} --pr --branch `, and +`porch done {{project_id}} --merged `. ## Verify Phase -After the final PR merges, the project enters the **verify** phase. You stay alive through verify: +After the final PR merges the project enters **verify**, and you stay alive through it: + 1. Pull the integration branch into your worktree 2. Run `porch done {{project_id}}` to signal verification is ready 3. The architect approves `verify-approval` when satisfied @@ -91,28 +76,6 @@ After the final PR merges, the project enters the **verify** phase. You stay ali If verification is not needed: `porch verify {{project_id}} --skip "reason"` ## Notifications -Always use `afx send architect "..."` to notify the architect at key moments: -- **Gate reached**: `afx send architect "Project {{project_id}}: ready for approval"` -- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"` -- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."` -- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"` - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue with your work - -## Getting Started -1. Read the protocol document thoroughly -2. Review the spec and plan (if available) -3. Begin implementation following the protocol phases - ---- - -## Protocol Reference (full text) -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/aspir/consult-types/impl-review.md b/codev/protocols/aspir/consult-types/impl-review.md index de01b8d00..7028b4947 100644 --- a/codev/protocols/aspir/consult-types/impl-review.md +++ b/codev/protocols/aspir/consult-types/impl-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev/protocols/aspir/consult-types/phase-review.md b/codev/protocols/aspir/consult-types/phase-review.md index de01b8d00..7028b4947 100644 --- a/codev/protocols/aspir/consult-types/phase-review.md +++ b/codev/protocols/aspir/consult-types/phase-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev/protocols/aspir/consult-types/plan-review.md b/codev/protocols/aspir/consult-types/plan-review.md index 485ff3183..b278aa4ea 100644 --- a/codev/protocols/aspir/consult-types/plan-review.md +++ b/codev/protocols/aspir/consult-types/plan-review.md @@ -1,44 +1,28 @@ # Plan Review Prompt ## Context -You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it. + +You are reviewing an implementation plan during the Plan phase. The spec is already approved; judge whether the plan adequately describes HOW to implement it. ## Baked Decisions -If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. +If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Spec Coverage** - - Does the plan address all requirements in the spec? - - Are there spec requirements not covered by any phase? - - Are there phases that go beyond the spec scope? - -2. **Phase Breakdown** - - Are phases appropriately sized (not too large or too small)? - - Is the sequence logical (dependencies respected)? - - Can each phase be completed and committed independently? - -3. **Technical Approach** - - Is the implementation approach sound? - - Are the right files/modules being modified? - - Are there obvious better approaches being missed? +- **Spec coverage** — every spec requirement is addressed by some phase; nothing goes beyond the spec's scope. +- **Phase breakdown** — phases are appropriately sized, logically sequenced (dependencies respected), and each can be completed and committed independently. +- **Technical approach** — the approach is sound, the right files/modules are targeted, and no obviously better approach is being missed. +- **Testability** — each phase has clear test criteria and the spec's edge cases are addressable. +- **Risk** — blockers and cross-system dependencies are identified; the plan is realistic given the constraints. -4. **Testability** - - Does each phase have clear test criteria? - - Will the Defend step (writing tests) be feasible? - - Are edge cases from the spec addressable? - -5. **Risk Assessment** - - Are there potential blockers not addressed? - - Are dependencies on other systems identified? - - Is the plan realistic given constraints? +The spec is already approved — do not re-litigate spec decisions. Judge the plan as a guide a builder can follow successfully; verify referenced file paths look accurate. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -52,14 +36,6 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Plan is ready for human review -- `REQUEST_CHANGES`: Significant issues with approach or coverage -- `COMMENT`: Minor suggestions, plan is workable but could improve - -## Notes - -- The spec has already been approved - don't re-litigate spec decisions -- Focus on the quality of the plan as a guide for builders -- Consider: Would a builder be able to follow this plan successfully? -- If referencing existing code, verify file paths seem accurate +- `APPROVE`: plan is ready for human review. +- `REQUEST_CHANGES`: significant issues with approach or coverage. +- `COMMENT`: minor suggestions; the plan is workable but could improve. diff --git a/codev/protocols/aspir/consult-types/pr-review.md b/codev/protocols/aspir/consult-types/pr-review.md index 837cdea33..6b9a3e82a 100644 --- a/codev/protocols/aspir/consult-types/pr-review.md +++ b/codev/protocols/aspir/consult-types/pr-review.md @@ -1,44 +1,24 @@ # PR Ready Review Prompt ## Context -You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. -## Focus Areas - -1. **Completeness** - - Are all spec requirements implemented? - - Are all plan phases complete? - - Is the review document written (`codev/reviews/XXXX-name.md`)? - - Are all commits properly formatted (`[Spec XXXX][Phase]`)? - -2. **Test Status** - - Do all tests pass? - - Is test coverage adequate for the changes? - - Are there any skipped or flaky tests? +You are performing the final self-check during the Review phase — the builder has completed all implementation phases and is about to open the PR. This is the last check before the work goes to the architect for integration review. -3. **Code Cleanliness** - - Is there any debug code left in? - - Are there any TODO comments that should be resolved? - - Are there any `// REVIEW:` comments that weren't addressed? - - Is the code properly formatted? - -4. **Documentation** - - Are inline comments clear where needed? - - Is the review document comprehensive? - - Are any new APIs documented? +## Focus Areas -5. **PR Readiness** - - Is the branch up to date with its base (the integration branch the PR targets)? - - Are commits atomic and well-described? - - Is the change diff reasonable in size? +- **Completeness** — all spec requirements implemented, all plan phases complete, the review document written (`codev/reviews/XXXX-name.md`), and commits in the `[Spec XXXX][Phase]` format. +- **Test Status** — all tests pass, coverage is adequate for the changes, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO` / `// REVIEW:` left unaddressed, code properly formatted. +- **Documentation** — inline comments clear where needed, the review document comprehensive, new APIs documented. +- **PR Readiness** — the branch is up to date with its base (the integration branch the PR targets), commits are atomic and well-described, and the diff size is reasonable. ## Scope -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -63,14 +43,8 @@ PR_SUMMARY: | - [How to test] ``` -**Verdict meanings:** -- `APPROVE`: Ready to create PR -- `REQUEST_CHANGES`: Issues to fix before PR creation -- `COMMENT`: Minor items, can create PR but note feedback - -## Notes +- `APPROVE`: ready to create the PR. +- `REQUEST_CHANGES`: issues to fix before PR creation. +- `COMMENT`: minor items; can create the PR but note the feedback. -- This is the builder's final self-review before hand-off -- The PR_SUMMARY in your output can be used as the PR description -- Focus on "is this ready for someone else to review" not "is this perfect" -- Any issues found here are cheaper to fix than during integration review +The `PR_SUMMARY` block can be used directly as the PR description. diff --git a/codev/protocols/aspir/consult-types/spec-review.md b/codev/protocols/aspir/consult-types/spec-review.md index 73e346e00..48f0c495b 100644 --- a/codev/protocols/aspir/consult-types/spec-review.md +++ b/codev/protocols/aspir/consult-types/spec-review.md @@ -1,46 +1,28 @@ # Specification Review Prompt ## Context -You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval. + +You are reviewing a feature specification during the Specify phase, before it goes to human approval. Judge whether the spec is complete, correct, feasible, and clear enough for a builder to plan from. ## Baked Decisions If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Completeness** - - Are all requirements clearly stated? - - Are success criteria defined? - - Are edge cases considered? - - Is scope well-bounded (not too broad or vague)? - -2. **Correctness** - - Do requirements make sense technically? - - Are there contradictions? - - Is the problem statement accurate? - -3. **Feasibility** - - Can this be implemented with available tools/constraints? - - Are there obvious technical blockers? - - Is the scope realistic for a single spec? +- **Completeness** — requirements, success criteria, and edge cases are stated; scope is bounded, not vague. +- **Correctness** — the requirements are technically sound and internally consistent; the problem statement is accurate. +- **Feasibility** — implementable within the stated tools and constraints, with no obvious blockers. +- **Clarity** — a builder would know what to build; acceptance criteria are testable; terminology is consistent. +- **Structure** — the spec follows the delivered template (`protocols/spir/templates/spec.md`), which the specify prompt inlines. A spec that ignores the template's headings — usually because the builder pattern-matched an older spec in `codev/specs/` — is a defect: `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). A single genuinely-inapplicable section reduced to a one-line "N/A — [reason]" with its heading kept is fine, not grounds for `REQUEST_CHANGES`. -4. **Clarity** - - Would a builder understand what to build? - - Are acceptance criteria testable? - - Is terminology consistent? - -5. **Structure** - - The specify prompt delivers a canonical spec template (`protocols/spir/templates/spec.md`) inline. Does the spec actually follow it? - - Required headings, in order: `## Metadata`, `## Clarifying Questions Asked`, `## Problem Statement`, `## Current State`, `## Desired State`, `## Stakeholders`, `## Success Criteria`, `## Constraints`, `## Assumptions`, `## Solution Approaches`, `## Open Questions`, `## Performance Requirements`, `## Security Considerations`, `## Test Scenarios`, `## Dependencies`, `## References`, `## Risks and Mitigation`, `## Expert Consultation`, `## Approval`, `## Notes`. - - A free-form spec that reads well but ignores the template is a **defect**, not a style preference — it usually means the builder pattern-matched an older spec in `codev/specs/` instead of the delivered template. `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). - - A section that genuinely does not apply may be reduced to a one-line "N/A — [reason]", but the heading should remain. Do not `REQUEST_CHANGES` over one such section. +You are reviewing the specification (WHAT is built), not code or implementation (HOW) — that is the plan and implementation reviews. Be constructive: name the issue and suggest a fix. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -54,14 +36,6 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Spec is ready for human review -- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but consider feedback - -## Notes - -- You are NOT reviewing code - you are reviewing the specification document -- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review) -- Be constructive - identify issues AND suggest solutions -- If the spec references other specs, note if context seems missing +- `APPROVE`: spec is ready for human review. +- `REQUEST_CHANGES`: significant issues must be fixed first. +- `COMMENT`: minor suggestions; can proceed but consider the feedback. diff --git a/codev/protocols/aspir/prompts/implement.md b/codev/protocols/aspir/prompts/implement.md index bacc8502e..1dfb7e6eb 100644 --- a/codev/protocols/aspir/prompts/implement.md +++ b/codev/protocols/aspir/prompts/implement.md @@ -1,10 +1,10 @@ # IMPLEMENT Phase Prompt -You are executing the **IMPLEMENT** phase of the SPIR protocol. +You are executing the **IMPLEMENT** phase of the ASPIR protocol. -## Your Goal +## Goal -Write clean, well-structured code AND tests that implement the current plan phase. +Implement the current plan phase — code and tests — so it matches the spec and passes build and tests. ## Context @@ -13,203 +13,34 @@ Write clean, well-structured code AND tests that implement the current plan phas - **Current State**: {{current_state}} - **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}} -## ⚠️ SCOPE RESTRICTION — READ THIS FIRST +## Scope: this phase only -**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).** +Your scope is exactly `{{plan_phase_id}}` ({{plan_phase_title}}), whose details are included below under "Current Plan Phase Details". Other phases are handled in later porch iterations — do not implement them, and do not read the full plan and build everything you see. Read `codev/specs/{{project_id}}-*.md` for requirements, but implement only what this phase requires. -- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations. -- **DO NOT** read the full plan file and implement everything you see. -- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope. -- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires. +When you signal `PHASE_COMPLETE`, porch runs the 3-way consultation, checks that tests exist and pass, and either respawns you with feedback or commits and moves to the next phase. -## What Happens After You Finish +## What must be true when you finish -When you signal `PHASE_COMPLETE`, porch will: -1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation -2. Check that tests exist and pass -3. If reviewers request changes, you'll be respawned with their feedback -4. Once approved, porch commits and moves to the next plan phase - -## Spec Compliance (CRITICAL) - -**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".** - -### Trust Hierarchy - -``` -SPEC (source of truth) - ↓ -PLAN (implementation guide derived from spec) - ↓ -EXISTING CODE (NOT TRUSTED - must be validated against spec) -``` - -**Never trust existing code over the spec.** Previous implementations may have drifted. - -### Pre-Implementation Sanity Check (PISC) - -**Before writing ANY code:** - -1. ✅ "Have I read the spec in the last 30 minutes?" -2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?" -3. ✅ "Does my approach match the spec's Technical Implementation section?" -4. ✅ "If the spec has code examples, am I following them?" -5. ✅ "Does the existing code I'm building on actually match the spec?" - -**If ANY answer is "no" or "unsure" → STOP and re-read the spec.** - -### Avoiding "Fixing Mode" - -A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to: -- Cargo-culting patterns that may be wrong -- Building on broken foundations -- Implementing something different from the spec - -**When you catch yourself "fixing" code:** -1. STOP -2. Ask: "What does the spec say about this?" -3. Re-read the spec's Traps to Avoid section -4. Verify existing code matches the spec before building on it - -## Prerequisites - -Before implementing, verify: -1. Previous phase (if any) is committed to git -2. You've read the plan phase you're implementing -3. You understand the success criteria for this phase -4. Dependencies from earlier phases are available - -## Process - -### 1. Review the Plan Phase - -Read the current phase in the plan: -- What is the objective? -- What files need to be created/modified? -- What are the success criteria? -- What dependencies exist? - -### 2. Set Up - -- Verify you're on the correct branch -- Check that previous phase is committed: `git log --oneline -5` -- Ensure build passes before starting: `npm run build` (or equivalent) - -### 3. Implement the Code - -Write the code following these principles: - -**Code Quality Standards**: -- Self-documenting code (clear names, obvious structure) -- No commented-out code -- No debug prints in final code -- Explicit error handling -- Follow project style guide - -**Implementation Approach**: -- Work on one file at a time -- Make small, incremental changes -- Document complex logic with comments - -### 4. Write Tests - -**Tests are required.** For each piece of functionality you implement: - -- Write unit tests for core logic -- Write integration tests if the phase involves multiple components -- Test error cases and edge conditions -- Ensure tests are deterministic (no flaky tests) - -**Test file locations** (follow project conventions): -- `tests/` or `__tests__/` directories -- `*.test.ts` or `*.spec.ts` naming - -### 5. Verify Everything Works - -Run both build and tests: - -```bash -npm run build # Must pass -npm test # Must pass -``` - -**Important**: Don't assume these commands exist. Check `package.json` first. - -Fix any errors before signaling completion. - -### 6. Self-Review - -Before signaling completion: -- Read through all code changes -- Read through all test changes -- Verify code matches the spec requirements -- Ensure no accidental debug code -- Check test coverage is adequate - -## Output - -When complete, you should have: -- Modified/created source files as specified in the plan phase -- Tests covering the new functionality -- All build checks passing -- All tests passing +- **The implementation matches the spec.** The spec is the source of truth; the plan derives from it; existing code is not trusted until validated against the spec, because earlier work may have drifted. Code that "works" but diverges from the spec is wrong. When you notice yourself patching symptoms in existing code, stop and re-check what the spec actually requires before building further. +- **Tests exist and are meaningful.** Unit tests for the core logic, integration tests where the phase spans components, and coverage of error and edge cases. Tests are deterministic. Follow the project's existing test locations and naming. +- **Build and tests pass.** Confirm the actual project commands (check `package.json` rather than assuming `npm run build` / `npm test` exist) and run them; fix failures before signaling. +- **The change is clean.** Self-documenting names, explicit error handling, no commented-out or debug code, only the files this phase touches — the simplest solution that satisfies the phase, not more. ## Signals -When implementation AND tests are complete and passing: - -``` -PHASE_COMPLETE -``` - -If you encounter a blocker: - -``` -BLOCKED:reason goes here -``` - -If you need spec/plan clarification: - -``` - -Your specific questions here - -``` - -## Important Notes - -1. **Follow the plan** - Implement what's specified, not more -2. **Don't over-engineer** - Simplest solution that works -3. **Don't skip error handling** - But don't go overboard either -4. **Keep changes focused** - Only touch files in this phase -5. **Build AND tests must pass** - Don't signal complete until both pass -6. **Write tests** - Every implementation phase needs tests - -## What NOT to Do - -- Don't modify files outside this phase's scope -- Don't add features not in the spec -- Don't leave TODO comments for later (fix now or note as blocker) -- Don't skip writing tests -- Don't use `git add .` or `git add -A` when you commit (security risk) - -## Handling Problems - -**If the plan is unclear**: -Signal `AWAITING_INPUT` with your specific question. - -**If you discover the spec is wrong**: -Signal `BLOCKED` and explain the issue. The Architect may need to update the spec. - -**If a dependency is missing**: -Signal `BLOCKED` with details about what's missing. - -**If build or tests fail and you can't fix it**: -Signal `BLOCKED` with the error message. - -**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use workarounds to avoid the failure -3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up -5. Commit the skip and continue with your work +- Implementation and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Blocked — the plan is wrong, the spec is wrong, a dependency is missing, or build/tests fail in a way you cannot resolve: + ``` + BLOCKED:reason goes here + ``` +- Need spec/plan clarification: + ``` + + Your specific questions here + + ``` + +A blocker is a signal, not a silent workaround: never edit `status.yaml` or bypass a porch check to force a green. diff --git a/codev/protocols/aspir/prompts/plan.md b/codev/protocols/aspir/prompts/plan.md index 2c12250dd..de241ea21 100644 --- a/codev/protocols/aspir/prompts/plan.md +++ b/codev/protocols/aspir/prompts/plan.md @@ -1,10 +1,10 @@ # PLAN Phase Prompt -You are executing the **PLAN** phase of the SPIR protocol. +You are executing the **PLAN** phase of the ASPIR protocol. -## Your Goal +## Goal -Transform the approved specification into an executable implementation plan with clear phases. +Turn the approved spec into an executable plan at `codev/plans/{{artifact_name}}.md`: a phase breakdown a builder can implement one phase at a time. ## Context @@ -14,105 +14,41 @@ Transform the approved specification into an executable implementation plan with - **Spec File**: `codev/specs/{{artifact_name}}.md` - **Plan File**: `codev/plans/{{artifact_name}}.md` -## Prerequisites +## What must be true when you finish -Before planning, verify: -1. The specification exists and has been approved -2. You've read and understood the entire spec -3. Success criteria are clear and measurable +- **The plan derives from the spec.** You have read the whole spec — its functional and non-functional requirements, constraints, and success criteria — and the plan validates against them. +- **The work is decomposed into phases, each of which is:** + - **self-contained** — a complete unit of functionality; + - **independently testable** — verifiable on its own; + - **valuable** — delivers observable progress; + - **committable** — a single atomic commit. -## Process - -### 1. Analyze the Specification - -Read the spec thoroughly. Identify: -- All functional requirements -- Non-functional requirements -- Dependencies and constraints -- Success criteria to validate against - -### 2. Identify Implementation Phases - -Break the work into logical phases. Each phase should be: -- **Self-contained** - A complete unit of functionality -- **Independently testable** - Can be verified on its own -- **Valuable** - Delivers observable progress -- **Committable** - Can be a single atomic commit - -Good phase examples: -- "Database Schema" - Creates all tables/migrations -- "Core API Endpoints" - Implements main REST routes -- "Authentication Flow" - Handles login/logout/session - -Bad phase examples: -- "Setup" - Too vague -- "Part 1" - Not descriptive -- "Everything" - Not broken down - -### 3. Define Each Phase - -For each phase, document: -- **Objective** - Single clear goal -- **Files to modify/create** - Specific paths -- **Dependencies** - Which phases must complete first -- **Success criteria** - How to know it's done -- **Test approach** - What tests will verify it - -### 4. Order Phases by Dependencies - -Arrange phases so dependencies are satisfied: -``` -Phase 1: Database Schema (no dependencies) -Phase 2: Data Models (depends on Phase 1) -Phase 3: API Endpoints (depends on Phase 2) -Phase 4: Frontend Integration (depends on Phase 3) -``` - -### 5. Finalize - -After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. + A phase name states what it delivers ("Database schema", "Authentication flow"), not a position ("Setup", "Part 1"). +- **Each phase carries its own contract:** objective, the specific files it creates or modifies, which earlier phases it depends on, its success criteria, and how it will be tested. +- **Phases are ordered so dependencies are satisfied before the phase that needs them.** ## Output -Create the plan file at `codev/plans/{{artifact_name}}.md`, following the template below: +Write the plan to `codev/plans/{{artifact_name}}.md` using the template below as its interface: {{> protocols/spir/templates/plan.md}} ## Signals -Emit appropriate signals based on your progress: - -- After completing the plan draft: +- Draft done: ``` PLAN_DRAFTED ``` -## Commit Cadence +## Commit cadence -Make commits at these milestones: +Commit at each milestone, staging the plan file explicitly: +```bash +git add codev/plans/{{artifact_name}}.md +``` 1. `[Spec {{project_id}}] Initial implementation plan` 2. `[Spec {{project_id}}] Plan with multi-agent review` 3. `[Spec {{project_id}}] Plan with user feedback` 4. `[Spec {{project_id}}] Final approved plan` -**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: -```bash -git add codev/plans/{{artifact_name}}.md -``` - -## Important Notes - -1. **No time estimates** - Don't include hours/days/weeks -3. **Be specific about files** - Exact paths, not "the config file" -4. **Keep phases small** - 1-3 files per phase is ideal -5. **Document dependencies clearly** - Prevents blocked work - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't write code (that's for Implement phase) -- Don't estimate time (meaningless in AI development) -- Don't create phases that can't be independently tested -- Don't skip dependency analysis -- Don't make phases too large (if >5 files, split it) -- Don't use `git add .` or `git add -A` (security risk) +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Plan phase: decompose and sequence the work, do not write code, and do not estimate time. diff --git a/codev/protocols/aspir/prompts/review.md b/codev/protocols/aspir/prompts/review.md index eabe1b98e..fa2112549 100644 --- a/codev/protocols/aspir/prompts/review.md +++ b/codev/protocols/aspir/prompts/review.md @@ -1,10 +1,10 @@ # REVIEW Phase Prompt -You are executing the **REVIEW** phase of the SPIR protocol. +You are executing the **REVIEW** phase of the ASPIR protocol. -## Your Goal +## Goal -Perform a comprehensive review, document lessons learned, and prepare for PR submission. +Review the whole implementation, write the retrospective at `codev/reviews/{{artifact_name}}.md`, and open the PR — so porch's consultation and the architect both review a real PR. ## Context @@ -15,218 +15,65 @@ Perform a comprehensive review, document lessons learned, and prepare for PR sub - **Plan File**: `codev/plans/{{artifact_name}}.md` - **Review File**: `codev/reviews/{{artifact_name}}.md` -## Prerequisites +## What must be true when you finish -Before review, verify: -1. All implementation phases are committed -2. All tests are passing -3. Build is passing -4. Spec compliance verified for all phases +- **The work is done and green.** All phases committed (`git log --oneline | grep "[Spec {{project_id}}]"`), build and tests passing, no uncommitted changes. +- **The implementation has been reviewed against the spec** — code quality, architecture fit, and security considered; deviations from the spec noted with their reasons; every success criterion accounted for. +- **The review document exists** at `codev/reviews/{{artifact_name}}.md`, following the template below (its headings, its order — do not pattern-match an older review that predates it). +- **Consultation feedback is captured.** The review carries a `## Consultation Feedback` section that, per phase / round / model, records each concern and its disposition — **Addressed** (changed), **Rebutted** (why it does not apply), or **N/A** (out of scope / handled elsewhere). "No concerns raised — all consultations approved" is the right line when that is true; note COMMENT verdicts and any `CONSULT_ERROR`. Read the consult outputs from `codev/projects/{{project_id}}-*/`. +- **Governance facts are routed by tier** (see below). +- **The PR exists before you signal**, with a close-keyword so merging auto-closes the issue (see below). -Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"` - -## Process - -### 1. Comprehensive Review - -Review the entire implementation: - -**Code Quality**: -- Is the code readable and maintainable? -- Are there any code smells? -- Is error handling consistent? -- Are there any security concerns? - -**Architecture**: -- Does the implementation fit well with existing code? -- Are there any architectural concerns? -- Is the design scalable if needed? - -**Documentation**: -- Is code adequately commented where needed? -- Are public APIs documented? -- Is README updated if needed? - -### 2. Spec Comparison - -Compare final implementation to original specification: - -- What was delivered vs what was specified? -- Any deviations? Document why. -- All success criteria met? - -### 3. Create Review Document +## Output -Create `codev/reviews/{{artifact_name}}.md`, following the template below. Use these headings and this order — do not invent your own structure, and do not pattern-match an earlier review in `codev/reviews/` that predates this template. Steps 3b and 4 below expand on the `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch's review checks grep for the last two by exact heading. +Write the review to `codev/reviews/{{artifact_name}}.md` using the template below as its interface. Steps below expand its `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch greps the produced file for the last two by exact heading. {{> protocols/spir/templates/review.md}} -### 3b. Include Consultation Feedback - -**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded. - -Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model: - -```markdown -## Consultation Feedback - -### Specify Phase (Round 1) - -#### Gemini -- **Concern**: [Summary of the concern] - - **Addressed**: [What was changed to resolve it] - -#### Codex -- **Concern**: [Summary] - - **Rebutted**: [Why the current approach is correct] - -#### Claude -- No concerns raised (APPROVE) - -### Plan Phase (Round 1) -... -``` - -**Response types** — each concern gets exactly one: -- **Addressed**: Builder made a change to resolve the concern -- **Rebutted**: Builder explains why the concern doesn't apply -- **N/A**: Concern is out of scope, already handled elsewhere, or moot - -**Edge cases**: -- If all reviewers approved with no concerns: "No concerns raised — all consultations approved" -- For COMMENT verdicts: include their feedback (non-blocking but useful context) -- For CONSULT_ERROR (model failure): note "Consultation failed for [model]" -- If a phase had multiple rounds, give each round its own subsection +## Route governance facts by tier (Spec 987) -### 4. Update Architecture and Lessons Learned Documentation +Each governance doc has two tiers. **Route** each new fact; do not simply append to the cold archive. -**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing. +- **HOT** — `codev/resources/arch-critical.md` and `lessons-critical.md`: tiny, hard-capped, always injected into every prompt and into CLAUDE.md/AGENTS.md. Add here only a **behavior-changing, cross-cutting** fact a future builder must know up front. The hot files are capped: if one is full, **demote** a weaker entry into its cold counterpart to make room, and keep the hot file's cold-doc map accurate. +- **COLD** — `codev/resources/arch.md` and `lessons-learned.md`: full, on-demand reference for subsystem detail, file locations, one-offs, and spec-narrow recipes. -Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive: -- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer. -- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference. +The review's `## Architecture Updates` and `## Lessons Learned Updates` sections state what you routed where; if nothing qualifies, keep the heading with a one-line reason. Never grow a hot file past its cap by appending — route to cold or displace. The `update-arch-docs` skill encodes this discipline. -**Architecture Updates**: -1. Read `arch-critical.md` (hot) and skim `arch.md` (cold). -2. If this project produced a system-shape fact, route it: - - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate. - - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold). -3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason. +## Create the PR (before signaling) -**Lessons Learned Updates**: -1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold). -2. If this project produced a durable lesson, route it: - - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full). - - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file. -3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason. - -**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject. - -### 4b. Update Other Documentation - -If needed, also update: -- README.md (new features, changed behavior) -- API documentation - -### 5. Final Verification - -Before PR: -- [ ] All tests pass (use project-specific test command) -- [ ] Build passes (use project-specific build command) -- [ ] Lint passes (if configured) -- [ ] No uncommitted changes: `git status` -- [ ] Review document complete - -### 6. Create Pull Request - -**IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that -porch consultation reviews the actual PR, and the architect can review a real PR -when the pr gate fires. - -**PR body requirements**: The PR body MUST include `Closes #` (for feature issues) -or `Fixes #` (for bug issues) for the driving GitHub issue. If the PR closes -multiple issues (e.g. duplicates consolidated), include one keyword per issue. -Without this, GitHub will not auto-close the issue on merge. - -**Exception**: if this PR only partially addresses the issue (e.g. one phase of a -multi-PR effort), DO NOT use `Closes`/`Fixes` — reference the issue with `Refs #` -or `Part of #` instead. The issue stays open until the follow-up PR closes it. +The PR body must carry `Closes #` (feature) or `Fixes #` (bug) for the driving issue — one keyword per issue if several — so GitHub auto-closes on merge. **Exception:** a PR that only partially addresses its issue uses `Refs #` or `Part of #` instead, leaving the issue open for the follow-up. ```bash gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF' ## Summary -[Brief description of the implementation] +[what was implemented] -Closes # +Closes # ## Changes -- [Change 1] -- [Change 2] +- ... ## Testing -- All unit tests passing -- Integration tests added for [X] -- Manual testing completed for [Y] +- ... ## Spec -Link: codev/specs/{{artifact_name}}.md +codev/specs/{{artifact_name}}.md ## Review -Link: codev/reviews/{{artifact_name}}.md +codev/reviews/{{artifact_name}}.md EOF )" ``` -### 7. Signal Completion - -After the PR is created, signal completion. Porch will run 3-way consultation -(Gemini, Codex, Claude) automatically via the verify step. If reviewers request -changes, you'll be respawned with their feedback. - -## Output - -- Review document at `codev/reviews/{{artifact_name}}.md` -- Updated documentation (if needed) -- Pull request created and ready for review - ## Signals -- After review document is complete: +- Review document complete: ``` REVIEW_COMPLETE ``` - -- After PR is created — signal completion so porch runs consultation: +- PR created — signal so porch runs the 3-way consultation: ``` PR_READY ``` -## Important Notes - -1. **Be honest in lessons learned** - Future you will thank present you -3. **Document deviations** - They're not failures, they're learnings -4. **Update methodology** - If you found a better way, document it -5. **Don't skip the checklist** - It catches last-minute issues -6. **Clean PR description** - Makes review easier - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't skip lessons learned ("nothing to report") -- Don't merge your own PR (Architect handles integration) -- Don't leave uncommitted changes -- Don't forget to update documentation -- Don't rush this phase - it's valuable for learning -- Don't use `git add .` or `git add -A` (security risk) - -## Review Prompts for Reflection - -Ask yourself: -- What surprised me during implementation? -- Where did I spend the most time? Was it avoidable? -- What would have helped me go faster? -- Did the spec adequately describe what was needed? -- Did the plan phases make sense in hindsight? -- What tests caught issues? What tests were unnecessary? - -Capture these reflections in the lessons learned section. +Do not run `consult` (porch handles it) and merge your own PR only after the human approves the `pr` gate — never before. diff --git a/codev/protocols/aspir/prompts/specify.md b/codev/protocols/aspir/prompts/specify.md index daa5feab2..978b1e0a1 100644 --- a/codev/protocols/aspir/prompts/specify.md +++ b/codev/protocols/aspir/prompts/specify.md @@ -1,10 +1,10 @@ # SPECIFY Phase Prompt -You are executing the **SPECIFY** phase of the SPIR protocol. +You are executing the **SPECIFY** phase of the ASPIR protocol. -## Your Goal +## Goal -Create a comprehensive specification document that thoroughly explores the problem space and proposed solution. +Produce a specification at `codev/specs/{{artifact_name}}.md` that explores the problem space and the proposed solution well enough that the plan and implementation can follow without re-deciding anything. ## Context @@ -13,137 +13,47 @@ Create a comprehensive specification document that thoroughly explores the probl - **Current State**: {{current_state}} - **Spec File**: `codev/specs/{{artifact_name}}.md` -## Process +## What must be true when you finish -### 0. Check for Existing Spec (ALWAYS DO THIS FIRST) - -**Before asking ANY questions**, check if a spec already exists: - -```bash -ls codev/specs/{{project_id}}-*.md -``` - -**If a spec file exists:** -1. READ IT COMPLETELY - the answers to your questions are already there -2. The spec author has already made the key decisions -3. DO NOT ask clarifying questions - proceed directly to consultation -4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch - -**If no spec exists:** Proceed to Step 1 below. - -### 0.5 Baked Decisions - -Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec. - -If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting. - -### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS) - -Before writing anything, ask clarifying questions to understand: -- What problem is being solved? -- Who are the stakeholders? -- What are the constraints? -- What's in scope vs out of scope? -- What does success look like? - -If this is your first iteration AND no spec exists, ask these questions now and wait for answers. - -**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer. - -**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step. - -### 2. Problem Analysis - -Once you have answers, document: -- The problem being solved (clearly articulated) -- Current state vs desired state -- Stakeholders and their needs -- Assumptions and constraints - -### 3. Solution Exploration - -Generate multiple solution approaches. For each: -- Technical design overview -- Trade-offs (pros/cons) -- Complexity assessment -- Risk assessment - -### 4. Open Questions - -List uncertainties categorized as: -- **Critical** - blocks progress -- **Important** - affects design -- **Nice-to-know** - optimization - -### 5. Success Criteria - -Define measurable acceptance criteria: -- Functional requirements (MUST, SHOULD, COULD) -- Non-functional requirements (performance, security) -- Test scenarios - -### 6. Finalize - -After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. +- **An existing spec is honored, not rewritten.** If `codev/specs/{{project_id}}-*.md` already exists, it carries the architect's decisions — read it fully and refine it in place. Clarifying questions are for the case where no spec exists yet; when one does, the spec is the answer. +- **Baked Decisions are fixed.** If the issue body has a "Baked Decisions" section (any heading level, case-insensitive), copy it verbatim into the spec's Constraints and treat each item as settled — **do not autonomously override** the architect's choices in Solution Exploration. Raise a genuine problem with a baked decision via `afx send architect` rather than overriding it. If two baked decisions contradict each other, do not choose — **pause**, **flag** the contradiction via `afx send`, and wait for resolution. +- **The problem is characterized before solutions are.** Current state vs desired state, stakeholders, assumptions, and constraints are explicit. +- **Solutions are explored, not assumed.** More than one approach is considered, each with its trade-offs and risks, before one is recommended. +- **Open questions are surfaced and ranked** by whether they block progress, shape the design, or are merely nice to know. +- **Success is measurable.** Acceptance criteria are concrete enough to test against. ## Output -Create or update the specification file at `codev/specs/{{artifact_name}}.md`. - -Follow the canonical spec template reproduced below. Use these headings, in this order — do not invent your own structure, and do not pattern-match an earlier spec in `codev/specs/` that predates this template. If a section genuinely does not apply, keep the heading and write a one-line "N/A — [reason]" rather than deleting it. +Write the spec to `codev/specs/{{artifact_name}}.md` using the template below as its interface — these headings, in this order. A section that genuinely does not apply keeps its heading with a one-line `N/A — [reason]` rather than being deleted. Do not pattern-match an older spec in `codev/specs/` that predates this template. {{> protocols/spir/templates/spec.md}} -**IMPORTANT**: Keep spec/plan/review filenames in sync: -- Spec: `codev/specs/{{artifact_name}}.md` -- Plan: `codev/plans/{{artifact_name}}.md` -- Review: `codev/reviews/{{artifact_name}}.md` +Keep the three artifact filenames in sync: spec `codev/specs/{{artifact_name}}.md`, plan `codev/plans/{{artifact_name}}.md`, review `codev/reviews/{{artifact_name}}.md`. ## Signals -Emit appropriate signals based on your progress: - -- When waiting for clarifying question answers, **include your questions in the signal**: +- Waiting on clarifying-question answers — **put the questions inside the signal**, which is displayed prominently to the user: ``` - Please answer these questions: - 1. What should the primary use case be - internal tooling or customer-facing? - 2. What are the key constraints we should consider? - 3. Who are the main stakeholders? + Please answer: + 1. ... + 2. ... ``` - - The content inside the signal tag is displayed prominently to the user. - -- After completing the initial spec draft: +- Initial draft done: ``` SPEC_DRAFTED ``` +## Commit cadence -## Commit Cadence - -Make commits at these milestones: +Commit at each milestone, staging the spec file explicitly: +```bash +git add codev/specs/{{artifact_name}}.md +``` 1. `[Spec {{project_id}}] Initial specification draft` 2. `[Spec {{project_id}}] Specification with multi-agent review` 3. `[Spec {{project_id}}] Specification with user feedback` 4. `[Spec {{project_id}}] Final approved specification` -**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: -```bash -git add codev/specs/{{artifact_name}}.md -``` - -## Important Notes - -1. **Be thorough** - A good spec prevents implementation problems -3. **Be specific** - Vague specs lead to wrong implementations -4. **Include examples** - Concrete examples clarify intent - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't include implementation details (that's for the Plan phase) -- Don't estimate time (AI makes time estimates meaningless) -- Don't start coding (you're in Specify, not Implement) -- Don't use `git add .` or `git add -A` (security risk) +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Specify phase: no implementation detail (that is the plan), no code, no time estimates. diff --git a/codev/protocols/aspir/protocol.md b/codev/protocols/aspir/protocol.md index 6cc2caf97..390e74049 100644 --- a/codev/protocols/aspir/protocol.md +++ b/codev/protocols/aspir/protocol.md @@ -1,100 +1,52 @@ # ASPIR Protocol -> **ASPIR** = **A**utonomous **S**pecify → **P**lan → **I**mplement → **R**eview -> -> Identical to SPIR but without human approval gates on spec and plan phases. -> Each phase has one build-verify cycle with 3-way consultation. +Autonomous SPIR: the same phases, artifacts, consultations and checks, with the **spec and plan +human gates absent**. The builder runs Specify → Plan → Implement without stopping, and a human +still reviews everything at the `pr` gate before merge. -## What is ASPIR? +Use ASPIR for trusted, low-risk work where reviewing the approach up front would cost more than +it saves, and deferring that review to the PR is acceptable. When getting the shape wrong would +be expensive to unwind, use SPIR and take the gates. -ASPIR is an autonomous variant of the SPIR protocol. It follows the exact same phases (Specify → Plan → Implement → Review) with the same 3-way consultations, checks, and PR flow — but removes the `spec-approval` and `plan-approval` human gates. +## The state machine -This means the builder proceeds automatically from Specify → Plan → Implement without waiting for human approval at each gate. The `pr` gate in the Review phase is preserved — a human still reviews all code before merge. +Phases, gates and checks — note that `specify` and `plan` carry **no gate at all**; they are not +auto-approved, they are ungated: -### Differences from SPIR - -| Aspect | SPIR | ASPIR | -|--------|------|-------| -| Spec gate (`spec-approval`) | Human must approve | Auto-approved | -| Plan gate (`plan-approval`) | Human must approve | Auto-approved | -| PR gate (`pr`) | Human must approve | Human must approve | -| Phases | Specify → Plan → Implement → Review | Same | -| 3-way consultations | Yes, every phase | Same | -| Checks (build, tests, PR) | Yes | Same | -| Prompts / templates | Full set | Same prompts; templates included from SPIR (no copies) | - -### When to Use ASPIR - -Use ASPIR instead of SPIR when: - -- The work is **trusted and low-risk** — internal tooling, protocol additions, well-understood features -- The architect has **pre-written and approved** the spec before spawning -- The scope is **self-contained** with low blast radius -- You want **full SPIR discipline** (consultations, phased implementation, review) without waiting at gates - -### When NOT to Use ASPIR - -Use SPIR instead when: - -- The feature involves **novel architecture** or unclear requirements -- The spec needs **iterative human feedback** during drafting -- The work is **high-risk** — security-sensitive, user-facing, or broadly impactful -- You want to **review and adjust** the plan before implementation starts - -## Baked Decisions (Optional) - -When filing an issue for ASPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`. - -## Protocol Phases - -ASPIR follows the same four phases as SPIR. For full phase documentation, see the [SPIR protocol](../spir/protocol.md). - -### S - Specify -Write specification with 3-way review (Gemini, Codex, Claude). **No human gate** — proceeds directly to Plan after verification. +```json +{{> protocols/aspir/protocol.json}} +``` -### P - Plan -Write implementation plan with 3-way review. **No human gate** — proceeds directly to Implement after verification and checks pass. +## Everything else is SPIR -### I - Implement -Execute each plan phase with build-verify cycle. Same as SPIR — no gate between phases (SPIR also has no gate here). +Artifacts (`codev/specs/`, `codev/plans/`, `codev/reviews/`, same base filename), the +build-verify cycle per plan phase, mandatory 3-way consultation at each verify step, the +machine-readable `phases` block in the plan, commit and branch conventions, and Baked Decisions +handling are all identical to SPIR. ASPIR includes SPIR's templates rather than copying them, so +there is one set to keep correct. -### R - Review -Final review, PR preparation, and 3-way review. **PR gate preserved** — builder stops and waits for human approval before merge. +See `protocols/spir/protocol.md` for that shared substance. -## Usage +## Baked Decisions -```bash -# Spawn a builder using ASPIR -afx spawn 42 --protocol aspir +An issue may carry a `## Baked Decisions` section pinning architectural choices the architect +does not want re-litigated — typically **language**, **framework**, deployment shape, key +**dependencies**, or decisions deferred to a later spec. -# The builder runs autonomously through Specify → Plan → Implement -# and stops only at the PR gate in the Review phase -``` +Every item in it is fixed. Copy the section verbatim into the spec's Constraints and do not +re-open it in the spec, plan, or review; CMAP reviewers will not propose alternatives unless the +spec fails to honour one. If two items contradict each other, do not choose — surface the +contradiction and wait. -## File Structure +**Absence is the no-op default**: an issue with no such section is an invitation to explore +freely, not an omission to be filled in. -``` -codev/protocols/aspir/ -├── protocol.json # Protocol definition (SPIR minus gates) -├── protocol.md # This file -├── builder-prompt.md # Builder instructions (same as SPIR) -├── prompts/ -│ ├── specify.md # Specify phase prompt (same as SPIR) -│ ├── plan.md # Plan phase prompt (same as SPIR) -│ ├── implement.md # Implement phase prompt (same as SPIR) -│ └── review.md # Review phase prompt (same as SPIR) -└── consult-types/ - ├── spec-review.md # Spec consultation guide (same as SPIR) - ├── plan-review.md # Plan consultation guide (same as SPIR) - ├── impl-review.md # Impl consultation guide (same as SPIR) - ├── phase-review.md # Phase consultation guide (same as SPIR) - └── pr-review.md # PR consultation guide (same as SPIR) -``` +The architect can **amend or rescind** a baked decision at any time by updating the issue and +respawning, or by sending the builder a direct instruction via `afx send`. -ASPIR ships **no `templates/` directory**. Its phase prompts deliver SPIR's canonical -templates directly, via an include directive pointing at `protocols/spir/templates/`, so -there is exactly one copy of each template and it cannot drift between the two protocols. -(Written as a path, not as a literal include: an include directive in prose would be -expanded — and silently emptied — when this file is delivered to a builder.) +## The one thing to be careful about -All files except `protocol.json` and `protocol.md` are identical to their SPIR counterparts. +Without the spec and plan gates, nothing external catches a misread of the issue until the PR. +If the spec you write surprises you — if it turns out larger, or more architectural, than the +issue implied — that is the signal ASPIR was the wrong choice. Say so early rather than +carrying the misfit through to review. diff --git a/codev/protocols/bugfix/builder-prompt.md b/codev/protocols/bugfix/builder-prompt.md index aefa35a25..3ad3ba278 100644 --- a/codev/protocols/bugfix/builder-prompt.md +++ b/codev/protocols/bugfix/builder-prompt.md @@ -4,28 +4,21 @@ You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the BUGFIX protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Run consultations manually when the protocol calls for them -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way review** — always follow porch next → porch done cycle + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the BUGFIX protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. {{#if issue}} ## Issue #{{issue.number}} @@ -33,43 +26,28 @@ Follow the BUGFIX protocol. Read and internalize the protocol before starting an **Description**: {{issue.body}} +{{/if}} ## Your Mission + 1. Reproduce the bug -2. Identify root cause -3. Implement fix (< 300 LOC) -4. Add regression test -5. Create PR with "Fixes #{{issue.number}}" in body -6. Notify architect via `afx send architect "PR #N ready for review (fixes #{{issue.number}})"` +2. Identify the root cause — **no code in the investigate phase** +3. Implement the minimal fix (<300 LOC) +4. Add a regression test that **fails without the fix and passes with it** +5. Open a PR with `Fixes #{{issue.number}}` in the body +6. Notify: `afx send architect "PR #N ready for review (fixes #{{issue.number}})"` + +When merging, use `gh pr merge --merge` **without** `--delete-branch` — you are checked out on +that branch in a worktree. + +If the fix outgrows BUGFIX (>300 LOC, architectural impact, or an unclear root cause after +investigation), stop and say so: -If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via: ```bash afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to SPIR." ``` ## Notifications -Always use `afx send architect "..."` to notify the architect at key moments: -- **PR ready**: `afx send architect "PR #N ready for review (fixes #{{issue.number}})"` -- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."` -- **Blocked**: `afx send architect "Blocked on issue #{{issue.number}}: [reason]"` -{{/if}} - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue with your work - -## Getting Started -1. Read the BUGFIX protocol -2. Review the issue details -3. Reproduce the bug before fixing - ---- - -## Protocol Reference (full text) -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/bugfix/consult-types/impl-review.md b/codev/protocols/bugfix/consult-types/impl-review.md index 90d6a2d9e..500da5cc5 100644 --- a/codev/protocols/bugfix/consult-types/impl-review.md +++ b/codev/protocols/bugfix/consult-types/impl-review.md @@ -1,58 +1,40 @@ # Implementation Review Prompt (BUGFIX) ## Context -You are reviewing in-progress fix work for a **BUGFIX protocol** project. A builder has investigated a GitHub Issue, identified a root cause, and is implementing the fix + regression test. Your job is to verify the fix matches the issue's symptom and meets BUGFIX standards. -**BUGFIX is not SPIR.** There is **no spec, no plan, and no review document**. The GitHub Issue is the spec. The PR body will be the review. Do **not** request changes for missing `codev/specs/`, `codev/plans/`, or `codev/reviews/` artifacts. +You are reviewing in-progress fix work for a **BUGFIX protocol** project. A builder has investigated a GitHub Issue, identified a root cause, and is implementing the fix + regression test. Verify the fix matches the issue's symptom and meets BUGFIX standards. -## CRITICAL: Verify Before Flagging +**BUGFIX is not SPIR.** There is **no spec, no plan, and no review document** — the GitHub Issue is the spec, and the PR body will be the review. Do **not** request changes for missing `codev/specs/`, `codev/plans/`, or `codev/reviews/` artifacts. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions. -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs. -3. **Do not assume** your training data reflects the version in use — verify against project files. -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed. +## Verify before flagging -## Focus Areas - -1. **Issue Adherence** - - Does the implementation actually resolve the symptom described in the GitHub Issue? - - Is the root cause fix targeted, or is it a workaround that masks the symptom? - -2. **Regression Test** - - Is there a regression test that exercises the exact scenario from the issue? - - Without the fix applied, would this test fail? (The whole point.) - - Is the test deterministic? - - If no test was added, has the builder justified why (e.g., docs-only change with no testable behavior)? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Scope Discipline** - - Is the change focused on the root cause only — no unrelated refactors, no drive-by fixes? - - Is the net diff staying under ~300 LOC? If it has grown larger, should this escalate to SPIR/TICK? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues introduced by the fix? - - Are error cases handled appropriately for the path that was changed? - - No debug code, stray `console.log`, or commented-out code. +## Focus Areas -5. **Test Status** - - Existing tests still pass. - - Build still passes. - - No new flaky tests introduced. +- **Issue resolution** — the fix actually resolves the symptom in the issue, targeting the root cause rather than masking it with a workaround. +- **Regression test** — a deterministic test exercises the exact scenario from the issue and **would fail without the fix**. If none was added, the builder has justified why (e.g. a docs-only change with no testable behavior). +- **Scope discipline** — the change is focused on the root cause only (no unrelated refactors or drive-by fixes) and stays under ~300 LOC; if it grew larger, it should escalate to SPIR/TICK. +- **Code quality** — readable and maintainable; no bugs introduced; error cases on the changed path handled; no debug or commented-out code. +- **Test status** — existing tests and the build still pass; no new flaky tests. ## Out of Scope (Do NOT request changes for) -The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons: +These are **not** part of the BUGFIX protocol and must **not** be cited as `REQUEST_CHANGES` reasons: - Missing `codev/specs/-*.md`, `codev/plans/-*.md`, or `codev/reviews/-*.md` — BUGFIX produces none of these. The GitHub Issue is the spec; the PR body is the review. -- Commit format `[Spec NNNN][Phase]` — BUGFIX uses `Fix #N: ...` or `[Bugfix #N] ...`. This is the protocol-mandated format, **not** a bug. +- Commit format `[Spec NNNN][Phase]` — BUGFIX uses `Fix #N: ...` or `[Bugfix #N] ...`. That is the protocol-mandated format, **not** a bug. - `status.yaml` fields such as `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it manually. Treat porch state as informational, not a fixable issue. - "Plan Alignment" or "Spec Adherence" — there is no plan and no spec to align with. -- Phase-scoping concerns — BUGFIX is single-phase by design. There are no plan phases to scope against. +- Phase-scoping concerns — BUGFIX is single-phase by design; there are no plan phases to scope against. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -66,14 +48,8 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Fix and regression test are in good shape; builder can proceed to PR creation. -- `REQUEST_CHANGES`: Real BUGFIX-relevant issues (fix doesn't resolve the symptom, missing regression test without justification, scope creep, broken existing tests, etc.). -- `COMMENT`: Minor suggestions; builder can proceed but should consider the feedback. - -## Notes +- `APPROVE`: fix and regression test are in good shape; builder can proceed to PR creation. +- `REQUEST_CHANGES`: real BUGFIX-relevant issues (fix doesn't resolve the symptom, missing regression test without justification, scope creep, broken existing tests). +- `COMMENT`: minor suggestions; builder can proceed but should consider the feedback. -- This is an implementation-level review, not the final PR review. -- Focus on "does this fix actually resolve the issue, and is it protected by a regression test" — not on artifacts from other protocols. -- If referencing line numbers, use `file:line` format. -- The builder needs actionable, protocol-correct feedback to continue. +This is an implementation-level review, not the final PR review — focus on "does this fix resolve the issue, protected by a regression test", not on artifacts from other protocols. diff --git a/codev/protocols/bugfix/consult-types/pr-review.md b/codev/protocols/bugfix/consult-types/pr-review.md index efdb7a176..50f8fde31 100644 --- a/codev/protocols/bugfix/consult-types/pr-review.md +++ b/codev/protocols/bugfix/consult-types/pr-review.md @@ -1,64 +1,35 @@ # PR Ready Review Prompt (BUGFIX) ## Context -You are performing a final self-check during the PR phase of the **BUGFIX protocol**. The builder has investigated a GitHub Issue, implemented a focused fix, and added a regression test. They are about to create — or have just created — a PR for the architect's integration review. -**BUGFIX is not SPIR.** Do **not** review against the SPIR three-document trinity. The artifacts of a BUGFIX project are: -- The originating **GitHub Issue** (serves as the spec) -- The **code fix** (minimal, focused on root cause) -- A **regression test** that fails without the fix and passes with it -- The **PR body** (Summary, Root Cause, Fix, Test Plan) +You are performing the final self-check during the PR phase of the **BUGFIX protocol**. The builder has investigated a GitHub Issue, implemented a focused fix, and added a regression test, and is about to create — or has just created — the PR for the architect's integration review. -There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file** for a BUGFIX, and there should not be one. The commit format is `Fix #NNNN: ` (or `[Bugfix #NNNN] ...`), **not** `[Spec NNNN][Phase]`. +**BUGFIX is not SPIR.** Do **not** review against the SPIR three-document trinity. A BUGFIX project's artifacts are the originating **GitHub Issue** (the spec), the **code fix** (minimal, root-cause-focused), a **regression test** that fails without the fix and passes with it, and the **PR body** (Summary, Root Cause, Fix, Test Plan). There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file**, and there should not be. The commit format is `Fix #NNNN: ` (or `[Bugfix #NNNN] ...`), **not** `[Spec NNNN][Phase]`. ## Focus Areas -1. **Issue Resolution** - - Does the fix actually resolve the symptom described in the issue? - - Does the PR body include `Fixes #` so the issue auto-closes on merge? - - Does the PR description cover: Summary, Root Cause, Fix, Test Plan? - -2. **Regression Test** - - Is there a regression test that targets the exact scenario from the issue? - - Would the test fail without the fix? (If reviewers can't tell, ask the builder to demonstrate.) - - Is the test deterministic (not flaky)? - - If the fix is documentation-only or otherwise truly untestable, has the builder explicitly justified the absence of a test? - -3. **Scope Discipline** - - Is the change focused on the root cause? No unrelated refactors, no drive-by fixes for other bugs. - - Is the net diff under ~300 LOC (additions + deletions, excluding generated/lockfiles)? - - If the scope grew beyond a bugfix, should the builder have escalated to SPIR/TICK instead? - -4. **Code Cleanliness** - - No debug code, `console.log`, or commented-out blocks left behind. - - No stray TODOs introduced by this fix. - - Code follows existing project conventions. - -5. **Test Status** - - All existing tests pass. - - Build passes. - - No new flaky tests introduced. - -6. **PR Hygiene** - - Commits use the BUGFIX format: `Fix #: ...` or `[Bugfix #] ...` (**not** `[Spec NNNN][Phase]`). - - Branch is up to date with its base (or close enough for clean merge). - - PR is linked to the issue. +- **Issue resolution** — the fix resolves the symptom; the PR body includes `Fixes #` (so the issue auto-closes on merge) and covers Summary, Root Cause, Fix, Test Plan. +- **Regression test** — a deterministic test targets the exact scenario and would fail without the fix; a truly untestable (e.g. docs-only) fix has the absence explicitly justified. +- **Scope discipline** — focused on the root cause, no unrelated refactors or drive-by fixes, net diff under ~300 LOC; if it grew beyond a bugfix, it should have escalated to SPIR/TICK. +- **Code cleanliness** — no debug code, `console.log`, commented-out blocks, or stray TODOs; follows project conventions. +- **Test status** — existing tests and the build pass; no new flaky tests. +- **PR hygiene** — commits use `Fix #: ...` / `[Bugfix #] ...` (**not** `[Spec NNNN][Phase]`), the branch is current with its base, and the PR is linked to the issue. ## Out of Scope (Do NOT request changes for) -The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons: +These are **not** part of the BUGFIX protocol and must **not** be cited as `REQUEST_CHANGES` reasons: - Missing `codev/specs/-*.md` — BUGFIX has no spec; the GitHub Issue is the spec. - Missing `codev/plans/-*.md` — BUGFIX has no plan. -- Missing `codev/reviews/-*.md` — BUGFIX has no review document; review lives in the PR body. +- Missing `codev/reviews/-*.md` — BUGFIX has no review document; the review lives in the PR body. - Commit format `[Spec NNNN][Phase]` — BUGFIX intentionally uses `Fix #N:` / `[Bugfix #N]`. - `status.yaml` fields like `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it directly. Treat porch state as informational, not a fixable issue. - Phase-scoping concerns — BUGFIX is a single-phase protocol; there are no plan phases to scope against. -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +- The syntax of `git diff` examples in review-file prose (e.g. `git diff ci..HEAD` in a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -76,23 +47,18 @@ PR_SUMMARY: | Fixes #. [1-2 sentences on what was fixed.] ## Root Cause - [Brief explanation of what caused the bug] + [What caused the bug] ## Fix - [Brief explanation of the fix] + [What changed] ## Test Plan - [Regression test description] - [Manual verification, if applicable] ``` -**Verdict meanings:** -- `APPROVE`: Bug is resolved, regression test is in place, PR is ready for architect review. -- `REQUEST_CHANGES`: Real BUGFIX-relevant issues to fix (missing regression test, fix doesn't resolve the symptom, scope creep, etc.). -- `COMMENT`: Minor items, can proceed but note feedback. +- `APPROVE`: bug resolved, regression test in place, PR ready for architect review. +- `REQUEST_CHANGES`: real BUGFIX-relevant issues (missing regression test, fix doesn't resolve the symptom, scope creep). +- `COMMENT`: minor items; can proceed but note the feedback. -## Notes - -- This is the builder's final self-review before hand-off to the architect. -- The `PR_SUMMARY` block can be used directly as the PR description. -- Focus on "is this bug actually fixed and protected by a test" — not on artifacts from other protocols. +The `PR_SUMMARY` block can be used directly as the PR description. diff --git a/codev/protocols/bugfix/prompts/fix.md b/codev/protocols/bugfix/prompts/fix.md index afecc3343..ee57d903e 100644 --- a/codev/protocols/bugfix/prompts/fix.md +++ b/codev/protocols/bugfix/prompts/fix.md @@ -2,76 +2,31 @@ You are executing the **FIX** phase of the BUGFIX protocol. -## Your Goal +## Goal -Implement the bug fix and add a regression test. Keep it minimal and focused. +Fix the bug with the minimum change, and add a regression test that pins it. ## Context - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## What must be true when you finish -### 1. Implement the Fix +- **The change is minimal and targeted.** Fix the root cause from INVESTIGATE and nothing else — no refactoring of surrounding code, no unrelated features, no other bugs you happen to notice (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions. +- **A regression test pins the fix.** Every bugfix carries a test that **fails without the fix and passes with it**, covers the issue's scenario, and is deterministic. The only exception is a genuinely untestable change (e.g. a CSS-only tweak with no observable behavior) — and then you state why, in the commit message and PR description. +- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling. +- **The change stays within BUGFIX scope.** If the fix grows past ~300 LOC, signal `TOO_COMPLEX` rather than pressing on. -Apply the minimum change needed to resolve the bug: -- Fix the root cause identified in the INVESTIGATE phase -- Do NOT refactor surrounding code -- Do NOT add features beyond what's needed -- Do NOT fix other bugs you happen to notice (file separate issues) - -**Code Quality**: -- Self-documenting code (clear names, obvious structure) -- No commented-out code or debug prints -- Follow existing project conventions - -### 2. Add a Regression Test - -**A regression test is MANDATORY.** Every bugfix MUST include a test unless you provide explicit justification for why a test is impossible (e.g., pure CSS-only change with no testable behavior). If you skip the test, you MUST explain why in your commit message and PR description. - -Write a test that: -- Fails without the fix (demonstrates the bug) -- Passes with the fix (demonstrates the fix works) -- Covers the specific scenario from the issue -- Is deterministic (not flaky) - -Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.). - -### 3. Verify the Fix - -Run build and tests: - -```bash -npm run build # Must pass -npm test # Must pass -``` - -Fix any failures before proceeding. If build/test commands don't exist, check `package.json`. - -### 4. Commit - -Stage and commit your changes: -- Use explicit file paths (never `git add -A` or `git add .`) -- Commit message: `Fix #{{issue.number}}: ` +Commit with an explicit staged path and the message `Fix #{{issue.number}}: `. ## Signals -When fix and tests are complete and passing: - -``` -PHASE_COMPLETE -``` - -If you encounter a blocker: - -``` -BLOCKED:reason goes here -``` - -## Important Notes - -1. **Minimal changes only** — Fix the bug, nothing else -2. **Regression test is MANDATORY** — No fix without a test. If truly untestable, justify in writing. -3. **Build AND tests must pass** — Don't signal complete until both pass -4. **Stay under 300 LOC** — If the fix grows beyond this, signal `TOO_COMPLEX` +- Fix and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Blocked: + ``` + BLOCKED:reason goes here + ``` diff --git a/codev/protocols/bugfix/prompts/investigate.md b/codev/protocols/bugfix/prompts/investigate.md index ffa54385e..21bee598a 100644 --- a/codev/protocols/bugfix/prompts/investigate.md +++ b/codev/protocols/bugfix/prompts/investigate.md @@ -2,76 +2,32 @@ You are executing the **INVESTIGATE** phase of the BUGFIX protocol. -## Your Goal +## Goal -Understand the bug, reproduce it, identify the root cause, and assess whether it's fixable within BUGFIX scope (< 300 LOC). +Understand the bug, reproduce it, find the root cause, and decide whether it fits BUGFIX scope (a focused change under ~300 LOC). ## Context - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## What must be true when you finish -### 1. Read the Issue - -Read the full issue description. Identify: -- What is the expected behavior? -- What is the actual behavior? -- Are there reproduction steps? -- Are there error messages or screenshots? - -### 2. Reproduce the Bug - -Before fixing anything, confirm the bug exists: -- Follow the reproduction steps from the issue -- If no steps are given, infer them from the description -- Document the exact reproduction steps you used -- If you **cannot** reproduce, signal `BLOCKED` with details - -### 3. Identify Root Cause - -Trace the bug to its source: -- Read the relevant code paths -- Use grep/search to find related code -- Identify the exact file(s) and line(s) causing the issue -- Understand **why** the bug occurs, not just **where** - -### 4. Assess Complexity - -Determine if this is BUGFIX-appropriate: -- **< 300 LOC change**: Proceed with BUGFIX -- **> 300 LOC or architectural**: Signal `TOO_COMPLEX` to escalate - -Consider: -- How many files need to change? -- Does it require new abstractions or refactoring? -- Are there cascading effects? - -## Output - -By the end of this phase, you should know: -1. The exact root cause -2. Which files need to change -3. The approximate size of the fix -4. Whether it's BUGFIX-appropriate +- **The bug is reproduced, not assumed.** You have confirmed the expected-vs-actual behavior from the issue and established concrete reproduction steps (inferring them if the issue gives none). If you cannot reproduce it, that is a `BLOCKED` signal with what you tried. +- **The root cause is understood** — the exact file(s) and line(s), and *why* the bug happens, not just where. Trace the failure path rather than pattern-matching a symptom. +- **The scope is assessed against BUGFIX's ceiling.** A focused fix under ~300 LOC proceeds; anything larger or architectural (new abstractions, refactors, cascading effects across many files) is a `TOO_COMPLEX` signal to escalate. ## Signals -When investigation is complete: - -``` -PHASE_COMPLETE -``` - -If the bug is too complex for BUGFIX: - -``` -TOO_COMPLEX -``` - -If you're blocked (can't reproduce, missing context, etc.): - -``` -BLOCKED:reason goes here -``` +- Investigation complete (root cause + fix scope known): + ``` + PHASE_COMPLETE + ``` +- Too large or architectural for BUGFIX: + ``` + TOO_COMPLEX + ``` +- Blocked (cannot reproduce, missing context): + ``` + BLOCKED:reason goes here + ``` diff --git a/codev/protocols/bugfix/prompts/pr.md b/codev/protocols/bugfix/prompts/pr.md index d70d8dfdf..4dd89ff5c 100644 --- a/codev/protocols/bugfix/prompts/pr.md +++ b/codev/protocols/bugfix/prompts/pr.md @@ -2,32 +2,18 @@ You are executing the **PR** phase of the BUGFIX protocol. -## Your Goal +## Goal -Create a pull request, run CMAP review, and address feedback. +Open the PR, run CMAP review on it, address feedback, and hand off to the architect at the `pr` gate. ## Context - **Issue**: #{{issue.number}} — {{issue.title}} - **Current State**: {{current_state}} -## Process +## Create the PR -### 1. Create the Pull Request - -Create a PR that links to the issue. - -**PR body requirements**: The PR body MUST include `Fixes #` (where `` is -the driving issue number) so GitHub auto-closes the issue on merge. If the PR -fixes multiple issues (e.g. duplicates consolidated), include one `Fixes #` -per issue. Without this, GitHub will not auto-close the issue. - -**Exception**: if this PR only partially addresses the issue, use `Refs #` -or `Part of #` instead of `Fixes` — the issue stays open until a -follow-up PR closes it. - -**Note**: substitute the real issue number for `` — do not leave the -placeholder or any `{{...}}` template tag in the committed PR body. +The PR body must carry `Fixes #` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a PR that only partially addresses the issue uses `Refs #` or `Part of #` instead, leaving it open for the follow-up. Substitute the real number for ``; leave no `{{...}}` tag or `` placeholder in the committed body. ```bash gh pr create --title "Fix #: " --body "$(cat <<'EOF' @@ -35,15 +21,15 @@ gh pr create --title "Fix #: " --body "$(cat <<'EOF' <1-2 sentence description of the bug and fix> -Fixes # +Fixes # ## Root Cause - + ## Fix - + ## Test Plan @@ -54,9 +40,9 @@ EOF )" ``` -### 2. Run CMAP Review +## Run CMAP review -Run 3-way parallel consultation on the PR: +BUGFIX runs its own 3-way consultation on the PR (porch does not do it for you). Dispatch all three in the background: ```bash consult -m gemini --protocol bugfix --type pr & @@ -64,47 +50,26 @@ consult -m codex --protocol bugfix --type pr & consult -m claude --protocol bugfix --type pr & ``` -All three should run in the background (`run_in_background: true`). - -### 3. Wait for Results and Address Feedback - -**DO NOT proceed to step 4 until ALL THREE consultations have returned results.** - -Wait for each background consultation to complete, then read the results: -- Use `TaskOutput` (with `block: true`) to retrieve each consultation result -- Record each model's verdict (APPROVE or REQUEST_CHANGES) -- Fix any issues identified by reviewers -- Push updates to the PR branch -- Re-run CMAP if substantial changes were made - -You must have three concrete verdicts (e.g., "gemini: APPROVE, codex: APPROVE, claude: APPROVE") before continuing. +Do not proceed until **ALL THREE consultations have returned results** — retrieve each with `TaskOutput` (`block: true`), record its verdict (APPROVE / REQUEST_CHANGES), fix real issues, push, and re-run CMAP if the changes were substantial. You must hold three concrete verdicts before you notify. -### 4. Notify Architect +## Notify and hand off at the gate -**DO NOT send this notification until you have all three CMAP verdicts from step 3.** - -Send a **single** notification that includes the PR link and each model's verdict: +**DO NOT send this notification until you have all three CMAP verdicts.** Send a **single** notification with the PR link and all three verdicts, then request the gate: ```bash afx send architect "PR # ready for review (fixes issue #{{issue.number}}). CMAP: gemini=, codex=, claude=" +porch done ``` -Then run `porch done ` to auto-request the `pr` gate. The PR surfaces -in Needs Attention from this point; **STOP and wait** for the architect to call -`porch approve pr`. After gate approval, porch will emit a merge task -(via the next `porch next` call) — follow it to merge the PR and advance to -`verified`. +`porch done` fires the `pr` gate and surfaces the PR in Needs Attention. Wait for the architect to approve it (`porch approve pr`) — a CMAP APPROVE is not merge authorization. After gate approval, follow the merge task from `porch next` to merge and advance to `verified`. ## Signals -When PR is created and reviews are complete: - -``` -PHASE_COMPLETE -``` - -If you're blocked: - -``` -BLOCKED:reason goes here -``` +- PR created and reviews complete: + ``` + PHASE_COMPLETE + ``` +- Blocked: + ``` + BLOCKED:reason goes here + ``` diff --git a/codev/protocols/bugfix/protocol.md b/codev/protocols/bugfix/protocol.md index 29fb7ed5b..5854a9434 100644 --- a/codev/protocols/bugfix/protocol.md +++ b/codev/protocols/bugfix/protocol.md @@ -1,78 +1,72 @@ # BUGFIX Protocol -> Lightweight, issue-driven protocol for minor bug fixes. **Investigate → Fix → PR**, with a single `pr` gate before merge. No spec or plan artifacts: the GitHub issue is the spec, and the review goes in the PR body. +Investigate → Fix → PR, driven by a GitHub issue. No spec, no plan, no artifact files: the issue +is the specification and the PR body carries the reasoning. -## When to Use +Use it for a defect whose fix is isolated. For a small *feature* use AIR; for anything needing a +design decision use SPIR. -Use BUGFIX when a bug is reported as a GitHub Issue and: +## The state machine -- The reproduction is clear (or inferable) and the root cause is isolated -- The fix is small (guideline: < 300 LOC net diff) and contained to one area -- No architectural changes or new design decisions are needed - -Escalate to **SPIR** (or another heavier protocol) instead when: - -- It is actually a feature request, not a bug -- The root cause reveals a deeper architectural issue -- The fix needs design review, spans multiple components, or clearly exceeds ~300 LOC - -## Phases - -``` -investigate → fix → pr +```json +{{> protocols/bugfix/protocol.json}} ``` -### Investigate - -Read the issue, reproduce the bug, and identify the root cause. Confirm the fix fits BUGFIX scope. If it does not, signal `BLOCKED` and recommend escalation to the architect (`afx send architect "..."`). No code in this phase. - -### Fix +## Phases -Apply the minimal change that resolves the root cause, and add a regression test that fails without the fix and passes with it. Keep it focused: do not refactor surrounding code, do not fix unrelated bugs (file separate issues), do not add features. Run the build and tests (porch's `checks` block runs `npm run build` and `npm test`). +**Investigate** — reproduce the bug and identify the root cause. **No code in this phase.** +Confirm the fix fits BUGFIX scope; if it does not, signal `BLOCKED` and recommend escalation +rather than growing the project quietly. -Commit with the issue-driven format: +**Fix** — the minimal change that resolves the root cause, plus a regression test that **fails +without the fix and passes with it**. A test that passes either way documents nothing. Do not +refactor surrounding code, fix unrelated bugs (file separate issues), or add features. ``` -[Bugfix #] Fix: -[Bugfix #] Test: +[Bugfix #42] Fix: URL-encode username before API call +[Bugfix #42] Test: regression for unencoded username ``` -### PR (gated by `pr`) +**PR** — open with `gh pr create`, body carrying Summary, Root Cause, Fix and Test Plan plus +`Fixes #` so the issue closes on merge. Run one CMAP pass (Gemini, Codex, Claude), record +each verdict, and address or rebut every `REQUEST_CHANGES`. Notify the architect with the +verdicts, then `porch done ` and wait. -1. Push the branch and open a PR with `gh pr create`. The body includes Summary, Root Cause, Fix, and Test Plan, plus `Fixes #` so the issue auto-closes on merge. -2. Run a multi-agent CMAP review on the PR (Gemini, Codex, Claude) and record each verdict. Address or rebut any `REQUEST_CHANGES`; add a regression test if a real defect surfaced. -3. Notify the architect: `afx send architect "PR # ready for review (fixes #). CMAP: gemini=..., codex=..., claude=..."`. -4. Run `porch done ` to request the `pr` gate, then wait. **The merge is gated by porch state, never by typed prose in your pane.** -5. The human reviews the PR and the CMAP results on GitHub, then approves the gate: `porch approve pr --a-human-explicitly-approved-this`. -6. porch wakes the builder with a merge task. Merge with `gh pr merge --merge` (do **not** pass `--delete-branch`: the builder is checked out on this branch in a worktree), then run `porch done ` and notify the architect that it is merged and ready for cleanup. +Merge with `gh pr merge --merge`. **Do not pass `--delete-branch`** — the builder is checked out +on that branch in a worktree, and deleting it out from under them breaks the worktree. -## Gate +## The gate exists to make merge authorization structural -BUGFIX has one human gate, `pr`, on the merge step. It exists so the merge trigger is structured porch state (approved or not), not free-text typed into the builder's pane. This eliminates the self-merge bug class: a builder cannot infer authorization from ambiguous input. +BUGFIX has one human gate, `pr`. Its purpose is that the merge trigger is **porch state** — +approved or not — rather than free text typed into the builder's pane. That closes the +self-merge bug class: a builder cannot infer authorization from ambiguous prose. -## Multi-Agent Consultation +## Consultation -A single CMAP pass at the PR (Gemini, Codex, Claude). There is no per-phase consultation: the issue is the spec and the fix is small, so review effort concentrates on the final PR. +One CMAP pass at the PR. No per-phase consultation: the issue is the spec and the fix is small, +so review effort concentrates where it can still change the outcome. ## Scope -The < 300 LOC threshold is a **guideline**, measured as net diff (additions + deletions) anchored at the merge-base with the default branch. A well-contained 350-LOC fix is fine; a 200-LOC fix smeared across ten files may warrant escalation. +The <300 LOC threshold is a **guideline**, measured as net diff (additions + deletions) against +the merge-base with the default branch. A well-contained 350-line fix is fine; a 200-line fix +smeared across ten files probably warrants escalation. ## Escalation -If, mid-fix, the change outgrows BUGFIX (architectural impact, multiple components, unclear root cause after investigation, or more than ~300 LOC), notify the architect with specifics and recommend escalating to SPIR. Do not silently expand scope. - -## Branch Naming +If the change outgrows BUGFIX mid-flight — architectural impact, multiple components, unclear +root cause after investigation — notify the architect with specifics and recommend SPIR. **Do +not silently expand scope.** -``` -builder/bugfix-- -``` - -## Edge Cases +## Edge cases | Scenario | Action | |---|---| -| Cannot reproduce | Document the attempts in an issue comment, ask the reporter for detail, notify the architect | -| Fix outgrows scope (architectural / multi-component / > ~300 LOC) | Notify the architect, recommend escalation; do not proceed | -| Unrelated test failures | Out of scope: note them for the architect, do not fix them here | -| Multiple bugs in one issue | Fix only the primary bug; file separate issues for the rest | +| Cannot reproduce | Document the attempts on the issue, ask the reporter for detail, notify the architect | +| Fix outgrows scope | Notify the architect and recommend escalation; do not proceed | +| Unrelated test failures | Out of scope — note them for the architect, do not fix here | +| Multiple bugs in one issue | Fix the primary one; file separate issues for the rest | + +## Branch naming + +`builder/bugfix--` diff --git a/codev/protocols/experiment/builder-prompt.md b/codev/protocols/experiment/builder-prompt.md index 31c5581e5..20efb1ebe 100644 --- a/codev/protocols/experiment/builder-prompt.md +++ b/codev/protocols/experiment/builder-prompt.md @@ -1,82 +1,49 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are executing a disciplined experiment. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the EXPERIMENT protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Document your findings thoroughly + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way review** — always follow porch next → porch done cycle + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the EXPERIMENT protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. - -## EXPERIMENT Overview -The EXPERIMENT protocol ensures disciplined experimentation: -1. **Hypothesis Phase**: Define what you're testing and success criteria -2. **Design Phase**: Plan the experiment approach -3. **Execute Phase**: Run the experiment and gather data -4. **Analyze Phase**: Evaluate results and draw conclusions +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. -{{#if task}} ## Experiment Focus + {{task_text}} -{{/if}} ## Key Principles -- Start with a clear, falsifiable hypothesis -- Define success/failure criteria upfront -- Keep scope minimal for quick iteration -- Document findings regardless of outcome -- Separate experiment artifacts from production code -## If You Open a PR +- Start with a **clear, falsifiable hypothesis** and define success/failure criteria **upfront** — + an experiment scored after the fact always succeeds +- Keep scope minimal for fast iteration +- **Document findings regardless of outcome.** A directory containing only successes has been + curated, not run +- Keep experiment artifacts separate from production code -Most experiments are committed to a branch without a PR, but if you do open one -to integrate findings and the experiment was triggered by a GitHub issue: - -**PR body requirements**: The PR body MUST include `Closes #` (for feature -issues) or `Fixes #` (for bug issues) for the driving issue so GitHub -auto-closes it on merge. If the PR closes multiple issues, include one keyword -per issue. - -**Exception**: if this PR only partially addresses the issue (e.g. experiment -validates an approach but production implementation is deferred), use -`Refs #` or `Part of #` instead — the issue stays open until a follow-up -PR closes it. - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue with your work +## If You Open a PR -## Getting Started -1. Read the EXPERIMENT protocol document -2. Define your hypothesis clearly -3. Follow the phases in order +Most experiments are committed to a branch without a PR. If you do open one and the experiment +came from a GitHub issue, the body **must** carry `Closes #` (feature) or `Fixes #` (bug) +so GitHub auto-closes it on merge — one keyword per issue if several. ---- +**Exception**: if the PR only *partially* addresses the issue (the experiment validates an +approach but the production implementation is deferred), use `Refs #` or `Part of #` so +the issue stays open for the follow-up. -## Protocol Reference (full text) +## Notifications -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/experiment/protocol.md b/codev/protocols/experiment/protocol.md index 2e53487d4..1904727f7 100644 --- a/codev/protocols/experiment/protocol.md +++ b/codev/protocols/experiment/protocol.md @@ -1,203 +1,37 @@ # EXPERIMENT Protocol -## Overview +A disciplined experiment: state the hypothesis before running it, record what actually happened, +and keep the result whichever way it goes. -Disciplined experimentation: Each experiment gets its own directory with `notes.md` tracking goals, code, and results. +Use it for evaluating models or libraries, proof-of-concept work, and technique comparisons — +questions that should be settled by evidence rather than by argument. -**Core Principle**: Document what you're trying, what you did, and what you learned. - -## When to Use - -**Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes - -**Skip for**: Production code (use SPIR), simple one-off scripts - -## Structure - -``` -experiments/ -├── 1_descriptive_name/ -│ ├── notes.md # Goal, code, results -│ ├── experiment.py # Your experiment code -│ └── data/ -│ ├── input/ # Input data -│ └── output/ # Results, plots, etc. -└── 2_another_experiment/ - ├── notes.md - └── ... -``` - -## Workflow - -### 1. Create Experiment Directory - -```bash -# Create numbered directory -mkdir -p experiments/1_experiment_name -cd experiments/1_experiment_name - -# Initialize notes.md from template -touch notes.md # then fill it from the embedded template at the end of this protocol -``` - -Or ask your AI assistant: "Create a new experiment for [goal]" - -### 2. Document the Goal - -Before writing code, clearly state what you're trying to learn in `notes.md`: - -```markdown -## Goal - -What specific question are you trying to answer? -What hypothesis are you testing? -``` - -### 3. Write Experiment Code - -- Keep it simple - experiments don't need production polish -- Reuse existing project modules where possible -- Any structure is fine - focus on learning, not architecture - -**Dependencies**: If your experiment requires libraries not in the main project: -1. Do NOT add them to the main project's `requirements.txt` or `pyproject.toml` -2. Create a `requirements.txt` inside your experiment folder -3. Document installation in `notes.md` - -### 4. Run and Observe - -Execute your experiment and capture results: -- Save output files to `data/output/` -- Take screenshots of visualizations -- Log key metrics - -### 5. Document Results - -Update `notes.md` with: -- What happened (actual results) -- What you learned (insights) -- What's next (follow-up actions) - -### 6. Commit - -```bash -git add experiments/1_experiment_name/ -git commit -m "[Experiment 1] Brief description of findings" -``` - -## Best Practices - -### Keep It Simple -- Experiments don't need production polish -- Skip comprehensive error handling -- Focus on answering the question - -### Document Honestly -- Include failures - they're valuable learnings -- Note dead ends and why they didn't work -- Be specific about what surprised you - -### Track Time Investment -- Wall clock time: Total elapsed time -- Developer time: Active working time (excluding waiting) -- Helps estimate future similar work - -### Use Project Modules -- Don't duplicate existing code -- Import from your `src/` directory -- Experiments validate approaches, not reimplement them - -### Commit Progress -- Use `[Experiment ####]` commit prefix -- Commit intermediate results -- Include output files when reasonable - -## Integration with Other Protocols - -### Experiment → SPIR -When an experiment validates an approach for production use: - -1. Create a specification referencing the experiment -2. Link to experiment results as evidence -3. Use experiment code as reference implementation - -Example spec reference: -```markdown -## Background - -Experiment 5 validated that [approach] achieves [results]. -See: experiments/5_validation_test/notes.md -``` - -## Numbering Convention - -Use four-digit sequential numbering (consistent with project list): -- `1_`, `2_`, `3_`... -- Shared sequence across all experiments -- Descriptive name after the number (snake_case) - -Examples: -- `1_api_response_caching` -- `2_model_comparison` -- `3_performance_baseline` - -## Git Workflow - -### Commits -``` -[Experiment 1] Initial setup and goal -[Experiment 1] Add baseline measurements -[Experiment 1] Complete - caching improves latency 40% -``` - -### When to Commit -- After setting up the experiment -- After significant findings -- When completing the experiment - -**Data Management**: -- Include `data/output/` ONLY if files are small (summary metrics, small plots) -- Do NOT commit large datasets, binary model checkpoints, or heavy artifacts -- Add appropriate entries to `.gitignore` for large files -- Consider storing large outputs externally and linking in notes - -## Example Experiment +## The state machine -``` -experiments/1_caching_strategy/ -├── notes.md -├── benchmark.py -├── cache_test.py -└── data/ - ├── input/ - │ └── sample_requests.json - └── output/ - ├── results.csv - └── latency_chart.png +```json +{{> protocols/experiment/protocol.json}} ``` -**notes.md excerpt:** -```markdown -# Experiment 1: Caching Strategy Evaluation +## Structure -**Status**: Complete +Each experiment gets a numbered directory under `codev/experiments/` with a `notes.md` recording +the hypothesis, method, results and conclusion. -**Date**: 2024-01-15 +## Notes structure -## Goal -Determine if Redis caching improves API response times for repeated queries. +`notes.md` uses this structure: -## Results -- 40% latency reduction for cached queries -- Cache hit rate: 73% after warm-up -- Memory usage: 50MB for 10k cached responses +{{> protocols/experiment/templates/notes.md}} -## Next Steps -Create SPIR spec for production caching implementation. -``` +## The discipline that makes it worth doing -## Template: notes.md +**Write the hypothesis and the success criteria before running anything.** An experiment scored +after the fact always succeeds — you discover the criterion the result happens to meet. -Create `notes.md` with the following content: +**Record negative results.** "We tried X and it did not work, here is why" is the output that +saves the next person a week. An experiment directory containing only successes is a directory +that has been curated rather than run. -{{> protocols/experiment/templates/notes.md}} +**Keep the experiment separate from production code.** Experimental code answers a question; it +has not earned the standards production code is held to, and promoting it silently is how a +proof of concept becomes a maintenance burden nobody chose. diff --git a/codev/protocols/experiment/templates/notes.md b/codev/protocols/experiment/templates/notes.md index 18e1c63f6..42df40dda 100644 --- a/codev/protocols/experiment/templates/notes.md +++ b/codev/protocols/experiment/templates/notes.md @@ -1,97 +1,37 @@ # Experiment ####: Name -**Status**: In Progress | Complete | Disproved | Aborted - -**Date**: YYYY-MM-DD +**Status**: In Progress | Complete | Disproved | Aborted · **Date**: YYYY-MM-DD ## Goal -What are you trying to learn or test? Be specific about: -- The question you're answering -- The hypothesis you're testing -- Success criteria (how will you know if it worked?) - -## Effort - -**Approximate time spent**: [e.g., "4 hours"] - -*(Optional: Break down into setup, coding, analysis if helpful)* +The question you are answering, the hypothesis you are testing, and the success criteria — how you will know if it worked. ## Approach -Brief description of the approach being tested: -- Key technique or method -- Why this approach was chosen -- Any alternatives considered +The technique being tested, why it was chosen, and any alternatives considered. ## Environment & Reproduction -**How to run**: -```bash -# Command to reproduce results -python experiment.py --input data/input/sample.json -``` - -**Dependencies** (if different from main project): -- List any additional packages required -- Or reference: `pip install -r requirements.txt` - -**Environment notes**: -- Python version, key library versions if relevant -- Any seeds or configuration needed for reproducibility +How to run it (the exact command), any dependencies beyond the main project, and the version/seed/config notes needed to reproduce the result. ## Code -List your experiment files: -- [`experiment.py`](experiment.py) - Brief description -- [Other files as needed] +The experiment files, each with a one-line description. ## Results -### Summary - -One-paragraph summary of key findings. - -### Key Findings - -1. **Finding one**: Description and significance -2. **Finding two**: Description and significance -3. **Finding three**: Description and significance - -### Metrics +A one-paragraph summary, then the key findings and the metrics that support them. | Metric | Value | Notes | |--------|-------|-------| -| Metric 1 | Value | Context | -| Metric 2 | Value | Context | - -### Output Files - -- `data/output/results.csv` - Raw results data -- `data/output/chart.png` - Visualization of findings +| | | | -## What Worked +Output artifacts (data, charts) with their paths. -- List things that went well -- Approaches that proved effective -- Useful discoveries +## What Worked / What Didn't -## What Didn't Work - -- Failed approaches (and why) -- Dead ends encountered -- Surprising obstacles +What proved effective, and the failed approaches or dead ends (with why). ## Next Steps -Based on these findings: - -1. **Immediate**: What should happen right after this experiment? -2. **Follow-up experiments**: What new questions emerged? -3. **Production path**: If validated, what's needed for production? (SPIR spec?) - -## References - -- Links to relevant documentation -- Related experiments -- External resources consulted +The immediate next action, any follow-up experiments the findings raised, and — if validated — the production path (e.g. a SPIR spec). diff --git a/codev/protocols/maintain/builder-prompt.md b/codev/protocols/maintain/builder-prompt.md index 6a2deda0d..9fc5949b8 100644 --- a/codev/protocols/maintain/builder-prompt.md +++ b/codev/protocols/maintain/builder-prompt.md @@ -1,62 +1,41 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are executing the MAINTAIN protocol to clean up and synchronize the codebase. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the MAINTAIN protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Work through each step methodically + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the MAINTAIN protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. ## MAINTAIN Overview -Two phases: -1. **Maintain**: Single pass — audit findings, clean dead code, sync docs, verify build -2. **Review**: Create PR with 3-way consultation +Two phases: **Maintain** (one pass — audit, clean, sync docs, verify build) then **Review** +(PR with 3-way consultation). ## Key Rules -- Use soft deletion (move to `codev/maintain/.trash/`) -- Verify build passes after each removal (`cd packages/codev && pnpm build && pnpm test`) -- Update documentation to match current architecture -- Don't remove anything actively used -- One removal at a time — commit after each -- Document every deletion with justification -- Never use `git add -A` or `git add .` - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your maintenance run file -5. Commit the skip and continue with your work - -## Getting Started -1. Read the MAINTAIN protocol document -2. Run `porch next` to get your first task -3. Work through audit → clean → sync → verify in a single pass -4. Document everything in the maintenance run file - ---- - -## Protocol Reference (full text) - -{{protocol_reference}} + +- **Soft-delete**: move removals to `codev/maintain/.trash/`, do not delete outright +- Verify the build after each removal (`cd packages/codev && pnpm build && pnpm test`) +- **One removal at a time, commit after each** — a bundled cleanup commit cannot be bisected +- Treat every audit hit as a *candidate*: a detector cannot tell "vestigial" from "used by a + path you did not search". Confirm with a targeted grep before removing +- Don't remove anything actively used; document every deletion with its justification +- Never `git add -A` / `--all` / `.` — stage each file explicitly by path + +## Notifications + +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/maintain/consult-types/impl-review.md b/codev/protocols/maintain/consult-types/impl-review.md index de01b8d00..7028b4947 100644 --- a/codev/protocols/maintain/consult-types/impl-review.md +++ b/codev/protocols/maintain/consult-types/impl-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev/protocols/maintain/consult-types/pr-review.md b/codev/protocols/maintain/consult-types/pr-review.md index 837cdea33..6b9a3e82a 100644 --- a/codev/protocols/maintain/consult-types/pr-review.md +++ b/codev/protocols/maintain/consult-types/pr-review.md @@ -1,44 +1,24 @@ # PR Ready Review Prompt ## Context -You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. -## Focus Areas - -1. **Completeness** - - Are all spec requirements implemented? - - Are all plan phases complete? - - Is the review document written (`codev/reviews/XXXX-name.md`)? - - Are all commits properly formatted (`[Spec XXXX][Phase]`)? - -2. **Test Status** - - Do all tests pass? - - Is test coverage adequate for the changes? - - Are there any skipped or flaky tests? +You are performing the final self-check during the Review phase — the builder has completed all implementation phases and is about to open the PR. This is the last check before the work goes to the architect for integration review. -3. **Code Cleanliness** - - Is there any debug code left in? - - Are there any TODO comments that should be resolved? - - Are there any `// REVIEW:` comments that weren't addressed? - - Is the code properly formatted? - -4. **Documentation** - - Are inline comments clear where needed? - - Is the review document comprehensive? - - Are any new APIs documented? +## Focus Areas -5. **PR Readiness** - - Is the branch up to date with its base (the integration branch the PR targets)? - - Are commits atomic and well-described? - - Is the change diff reasonable in size? +- **Completeness** — all spec requirements implemented, all plan phases complete, the review document written (`codev/reviews/XXXX-name.md`), and commits in the `[Spec XXXX][Phase]` format. +- **Test Status** — all tests pass, coverage is adequate for the changes, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO` / `// REVIEW:` left unaddressed, code properly formatted. +- **Documentation** — inline comments clear where needed, the review document comprehensive, new APIs documented. +- **PR Readiness** — the branch is up to date with its base (the integration branch the PR targets), commits are atomic and well-described, and the diff size is reasonable. ## Scope -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -63,14 +43,8 @@ PR_SUMMARY: | - [How to test] ``` -**Verdict meanings:** -- `APPROVE`: Ready to create PR -- `REQUEST_CHANGES`: Issues to fix before PR creation -- `COMMENT`: Minor items, can create PR but note feedback - -## Notes +- `APPROVE`: ready to create the PR. +- `REQUEST_CHANGES`: issues to fix before PR creation. +- `COMMENT`: minor items; can create the PR but note the feedback. -- This is the builder's final self-review before hand-off -- The PR_SUMMARY in your output can be used as the PR description -- Focus on "is this ready for someone else to review" not "is this perfect" -- Any issues found here are cheaper to fix than during integration review +The `PR_SUMMARY` block can be used directly as the PR description. diff --git a/codev/protocols/maintain/prompts/maintain.md b/codev/protocols/maintain/prompts/maintain.md index 3c83f404d..620155f21 100644 --- a/codev/protocols/maintain/prompts/maintain.md +++ b/codev/protocols/maintain/prompts/maintain.md @@ -47,7 +47,7 @@ For each audit finding: 3. Build and test: `cd packages/codev && pnpm build && pnpm test` 4. Commit: `git add && git commit -m "[Maintain] Remove unused X"` -One removal at a time. Verify after each. Never use `git add -A`. +One removal at a time, verified after each — staging only the specific files that removal touched. ## Step 4: Sync Documentation diff --git a/codev/protocols/maintain/protocol.md b/codev/protocols/maintain/protocol.md index 08199b956..a75057cda 100644 --- a/codev/protocols/maintain/protocol.md +++ b/codev/protocols/maintain/protocol.md @@ -1,241 +1,50 @@ # MAINTAIN Protocol -## Overview +Audit → Clean → Sync, in a single pass, then a PR. Two phases, one consultation during the +maintain phase and one before the PR. -MAINTAIN is a single-pass maintenance protocol for keeping codebases healthy. The builder does all maintenance work in one phase, then creates a PR with a 3-way review. +Use it for dead code and unused dependencies, quarterly hygiene, pre-release cleanup, and +keeping the governance docs honest — `arch.md`/`arch-critical.md`, +`lessons-learned.md`/`lessons-critical.md`, and the `CLAUDE.md`↔`AGENTS.md` twins. -**Core Principle**: Do the work in one pass. Don't over-ceremonialize housekeeping. +## The state machine -**Key Documents** MAINTAIN keeps current: -- `codev/resources/arch.md` (COLD reference) + `codev/resources/arch-critical.md` (HOT, always-injected) — Architecture, two tiers (Spec 987) -- `codev/resources/lessons-learned.md` (COLD reference) + `codev/resources/lessons-critical.md` (HOT, always-injected) — Engineering wisdom, two tiers - -The two governance docs are siblings with **different purposes**: `arch.md` owns system shape (services, transports, mental models, verified-wrong assumptions about *this* system); `lessons-learned.md` owns durable engineering wisdom that applies *across* specs. Use the routing matrix below to decide where each fact belongs. - -### Lives where: routing facts to the right home - -| Type of fact/insight | Lives in | -|---|---| -| Current system shape (services, transports, key mental models) | `codev/resources/arch.md` | -| Mechanism for a unique subsystem | `codev/resources/arch.md` (subsystem section) OR a meta-spec under `codev/architecture/.md` if the mechanism is large enough to warrant its own doc | -| A durable engineering pattern that applies across multiple specs | `codev/resources/lessons-learned.md` (COLD reference) | -| A **behavior-changing, cross-cutting** rule (should change how the next project is built) | `codev/resources/lessons-critical.md` (HOT, capped) — demote to `lessons-learned.md` if full | -| A **behavior-changing, cross-cutting** architecture invariant (a future builder must know up front) | `codev/resources/arch-critical.md` (HOT, capped) — demote to `arch.md` if full | -| A spec-narrow fix recipe (reference detail) | `codev/resources/lessons-learned.md` (COLD) — kept as reference; **never** the hot file | -| A system-shape surprise verified-wrong in production ("looks like X but isn't") | `codev/resources/arch.md` § "Verified-Wrong Assumptions" | -| Aspirational architectural direction (where we want to go) | The relevant meta-spec or roadmap doc, NOT `arch.md` body | -| A changelog entry ("we shipped X in spec Y on date Z") | `git log` + the spec/review document — NOT `arch.md`, NOT `lessons-learned.md` | -| A retired or removed component | Delete the section entirely; do NOT keep a "retired components" graveyard. (`git log` retains history.) | - -The most commonly-misrouted entry is the system-shape surprise. If a future reader needs to know "the system *looks* like X but actually does Y," that is system shape and lives in `arch.md`. If they need to know "we learned that doing X is generally a bad idea," that is engineering wisdom and lives in `lessons-learned.md`. - -## When to Use - -- Before a release (clean slate for shipping) -- After completing a major feature -- Quarterly maintenance window -- When the codebase feels "crusty" - -## Execution Model - -``` -afx spawn --protocol maintain - ↓ -1. MAINTAIN: Audit → Clean → Sync docs (single pass) - ↓ (build + test checks, 3-way review) -2. REVIEW: Create PR - ↓ (3-way review) -Architect reviews → Merge -``` - -Two phases total. One consultation during the maintain phase, one before PR. - -## Prerequisites - -Before starting: -1. Check `codev/maintain/` for the last run number -2. Note the base commit: `git log --oneline -1` on the last run file -3. Focus on changes since then: `git log --oneline ..HEAD` - ---- - -## The Maintain Phase (Single Pass) - -The builder works through these tasks in order, committing as they go. - -### Step 1: Audit - -Identify what needs fixing. Don't fix yet — just catalog. - -**Dead code**: -```bash -# Find unused exports (TypeScript) -npx ts-prune 2>/dev/null || echo "ts-prune not available" - -# Find unused dependencies -npx depcheck 2>/dev/null || echo "depcheck not available" -``` - -**Stale documentation**: -```bash -# What changed since last maintenance? -git log --oneline ..HEAD - -# Check arch.md references still exist -grep -oE '[a-zA-Z]+/[a-zA-Z/]+\.[a-z]+' codev/resources/arch.md | sort -u | while read f; do - [ -e "$f" ] || echo "Missing: $f" -done -``` - -**Stale project tracking**: -- GitHub Issues that should be closed -- Labels that need updating - -Record findings in the maintenance run file (`codev/maintain/NNNN.md`). - -### Step 2: Clean - -For each finding from the audit: -1. Verify it's truly unused (grep the codebase) -2. Remove it (use `git rm` for tracked files) -3. Verify build + tests still pass -4. Commit with `[Maintain] Remove unused X` - -**Rules**: -- One removal at a time — don't batch unrelated changes -- Verify after each removal — build must pass -- Use soft deletion for untracked files: `mv file codev/maintain/.trash/$(date +%Y-%m-%d)/` -- Never use `git add -A` or `git add .` - -### Step 3: Sync Documentation - -Step 3 is split into two sub-steps: **Audit first, then update.** This split exists because `arch.md` and `lessons-learned.md` accumulate without bound when MAINTAIN does only "what's new" — the audit pass surfaces what should be cut so the update pass is not purely additive. - -The `update-arch-docs` skill (at `.claude/skills/update-arch-docs/SKILL.md`) is invoked by both sub-steps. Read it before starting Step 3 so the discipline is fresh. - -#### Step 3a: Audit documentation - -Invoke the `update-arch-docs` skill in **audit-mode**. The skill reads all four governance files — `codev/resources/arch.md` / `arch-critical.md` and `codev/resources/lessons-learned.md` / `lessons-critical.md` — end-to-end against the discipline below, applies the cuts via the Edit tool, and records each cut's reason in the run file (`codev/maintain/NNNN.md`) under a `## Audit Findings` section. The diff plus the recorded reasons **is** the proposal; the architect's PR review is the human-confirmation step (consistent with the skill's audit-mode). - -**Per-arch.md-section pruning checklist** — for each section in `arch.md`, ask: -- Does it describe **current state**? If aspirational, the section moves to a meta-spec; `arch.md` keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own). -- Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer. -- Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files. -- Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing. -- Is the component still alive? If retired, delete the section entirely. - -**Per-COLD-`lessons-learned.md`-entry pruning checklist** — for each entry, ask: -- Is it terse (1–3 sentences)? If multi-paragraph, split or compress. -- Is the topic section the right home? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home. -- Is it a duplicate of an adjacent entry? If yes, fold them. -- (Spec-narrow recipes are **kept** as reference — do not cut them just for being spec-narrow. Anti-accretion now lives in the hot cap, not the cold archive.) - -**Per-HOT-file checklist** (`arch-critical.md`, `lessons-critical.md`) — audit the cap and map: -- Within the cap (≈10 entries + a ≈12-topic map, ≤35 lines)? If over, **demote** the weakest entries into the cold doc. -- Does every map topic name a real top-level cold-doc section, and is any new/renamed section reflected? Fix drift; keep the map top-level only. -- Is every entry still behavior-changing? Demote reference detail into the cold archive. - -**Sample audit prompt** (paste into the skill invocation if you want a baseline checklist run): - -``` -Audit all four governance files — codev/resources/arch.md + arch-critical.md and -lessons-learned.md + lessons-critical.md — against the discipline in the -update-arch-docs skill. For each cold section/entry run the cold pruning checklists, -and for each hot file check the cap, displacement, and map accuracy (Step 3a). -Apply the cuts with one-line reasons. Bias toward fewer, higher-confidence -cuts ("when in doubt, KEEP"). Record each cut's reason in the current run -file's ## Audit Findings section as you go — the diff plus those reasons is the proposal. +```json +{{> protocols/maintain/protocol.json}} ``` -**When in doubt, KEEP.** This rule is preserved from the older Step 3. A confident cut is better than three speculative ones. The audit pass is a *proposal*; the architect's PR review confirms it. - -#### Step 3b: Update documentation - -Apply the audit decisions from Step 3a, plus any additive content needed. - -**arch.md / arch-critical.md**: Compare documented structure with actual codebase. Route behavior-changing invariants to `arch-critical.md` (HOT — respect the cap + keep its map accurate); reference detail to `arch.md` (COLD). Update: -- Directory structure -- Component descriptions (explain HOW things work, not just WHAT) -- Key files and their purposes -- Remove references to deleted code (per Step 3a audit findings) -- Add new components/utilities - -**lessons-learned.md / lessons-critical.md**: Scan `codev/reviews/` for new reviews since last run. **Route** each new lesson by tier — behavior-changing + cross-cutting → `lessons-critical.md` (HOT; respect the cap, demote a weaker entry to cold if full); reference recipe / spec-narrow → `lessons-learned.md` (COLD). Apply Step 3a's per-entry cuts and keep each hot file's cold-doc map accurate. - -For specific additive changes, invoke `update-arch-docs` in **diff-mode** — it applies the smallest section update needed. +## Before starting -**CLAUDE.md / AGENTS.md**: Diff the two files. They must be identical. Update the stale one. +Find the last run in `codev/maintain/`, note its base commit, and scope the audit to +`git log --oneline ..HEAD`. Maintenance without a since-marker re-audits the whole +repository every time and quietly stops being run. -**Documentation pruning**: -- Remove obsolete references -- ~400 line guideline for CLAUDE.md/README.md (not a hard limit) -- Document every deletion with justification (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE) -- When in doubt, KEEP the content +## The maintain phase -### Step 4: Final Checks +**Audit** — find unused exports, unused dependencies, and orphaned files. Treat every hit as a +*candidate*, not a verdict: a detector cannot tell "vestigial" from "used by a path you did not +search". Confirm each with a targeted grep before removing it. -```bash -# Build and test from the package directory -cd packages/codev && pnpm build && pnpm test -``` - -Both must pass before moving to the review phase. +**Clean** — remove what you confirmed. Deletions go to `codev/maintain/.trash/` (gitignored, +30-day retention) rather than straight out, so a wrong call is recoverable for a month rather +than needing an archaeology session. ---- +**Sync documentation** — route facts by tier rather than appending: behaviour-changing and +cross-cutting go to the capped hot files (displace a weaker entry rather than growing them), +reference detail to the cold archives. The `update-arch-docs` skill encodes the routing matrix, +the caps, and what does *not* belong in each tier. Keep `CLAUDE.md` and `AGENTS.md` +byte-identical. -## Maintenance Run File +## The maintenance run file -Each run creates `codev/maintain/NNNN.md`, following the template below: +Each run is recorded in `codev/maintain/` using this structure: {{> protocols/maintain/templates/maintenance-run.md}} -Keep it factual and short. The run file documents what happened, not what might happen. - ---- - -## Commit Messages - -``` -[Maintain] Remove 5 unused exports -[Maintain] Remove http-proxy dependency -[Maintain] Update arch.md — add VS Code extension, remove dashboard-server refs -[Maintain] Generate lessons-learned.md from reviews 653, 672 -[Maintain] Sync CLAUDE.md with AGENTS.md -``` - ---- - -## Governance - -MAINTAIN is an operational protocol, not a feature protocol: - -| Document | Required? | -|----------|-----------| -| Spec | No | -| Plan | No | -| Review | No (maintenance run file serves this purpose) | -| Consultation | Yes — 3-way review before PR | - -If maintenance reveals need for architectural changes, those should follow SPIR. - ---- - -## Rules - -1. **Don't be aggressive** — when in doubt, KEEP the content -2. **Check git blame** — understand why code/docs exist before removing -3. **Run full test suite** — not just affected tests -4. **Group related changes** — one commit per logical change -5. **Document every deletion** — what, why, and where (if moved) -6. **Prefer moving over deleting** — extract to another file rather than removing -7. **Size targets are guidelines** — never sacrifice clarity to hit a line count +## Scope discipline -## Anti-Patterns +Maintenance is where scope creep is most tempting, because everything you touch looks +improvable. Removing dead code is in scope; refactoring live code because you are already in the +file is not. File an issue instead. -1. Aggressive rewriting without explanation -2. Deleting without documenting why -3. Hitting line count targets at all costs -4. Removing "patterns" or "best practices" sections without explicit approval -5. Deleting everything the audit finds — review each item individually -6. Skipping validation — "it looked dead" is not validation -7. Using `rm` instead of `git rm` +Never `git add -A` / `--all` / `.` — stage each file explicitly by path. diff --git a/codev/protocols/maintain/templates/audit-report.md b/codev/protocols/maintain/templates/audit-report.md index 2dfb6c192..33f1d7402 100644 --- a/codev/protocols/maintain/templates/audit-report.md +++ b/codev/protocols/maintain/templates/audit-report.md @@ -1,192 +1,46 @@ # Cleanup Audit Report -## Metadata -- **Date**: YYYY-MM-DD -- **Project**: -- **Auditor**: -- **Categories**: dead-code, dependencies, docs, tests, temp, metadata -- **Tools Used**: - -## Summary - -| Category | Items Found | Approved for Removal | -|----------|-------------|---------------------| -| Dead Code | 0 | 0 | -| Dependencies | 0 | 0 | -| Documentation | 0 | 0 | -| Tests | 0 | 0 | -| Temp Files | 0 | 0 | -| Metadata | 0 | 0 | -| **Total** | **0** | **0** | +**Date**: YYYY-MM-DD · **Project**: · **Auditor**: ## Pre-Audit Checks - [ ] Git working directory is clean -- [ ] All tests are currently passing +- [ ] All tests currently passing - [ ] No pending merges or PRs in flight ---- - -## Dead Code - -### Unused Exports - -**Tool**: `npx ts-prune` / `ruff check --select F401` / other - -| Approve | File | Line | Export | Tool Output | Owner Decision | -|---------|------|------|--------|-------------|----------------| -| | | | | | | - -### Unreachable Code - -**Tool**: static analysis / manual review - -| Approve | File | Line | Description | Tool Output | Owner Decision | -|---------|------|------|-------------|-------------|----------------| -| | | | | | | - -### Unused Files - -**Tool**: `grep -r "import.*from"` analysis / IDE unused file detection - -| Approve | File | Tool Output | Owner Decision | -|---------|------|-------------|----------------| -| | | | | - ---- - -## Unused Dependencies - -### npm packages - -**Tool**: `npx depcheck` - -| Approve | Package | Version | Tool Output | Owner Decision | -|---------|---------|---------|-------------|----------------| -| | | | | | - -### Python packages - -**Tool**: `pip-autoremove --list` / `deptry` - -| Approve | Package | Tool Output | Owner Decision | -|---------|---------|-------------|----------------| -| | | | | - ---- - -## Stale Documentation - -**Tool**: manual review / link checker - -| Approve | File | Issue | Suggestion | Owner Decision | -|---------|------|-------|------------|----------------| -| | | | | | - ---- - -## Test Infrastructure - -### Test Status -- All tests passing: [ ] Yes / [ ] No -- If no, which tests are failing? - -### Orphaned Test Files - -**Tool**: cross-reference with deleted features - -| Approve | File | Reason | Owner Decision | -|---------|------|--------|----------------| -| | | | | - -### Low-ROI Tests - -**Tool**: test coverage analysis / flaky test detection - -| Approve | File | Reason | Owner Decision | -|---------|------|--------|----------------| -| | | | | - -### Orphaned Fixtures - -**Tool**: grep for fixture usage - -| Approve | File | Reason | Owner Decision | -|---------|------|--------|----------------| -| | | | | - ---- - -## Temporary Files - -**Tool**: `find` / `du -sh` - -| Approve | Path | Type | Size | Owner Decision | -|---------|------|------|------|----------------| -| | | | | | - ---- - -## Metadata Updates Required - -### projectlist.md +## Summary -| Approve | Entry | Current Status | Suggested Action | Owner Decision | -|---------|-------|----------------|------------------|----------------| -| | | | | | +One row per category; totals reconcile against the findings below. -### AGENTS.md / CLAUDE.md +| Category | Items Found | Approved for Removal | +|----------|------------:|---------------------:| +| Dead code (unused exports, unreachable code, unused files) | 0 | 0 | +| Dependencies (npm, Python) | 0 | 0 | +| Documentation (stale, broken links) | 0 | 0 | +| Tests (orphaned files, low-ROI, orphaned fixtures) | 0 | 0 | +| Temp files | 0 | 0 | +| Metadata (projectlist, AGENTS/CLAUDE, arch) | 0 | 0 | +| **Total** | **0** | **0** | -| Approve | Section | Issue | Suggestion | Owner Decision | -|---------|---------|-------|------------|----------------| -| | | | | | +## Findings -### arch.md +One table per category that has findings, using this schema (add/drop columns as the category needs — dependencies use Package/Version, temp files use Path/Size). Name the tool that surfaced each item so the owner can verify it. -| Approve | Section | Issue | Suggestion | Owner Decision | -|---------|---------|-------|------------|----------------| +| Approve | Location (`file:line` / package / path) | Item | Tool + output | Owner decision | +|:-------:|------------------------------------------|------|---------------|----------------| | | | | | | ---- +Typical tools: `npx ts-prune` / `ruff check --select F401` (unused exports), `npx depcheck` / `deptry` (dependencies), link checker (docs), coverage + flaky detection (tests), `find` / `du -sh` (temp files). ## Recommendations -### High Priority (Should Remove) -1. - -### Medium Priority (Likely Safe) -1. - -### Low Priority / Needs Investigation -1. - -### Do Not Remove -1. - ---- +Grouped by confidence: **Should remove** · **Likely safe** · **Needs investigation** · **Do not remove** (with reason). ## Rollback Notes -If VALIDATE fails, document restoration steps here: - -| Item | Restoration Command | Notes | -|------|---------------------|-------| -| Tracked files | `git revert HEAD` or `git checkout HEAD~1 -- path/to/file` | | -| Untracked files | `./codev/cleanup/.trash/YYYY-MM-DD-HHMM/restore.sh` | | - ---- +Restoration path if VALIDATE fails — tracked files via `git revert` / `git checkout HEAD~1 -- `; untracked via the dated `codev/cleanup/.trash/…/restore.sh`. ## Approval -- [ ] Human has reviewed all items -- [ ] Checkboxes marked for approved items -- [ ] Ready to proceed to PRUNE phase - -**Reviewed by**: _________________ **Date**: _________________ - ---- - -## Notes - - - +- [ ] Human reviewed all items and marked the approved ones. +- [ ] Ready to proceed to the PRUNE phase. diff --git a/codev/protocols/maintain/templates/maintenance-run.md b/codev/protocols/maintain/templates/maintenance-run.md index a55110215..1d8e1a147 100644 --- a/codev/protocols/maintain/templates/maintenance-run.md +++ b/codev/protocols/maintain/templates/maintenance-run.md @@ -33,7 +33,7 @@ Recorded by Step 3a (Audit documentation) as the cuts are applied — one line p ### Documentation Changes Log | Document | Section | Action | Reason | |----------|---------|--------|--------| -| arch.md | "Dashboard Server" | DELETED | OBSOLETE — replaced by Tower | +| | | | | ## Deferred diff --git a/codev/protocols/pir/builder-prompt.md b/codev/protocols/pir/builder-prompt.md index 86016f310..c99fd2985 100644 --- a/codev/protocols/pir/builder-prompt.md +++ b/codev/protocols/pir/builder-prompt.md @@ -1,38 +1,24 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are implementing a fix or feature driven by a GitHub issue, using the PIR protocol. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the PIR protocol document yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Run consultations manually when the protocol calls for them -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals -- Do not deviate from the porch-driven workflow - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip consultations** — porch handles them via the verify step -- **NEVER advance phases manually** — porch handles phase transitions on gate approval + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the PIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. -PIR has three phases: -1. **plan** (gated by `plan-approval`) — write `codev/plans/{{artifact_name}}.md`, await human review -2. **implement** (gated by `dev-approval`) — write code + tests, run build/tests, push branch; await the human's review of the *running worktree* (no file artifact in this phase — dev-approval summary is prose-in-pane) -3. **review** (gated by `pr`) — write `codev/reviews/{{artifact_name}}.md` (retrospective with Architecture Updates and Lessons Learned sections), open PR with the review as body, record the PR with porch, run 3-way consultation (Gemini, Codex, Claude) via porch's verify block (a **single advisory pass** — `max_iterations: 1`, no iterate-until-APPROVE loop; address or rebut any `REQUEST_CHANGES`, add a regression test if it's a real defect, and escalate it in the architect notification since PIR will not re-review it), notify architect, and wait at the `pr` gate. After the human approves the gate (porch wakes you with "Gate pr approved"), run `gh pr merge --merge` and record the merge with `porch done --merged `. **Merge is gated by porch state — never by typed prose in your pane.** +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. {{#if issue}} ## Issue #{{issue.number}} @@ -44,54 +30,31 @@ PIR has three phases: ## Sitting at Gates -PIR has two human gates. When you reach one: - -1. Finish your phase work and run `porch done ` -2. Run `porch next ` — you'll get a `gate_pending` response -3. End your turn with a short prose summary: what file you wrote, where it lives, how to approve -4. **Stay in the interactive session**. Do NOT exit. Wait for the user's next message. +PIR has two pre-PR human gates. When you reach one: -The reviewer can give feedback by: -- Editing the plan file (at the plan-approval gate) or the code itself (at the dev-approval gate) in the worktree directly — you'll see changes via `git diff` -- Typing into your PTY pane (this reaches you live) -- `afx send ""` (queued; check on next turn) -- Commenting on the GitHub issue (re-fetch with `gh issue view --comments` if asked) - -When the user provides feedback, revise the artifact, recommit, and ask if there's more to address. The gate remains pending until the user runs `porch approve` — do NOT call `porch approve` yourself. - -## Notifications -Use `afx send architect "..."` at key moments: -- **PR ready**: `afx send architect "PR # ready for review (PIR #{{issue.number}})"` -- **PR merged**: `afx send architect "PR # merged for PIR #{{issue.number}}. Ready for cleanup."` -- **Blocked**: `afx send architect "Blocked on PIR #{{issue.number}}: [reason]"` +1. Finish the phase work and run `porch done ` +2. Run `porch next ` — you get a `gate_pending` response +3. End your turn with a short summary: what you wrote, where it lives, how to approve +4. **Stay in the interactive session. Do not exit.** Wait for the next message. -**Gates are not architect-notified.** When porch transitions a gate to `pending`, the gate-reached message (including the `porch approve --a-human-explicitly-approved-this` invocation) appears in YOUR pane as part of your normal output. That's the universal notification surface — visible whether the user is in VSCode, tmux, plain Terminal, or any other host. The user reads it directly from your pane (or runs `porch pending` from a shell) and approves themselves; the architect can't approve gates, so notifying it would be informational noise. +Feedback can arrive four ways, and all of them reach you: the reviewer editing the plan file or +the code directly in the worktree (you see it via `git diff`), typing into your PTY pane (live), +`afx send ` (queued — check next turn), or a comment on the GitHub issue +(re-fetch with `gh issue view --comments`). -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in the review file under a `## Flaky Tests` section -5. Commit the skip and continue with your work +Revise, recommit, ask whether more remains. **The gate stays pending until the human runs +`porch approve` — never call it yourself.** ## Resumption After Crash -If your Claude session crashes mid-flow, Tower's `while true` loop will relaunch you with the same prompt. On startup: - -1. Run `porch next {{project_id}}` to learn what phase you're in -2. If `gate_pending`: read the latest plan file (plan-approval) or `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); git diff "$(git merge-base "${DEFAULT_BRANCH:-main}" HEAD)"` (dev-approval) plus any new GitHub issue comments; check `afx send` queue. Decide whether to revise or just announce you're back. -3. Otherwise: pick up where you left off - -## Getting Started +If your session crashes, Tower's `while true` loop relaunches you with the same prompt: -1. Read the PIR protocol (provided inline in this prompt). -2. Run `porch next {{project_id}}` to see what to do next -3. Begin work +1. `porch next {{project_id}}` to learn what phase you are in +2. If `gate_pending`: read the latest plan file (plan-approval), or the diff (dev-approval) via + `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); git diff "$(git merge-base "${DEFAULT_BRANCH:-main}" HEAD)"`, plus any new issue comments and your `afx send` queue. Decide whether to revise or just announce you are back +3. Otherwise pick up where you left off ---- - -## Protocol Reference (full text) +## Notifications -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/pir/consult-types/impl-review.md b/codev/protocols/pir/consult-types/impl-review.md index 380bceee9..6cbae9f84 100644 --- a/codev/protocols/pir/consult-types/impl-review.md +++ b/codev/protocols/pir/consult-types/impl-review.md @@ -2,47 +2,27 @@ ## Context -You are reviewing the implementation of a PIR protocol project before it reaches the `dev-approval` human gate. A builder has implemented the approved plan and written a dev-approval summary. Your job is to verify the implementation matches the plan and is ready for human review. +You are reviewing a PIR implementation before it reaches the `dev-approval` human gate. A builder has implemented the approved plan and written a dev-approval summary. Verify the implementation matches the plan and is ready for human review. -## CRITICAL: Verify Before Flagging +## Verify before flagging -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -## Focus Areas - -1. **Plan Adherence** - - Does the implementation fulfill the approved plan? - - Are all "Files to Change" actually changed? - - Are the changes scoped to what the plan described, or has scope crept? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs? - - Are error cases handled appropriately? - - Is the change minimal — no unnecessary refactoring or unrelated tidy-ups? - -3. **Test Coverage** - - Are the tests adequate for the changes? - - Do tests cover both the main path and the edge cases the plan called out? - - For a bug fix: is there a regression test that would fail without the fix? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Review File Quality** - - Does `codev/reviews/-.md` exist and follow the template? - - Does it accurately describe what changed? - - Is "Things to Look At" honest about tricky spots? - - Is "How to Test Locally" specific enough that the human reviewer can act on it? +## Focus Areas -5. **PIR-Specific Concerns** - - For UI / mobile / cross-platform changes: does the review file explain platform-specific behavior the human should verify? - - For changes with external integrations: are the integration points documented? +- **Plan Adherence** — the implementation fulfills the approved plan; every "Files to Change" is changed; the change is scoped to the plan, no creep. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled; the change is minimal, with no unrelated refactors. +- **Test Coverage** — tests are adequate and cover the plan's main path and edge cases; a bug fix has a regression test that would fail without the fix. +- **Review File Quality** — `codev/reviews/-.md` exists, follows the template, describes what changed accurately, is honest in "Things to Look At", and specific enough in "How to Test Locally" for the human to act on. +- **PIR-Specific Concerns** — for UI / mobile / cross-platform changes, the review file explains platform-specific behavior the human should verify; for external integrations, the integration points are documented. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -56,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Ready for human at the `dev-approval` gate -- `REQUEST_CHANGES`: Issues that must be fixed before reaching the human -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: ready for the human at the `dev-approval` gate. +- `REQUEST_CHANGES`: issues that must be fixed before reaching the human. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scope -- **DO** review the implementation against the approved plan -- **DO** flag missing regression tests for bug fixes -- **DO** flag obvious bugs, code smells, security issues -- **DO NOT** redesign the approach — that was settled at `plan-approval` -- **DO NOT** demand changes outside the plan's scope -- **DO NOT** request architecture-level refactors unless the change introduces a clear new problem - -## Notes - -- This is a pre-gate review; the human is the final authority -- Focus on "is this ready for someone else to test in a browser / simulator" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to iterate +Review the implementation against the approved plan; flag missing regression tests for bug fixes, and obvious bugs, code smells, or security issues. Do **not** redesign the approach (that was settled at `plan-approval`), demand changes outside the plan's scope, or request architecture-level refactors unless the change introduces a clear new problem. This is a pre-gate review — the human is the final authority; focus on "is this ready for someone else to test in a browser / simulator". diff --git a/codev/protocols/pir/consult-types/pr-review.md b/codev/protocols/pir/consult-types/pr-review.md index cf49c3a05..1c075a9a4 100644 --- a/codev/protocols/pir/consult-types/pr-review.md +++ b/codev/protocols/pir/consult-types/pr-review.md @@ -2,37 +2,19 @@ ## Context -You are performing the 3-way review of a PIR protocol PR. The builder has implemented an approved plan, the human has approved the `dev-approval` gate (meaning a human has run the code locally and tested it), and the PR has been opened. This is a single advisory pass (`max_iterations: 1`) — your verdict is surfaced to the human at the `pr` gate, who is the sole remaining reviewer; it is not auto-re-reviewed. +You are performing the 3-way review of a PIR PR. The builder implemented an approved plan, the human approved the `dev-approval` gate (having run and tested the code locally), and the PR is open. This is a single advisory pass (`max_iterations: 1`) — your verdict is surfaced to the human at the `pr` gate, who is the sole remaining reviewer; it is not auto-re-reviewed. ## Focus Areas -1. **Completeness** - - Is the PR body the review file content + `Fixes #`? - - Are all commits properly formatted (`[PIR #] ...`)? - - Does the diff match what the review file describes? - -2. **Test Status** - - Do all tests pass on the branch? - - Is test coverage adequate for the change? - - Are there skipped or flaky tests documented? - -3. **Code Quality** - - Any debug code left in? - - Any TODO comments that should be resolved? - - Any `// REVIEW:` markers that weren't addressed? - -4. **Branch Hygiene** - - Is the branch up to date with the default branch? (If not, suggest a rebase. The default branch is whatever `git symbolic-ref --short refs/remotes/origin/HEAD` reports — typically `main`, but may be `dev`, `ci`, etc.) - - Are commits atomic and well-described? - - Is the change diff a reasonable size for the issue scope? - -5. **Issue Linkage** - - Does the PR body contain `Fixes #` (or `Refs #` for partial fixes)? - - Without this, GitHub won't auto-close the issue on merge +- **Completeness** — the PR body is the review-file content plus `Fixes #`; commits are formatted `[PIR #] ...`; the diff matches what the review file describes. +- **Test Status** — all tests pass on the branch, coverage is adequate, and skipped/flaky tests are documented. +- **Code Quality** — no debug code, no stray `TODO` or unaddressed `// REVIEW:` markers. +- **Branch Hygiene** — the branch is up to date with the default branch (whatever `git symbolic-ref --short refs/remotes/origin/HEAD` reports — typically `main`, sometimes `dev`/`ci`); commits are atomic; the diff size is reasonable for the issue. +- **Issue Linkage** — the PR body carries `Fixes #` (or `Refs #` for a partial fix), without which GitHub won't auto-close the issue on merge. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -46,21 +28,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Ready to merge -- `REQUEST_CHANGES`: Issues to fix before merging -- `COMMENT`: Minor items, can merge but note feedback +- `APPROVE`: ready to merge. +- `REQUEST_CHANGES`: issues to fix before merging. +- `COMMENT`: minor items; can merge but note the feedback. ## Scope -- **DO** flag missing `Fixes #` lines -- **DO** flag obvious problems the human reviewer at the gate might have missed -- **DO NOT** redesign the approach — that was settled at `plan-approval` and validated at `dev-approval` -- **DO NOT** demand changes the human reviewer already accepted at the `dev-approval` gate (the human ran the code and approved it; you didn't) -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. - -## Notes - -- The human at the `dev-approval` gate is the primary reviewer for behavior; you are the secondary reviewer for hygiene and edge cases -- Focus on "what would an integration reviewer catch that the gate reviewer missed" -- If referencing line numbers, use `file:line` format +Flag a missing `Fixes #` and obvious problems the gate reviewer might have missed. Do **not** redesign the approach (settled at `plan-approval`, validated at `dev-approval`), demand changes the human already accepted at `dev-approval` (they ran the code; you didn't), or flag the syntax of `git diff` examples in review-file prose — quoted diff syntax is documentation, not a command; apply two-dot/three-dot scrutiny only to diffs you compute yourself. You are the secondary reviewer for hygiene and edge cases: "what would an integration reviewer catch that the gate reviewer missed". diff --git a/codev/protocols/pir/prompts/implement.md b/codev/protocols/pir/prompts/implement.md index 9d7f88a8c..7e6b5d5bd 100644 --- a/codev/protocols/pir/prompts/implement.md +++ b/codev/protocols/pir/prompts/implement.md @@ -61,7 +61,7 @@ Follow the plan's "Files to Change" section. Apply the changes. [PIR #{{issue.number}}] ``` -**Never use `git add .` or `git add -A`.** Stage files explicitly: +Stage files explicitly: ```bash git add path/to/changed-file.ts @@ -143,7 +143,6 @@ Then **stay in the interactive session**. Do not exit. Wait for the user's next - Don't run `porch approve` yourself - Don't push to the default branch — only to your builder branch - Don't squash commits — let the merge commit preserve history -- Don't use `git add .` or `git add -A` - Don't open the PR yet — that's the `review` phase - Don't exit the interactive session at the gate diff --git a/codev/protocols/pir/prompts/plan.md b/codev/protocols/pir/prompts/plan.md index a40cdee2d..2f4eaf042 100644 --- a/codev/protocols/pir/prompts/plan.md +++ b/codev/protocols/pir/prompts/plan.md @@ -87,8 +87,6 @@ git commit -m "[PIR #{{issue.number}}] Plan draft" git push -u origin "$(git branch --show-current)" ``` -**Never use `git add .` or `git add -A`.** - ### 5. Signal Phase Complete ```bash @@ -118,7 +116,6 @@ Then **stay in the interactive session**. Do not exit. Wait for the user's next - Don't write code — that's the implement phase - Don't run `porch approve` yourself — only the human can approve the gate - Don't post the plan content as a GitHub issue comment — the plan lives in the file, not the issue thread. A one-line pointer comment on the issue is fine if you think it helps the discussion. -- Don't use `git add .` or `git add -A` - Don't exit the interactive session at the gate ## Handling Feedback diff --git a/codev/protocols/pir/prompts/review.md b/codev/protocols/pir/prompts/review.md index 952f19c29..3966f7b79 100644 --- a/codev/protocols/pir/prompts/review.md +++ b/codev/protocols/pir/prompts/review.md @@ -238,7 +238,7 @@ Together with the `--pr` record from step 4a and the `--merged` record from step ## What NOT to Do -- **Don't merge before the `pr` gate is approved.** A consultation APPROVE verdict is NOT merge authorization. User-in-pane prose ("looks good", "lgtm", "merge it") is NOT merge authorization. The *only* signal that authorizes `gh pr merge` is porch reporting `gate_status: approved` for the `pr` gate (which only the user can do, via Cmd+K G or `porch approve` from a non-Claude shell). If `porch next` doesn't show the gate as approved, you wait. +- **Don't merge before the `pr` gate is approved** (steps 8–9). Neither a consultation APPROVE verdict nor user-in-pane prose ("looks good", "lgtm", "merge it") authorizes `gh pr merge` — only porch reporting `gate_status: approved` for the `pr` gate does. - Don't skip porch's PR/merge records (steps 4a, 9). The `--pr` record (step 4a) lets the gate-pending state link to the actual PR; the `--merged` record (step 9) closes the lifecycle in porch state. Skipping either leaves `history:` empty and downstream tooling blind. - Don't run `porch approve` for any gate yourself - Don't push to the default branch — only merge via PR diff --git a/codev/protocols/pir/protocol.md b/codev/protocols/pir/protocol.md index b3befc173..889283150 100644 --- a/codev/protocols/pir/protocol.md +++ b/codev/protocols/pir/protocol.md @@ -1,202 +1,76 @@ # PIR Protocol -> **Plan → Implement → Review** for GitHub-issue-driven work that needs human review of *either* the approach (before code is written) *or* the implementation (before a PR exists), or both. Lighter than SPIR/ASPIR (no `specify` phase — the GitHub issue is the implicit spec) with the human dev-approval moved earlier (pre-PR instead of post-PR). Stronger than BUGFIX/AIR (two human gates before the PR). +Plan → Implement → Review, driven by a GitHub issue, with **two human gates before any PR +exists**. The issue is the implicit spec; there is no specify phase. -## When to Use PIR +Choose PIR when either is true: -Pick PIR when working from a GitHub Issue and ONE or BOTH of the following apply — based on the *nature* of the change, not its size: +- **The approach needs review before coding.** Ambiguous root cause, unfamiliar or + high-blast-radius area, or a design-sensitive change — cheaper to redirect at plan time than + at PR time. +- **The implementation must be exercised running, before a PR exists.** Mobile, UI/UX, + hardware-adjacent behaviour, OAuth or payment integrations, full user journeys, anything + performance-sensitive. A diff cannot show you these; a running worktree can. -### 1. The approach needs review before coding starts -- Root cause is ambiguous; multiple valid fixes exist -- Area is unfamiliar or high-blast-radius (shared utilities, auth, migrations, public APIs) -- Design-sensitive (affects conventions, patterns, architecture) -- Cheaper to redirect at plan time than at PR time +Lighter than SPIR (no spec phase, one consult at the PR). Stronger than BUGFIX/AIR (two human +gates *before* a PR, where the human reviews the running code rather than the diff). -### 2. The implementation needs to be tested before a PR is created -The PR diff alone is insufficient; the reviewer must *run* the code: -- Mobile app changes (needs device testing on Android, iOS, possibly web) -- UI / UX changes (visual inspection, interaction flow, accessibility) -- Hardware-adjacent behavior (sensors, camera, permissions, notifications) -- Integration with external services that don't mock cleanly (OAuth, payments, analytics) -- User-journey changes that need a full-flow exercise -- Performance-sensitive changes that need profiling on the running app - -### Use SPIR / ASPIR / BUGFIX / AIR instead when -- **SPIR / ASPIR**: the change is complex enough to warrant careful specification, multi-agent consultation at every phase, and the full spec → plan → implement → review ceremony with file artifacts. The driving issue is incidental — what matters is that the design work deserves a formal spec and the implementation deserves consult-driven review at each phase -- **BUGFIX**: small bug fix, no design review needed, diff-on-PR review is enough -- **AIR**: small feature from an issue, autonomous, diff-on-PR review is enough - -## How PIR Differs from SPIR - -PIR is structurally *SPIR minus the `specify` phase*, with the human dev-approval moved earlier (pre-PR instead of post-PR). - -| Aspect | SPIR | PIR | -|---|---|---| -| Phases | specify → plan → implement → review → verify | plan → implement → review | -| Spec artifact | `codev/specs/-.md` | GitHub Issue body (implicit spec) | -| Plan artifact | `codev/plans/-.md` | Same — committed on builder branch | -| Review artifact | `codev/reviews/-.md` (Summary + Architecture Updates + Lessons Learned, becomes PR body) | **Same shape** — `codev/reviews/-.md` with the same sections, also becomes PR body | -| Human gates | spec-approval, plan-approval, pr, verify-approval | plan-approval, dev-approval, pr | -| Where code is reviewed by the human | On the PR (post-creation) — read the diff | Pre-PR (at the `dev-approval` gate) — read the diff **and run the worktree locally** | - -The review file always includes Summary, Architecture Updates, and Lessons Learned sections so `codev/reviews/` stays semantically consistent across all protocols. PIR's lightness comes from skipping the `specify` phase (the issue body is the spec), not from cutting corners on the retrospective. - -The `dev-approval` gate is what makes PIR genuinely different: the human gates the *running implementation* via the worktree before the PR exists, instead of gating the PR after creation. - -## Phases - -``` -plan → implement → review -``` - -### Plan (gated by `plan-approval`) - -The builder: -1. Reads the GitHub issue and investigates the codebase -2. Writes `codev/plans/-.md` with: Understanding / Proposed change / Files to change / Risks & alternatives / Test plan -3. Commits the plan on the builder branch and pushes -4. Runs `porch done` and `porch next` — the `plan-approval` gate becomes pending -5. Sits at the interactive prompt waiting for review - -**Reviewer paths** (all equivalent): -- Open `codev/plans/-.md` in the worktree, read and / or edit directly, save -- Type feedback into the builder's PTY pane — the builder is alive in interactive mode -- `afx send ""` -- Comment on the GitHub issue (sidecar discussion) - -When satisfied, approve via VSCode's "Approve Gate" command (Cmd+K G) or: - -```bash -porch approve plan-approval --a-human-explicitly-approved-this -``` - -### Implement (gated by `dev-approval`) - -The builder: -1. Reads the approved plan file -2. Writes code and tests; runs build + tests via the `checks` block -3. *No AI consult on this phase* — the human at the `dev-approval` gate is the sole reviewer of the running code. Matches BUGFIX / AIR's pattern of "no consult on implementation, one consult at PR creation". -4. Pushes the branch -5. Runs `porch done` and `porch next` — the `dev-approval` gate becomes pending -6. Outputs a **prose** dev-approval summary in the PTY pane (Summary / Files / Test results / Things to look at / How to test locally). This is a transient message to orient the human reviewer — **not a committed file**. The retrospective file is written in the next phase, after the human approves the running code. -7. Sits at the interactive prompt - -**The reviewer's killer move**: run the worktree locally. - -- VSCode: right-click the builder in the Codev sidebar → **Run Dev** (spawns `afx dev ` via Tower) -- CLI: `afx dev ` - -The dev process uses **the same ports and URLs as main** intentionally (OAuth callbacks, CORS, cookie scoping all depend on consistent origins). Only one dev env runs at a time; stop main's `pnpm dev` before starting the worktree's, or use VSCode's **Stop Dev** to swap. - -Reviewer tests the change on real devices / browsers / simulators. When satisfied, approves via Cmd+K G or: - -```bash -porch approve dev-approval --a-human-explicitly-approved-this -``` - -### Review (gated by `pr`) - -The builder: -1. Writes `codev/reviews/-.md` with **Summary**, **Architecture Updates**, **Lessons Learned Updates**, plus the supporting sections (Files Changed, Commits, Test Results, Things to Look At, How to Test Locally). -2. Routes new facts/wisdom by tier (Spec 987) — HOT `codev/resources/arch-critical.md` / `lessons-critical.md` (capped) or COLD `codev/resources/arch.md` / `lessons-learned.md` (reference) — if real changes need recording. If not, the review file's sections state "no changes needed" with a one-line explanation (the porch `checks` block enforces section presence, not content). -3. Commits the review file (and arch / lessons updates if any) and pushes -4. Opens a PR with `gh pr create`; PR body is the review file content + `Fixes #`. Records the PR with `porch done --pr --branch `. -5. Runs `porch done ` — porch's `verify` block runs 3-way consultation (Gemini, Codex, Claude; type=impl) as a **single advisory pass** (`max_iterations: 1`); consultation outputs land in `codev/projects/-*/`. There is no iterate-until-APPROVE loop: whatever the verdicts, porch records them and advances to the `pr` gate. A `REQUEST_CHANGES` is not auto-re-reviewed — the builder addresses or rebuts it, adds a regression test if it's a real defect, and escalates it in the architect notification so the human verifies it at the `pr` gate. Outcomes are not auto-appended to the PR body; reviewers with the worktree read them from the projects dir. -6. The `pr` gate fires (pending) regardless of verdict. Builder notifies the architect once — leading with any `REQUEST_CHANGES` and its disposition (since PIR will not re-review it) rather than burying it in a flat status line. -7. Builder waits at the `pr` gate. The human reviews the PR on GitHub, then approves the `pr` gate (Cmd+K G or `porch approve pr --a-human-explicitly-approved-this`). Porch wakes the builder. -8. Builder verifies the gate is genuinely approved via `porch next` (defensive — typed prose can't trigger this branch, only real porch state does), then runs `gh pr merge --merge`, records via `porch done --merged `, and sends the cleanup-ready notification. Protocol complete (`next: null`). - -## Gates - -PIR uses porch's existing gate machinery. Gate names are opaque strings; no porch engine changes are needed. - -- **`plan-approval`** — pre-PR. Human reads the plan file (committed on the builder branch) and approves before any code is written. Gates are keyed by `(project_id, gate_name)` so the name is safe to share with other protocols. -- **`dev-approval`** — pre-PR. The human reviews the *running* worktree (via `afx dev`) before any PR exists. This is PIR's distinctive gate. -- **`pr`** — post-PR. Gates the merge step. The human reviews the PR on GitHub and approves this gate; porch wakes the builder, which then runs `gh pr merge`. The gate exists so the merge trigger is structured porch state (binary approved/not), not free-text prose typed into the builder's pane. Eliminates the self-merge bug class: builders can't infer authorization from ambiguous user input. - -When a gate becomes pending, porch broadcasts `overview-changed` via SSE. The VSCode Builders tree picks up the blocked state and renders it with a bell icon; a toast surfaces the new gate-pending event. Architect notification is *not* automatic — gates surface via the toast/sidebar (for IDE users) or by checking the builder pane / `porch pending` (for CLI users). The builder's job at any gate is to write the artifact, commit, signal completion, and wait — never to invoke `porch approve` itself (Claude refuses the `--a-human-explicitly-approved-this` flag by design). - -## Rejection / Feedback Model - -There is no formal `porch reject` command. Rejection works via the feedback-iterate pattern: - -1. Reviewer provides feedback (edit the plan file in VSCode, type in the builder pane, `afx send`, or issue comment) -2. Builder reads the feedback on its next turn, revises the artifact, recommits -3. The gate remains pending — porch doesn't advance until the human runs `porch approve` - -The same pattern works at both gates. - -## Builder Session Lifetime - -The builder is a long-running interactive Claude Code session in a PTY pane managed by Tower. The session is launched as `claude ""` (no `--print`) inside a `while true` restart loop. That form starts an interactive Claude REPL with the prompt as the first user message; after Claude finishes the prompted work it sits at the input prompt awaiting next user input. The outer `while true` loop only fires if Claude crashes — it is a crash-recovery safety net, not the gate-wait mechanism. - -This means typed input in the builder pane reaches the live Claude session immediately, exactly like any other interactive Claude Code conversation. There is no "session ended at gate" state to worry about under normal operation. - -## Configuration - -PIR uses the same `.codev/config.json` configuration as other protocols. The `worktree` block (from Issue 689) enables the at-gate dev review flow: +## The state machine ```json -{ - "worktree": { - "symlinks": [".env.local", "packages/*/.env"], - "postSpawn": ["pnpm install --frozen-lockfile"], - "devCommand": "pnpm dev" - } -} +{{> protocols/pir/protocol.json}} ``` -Without `worktree.devCommand`, `afx dev` won't work and the `dev-approval` gate degenerates to a diff-read — at which point you should probably use AIR or BUGFIX instead. - -## Multi-Agent Consultation - -- **plan**: human-only review. No AI consultation. -- **implement**: no AI consult — the human at the `dev-approval` gate is the sole reviewer of the running code. -- **review**: 3-way consultation (Gemini, Codex, Claude; type=impl) after the PR is opened, as a **single advisory pass** (`max_iterations: 1`). Same consult type (`impl`) as BUGFIX / AIR's PR-creation consult. - -The consultation at the PR is a single pass — there is **no iterate-until-APPROVE loop**. A `REQUEST_CHANGES` does not block or re-trigger it; the builder addresses or rebuts it and escalates it to the human at the `pr` gate, who is the sole remaining reviewer of any resulting fix (the consultation does not re-check it). - -Net: PIR's distinguishing features are the two human gates (`plan-approval`, `dev-approval`), not AI-consult density. +## Gates -To disable consultation entirely, say "without multi-agent consultation" when starting work. +Gate names are opaque strings keyed by `(project_id, gate_name)`, so sharing a name with another +protocol is safe and needs no porch change. -## Signals +| Gate | When | What the human does | +|---|---|---| +| `plan-approval` | pre-PR | Reads the plan committed on the builder branch, before any code exists | +| `dev-approval` | pre-PR | **PIR's distinctive gate** — reviews the *running* worktree via `afx dev` | +| `pr` | post-PR | Reviews on GitHub, then approves; porch wakes the builder to merge | -PIR uses the standard porch signal vocabulary: +The `pr` gate makes the merge trigger **structured porch state** rather than free text in the +builder's pane — closing the self-merge class where a builder infers authorization from +ambiguous prose. -``` -PHASE_COMPLETE # Current phase build complete -BLOCKED:reason # Cannot proceed -``` +**Gates do not notify the architect automatically.** Porch broadcasts `overview-changed` over +SSE; the VSCode Builders tree renders the blocked state with a bell and raises a toast. CLI +users see it via the builder pane or `porch pending`. The builder's job at any gate is: write +the artifact, commit, signal, wait — never to invoke `porch approve` itself. -Signals are informational for log readability. The state machine is driven by `porch done` and `porch next` CLI calls inside the builder turn. +## Rejection is iteration, not a command -## Commit Messages +There is no `porch reject`. Feedback arrives however is convenient — editing the plan file, +typing in the builder pane, `afx send`, an issue comment — the builder revises and recommits, +and **the gate stays pending until a human approves it**. The same pattern works at both +pre-PR gates. -Commits during PIR phases use the issue-driven format: +## Artifacts -``` -[PIR #] Plan draft -[PIR #] Implement avatar masking -[PIR #] Add Android-side regression test -``` +Plan and review live in `codev/plans/` and `codev/reviews/` on the builder branch and ship to +the default branch with the merge. The review is shaped like SPIR's (Summary, Architecture +Updates, Lessons Learned) so `codev/reviews/` stays semantically consistent across protocols. -The PR title follows the project's existing PR convention. +## Consultation -## Branch Naming +**One advisory CMAP pass at the PR** (`max_iterations: 1`) — no iterate-until-APPROVE loop. A +`REQUEST_CHANGES` escalates to the human at the `pr` gate rather than triggering an automatic +re-review. -``` -builder/pir- -``` +That footprint is a **design invariant, and it is fragile**: porch resolves models as +*config > protocol*, so a project-wide `porch.consultation.models` (say a SPIR-tuned 3-model +list) silently inflates PIR's cost. Leave it unset, or scope it per-protocol. -Example: `builder/pir-842` for a PIR spawn against GitHub issue #842. +## Builder session -## File Locations +A long-running interactive session in a Tower-managed PTY, launched as `claude ""` +inside a `while true` restart loop. Typed input reaches the live session immediately; the loop +is crash recovery, not the gate-wait mechanism. There is no "session ended at gate" state. -``` -codev/plans/-.md # written in plan phase, on builder branch -codev/reviews/-.md # written in review phase (post-dev-approval-approval), on builder branch; becomes PR body -codev/projects/-/status.yaml # porch state, managed automatically -``` +## Configuration -The plan and review files ship to `main` with the merged PR — durable, searchable, git-versioned. The review file includes Summary + Architecture Updates + Lessons Learned + supporting sections, so `codev/reviews/` stays semantically consistent across protocols. +The `worktree` block in `.codev/config.json` is what makes the `dev-approval` gate work — see +the `runnable-worktrees` skill for `symlinks`, `postSpawn` and `devCommand`. diff --git a/codev/protocols/research/builder-prompt.md b/codev/protocols/research/builder-prompt.md index 088262853..b54c6be0f 100644 --- a/codev/protocols/research/builder-prompt.md +++ b/codev/protocols/research/builder-prompt.md @@ -1,91 +1,60 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are conducting multi-agent research. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the RESEARCH protocol yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Use `consult` for the 3-way investigation and critique phases + +You follow the protocol yourself; the architect verifies compliance. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way consultation** — always follow porch next → porch done cycle + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the RESEARCH protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. -## RESEARCH Overview +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. -The RESEARCH protocol produces a high-confidence research report through triangulation: +## Research Topic -1. **Scope** — Define the precise question, scope, and acceptance criteria. Write a research brief. Gate: architect approval before proceeding. -2. **Investigate** — Dispatch the brief to 3 models (Gemini, Codex, Claude) in parallel. Each investigates independently. No anchoring — they don't see each other's work. -3. **Synthesize** — Read all 3 reports. Identify consensus, disagreements, and unique contributions. Write a single synthesis report organized by topic (not by model). -4. **Critique** — Send the synthesis back to all 3 models for critique. Incorporate valid feedback. Document rejected critique. Finalize the report. +{{task_text}} -## Output Location +## Output -All artifacts go to `codev/research/`: -- `-brief.md` — the scoped question (Phase 1) -- `-gemini.md`, `-codex.md`, `-claude.md` — individual investigations (Phase 2) -- `.md` — the final synthesis report (Phase 3+4, this is the deliverable) -- `-critique-rebuttals.md` — critique responses (Phase 4) - -{{#if task}} -## Research Topic -{{task_text}} -{{/if}} +`codev/research/.md` ## Key Principles -- **Triangulate**: consensus across 3 models > any single model's claim -- **Cite sources**: tell investigators to provide sources where possible -- **Be candid about uncertainty**: "I don't know" > confabulation -- **Organize by topic, not by model**: the synthesis is a standalone document -- **Note surprises**: the most valuable findings are often unexpected -- **Keep it concise**: the synthesis should be shorter than the sum of the investigations - -## Using consult for 3-way Investigation +- **Triangulate**: consensus across three models beats any single model's claim +- **Cite sources**; be candid about uncertainty — "I don't know" beats confabulation +- **Organize by topic, not by model** — the synthesis is a standalone document +- **Note surprises**: the most valuable findings are usually the unexpected ones +- **Preserve disagreement**: smoothing over conflict destroys the signal that made a 3-way + investigation worth running +- Keep the synthesis shorter than the sum of its investigations -For the investigate phase, use the `consult` CLI to dispatch to each model: +## Dispatching the investigation ```bash -# Phase 2: parallel investigation +# investigate — parallel, independent consult -m gemini --prompt-file codev/research/-brief.md --output codev/research/-gemini.md & -consult -m codex --prompt-file codev/research/-brief.md --output codev/research/-codex.md & +consult -m codex --prompt-file codev/research/-brief.md --output codev/research/-codex.md & consult -m claude --prompt-file codev/research/-brief.md --output codev/research/-claude.md & wait -``` -For the critique phase: -```bash -# Phase 4: parallel critique +# critique — same shape, pointed at the synthesis consult -m gemini --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/.md --output codev/research/-critique-gemini.md & -consult -m codex --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/.md --output codev/research/-critique-codex.md & +consult -m codex --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/.md --output codev/research/-critique-codex.md & consult -m claude --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/.md --output codev/research/-critique-claude.md & wait ``` -## Getting Started -1. Read the RESEARCH protocol document -2. Understand the research question from the architect -3. Write the research brief (Phase 1) -4. Wait for scope-approval before proceeding to investigation - ---- - -## Protocol Reference (full text) +## Notifications -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/research/protocol.md b/codev/protocols/research/protocol.md index 2c2e8ec02..8d7cb72e2 100644 --- a/codev/protocols/research/protocol.md +++ b/codev/protocols/research/protocol.md @@ -1,169 +1,44 @@ # RESEARCH Protocol -## Overview +Scope → Investigate → Synthesize → Critique. Multiple models investigate the same question +independently, their findings are synthesized, and the synthesis is adversarially critiqued +before it is trusted. **The state machine below is authoritative on which models actually +run** — the set can be smaller than the ideal when a provider's consult lane is unavailable +(it is currently `["codex"]` for investigation, the agy/Gemini and hermes lanes being degraded). -Multi-agent research with 3-way investigation, synthesis, and critique. Three AI models independently investigate a question, their findings are synthesized into a single report, and then all three models critique the synthesis for gaps, errors, and bias. +Use it for competitive and technology analysis, "state of X" questions, and architectural +decision support in an unfamiliar domain — cases where a single model's confident answer is +exactly the failure mode. -**Core Principle**: Triangulate. No single model's knowledge is authoritative. Consensus across models is more reliable than any individual output. +## The state machine -## When to Use - -**Use for**: Competitive analysis, technology evaluation, market research, architectural decision support, "what's the state of X?" questions, exploring unfamiliar domains. - -**Skip for**: Implementation work (use SPIR/ASPIR), quick questions (just ask), experiments (use EXPERIMENT), known-answer lookups (just search). +```json +{{> protocols/research/protocol.json}} +``` ## Output -All research artifacts go to `codev/research/`. The final deliverable is a single synthesis report at `codev/research/.md`. +`codev/research/.md` — the report, with its sources and its disagreements preserved. ## Phases -### Phase 1: Scope - -**Purpose**: Make sure we're asking the right question before spending 3 models' worth of compute on answering it. - -The builder: -1. Reads the architect's research request -2. Clarifies the question — what specifically are we trying to learn? -3. Defines the scope — what's in, what's out, what depth is needed -4. Defines acceptance criteria — what does a good answer look like? -5. Writes a **research brief** (`codev/research/-brief.md`) with: - - The precise question(s) - - Scope boundaries - - **Required targets** (when applicable — not all research questions have them). When the user names specific projects, products, or systems, those are exemplars of a CLASS, not an exhaustive list. The brief should: - - List the named targets as required coverage (each gets a dedicated section) - - Identify the CLASS they represent (e.g., "open-source always-on agent frameworks") - - Instruct investigators to find OTHER members of that class the user didn't name — discovering what the user SHOULD be thinking about is often the most valuable part of the research - - If an investigator cannot find information about a required target, they must say so explicitly — not silently skip it - - **Optional context** — additional sources that may be useful but are not required - - What a useful answer looks like - - Suggested sources or angles for the investigators -6. Sends the brief to the architect for approval - -**Gate**: `scope-approval` — the architect confirms the question is correctly scoped before the 3-way investigation begins. This prevents wasting compute on a badly-framed question. - -### Phase 2: Investigate (3-way parallel) - -**Purpose**: Get three independent perspectives on the question. - -The builder dispatches the research brief to three models (Gemini, Codex, Claude) via `consult`. Each model: -1. Receives the scoped research brief -2. Independently investigates using web search, its training knowledge, and reasoning -3. Produces a standalone investigation report with: - - **A dedicated section for each required target** from the brief. Every required target gets its own heading with specific findings — not mentioned in passing, not substituted with an easier target. If a required target yields no findings, the section must say "No information found" rather than being omitted. - - Findings (with sources where possible) - - Confidence levels on key claims - - Gaps it couldn't fill - - Surprises or things that contradicted expectations - -The investigations run in **parallel** — each model works independently without seeing the others' output. This prevents anchoring bias. - -Investigation reports are saved to: -- `codev/research/-gemini.md` -- `codev/research/-codex.md` -- `codev/research/-claude.md` - -### Phase 3: Synthesize - -**Purpose**: Merge three independent reports into one coherent document. - -The builder: -1. Reads all three investigation reports -2. Identifies **consensus** — what all three agree on (highest confidence) -3. Identifies **disagreements** — where models contradict each other -4. Resolves conflicts — picks the best-supported position, notes the disagreement -5. Identifies **unique contributions** — things only one model found that the others missed -6. Writes the **synthesis report** (`codev/research/.md`) with: - - **Scope summary** — a short section (before the executive summary) restating the research question, required targets, and scope boundaries from the brief. A reader should understand what was asked without needing to read the brief separately. - - Executive summary - - Findings (organized by topic, not by model) - - Confidence annotations (consensus vs. single-source) - - Gaps and limitations - - Recommendations (if the research brief asked for them) - -The synthesis is written as a **standalone document** — a reader should never need to reference the individual investigation reports. Those are kept as appendices for traceability. - -### Phase 4: Critique (3-way review) - -**Purpose**: Pressure-test the synthesis for gaps, errors, and bias. +**Scope** — write the research brief: the question, why it matters, what would count as an +answer, and what is out of scope. Gated by `scope-approval`, because a badly framed question +wastes the investigation's compute and produces a confident answer to the wrong thing. -The builder dispatches the synthesis report back to all three models for critique. Each model: -1. Reads the synthesis -2. **Checks coverage against the brief** — does every required target from the research brief have dedicated coverage in the synthesis? Lists any required targets that were named in the brief but have zero or minimal coverage. This is the #1 critique check. -3. Checks for factual errors or unsupported claims -4. Identifies gaps — important aspects the synthesis missed -5. Flags potential bias — did the synthesis over-weight one model's perspective? -6. Suggests specific improvements +**Investigate** — the configured models (see the state machine) work the question +**independently**. Independence is the point: cross-contaminated investigations converge on a +shared error, so where more than one model is available each researches without seeing the others. -The builder then: -1. Incorporates valid critique -2. Documents rejected critique with rationale -3. Finalizes the report -4. Commits to `codev/research/.md` +**Synthesize** — merge findings and, critically, **preserve disagreement**. Where models +diverge, say so and say why; a synthesis that smooths over conflict has destroyed the signal +that made a multi-model investigation worth running. -## File Structure +**Critique** — adversarial pass over the synthesis. What is asserted without a source? What +would change the conclusion? Reaching `research-complete` means the report survived this, not +that it was written. -Only the brief and final report are checked in. Individual investigation reports and full critique outputs are working artifacts — useful during the process but not committed to the repo. - -``` -codev/research/ -├── -brief.md # Phase 1: scoped research question (checked in) -└── .md # Phase 3+4: final synthesis (the deliverable, checked in) -``` - -The final report includes: -- A **"Disagreements and resolution"** section documenting where the three investigators disagreed and how the synthesis resolved each disagreement -- A **"Changes from critique"** section summarizing what the critique phase changed (not the full critique — just what was added, removed, or corrected and why) - -Individual investigation reports (`-gemini.md`, `-codex.md`, `-claude.md`) and raw critique outputs are kept locally during the research process but NOT committed. The final report is the deliverable; the process artifacts are disposable. - -## Best Practices - -### Scoping -- A good research question is specific enough to answer in 1500-3000 words per model -- "What's the state of X?" is too broad — "What are the top 5 players in X, their strengths/weaknesses, and the structural gaps?" is better -- Include the "so what" — why are we researching this? What decision does it inform? - -### Investigation -- Tell each model to cite sources where possible -- Tell each model to be candid about uncertainty — "I don't know" is better than confabulation -- Tell each model to note surprises — the most valuable findings are often the unexpected ones - -### Synthesis -- Organize by topic, not by model ("here's what we found about X" not "here's what Gemini said") -- Weight consensus over single-model claims -- Don't smooth over disagreements — note them explicitly -- Keep the synthesis shorter than the sum of the investigations - -### Critique -- Critiquers should focus on gaps and errors, not style -- A critique that says "add more about X" is useful; "rewrite the intro" is not -- The builder should reject critique that's outside the original scope - -## Integration with Other Protocols - -### Research → SPIR -When research informs a feature decision: -1. Reference the research report in the spec -2. Link specific findings as evidence for design choices - -### Research → EXPERIMENT -When research identifies something worth testing: -1. Create an experiment to validate the research finding -2. Reference the research report as motivation - -## Git Workflow - -### Commits -``` -[Research: topic] Scoped research brief -[Research: topic] 3-way investigation complete -[Research: topic] Synthesis report -[Research: topic] Final report (post-critique) -``` +## Reporting standard -### What to Commit -- All investigation reports (for traceability) -- The final synthesis (the deliverable) -- The critique rebuttals (for process transparency) -- Do NOT commit raw web search results or intermediate notes +Cite sources for factual claims and mark inference as inference. A research report that cannot +be checked is an opinion with footnotes. diff --git a/codev/protocols/spike/builder-prompt.md b/codev/protocols/spike/builder-prompt.md index 6d30dc649..4253b086d 100644 --- a/codev/protocols/spike/builder-prompt.md +++ b/codev/protocols/spike/builder-prompt.md @@ -1,68 +1,50 @@ # {{protocol_name}} Builder ({{mode}} mode) -You are executing a time-boxed technical feasibility spike. +You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the SPIKE protocol yourself (no porch orchestration) -- Stay focused on the question — don't gold-plate -- The findings document is your deliverable, not the code -{{/if}} - -## Protocol -Follow the SPIKE protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. -{{#if task}} -## Spike Question -{{task_text}} +You follow the protocol yourself; the architect verifies compliance. {{/if}} -## Recommended Workflow +{{#if mode_strict}} +## Mode: STRICT -Follow this 3-step workflow. You can skip or reorder steps as the investigation demands. +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. +{{/if}} -### 1. Research -- Read documentation, examine existing code, search for prior art -- Identify constraints, dependencies, and potential blockers -- Understand the problem space before writing any code +## Protocol -### 2. Iterate -- Build minimal proof-of-concept code to test approaches -- Focus on answering the feasibility question, not building production code -- POC code doesn't need tests or polish -- **Skip this step** if the answer is clear from research alone +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. -### 3. Findings -- Write findings to `codev/spikes/-.md` using the template -- Provide a clear feasibility verdict: Feasible / Not Feasible / Feasible with Caveats -- Commit the findings document -- Notify the architect: `afx send architect "Spike complete. Verdict: [verdict]"` +## Spike Question -## Key Principles +{{task_text}} -- **Time-boxing**: Stay focused on the question. Don't explore tangents. -- **Exploration over perfection**: POC code doesn't need tests or polish. -- **Clear output**: The findings document is the deliverable, not the code. -- **Know when to stop**: Once you can answer the feasibility question, write findings and stop. Don't keep iterating. -- **Document failures**: "Not feasible" is a valid and valuable finding. +## Workflow -## Handling Flaky Tests +Three steps; skip or reorder as the investigation demands. -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your findings under a `## Flaky Tests` section -5. Commit the skip and continue with your work +1. **Research** — documentation, existing code, prior art. Identify constraints, dependencies + and blockers before writing any code. +2. **Iterate** — minimal proof-of-concept to test approaches. POC code needs no tests or polish; + it exists to answer the question. **Skip this entirely** if research already answers it. +3. **Findings** — write `codev/spikes/-.md` with a clear verdict (Feasible / Not + Feasible / Feasible with Caveats), commit it, and notify: + `afx send architect "Spike complete. Verdict: [verdict]"` -## Getting Started -1. Read the SPIKE protocol document -2. Understand the question you're investigating -3. Start with research — don't jump straight to code +## Key Principles ---- +- **Time-box**: stay on the question, don't explore tangents +- **The findings document is the deliverable, not the code** +- **Know when to stop**: once you can answer the question, write findings and stop +- **"Not feasible" is a valuable finding.** The failure mode is an inconclusive spike — time + spent, nothing recorded, question still open -## Protocol Reference (full text) +## Notifications -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/spike/protocol.md b/codev/protocols/spike/protocol.md index 764a0bea6..0e72fdb1d 100644 --- a/codev/protocols/spike/protocol.md +++ b/codev/protocols/spike/protocol.md @@ -1,128 +1,45 @@ # SPIKE Protocol -## Overview +A time-boxed feasibility investigation that answers one question: **can this be done, and at +what cost?** The deliverable is findings, not shipped code. -Time-boxed technical feasibility exploration. Answer "Can we do X?" and "What would it take?" before committing to a full SPIR project. +Use it before committing to a SPIR project whose feasibility is genuinely unknown — an unfamiliar +library, an unproven integration, a performance question that argument cannot settle. -**Core Principle**: Stay focused on the question. Once you can answer it, write findings and stop. +## The state machine -## When to Use - -**Use for**: Quick technical feasibility investigations, proof-of-concept explorations, "can we do X?" questions, evaluating approaches before committing to SPIR - -**Skip for**: Production code (use SPIR), formal hypothesis testing (use EXPERIMENT), bug fixes (use BUGFIX) - -### Spike vs Experiment - -| | Spike | Experiment | -|---|---|---| -| **Goal** | Answer a feasibility question | Test a formal hypothesis | -| **Structure** | Lightweight guidance | Formal phases (hypothesis/design/execute/analyze) | -| **Output** | Findings document | Experiment notes with metrics | -| **Rigor** | Exploration-first | Measurement-first | -| **Time** | Short (hours) | Longer (days) | - -## Spawning a Spike - -```bash -afx spawn --task "Can we use WebSockets for real-time updates?" --protocol spike -afx spawn --task "What would it take to support SQLite FTS?" --protocol spike +```json +{{> protocols/spike/protocol.json}} ``` -Spikes are always soft mode — no porch orchestration, no gates, no consultation. - -## Recommended Workflow - -The following 3-step workflow is **guidance only** — not enforced by porch. Follow it, skip steps, or reorder as the investigation demands. - -### Step 1: Research - -- Read documentation, examine existing code, search for prior art -- Identify constraints, dependencies, and potential blockers -- Understand the problem space before writing any code -- Check if someone has already investigated this (look in `codev/spikes/`) - -### Step 2: Iterate - -- Build minimal proof-of-concept code -- Try different approaches, hit walls, pivot -- Focus on answering the feasibility question, not building production code -- **Skip this step** if the answer is clear from research alone - -### Step 3: Findings - -- Write the findings document at `codev/spikes/-.md` -- Use the embedded template at the end of this protocol -- Provide a clear feasibility verdict -- Commit and notify the architect +## Proof-of-concept code -## Output +Throwaway by design. It exists to answer the question, and it is not held to production +standards — but it must not be quietly promoted into production later either. If the answer is +"feasible", a SPIR project builds the real thing. -Findings are stored in `codev/spikes/` using the pattern: `-.md` +## Outcomes -Examples: -- `codev/spikes/462-websocket-feasibility.md` -- `codev/spikes/475-sqlite-fts-performance.md` +| Verdict | What the findings must contain | +|---|---| +| **Feasible** | Recommended approach and rough cost, enough for the architect to decide on a SPIR project | +| **Not feasible** | Why, what was tried, and what alternatives exist — this is what stops the investigation being repeated in six months | +| **Feasible with caveats** | The conditions, risks and trade-offs that make it conditional | -The `` is the GitHub issue number or project ID. +A negative result is a successful spike. The failure mode is an inconclusive one: time spent, +nothing recorded, question still open. -## Proof-of-Concept Code +Notify the architect with the verdict when done. -POC code from the iterate step is committed to the spike branch alongside the findings document. It serves as evidence supporting the findings. However: +## Findings -- POC code does NOT need tests, polish, or production quality -- POC code does NOT get merged to main — it stays on the spike branch -- The findings document is the primary deliverable; the code is supporting evidence -- If the spike leads to a SPIR project, the builder starts fresh +Write findings using this structure: -## Outcome Handling - -- **Feasible**: Write findings with recommended approach and effort estimate. Architect decides whether to create a SPIR project. -- **Not Feasible**: Write findings documenting why, what was tried, and what alternatives exist. This prevents future teams from repeating the investigation. -- **Feasible with Caveats**: Write findings with conditions, risks, and trade-offs. - -In all cases, notify the architect: -```bash -afx send architect "Spike complete. Verdict: [feasible/not feasible/caveats]" -``` +{{> protocols/spike/templates/findings.md}} -## Git Workflow +## Git -### Commits ``` [Spike 462] Research: WebSocket library comparison -[Spike 462] Iterate: POC with ws library [Spike 462] Findings: WebSockets feasible for real-time updates ``` - -### When to Commit -- After significant research findings -- After each iteration attempt -- When writing the findings document (final commit) - -## Integration with Other Protocols - -### Spike -> SPIR -When a spike validates feasibility: -1. Create a SPIR spec referencing the spike findings -2. Use findings to inform the solution approach -3. Reference effort estimate for planning - -Example spec reference: -```markdown -## Background -Spike 462 confirmed WebSocket feasibility with the `ws` library. -See: codev/spikes/462-websocket-feasibility.md -``` - -### Spike -> "Do Not Pursue" -When a spike finds something is not feasible: -1. Document clearly in findings -2. Close the related GitHub issue with a link to findings -3. The findings become institutional knowledge - -## Template: findings.md - -Write the findings document using the following template: - -{{> protocols/spike/templates/findings.md}} diff --git a/codev/protocols/spike/templates/findings.md b/codev/protocols/spike/templates/findings.md index 3fa8c2c36..740d28dcf 100644 --- a/codev/protocols/spike/templates/findings.md +++ b/codev/protocols/spike/templates/findings.md @@ -1,67 +1,37 @@ # Spike: [Title] -**Date**: YYYY-MM-DD - -**Verdict**: Feasible | Not Feasible | Feasible with Caveats +**Date**: YYYY-MM-DD · **Verdict**: Feasible | Not Feasible | Feasible with Caveats ## Question -What technical question was being investigated? Be specific: -- What are you trying to determine? -- What prompted this investigation? -- What decision depends on the answer? +The technical question investigated, what prompted it, and the decision that depends on the answer. ## Research Summary -What was explored during the research phase: -- Documentation read -- Existing code examined -- Prior art found -- Key constraints identified +What was explored — documentation read, existing code examined, prior art, and the key constraints identified. ## Approaches Tried -What was built or tested during the iterate phase: +What was built or tested. For each: what it was, what happened, and whether it worked. ### Approach 1: [Name] -- **What**: Brief description of what was tried -- **Result**: What happened -- **Verdict**: Worked / Didn't work / Partially worked - -### Approach 2: [Name] -*(Add more approaches as needed, or remove if research alone answered the question)* ## Constraints Discovered -Technical limitations, dependencies, and gotchas found during the investigation: -- [Constraint 1] -- [Constraint 2] +Technical limitations, dependencies, and gotchas found during the investigation. ## Recommended Approach -*(If feasible)* How should full implementation proceed? -- Recommended library/technique/pattern -- Key architectural decisions -- Things to watch out for - -*(If not feasible)* Why not, and what alternatives exist? +If feasible: how full implementation should proceed — recommended library/technique/pattern, key architectural decisions, and what to watch out for. If not feasible: why, and what alternatives exist. ## Effort Estimate -Rough sizing for a full SPIR project: **Small** | **Medium** | **Large** - -- Small: < 300 LOC, 1-2 files, straightforward -- Medium: 300-1000 LOC, multiple files, some complexity -- Large: 1000+ LOC, architectural changes, significant complexity +Rough sizing for a full SPIR project: **Small** (< 300 LOC) | **Medium** (300–1000 LOC) | **Large** (1000+ LOC, architectural). ## Next Steps -- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"] -- [ ] [Or: "Do not pursue — blocked by X"] -- [ ] [Or: "Investigate Y further before deciding"] +- [ ] The recommended action (create a SPIR spec, do not pursue, or investigate further before deciding). ## References -- [Link to relevant documentation] -- [Link to relevant code/commits] -- [Link to external resources consulted] +Relevant documentation, code/commits, and external resources consulted. diff --git a/codev/protocols/spir/builder-prompt.md b/codev/protocols/spir/builder-prompt.md index 437287968..1f885ca49 100644 --- a/codev/protocols/spir/builder-prompt.md +++ b/codev/protocols/spir/builder-prompt.md @@ -4,36 +4,36 @@ You are implementing {{input_description}}. {{#if mode_soft}} ## Mode: SOFT -You are running in SOFT mode. This means: -- You follow the protocol document yourself (no porch orchestration) -- The architect monitors your work and verifies you're adhering to the protocol -- Run consultations manually when the protocol calls for them -- You have flexibility in execution, but must stay compliant with the protocol + +You follow the protocol yourself; the architect verifies compliance. Run consultations where the +protocol calls for them. {{/if}} {{#if mode_strict}} ## Mode: STRICT -You are running in STRICT mode. This means: -- Porch orchestrates your work -- Run: `porch next` to get your next tasks -- Follow porch signals and gate approvals -- Do not deviate from the porch-driven workflow - -### ABSOLUTE RESTRICTIONS (STRICT MODE) -- **NEVER edit `status.yaml` directly** — only porch commands may modify project state -- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to -- **NEVER skip the 3-way review** — always follow porch next → porch done cycle -- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Do not +hand-run consultations porch would run, advance plan phases yourself, or skip the 3-way review. + +Never hand-edit `status.yaml` — only porch commands modify project state. {{/if}} ## Protocol -Follow the SPIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**. + +Follow the SPIR protocol. The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. ## Baked Decisions -If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review. +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. -If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding. +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. {{#if spec}} ## Spec @@ -60,31 +60,24 @@ Follow the implementation plan at: `{{plan.path}}` ## PR Strategy -**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs. - -By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch. - -### Architect-requested PRs - -The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request. - -### Multi-PR Mechanics (when the architect requests sequential PRs) +**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits +within a single PR, not as separate PRs. The plan's instruction that "each phase commits +independently" refers to git commits, not PRs. -Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop: +By default, the PR is opened during/after the final implement phase, with all phase-commits +already on the branch. -1. Cut a branch, open a PR, wait for merge -2. After merge: `git fetch origin && git checkout -b origin/` — where `` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure) -3. Continue to the next slice, open another PR -4. Repeat +The architect MAY request a PR at any point — for spec review, mid-implementation feedback, or +slicing a large spec into shippable pieces. Follow that direction when they do; the prohibition +is on *you* deciding to open per-phase PRs unasked. -**Important**: Do NOT run `git checkout ` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/` via fetch. - -Record PRs in status.yaml: `porch done {{project_id}} --pr --branch ` -Record merges: `porch done {{project_id}} --merged ` +Record them: `porch done {{project_id}} --pr --branch `, and +`porch done {{project_id}} --merged `. ## Verify Phase -After the final PR merges, the project enters the **verify** phase. You stay alive through verify: +After the final PR merges the project enters **verify**, and you stay alive through it: + 1. Pull the integration branch into your worktree 2. Run `porch done {{project_id}}` to signal verification is ready 3. The architect approves `verify-approval` when satisfied @@ -92,28 +85,6 @@ After the final PR merges, the project enters the **verify** phase. You stay ali If verification is not needed: `porch verify {{project_id}} --skip "reason"` ## Notifications -Always use `afx send architect "..."` to notify the architect at key moments: -- **Gate reached**: `afx send architect "Project {{project_id}}: ready for approval"` -- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"` -- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."` -- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"` - -## Handling Flaky Tests - -If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use any workaround to avoid the failure -3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section -5. Commit the skip and continue with your work - -## Getting Started -1. Read the protocol document thoroughly -2. Review the spec and plan (if available) -3. Begin implementation following the protocol phases - ---- - -## Protocol Reference (full text) -{{protocol_reference}} +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/codev/protocols/spir/consult-types/impl-review.md b/codev/protocols/spir/consult-types/impl-review.md index de01b8d00..7028b4947 100644 --- a/codev/protocols/spir/consult-types/impl-review.md +++ b/codev/protocols/spir/consult-types/impl-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev/protocols/spir/consult-types/phase-review.md b/codev/protocols/spir/consult-types/phase-review.md index de01b8d00..7028b4947 100644 --- a/codev/protocols/spir/consult-types/phase-review.md +++ b/codev/protocols/spir/consult-types/phase-review.md @@ -1,42 +1,28 @@ # Implementation Review Prompt ## Context -You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. -## CRITICAL: Verify Before Flagging +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan. -Before requesting changes for missing configuration, incorrect patterns, or framework issues: -1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions -2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs -3. **Do not assume** your training data reflects the version in use — verify against project files -4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed +## Verify before flagging -## Focus Areas - -1. **Spec Adherence** - - Does the implementation fulfill the spec requirements for this phase? - - Are acceptance criteria met? - -2. **Code Quality** - - Is the code readable and maintainable? - - Are there obvious bugs or issues? - - Are error cases handled appropriately? +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: -3. **Test Coverage** - - Are the tests adequate for this phase? - - Do tests cover the main paths AND edge cases? +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. +- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed. -4. **Plan Alignment** - - Does the implementation follow the plan? - - Are there plan items skipped or partially completed? +## Focus Areas -5. **UX Verification** (if spec has UX requirements) - - Does the actual user experience match what the spec describes? - - If spec says "async" or "non-blocking", is it actually async? +- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases. +- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped. +- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is). ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -50,23 +36,10 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Phase is complete, builder can proceed -- `REQUEST_CHANGES`: Issues that must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but note feedback +- `APPROVE`: phase is complete, builder can proceed. +- `REQUEST_CHANGES`: issues that must be fixed before proceeding. +- `COMMENT`: minor suggestions; can proceed but note the feedback. ## Scoping (Multi-Phase Plans) -When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): -- **ONLY review work belonging to the current plan phase** -- The query will specify which phase you are reviewing -- Do NOT request changes for functionality scheduled in later phases -- Do NOT flag missing features that are out of scope for this phase -- If unsure whether something belongs to this phase, check the plan file - -## Notes - -- This is a phase-level review, not the final PR review -- Focus on "does this phase work" not "is the whole feature done" -- If referencing line numbers, use `file:line` format -- The builder needs actionable feedback to continue +Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review. diff --git a/codev/protocols/spir/consult-types/plan-review.md b/codev/protocols/spir/consult-types/plan-review.md index 485ff3183..b278aa4ea 100644 --- a/codev/protocols/spir/consult-types/plan-review.md +++ b/codev/protocols/spir/consult-types/plan-review.md @@ -1,44 +1,28 @@ # Plan Review Prompt ## Context -You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it. + +You are reviewing an implementation plan during the Plan phase. The spec is already approved; judge whether the plan adequately describes HOW to implement it. ## Baked Decisions -If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. +If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Spec Coverage** - - Does the plan address all requirements in the spec? - - Are there spec requirements not covered by any phase? - - Are there phases that go beyond the spec scope? - -2. **Phase Breakdown** - - Are phases appropriately sized (not too large or too small)? - - Is the sequence logical (dependencies respected)? - - Can each phase be completed and committed independently? - -3. **Technical Approach** - - Is the implementation approach sound? - - Are the right files/modules being modified? - - Are there obvious better approaches being missed? +- **Spec coverage** — every spec requirement is addressed by some phase; nothing goes beyond the spec's scope. +- **Phase breakdown** — phases are appropriately sized, logically sequenced (dependencies respected), and each can be completed and committed independently. +- **Technical approach** — the approach is sound, the right files/modules are targeted, and no obviously better approach is being missed. +- **Testability** — each phase has clear test criteria and the spec's edge cases are addressable. +- **Risk** — blockers and cross-system dependencies are identified; the plan is realistic given the constraints. -4. **Testability** - - Does each phase have clear test criteria? - - Will the Defend step (writing tests) be feasible? - - Are edge cases from the spec addressable? - -5. **Risk Assessment** - - Are there potential blockers not addressed? - - Are dependencies on other systems identified? - - Is the plan realistic given constraints? +The spec is already approved — do not re-litigate spec decisions. Judge the plan as a guide a builder can follow successfully; verify referenced file paths look accurate. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -52,14 +36,6 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Plan is ready for human review -- `REQUEST_CHANGES`: Significant issues with approach or coverage -- `COMMENT`: Minor suggestions, plan is workable but could improve - -## Notes - -- The spec has already been approved - don't re-litigate spec decisions -- Focus on the quality of the plan as a guide for builders -- Consider: Would a builder be able to follow this plan successfully? -- If referencing existing code, verify file paths seem accurate +- `APPROVE`: plan is ready for human review. +- `REQUEST_CHANGES`: significant issues with approach or coverage. +- `COMMENT`: minor suggestions; the plan is workable but could improve. diff --git a/codev/protocols/spir/consult-types/pr-review.md b/codev/protocols/spir/consult-types/pr-review.md index 837cdea33..6b9a3e82a 100644 --- a/codev/protocols/spir/consult-types/pr-review.md +++ b/codev/protocols/spir/consult-types/pr-review.md @@ -1,44 +1,24 @@ # PR Ready Review Prompt ## Context -You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. -## Focus Areas - -1. **Completeness** - - Are all spec requirements implemented? - - Are all plan phases complete? - - Is the review document written (`codev/reviews/XXXX-name.md`)? - - Are all commits properly formatted (`[Spec XXXX][Phase]`)? - -2. **Test Status** - - Do all tests pass? - - Is test coverage adequate for the changes? - - Are there any skipped or flaky tests? +You are performing the final self-check during the Review phase — the builder has completed all implementation phases and is about to open the PR. This is the last check before the work goes to the architect for integration review. -3. **Code Cleanliness** - - Is there any debug code left in? - - Are there any TODO comments that should be resolved? - - Are there any `// REVIEW:` comments that weren't addressed? - - Is the code properly formatted? - -4. **Documentation** - - Are inline comments clear where needed? - - Is the review document comprehensive? - - Are any new APIs documented? +## Focus Areas -5. **PR Readiness** - - Is the branch up to date with its base (the integration branch the PR targets)? - - Are commits atomic and well-described? - - Is the change diff reasonable in size? +- **Completeness** — all spec requirements implemented, all plan phases complete, the review document written (`codev/reviews/XXXX-name.md`), and commits in the `[Spec XXXX][Phase]` format. +- **Test Status** — all tests pass, coverage is adequate for the changes, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO` / `// REVIEW:` left unaddressed, code properly formatted. +- **Documentation** — inline comments clear where needed, the review document comprehensive, new APIs documented. +- **PR Readiness** — the branch is up to date with its base (the integration branch the PR targets), commits are atomic and well-described, and the diff size is reasonable. ## Scope -- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -63,14 +43,8 @@ PR_SUMMARY: | - [How to test] ``` -**Verdict meanings:** -- `APPROVE`: Ready to create PR -- `REQUEST_CHANGES`: Issues to fix before PR creation -- `COMMENT`: Minor items, can create PR but note feedback - -## Notes +- `APPROVE`: ready to create the PR. +- `REQUEST_CHANGES`: issues to fix before PR creation. +- `COMMENT`: minor items; can create the PR but note the feedback. -- This is the builder's final self-review before hand-off -- The PR_SUMMARY in your output can be used as the PR description -- Focus on "is this ready for someone else to review" not "is this perfect" -- Any issues found here are cheaper to fix than during integration review +The `PR_SUMMARY` block can be used directly as the PR description. diff --git a/codev/protocols/spir/consult-types/spec-review.md b/codev/protocols/spir/consult-types/spec-review.md index 73e346e00..48f0c495b 100644 --- a/codev/protocols/spir/consult-types/spec-review.md +++ b/codev/protocols/spir/consult-types/spec-review.md @@ -1,46 +1,28 @@ # Specification Review Prompt ## Context -You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval. + +You are reviewing a feature specification during the Specify phase, before it goes to human approval. Judge whether the spec is complete, correct, feasible, and clear enough for a builder to plan from. ## Baked Decisions If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect. -If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. +If the baked decisions themselves contradict each other (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. ## Focus Areas -1. **Completeness** - - Are all requirements clearly stated? - - Are success criteria defined? - - Are edge cases considered? - - Is scope well-bounded (not too broad or vague)? - -2. **Correctness** - - Do requirements make sense technically? - - Are there contradictions? - - Is the problem statement accurate? - -3. **Feasibility** - - Can this be implemented with available tools/constraints? - - Are there obvious technical blockers? - - Is the scope realistic for a single spec? +- **Completeness** — requirements, success criteria, and edge cases are stated; scope is bounded, not vague. +- **Correctness** — the requirements are technically sound and internally consistent; the problem statement is accurate. +- **Feasibility** — implementable within the stated tools and constraints, with no obvious blockers. +- **Clarity** — a builder would know what to build; acceptance criteria are testable; terminology is consistent. +- **Structure** — the spec follows the delivered template (`protocols/spir/templates/spec.md`), which the specify prompt inlines. A spec that ignores the template's headings — usually because the builder pattern-matched an older spec in `codev/specs/` — is a defect: `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). A single genuinely-inapplicable section reduced to a one-line "N/A — [reason]" with its heading kept is fine, not grounds for `REQUEST_CHANGES`. -4. **Clarity** - - Would a builder understand what to build? - - Are acceptance criteria testable? - - Is terminology consistent? - -5. **Structure** - - The specify prompt delivers a canonical spec template (`protocols/spir/templates/spec.md`) inline. Does the spec actually follow it? - - Required headings, in order: `## Metadata`, `## Clarifying Questions Asked`, `## Problem Statement`, `## Current State`, `## Desired State`, `## Stakeholders`, `## Success Criteria`, `## Constraints`, `## Assumptions`, `## Solution Approaches`, `## Open Questions`, `## Performance Requirements`, `## Security Considerations`, `## Test Scenarios`, `## Dependencies`, `## References`, `## Risks and Mitigation`, `## Expert Consultation`, `## Approval`, `## Notes`. - - A free-form spec that reads well but ignores the template is a **defect**, not a style preference — it usually means the builder pattern-matched an older spec in `codev/specs/` instead of the delivered template. `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). - - A section that genuinely does not apply may be reduced to a one-line "N/A — [reason]", but the heading should remain. Do not `REQUEST_CHANGES` over one such section. +You are reviewing the specification (WHAT is built), not code or implementation (HOW) — that is the plan and implementation reviews. Be constructive: name the issue and suggest a fix. ## Verdict Format -After your review, provide your verdict in exactly this format: +Provide your verdict in exactly this format — `consult` parses it: ``` --- @@ -54,14 +36,6 @@ KEY_ISSUES: ... ``` -**Verdict meanings:** -- `APPROVE`: Spec is ready for human review -- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding -- `COMMENT`: Minor suggestions, can proceed but consider feedback - -## Notes - -- You are NOT reviewing code - you are reviewing the specification document -- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review) -- Be constructive - identify issues AND suggest solutions -- If the spec references other specs, note if context seems missing +- `APPROVE`: spec is ready for human review. +- `REQUEST_CHANGES`: significant issues must be fixed first. +- `COMMENT`: minor suggestions; can proceed but consider the feedback. diff --git a/codev/protocols/spir/prompts/implement.md b/codev/protocols/spir/prompts/implement.md index bacc8502e..730c91ec4 100644 --- a/codev/protocols/spir/prompts/implement.md +++ b/codev/protocols/spir/prompts/implement.md @@ -2,9 +2,9 @@ You are executing the **IMPLEMENT** phase of the SPIR protocol. -## Your Goal +## Goal -Write clean, well-structured code AND tests that implement the current plan phase. +Implement the current plan phase — code and tests — so it matches the spec and passes build and tests. ## Context @@ -13,203 +13,34 @@ Write clean, well-structured code AND tests that implement the current plan phas - **Current State**: {{current_state}} - **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}} -## ⚠️ SCOPE RESTRICTION — READ THIS FIRST +## Scope: this phase only -**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).** +Your scope is exactly `{{plan_phase_id}}` ({{plan_phase_title}}), whose details are included below under "Current Plan Phase Details". Other phases are handled in later porch iterations — do not implement them, and do not read the full plan and build everything you see. Read `codev/specs/{{project_id}}-*.md` for requirements, but implement only what this phase requires. -- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations. -- **DO NOT** read the full plan file and implement everything you see. -- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope. -- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires. +When you signal `PHASE_COMPLETE`, porch runs the 3-way consultation, checks that tests exist and pass, and either respawns you with feedback or commits and moves to the next phase. -## What Happens After You Finish +## What must be true when you finish -When you signal `PHASE_COMPLETE`, porch will: -1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation -2. Check that tests exist and pass -3. If reviewers request changes, you'll be respawned with their feedback -4. Once approved, porch commits and moves to the next plan phase - -## Spec Compliance (CRITICAL) - -**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".** - -### Trust Hierarchy - -``` -SPEC (source of truth) - ↓ -PLAN (implementation guide derived from spec) - ↓ -EXISTING CODE (NOT TRUSTED - must be validated against spec) -``` - -**Never trust existing code over the spec.** Previous implementations may have drifted. - -### Pre-Implementation Sanity Check (PISC) - -**Before writing ANY code:** - -1. ✅ "Have I read the spec in the last 30 minutes?" -2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?" -3. ✅ "Does my approach match the spec's Technical Implementation section?" -4. ✅ "If the spec has code examples, am I following them?" -5. ✅ "Does the existing code I'm building on actually match the spec?" - -**If ANY answer is "no" or "unsure" → STOP and re-read the spec.** - -### Avoiding "Fixing Mode" - -A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to: -- Cargo-culting patterns that may be wrong -- Building on broken foundations -- Implementing something different from the spec - -**When you catch yourself "fixing" code:** -1. STOP -2. Ask: "What does the spec say about this?" -3. Re-read the spec's Traps to Avoid section -4. Verify existing code matches the spec before building on it - -## Prerequisites - -Before implementing, verify: -1. Previous phase (if any) is committed to git -2. You've read the plan phase you're implementing -3. You understand the success criteria for this phase -4. Dependencies from earlier phases are available - -## Process - -### 1. Review the Plan Phase - -Read the current phase in the plan: -- What is the objective? -- What files need to be created/modified? -- What are the success criteria? -- What dependencies exist? - -### 2. Set Up - -- Verify you're on the correct branch -- Check that previous phase is committed: `git log --oneline -5` -- Ensure build passes before starting: `npm run build` (or equivalent) - -### 3. Implement the Code - -Write the code following these principles: - -**Code Quality Standards**: -- Self-documenting code (clear names, obvious structure) -- No commented-out code -- No debug prints in final code -- Explicit error handling -- Follow project style guide - -**Implementation Approach**: -- Work on one file at a time -- Make small, incremental changes -- Document complex logic with comments - -### 4. Write Tests - -**Tests are required.** For each piece of functionality you implement: - -- Write unit tests for core logic -- Write integration tests if the phase involves multiple components -- Test error cases and edge conditions -- Ensure tests are deterministic (no flaky tests) - -**Test file locations** (follow project conventions): -- `tests/` or `__tests__/` directories -- `*.test.ts` or `*.spec.ts` naming - -### 5. Verify Everything Works - -Run both build and tests: - -```bash -npm run build # Must pass -npm test # Must pass -``` - -**Important**: Don't assume these commands exist. Check `package.json` first. - -Fix any errors before signaling completion. - -### 6. Self-Review - -Before signaling completion: -- Read through all code changes -- Read through all test changes -- Verify code matches the spec requirements -- Ensure no accidental debug code -- Check test coverage is adequate - -## Output - -When complete, you should have: -- Modified/created source files as specified in the plan phase -- Tests covering the new functionality -- All build checks passing -- All tests passing +- **The implementation matches the spec.** The spec is the source of truth; the plan derives from it; existing code is not trusted until validated against the spec, because earlier work may have drifted. Code that "works" but diverges from the spec is wrong. When you notice yourself patching symptoms in existing code, stop and re-check what the spec actually requires before building further. +- **Tests exist and are meaningful.** Unit tests for the core logic, integration tests where the phase spans components, and coverage of error and edge cases. Tests are deterministic. Follow the project's existing test locations and naming. +- **Build and tests pass.** Confirm the actual project commands (check `package.json` rather than assuming `npm run build` / `npm test` exist) and run them; fix failures before signaling. +- **The change is clean.** Self-documenting names, explicit error handling, no commented-out or debug code, only the files this phase touches — the simplest solution that satisfies the phase, not more. ## Signals -When implementation AND tests are complete and passing: - -``` -PHASE_COMPLETE -``` - -If you encounter a blocker: - -``` -BLOCKED:reason goes here -``` - -If you need spec/plan clarification: - -``` - -Your specific questions here - -``` - -## Important Notes - -1. **Follow the plan** - Implement what's specified, not more -2. **Don't over-engineer** - Simplest solution that works -3. **Don't skip error handling** - But don't go overboard either -4. **Keep changes focused** - Only touch files in this phase -5. **Build AND tests must pass** - Don't signal complete until both pass -6. **Write tests** - Every implementation phase needs tests - -## What NOT to Do - -- Don't modify files outside this phase's scope -- Don't add features not in the spec -- Don't leave TODO comments for later (fix now or note as blocker) -- Don't skip writing tests -- Don't use `git add .` or `git add -A` when you commit (security risk) - -## Handling Problems - -**If the plan is unclear**: -Signal `AWAITING_INPUT` with your specific question. - -**If you discover the spec is wrong**: -Signal `BLOCKED` and explain the issue. The Architect may need to update the spec. - -**If a dependency is missing**: -Signal `BLOCKED` with details about what's missing. - -**If build or tests fail and you can't fix it**: -Signal `BLOCKED` with the error message. - -**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes): -1. **DO NOT** edit `status.yaml` to bypass checks -2. **DO NOT** skip porch checks or use workarounds to avoid the failure -3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`) -4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up -5. Commit the skip and continue with your work +- Implementation and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Blocked — the plan is wrong, the spec is wrong, a dependency is missing, or build/tests fail in a way you cannot resolve: + ``` + BLOCKED:reason goes here + ``` +- Need spec/plan clarification: + ``` + + Your specific questions here + + ``` + +A blocker is a signal, not a silent workaround: never edit `status.yaml` or bypass a porch check to force a green. diff --git a/codev/protocols/spir/prompts/plan.md b/codev/protocols/spir/prompts/plan.md index 2c12250dd..a70914431 100644 --- a/codev/protocols/spir/prompts/plan.md +++ b/codev/protocols/spir/prompts/plan.md @@ -2,9 +2,9 @@ You are executing the **PLAN** phase of the SPIR protocol. -## Your Goal +## Goal -Transform the approved specification into an executable implementation plan with clear phases. +Turn the approved spec into an executable plan at `codev/plans/{{artifact_name}}.md`: a phase breakdown a builder can implement one phase at a time. ## Context @@ -14,105 +14,41 @@ Transform the approved specification into an executable implementation plan with - **Spec File**: `codev/specs/{{artifact_name}}.md` - **Plan File**: `codev/plans/{{artifact_name}}.md` -## Prerequisites +## What must be true when you finish -Before planning, verify: -1. The specification exists and has been approved -2. You've read and understood the entire spec -3. Success criteria are clear and measurable +- **The plan derives from the spec.** You have read the whole spec — its functional and non-functional requirements, constraints, and success criteria — and the plan validates against them. +- **The work is decomposed into phases, each of which is:** + - **self-contained** — a complete unit of functionality; + - **independently testable** — verifiable on its own; + - **valuable** — delivers observable progress; + - **committable** — a single atomic commit. -## Process - -### 1. Analyze the Specification - -Read the spec thoroughly. Identify: -- All functional requirements -- Non-functional requirements -- Dependencies and constraints -- Success criteria to validate against - -### 2. Identify Implementation Phases - -Break the work into logical phases. Each phase should be: -- **Self-contained** - A complete unit of functionality -- **Independently testable** - Can be verified on its own -- **Valuable** - Delivers observable progress -- **Committable** - Can be a single atomic commit - -Good phase examples: -- "Database Schema" - Creates all tables/migrations -- "Core API Endpoints" - Implements main REST routes -- "Authentication Flow" - Handles login/logout/session - -Bad phase examples: -- "Setup" - Too vague -- "Part 1" - Not descriptive -- "Everything" - Not broken down - -### 3. Define Each Phase - -For each phase, document: -- **Objective** - Single clear goal -- **Files to modify/create** - Specific paths -- **Dependencies** - Which phases must complete first -- **Success criteria** - How to know it's done -- **Test approach** - What tests will verify it - -### 4. Order Phases by Dependencies - -Arrange phases so dependencies are satisfied: -``` -Phase 1: Database Schema (no dependencies) -Phase 2: Data Models (depends on Phase 1) -Phase 3: API Endpoints (depends on Phase 2) -Phase 4: Frontend Integration (depends on Phase 3) -``` - -### 5. Finalize - -After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. + A phase name states what it delivers ("Database schema", "Authentication flow"), not a position ("Setup", "Part 1"). +- **Each phase carries its own contract:** objective, the specific files it creates or modifies, which earlier phases it depends on, its success criteria, and how it will be tested. +- **Phases are ordered so dependencies are satisfied before the phase that needs them.** ## Output -Create the plan file at `codev/plans/{{artifact_name}}.md`, following the template below: +Write the plan to `codev/plans/{{artifact_name}}.md` using the template below as its interface: {{> protocols/spir/templates/plan.md}} ## Signals -Emit appropriate signals based on your progress: - -- After completing the plan draft: +- Draft done: ``` PLAN_DRAFTED ``` -## Commit Cadence +## Commit cadence -Make commits at these milestones: +Commit at each milestone, staging the plan file explicitly: +```bash +git add codev/plans/{{artifact_name}}.md +``` 1. `[Spec {{project_id}}] Initial implementation plan` 2. `[Spec {{project_id}}] Plan with multi-agent review` 3. `[Spec {{project_id}}] Plan with user feedback` 4. `[Spec {{project_id}}] Final approved plan` -**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: -```bash -git add codev/plans/{{artifact_name}}.md -``` - -## Important Notes - -1. **No time estimates** - Don't include hours/days/weeks -3. **Be specific about files** - Exact paths, not "the config file" -4. **Keep phases small** - 1-3 files per phase is ideal -5. **Document dependencies clearly** - Prevents blocked work - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't write code (that's for Implement phase) -- Don't estimate time (meaningless in AI development) -- Don't create phases that can't be independently tested -- Don't skip dependency analysis -- Don't make phases too large (if >5 files, split it) -- Don't use `git add .` or `git add -A` (security risk) +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Plan phase: decompose and sequence the work, do not write code, and do not estimate time. diff --git a/codev/protocols/spir/prompts/review.md b/codev/protocols/spir/prompts/review.md index eabe1b98e..b08cea345 100644 --- a/codev/protocols/spir/prompts/review.md +++ b/codev/protocols/spir/prompts/review.md @@ -2,9 +2,9 @@ You are executing the **REVIEW** phase of the SPIR protocol. -## Your Goal +## Goal -Perform a comprehensive review, document lessons learned, and prepare for PR submission. +Review the whole implementation, write the retrospective at `codev/reviews/{{artifact_name}}.md`, and open the PR — so porch's consultation and the architect both review a real PR. ## Context @@ -15,218 +15,65 @@ Perform a comprehensive review, document lessons learned, and prepare for PR sub - **Plan File**: `codev/plans/{{artifact_name}}.md` - **Review File**: `codev/reviews/{{artifact_name}}.md` -## Prerequisites +## What must be true when you finish -Before review, verify: -1. All implementation phases are committed -2. All tests are passing -3. Build is passing -4. Spec compliance verified for all phases +- **The work is done and green.** All phases committed (`git log --oneline | grep "[Spec {{project_id}}]"`), build and tests passing, no uncommitted changes. +- **The implementation has been reviewed against the spec** — code quality, architecture fit, and security considered; deviations from the spec noted with their reasons; every success criterion accounted for. +- **The review document exists** at `codev/reviews/{{artifact_name}}.md`, following the template below (its headings, its order — do not pattern-match an older review that predates it). +- **Consultation feedback is captured.** The review carries a `## Consultation Feedback` section that, per phase / round / model, records each concern and its disposition — **Addressed** (changed), **Rebutted** (why it does not apply), or **N/A** (out of scope / handled elsewhere). "No concerns raised — all consultations approved" is the right line when that is true; note COMMENT verdicts and any `CONSULT_ERROR`. Read the consult outputs from `codev/projects/{{project_id}}-*/`. +- **Governance facts are routed by tier** (see below). +- **The PR exists before you signal**, with a close-keyword so merging auto-closes the issue (see below). -Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"` - -## Process - -### 1. Comprehensive Review - -Review the entire implementation: - -**Code Quality**: -- Is the code readable and maintainable? -- Are there any code smells? -- Is error handling consistent? -- Are there any security concerns? - -**Architecture**: -- Does the implementation fit well with existing code? -- Are there any architectural concerns? -- Is the design scalable if needed? - -**Documentation**: -- Is code adequately commented where needed? -- Are public APIs documented? -- Is README updated if needed? - -### 2. Spec Comparison - -Compare final implementation to original specification: - -- What was delivered vs what was specified? -- Any deviations? Document why. -- All success criteria met? - -### 3. Create Review Document +## Output -Create `codev/reviews/{{artifact_name}}.md`, following the template below. Use these headings and this order — do not invent your own structure, and do not pattern-match an earlier review in `codev/reviews/` that predates this template. Steps 3b and 4 below expand on the `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch's review checks grep for the last two by exact heading. +Write the review to `codev/reviews/{{artifact_name}}.md` using the template below as its interface. Steps below expand its `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch greps the produced file for the last two by exact heading. {{> protocols/spir/templates/review.md}} -### 3b. Include Consultation Feedback - -**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded. - -Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model: - -```markdown -## Consultation Feedback - -### Specify Phase (Round 1) - -#### Gemini -- **Concern**: [Summary of the concern] - - **Addressed**: [What was changed to resolve it] - -#### Codex -- **Concern**: [Summary] - - **Rebutted**: [Why the current approach is correct] - -#### Claude -- No concerns raised (APPROVE) - -### Plan Phase (Round 1) -... -``` - -**Response types** — each concern gets exactly one: -- **Addressed**: Builder made a change to resolve the concern -- **Rebutted**: Builder explains why the concern doesn't apply -- **N/A**: Concern is out of scope, already handled elsewhere, or moot - -**Edge cases**: -- If all reviewers approved with no concerns: "No concerns raised — all consultations approved" -- For COMMENT verdicts: include their feedback (non-blocking but useful context) -- For CONSULT_ERROR (model failure): note "Consultation failed for [model]" -- If a phase had multiple rounds, give each round its own subsection +## Route governance facts by tier (Spec 987) -### 4. Update Architecture and Lessons Learned Documentation +Each governance doc has two tiers. **Route** each new fact; do not simply append to the cold archive. -**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing. +- **HOT** — `codev/resources/arch-critical.md` and `lessons-critical.md`: tiny, hard-capped, always injected into every prompt and into CLAUDE.md/AGENTS.md. Add here only a **behavior-changing, cross-cutting** fact a future builder must know up front. The hot files are capped: if one is full, **demote** a weaker entry into its cold counterpart to make room, and keep the hot file's cold-doc map accurate. +- **COLD** — `codev/resources/arch.md` and `lessons-learned.md`: full, on-demand reference for subsystem detail, file locations, one-offs, and spec-narrow recipes. -Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive: -- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer. -- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference. +The review's `## Architecture Updates` and `## Lessons Learned Updates` sections state what you routed where; if nothing qualifies, keep the heading with a one-line reason. Never grow a hot file past its cap by appending — route to cold or displace. The `update-arch-docs` skill encodes this discipline. -**Architecture Updates**: -1. Read `arch-critical.md` (hot) and skim `arch.md` (cold). -2. If this project produced a system-shape fact, route it: - - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate. - - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold). -3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason. +## Create the PR (before signaling) -**Lessons Learned Updates**: -1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold). -2. If this project produced a durable lesson, route it: - - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full). - - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file. -3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason. - -**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject. - -### 4b. Update Other Documentation - -If needed, also update: -- README.md (new features, changed behavior) -- API documentation - -### 5. Final Verification - -Before PR: -- [ ] All tests pass (use project-specific test command) -- [ ] Build passes (use project-specific build command) -- [ ] Lint passes (if configured) -- [ ] No uncommitted changes: `git status` -- [ ] Review document complete - -### 6. Create Pull Request - -**IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that -porch consultation reviews the actual PR, and the architect can review a real PR -when the pr gate fires. - -**PR body requirements**: The PR body MUST include `Closes #` (for feature issues) -or `Fixes #` (for bug issues) for the driving GitHub issue. If the PR closes -multiple issues (e.g. duplicates consolidated), include one keyword per issue. -Without this, GitHub will not auto-close the issue on merge. - -**Exception**: if this PR only partially addresses the issue (e.g. one phase of a -multi-PR effort), DO NOT use `Closes`/`Fixes` — reference the issue with `Refs #` -or `Part of #` instead. The issue stays open until the follow-up PR closes it. +The PR body must carry `Closes #` (feature) or `Fixes #` (bug) for the driving issue — one keyword per issue if several — so GitHub auto-closes on merge. **Exception:** a PR that only partially addresses its issue uses `Refs #` or `Part of #` instead, leaving the issue open for the follow-up. ```bash gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF' ## Summary -[Brief description of the implementation] +[what was implemented] -Closes # +Closes # ## Changes -- [Change 1] -- [Change 2] +- ... ## Testing -- All unit tests passing -- Integration tests added for [X] -- Manual testing completed for [Y] +- ... ## Spec -Link: codev/specs/{{artifact_name}}.md +codev/specs/{{artifact_name}}.md ## Review -Link: codev/reviews/{{artifact_name}}.md +codev/reviews/{{artifact_name}}.md EOF )" ``` -### 7. Signal Completion - -After the PR is created, signal completion. Porch will run 3-way consultation -(Gemini, Codex, Claude) automatically via the verify step. If reviewers request -changes, you'll be respawned with their feedback. - -## Output - -- Review document at `codev/reviews/{{artifact_name}}.md` -- Updated documentation (if needed) -- Pull request created and ready for review - ## Signals -- After review document is complete: +- Review document complete: ``` REVIEW_COMPLETE ``` - -- After PR is created — signal completion so porch runs consultation: +- PR created — signal so porch runs the 3-way consultation: ``` PR_READY ``` -## Important Notes - -1. **Be honest in lessons learned** - Future you will thank present you -3. **Document deviations** - They're not failures, they're learnings -4. **Update methodology** - If you found a better way, document it -5. **Don't skip the checklist** - It catches last-minute issues -6. **Clean PR description** - Makes review easier - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't skip lessons learned ("nothing to report") -- Don't merge your own PR (Architect handles integration) -- Don't leave uncommitted changes -- Don't forget to update documentation -- Don't rush this phase - it's valuable for learning -- Don't use `git add .` or `git add -A` (security risk) - -## Review Prompts for Reflection - -Ask yourself: -- What surprised me during implementation? -- Where did I spend the most time? Was it avoidable? -- What would have helped me go faster? -- Did the spec adequately describe what was needed? -- Did the plan phases make sense in hindsight? -- What tests caught issues? What tests were unnecessary? - -Capture these reflections in the lessons learned section. +Do not run `consult` (porch handles it) and merge your own PR only after the human approves the `pr` gate — never before. diff --git a/codev/protocols/spir/prompts/specify.md b/codev/protocols/spir/prompts/specify.md index daa5feab2..3c5af5a81 100644 --- a/codev/protocols/spir/prompts/specify.md +++ b/codev/protocols/spir/prompts/specify.md @@ -2,9 +2,9 @@ You are executing the **SPECIFY** phase of the SPIR protocol. -## Your Goal +## Goal -Create a comprehensive specification document that thoroughly explores the problem space and proposed solution. +Produce a specification at `codev/specs/{{artifact_name}}.md` that explores the problem space and the proposed solution well enough that the plan and implementation can follow without re-deciding anything. ## Context @@ -13,137 +13,47 @@ Create a comprehensive specification document that thoroughly explores the probl - **Current State**: {{current_state}} - **Spec File**: `codev/specs/{{artifact_name}}.md` -## Process +## What must be true when you finish -### 0. Check for Existing Spec (ALWAYS DO THIS FIRST) - -**Before asking ANY questions**, check if a spec already exists: - -```bash -ls codev/specs/{{project_id}}-*.md -``` - -**If a spec file exists:** -1. READ IT COMPLETELY - the answers to your questions are already there -2. The spec author has already made the key decisions -3. DO NOT ask clarifying questions - proceed directly to consultation -4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch - -**If no spec exists:** Proceed to Step 1 below. - -### 0.5 Baked Decisions - -Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec. - -If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting. - -### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS) - -Before writing anything, ask clarifying questions to understand: -- What problem is being solved? -- Who are the stakeholders? -- What are the constraints? -- What's in scope vs out of scope? -- What does success look like? - -If this is your first iteration AND no spec exists, ask these questions now and wait for answers. - -**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer. - -**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step. - -### 2. Problem Analysis - -Once you have answers, document: -- The problem being solved (clearly articulated) -- Current state vs desired state -- Stakeholders and their needs -- Assumptions and constraints - -### 3. Solution Exploration - -Generate multiple solution approaches. For each: -- Technical design overview -- Trade-offs (pros/cons) -- Complexity assessment -- Risk assessment - -### 4. Open Questions - -List uncertainties categorized as: -- **Critical** - blocks progress -- **Important** - affects design -- **Nice-to-know** - optimization - -### 5. Success Criteria - -Define measurable acceptance criteria: -- Functional requirements (MUST, SHOULD, COULD) -- Non-functional requirements (performance, security) -- Test scenarios - -### 6. Finalize - -After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. +- **An existing spec is honored, not rewritten.** If `codev/specs/{{project_id}}-*.md` already exists, it carries the architect's decisions — read it fully and refine it in place. Clarifying questions are for the case where no spec exists yet; when one does, the spec is the answer. +- **Baked Decisions are fixed.** If the issue body has a "Baked Decisions" section (any heading level, case-insensitive), copy it verbatim into the spec's Constraints and treat each item as settled — **do not autonomously override** the architect's choices in Solution Exploration. Raise a genuine problem with a baked decision via `afx send architect` rather than overriding it. If two baked decisions contradict each other, do not choose — **pause**, **flag** the contradiction via `afx send`, and wait for resolution. +- **The problem is characterized before solutions are.** Current state vs desired state, stakeholders, assumptions, and constraints are explicit. +- **Solutions are explored, not assumed.** More than one approach is considered, each with its trade-offs and risks, before one is recommended. +- **Open questions are surfaced and ranked** by whether they block progress, shape the design, or are merely nice to know. +- **Success is measurable.** Acceptance criteria are concrete enough to test against. ## Output -Create or update the specification file at `codev/specs/{{artifact_name}}.md`. - -Follow the canonical spec template reproduced below. Use these headings, in this order — do not invent your own structure, and do not pattern-match an earlier spec in `codev/specs/` that predates this template. If a section genuinely does not apply, keep the heading and write a one-line "N/A — [reason]" rather than deleting it. +Write the spec to `codev/specs/{{artifact_name}}.md` using the template below as its interface — these headings, in this order. A section that genuinely does not apply keeps its heading with a one-line `N/A — [reason]` rather than being deleted. Do not pattern-match an older spec in `codev/specs/` that predates this template. {{> protocols/spir/templates/spec.md}} -**IMPORTANT**: Keep spec/plan/review filenames in sync: -- Spec: `codev/specs/{{artifact_name}}.md` -- Plan: `codev/plans/{{artifact_name}}.md` -- Review: `codev/reviews/{{artifact_name}}.md` +Keep the three artifact filenames in sync: spec `codev/specs/{{artifact_name}}.md`, plan `codev/plans/{{artifact_name}}.md`, review `codev/reviews/{{artifact_name}}.md`. ## Signals -Emit appropriate signals based on your progress: - -- When waiting for clarifying question answers, **include your questions in the signal**: +- Waiting on clarifying-question answers — **put the questions inside the signal**, which is displayed prominently to the user: ``` - Please answer these questions: - 1. What should the primary use case be - internal tooling or customer-facing? - 2. What are the key constraints we should consider? - 3. Who are the main stakeholders? + Please answer: + 1. ... + 2. ... ``` - - The content inside the signal tag is displayed prominently to the user. - -- After completing the initial spec draft: +- Initial draft done: ``` SPEC_DRAFTED ``` +## Commit cadence -## Commit Cadence - -Make commits at these milestones: +Commit at each milestone, staging the spec file explicitly: +```bash +git add codev/specs/{{artifact_name}}.md +``` 1. `[Spec {{project_id}}] Initial specification draft` 2. `[Spec {{project_id}}] Specification with multi-agent review` 3. `[Spec {{project_id}}] Specification with user feedback` 4. `[Spec {{project_id}}] Final approved specification` -**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: -```bash -git add codev/specs/{{artifact_name}}.md -``` - -## Important Notes - -1. **Be thorough** - A good spec prevents implementation problems -3. **Be specific** - Vague specs lead to wrong implementations -4. **Include examples** - Concrete examples clarify intent - -## What NOT to Do - -- Don't run `consult` commands yourself (porch handles consultations) -- Don't include implementation details (that's for the Plan phase) -- Don't estimate time (AI makes time estimates meaningless) -- Don't start coding (you're in Specify, not Implement) -- Don't use `git add .` or `git add -A` (security risk) +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Specify phase: no implementation detail (that is the plan), no code, no time estimates. diff --git a/codev/protocols/spir/protocol.md b/codev/protocols/spir/protocol.md index 5922d9883..d7aef53b0 100644 --- a/codev/protocols/spir/protocol.md +++ b/codev/protocols/spir/protocol.md @@ -1,657 +1,108 @@ # SPIR Protocol -> **SPIR** = **S**pecify → **P**lan → **I**mplement → **R**eview -> -> Each phase has one build-verify cycle with 3-way consultation. +**S**pecify → **P**lan → **I**mplement → **R**eview. Each phase is a build-verify cycle with +3-way consultation, and two human gates stand before implementation begins. +Use SPIR for new features, new protocols, architecture changes, and complex refactors — work +where getting the shape wrong is expensive to discover late. For an isolated bug fix or a small +feature fully described in an issue, a lighter protocol costs less and loses nothing. -## Prerequisites +## The state machine -**Clean Worktree Before Spawning Builders**: -- All specs, plans, and local changes **MUST be committed** before `afx spawn` -- Builders work in git worktrees branched from HEAD — uncommitted files are invisible -- This includes `codev update` results, spec drafts, and plan approvals -- The `afx spawn` command enforces this (use `--force` to override) - -**Required for Multi-Agent Consultation**: -- The `consult` CLI must be available (installed with `npm install -g @cluesmith/codev`) -- At least one consultation backend: `claude`, `gemini-cli`, or `codex` -- Check with: `codev doctor` or `consult --help` - -## Protocol Configuration - -### Multi-Agent Consultation (ENABLED BY DEFAULT) - -**DEFAULT BEHAVIOR:** -Multi-agent consultation is **ENABLED BY DEFAULT** when using SPIR protocol. - -**DEFAULT AGENTS:** -- **GPT-5 Codex**: Primary reviewer for architecture, feasibility, and code quality -- **Gemini Pro**: Secondary reviewer for completeness, edge cases, and alternative approaches - -**DISABLING CONSULTATION:** -To run SPIR without consultation, say "without consultation" when starting work. - -**CUSTOM AGENTS:** -The user can specify different agents by saying: "use SPIR with consultation from [agent1] and [agent2]" - -**CONSULTATION BEHAVIOR:** -- DEFAULT: MANDATORY consultation with GPT-5 and Gemini Pro at EVERY checkpoint -- When explicitly disabled: Skip all consultation steps -- The protocol is BLOCKED until all required consultations are complete - -**Consultation Checkpoints**: -- **Specification**: After initial draft, after human comments -- **Planning**: After initial plan, after human review -- **Implementation**: After code implementation -- **Defending**: After test creation -- **Evaluation**: Before marking phase complete -- **Review**: After review document - -## Overview -SPIR is a structured development protocol that emphasizes specification-driven development with iterative implementation and continuous review. It builds upon the DAPPER methodology with a focus on context-first development and multi-agent collaboration. - -**The SPIR Model**: -- **S - Specify**: Write specification with 3-way review → Gate: `spec-approval` -- **P - Plan**: Write implementation plan with 3-way review → Gate: `plan-approval` -- **I - Implement**: Execute each plan phase with build-verify cycle (one cycle per phase) -- **R - Review**: Final review and PR preparation with 3-way review - -Each phase follows a build-verify loop: build the artifact, then verify with 3-way consultation (Gemini, Codex, Claude). - -**Core Principle**: Each feature is tracked through exactly THREE documents - a specification, a plan, and a review with lessons learned - all sharing the same filename and sequential identifier. - -## When to Use SPIR - -### Use SPIR for: -- New feature development -- Architecture changes -- Complex refactoring -- System design decisions -- API design and implementation -- Performance optimization initiatives - -### Skip SPIR for: -- Simple bug fixes (< 10 lines) -- Documentation updates -- Configuration changes -- Dependency updates -- Emergency hotfixes (but do a lightweight retrospective after) - -## Baked Decisions (Optional) - -When filing an issue for SPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`. - -## Protocol Phases - -### S - Specify (Collaborative Design Exploration) - -**Purpose**: Thoroughly explore the problem space and solution options before committing to an approach. - -**Workflow Overview**: -1. User provides a prompt describing what they want built -2. Agent generates initial specification document -3. **COMMIT**: "Initial specification draft" -4. Multi-agent review (GPT-5 and Gemini Pro) -5. Agent updates spec with multi-agent feedback -6. **COMMIT**: "Specification with multi-agent review" -7. Human reviews and provides comments for changes -8. Agent makes changes and lists what was modified -9. **COMMIT**: "Specification with user feedback" -10. Multi-agent review of updated document -11. Final updates based on second review -12. **COMMIT**: "Final approved specification" -13. Iterate steps 7-12 until user approves and says to proceed to planning - -**Important**: Keep documentation minimal - use only THREE core files with the same name: -- `specs/####-descriptive-name.md` - The specification -- `plans/####-descriptive-name.md` - The implementation plan -- `reviews/####-descriptive-name.md` - Review and lessons learned (created during Review phase) - -**Process**: -1. **Clarifying Questions** (ALWAYS START HERE) - - Ask the user/stakeholder questions to understand the problem - - Probe for hidden requirements and constraints - - Understand the business context and goals - - Identify what's in scope and out of scope - - Continue asking until the problem is crystal clear - -2. **Problem Analysis** - - Clearly articulate the problem being solved - - Identify stakeholders and their needs - - Document current state and desired state - - List assumptions and constraints - -3. **Solution Exploration** - - Generate multiple solution approaches (as many as appropriate) - - For each approach, document: - - Technical design - - Trade-offs (pros/cons) - - Estimated complexity - - Risk assessment - -4. **Open Questions** - - List all uncertainties that need resolution - - Categorize as: - - Critical (blocks progress) - - Important (affects design) - - Nice-to-know (optimization) - -5. **Success Criteria** - - Define measurable acceptance criteria - - Include performance requirements - - Specify quality metrics - - Document test scenarios - -6. **Expert Consultation (DEFAULT - MANDATORY)** - - **First Consultation** (after initial draft): - - MUST consult GPT-5 AND Gemini Pro - - Focus: Problem clarity, solution completeness, missing requirements - - Update specification with ALL feedback from both models - - Document changes in "Consultation Log" section of the spec - - **Second Consultation** (after human comments): - - MUST consult GPT-5 AND Gemini Pro again - - Focus: Validate changes, ensure alignment - - Final specification update with both models' input - - Update "Consultation Log" with new feedback - - **Note**: Only skip if user explicitly requested "without multi-agent consultation" - -**⚠️ BLOCKING**: Cannot proceed without BOTH consultations (unless explicitly disabled) - -**Output**: Single specification document in `codev/specs/####-descriptive-name.md` -- All consultation feedback incorporated directly into this document -- Include a "Consultation Log" section summarizing key feedback and changes -- Version control captures evolution through commits -**Structure**: developed through the specify phase -**Review Required**: Yes - Human approval AFTER consultations - -### P - Plan (Structured Decomposition) - -**Purpose**: Transform the approved specification into an executable roadmap with clear phases. - -**⚠️ CRITICAL: No Time Estimates in the AI Age** -- **NEVER include time estimates** (hours, days, weeks, story points) -- AI-driven development makes traditional time estimates meaningless -- Delivery speed depends on iteration cycles, not calendar time -- Focus on logical dependencies and phase ordering instead -- Measure progress by completed phases, not elapsed time -- The only valid metrics are: "done" or "not done" - -**Workflow Overview**: -1. Agent creates initial plan document -2. **COMMIT**: "Initial plan draft" -3. Multi-agent review (GPT-5 and Gemini Pro) -4. Agent updates plan with multi-agent feedback -5. **COMMIT**: "Plan with multi-agent review" -6. User reviews and requests modifications -7. Agent updates plan based on user feedback -8. **COMMIT**: "Plan with user feedback" -9. Multi-agent review of updated plan -10. Final updates based on second review -11. **COMMIT**: "Final approved plan" -12. Iterate steps 6-11 until agreement is reached - -**Phase Design Goals**: -Each phase should be: -- A separate piece of work that can be checked in as a unit -- A complete set of functionality -- Self-contained and independently valuable - -**Process**: -1. **Phase Definition** - - Break work into logical phases - - Each phase must: - - Have a clear, single objective - - Be independently testable - - Deliver observable value - - Be a complete unit that can be committed - - End with evaluation discussion and single commit - - Note dependencies inline, for example: - ```markdown - Phase 2: API Endpoints - - Depends on: Phase 1 (Database Schema) - - Objective: Create /users and /todos endpoints - - Evaluation: Test coverage, API design review, performance check - - Commit: Will create single commit after user approval - ``` - -2. **Success Metrics** - - Define "done" for each phase - - Include test coverage requirements - - Specify performance benchmarks - - Document acceptance tests - -3. **Expert Review (DEFAULT - MANDATORY)** - - **First Consultation** (after plan creation): - - MUST consult GPT-5 AND Gemini Pro - - Focus: Feasibility, phase breakdown, completeness - - Update plan with ALL feedback from both models - - **Second Consultation** (after human review): - - MUST consult GPT-5 AND Gemini Pro again - - Focus: Validate adjustments, confirm approach - - Final plan refinement with both models' input - - **Note**: Only skip if user explicitly requested "without multi-agent consultation" - -**⚠️ BLOCKING**: Cannot proceed without BOTH consultations (unless explicitly disabled) - -**Output**: Single plan document in `codev/plans/####-descriptive-name.md` -- Same filename as specification, different directory -- All consultation feedback incorporated directly -- Include phase status tracking within this document -- **DO NOT include time estimates** - Focus on deliverables and dependencies, not hours/days -- Version control captures evolution through commits -**Structure**: follows the plan template provided by the plan phase -**Review Required**: Yes - Technical lead approval AFTER consultations - -### I - Implement (Per Plan Phase) - -Execute for each phase in the plan. Each phase follows a build-verify cycle. - -**CRITICAL PRECONDITION**: Before starting any phase, verify the previous phase was committed to git. No phase can begin without the prior phase's commit. - -**Build-Verify Cycle Per Phase**: -1. **Build** - Implement code and tests for this phase -2. **Verify** - 3-way consultation (Gemini, Codex, Claude) -3. **Iterate** - Address feedback until verification passes -4. **Commit** - Single atomic commit for the phase (MANDATORY before next phase) -5. **Proceed** - Move to next phase only after commit - -**Handling Failures**: -- If verification reveals gaps → iterate and fix -- If fundamental plan flaws found → mark phase as `blocked` and revise plan - -**Commit Requirements**: -- Each phase MUST end with a git commit before proceeding -- Commit message format: `[Spec ####][Phase: name] type: Description` -- No work on the next phase until current phase is committed -- If changes are needed after commit, create a new commit with fixes - -#### I - Implement (Build with Discipline) - -**Purpose**: Transform the plan into working code with high quality standards. - -**Precondition**: Previous phase must be committed (verify with `git log`) - -**Requirements**: -1. **Pre-Implementation** - - Verify previous phase is committed to git - - Review the phase plan and success criteria - - Set up the development environment - - Create feature branch following naming convention - - Document any plan deviations immediately - -2. **During Implementation** - - Write self-documenting code - - Follow project style guide strictly - - Implement incrementally with frequent commits - - Each commit must: - - Be atomic (single logical change) - - Include descriptive message - - Reference the phase - - Pass basic syntax checks - -3. **Code Quality Standards** - - No commented-out code - - No debug prints in final code - - Handle all error cases explicitly - - Include necessary logging - - Follow security best practices - -4. **Documentation Requirements** - - Update API documentation - - Add inline comments for complex logic - - Update README if needed - - Document configuration changes - -**Evidence Required**: -- Link to commits -- Code review approval (if applicable) -- No linting errors -- CI pipeline pass link (build/test/lint) - -**Expert Consultation (DEFAULT - MANDATORY)**: -- MUST consult BOTH GPT-5 AND Gemini Pro after implementation -- Focus: Code quality, patterns, security, best practices -- Update code based on feedback from BOTH models before proceeding -- Only skip if user explicitly disabled multi-agent consultation - -#### D - Defend (Write Comprehensive Tests) - -**Purpose**: Create comprehensive automated tests that safeguard intended behavior and prevent regressions. - -**CRITICAL**: Tests must be written IMMEDIATELY after implementation, NOT retroactively at the end of all phases. This is MANDATORY. - -**Requirements**: -1. **Defensive Test Creation** - - Write unit tests for all new functions - - Create integration tests for feature flows - - Develop edge case coverage - - Build error condition tests - - Establish performance benchmarks - -2. **Test Validation** (ALL MANDATORY) - - All new tests must pass - - All existing tests must pass - - No reduction in overall coverage - - Performance benchmarks met - - Security scans pass - - **Avoid Overmocking**: - - Test behavior, not implementation details - - Prefer integration tests over unit tests with heavy mocking - - Only mock external dependencies (APIs, databases, file systems) - - Never mock the system under test itself - - Use real implementations for internal module boundaries - -3. **Test Suite Documentation** - - Document test scenarios - - Explain complex test setups - - Note any flaky tests - - Record performance baselines - -**Evidence Required**: -- Test execution logs -- Coverage report (show no reduction) -- Performance test results (if applicable per spec) -- Security scan results (if configured) -- CI test run link with artifacts - -**Expert Consultation (DEFAULT - MANDATORY)**: -- MUST consult BOTH GPT-5 AND Gemini Pro for test defense review -- Focus: Test coverage completeness, edge cases, defensive patterns, test strategy -- Write additional defensive tests based on feedback from BOTH models -- Share their feedback during the Evaluation discussion -- Only skip if user explicitly disabled multi-agent consultation - -#### E - Evaluate (Assess Objectively) - -**Purpose**: Verify the implementation fully satisfies the phase requirements and maintains system quality. This is where the critical discussion happens before committing the phase. - -**Requirements**: -1. **Functional Evaluation** - - All acceptance criteria met - - User scenarios work as expected - - Edge cases handled properly - - Error messages are helpful - -2. **Non-Functional Evaluation** - - Performance requirements satisfied - - Security standards maintained - - Code maintainability assessed - - Technical debt documented - -3. **Deviation Analysis** - - Document any changes from plan - - Explain reasoning for changes - - Assess impact on other phases - - Update future phases if needed - - **Overmocking Check** (MANDATORY): - - Verify tests focus on behavior, not implementation - - Ensure at least one integration test per critical path - - Check that internal module boundaries use real implementations - - Confirm mocks are only used for external dependencies - - Tests should survive refactoring that preserves behavior - -4. **Expert Consultation Before User Evaluation** (MANDATORY - NO EXCEPTIONS) - - Get initial feedback from experts - - Make ALL necessary fixes based on feedback - - **CRITICAL**: Get FINAL approval from ALL consulted experts on the FIXED version - - Only proceed to user evaluation after ALL experts approve - - If any expert says "not quite" or has concerns, fix them FIRST - -5. **Evaluation Discussion with User** (ONLY AFTER EXPERT APPROVAL) - - Present to user: "Phase X complete. Here's what was built: [summary]" - - Share test results and coverage metrics - - Share that ALL experts have given final approval - - Ask: "Any changes needed before I commit this phase?" - - Incorporate user feedback if requested - - Get explicit approval to proceed - -6. **Phase Commit** (MANDATORY - NO EXCEPTIONS) - - Create single atomic commit for the entire phase - - Commit message: `[Spec ####][Phase: name] type: Description` - - Update the plan document marking this phase as complete - - Push all changes to version control - - Document any deviations or decisions in the plan - - **CRITICAL**: Next phase CANNOT begin until this commit is complete - - Verify commit with `git log` before proceeding - -7. **Final Verification** - - Confirm all expert feedback was addressed - - Verify all tests pass - - Check that documentation is updated - - Ensure no outstanding concerns from experts or user - -**Evidence Required**: -- Evaluation checklist completed -- Test results and coverage report -- Expert review notes from GPT-5 and Gemini Pro -- User approval from evaluation discussion -- Updated plan document with: - - Phase marked complete - - Evaluation discussion summary - - Any deviations noted -- Git commit for this phase -- Final CI run link after all fixes - -## 📋 PHASE COMPLETION CHECKLIST (MANDATORY BEFORE NEXT PHASE) - -**⚠️ STOP: DO NOT PROCEED TO NEXT PHASE UNTIL ALL ITEMS ARE ✅** - -### Before Starting ANY Phase: -- [ ] Previous phase is committed to git (verify with `git log`) -- [ ] Plan document shows previous phase as `completed` -- [ ] No outstanding issues from previous phase - -### After Implement Phase: -- [ ] All code for this phase is complete -- [ ] Code follows project style guide -- [ ] No commented-out code or debug prints -- [ ] Error handling is implemented -- [ ] Documentation is updated (if needed) -- [ ] Expert consultation completed (GPT-5 + Gemini Pro) -- [ ] Expert feedback has been addressed - -### After Defend Phase: -- [ ] Unit tests written for all new functions -- [ ] Integration tests written for critical paths -- [ ] Edge cases have test coverage -- [ ] All new tests are passing -- [ ] All existing tests still pass -- [ ] No reduction in code coverage -- [ ] Overmocking check completed (tests focus on behavior) -- [ ] Expert consultation on tests completed -- [ ] Test feedback has been addressed - -### After Evaluate Phase: -- [ ] All acceptance criteria from spec are met -- [ ] Performance requirements satisfied -- [ ] Security standards maintained -- [ ] Expert consultation shows FINAL approval -- [ ] User evaluation discussion completed -- [ ] User has given explicit approval to proceed -- [ ] Plan document updated with phase status -- [ ] Phase commit created with proper message format -- [ ] Commit pushed to version control -- [ ] Commit verified with `git log` - -### ❌ PHASE BLOCKERS (Fix Before Proceeding): -- Any failing tests -- Unaddressed expert feedback -- Missing user approval -- Uncommitted changes -- Incomplete documentation -- Coverage reduction - -**REMINDER**: Each phase is atomic. You cannot start the next phase until the current phase is fully complete, tested, evaluated, and committed. - -### R - Review/Refine/Revise (Continuous Improvement) - -**Purpose**: Ensure overall coherence, capture learnings, improve the methodology, and perform systematic review. - -**Precondition**: All implementation phases must be committed (verify with `git log --oneline | grep "\[Phase"`) - -**Process**: -1. **Comprehensive Review** - - Verify all phases have been committed to git - - Compare final implementation to original specification - - Assess overall architecture impact - - Review code quality across all changes - - Validate documentation completeness - -2. **Refinement Actions** - - Refactor code for clarity if needed - - Optimize performance bottlenecks - - Improve test coverage gaps - - Enhance documentation - -3. **Update Architecture Documentation** - - Route new system-shape facts and durable wisdom by tier (Spec 987): behavior-changing + cross-cutting → the HOT `codev/resources/arch-critical.md` / `lessons-critical.md` (capped, always-injected; demote a weaker entry to cold if full); reference detail → the COLD `codev/resources/arch.md` / `lessons-learned.md` - - Use the **`update-arch-docs` skill** (at `.claude/skills/update-arch-docs/SKILL.md`) to apply changes — it encodes the hot/cold two-tier discipline (caps + cold-doc maps for the hot files; reference archive for the cold files) and what NOT to include - - Follow guidance in the MAINTAIN protocol's Step 3 ("Sync Documentation") for structure, the "Lives where" routing matrix, and pruning checklists - - Ensure both docs reflect current state - -4. **Revision Requirements** (MANDATORY) - - Update README.md with any new features or changes - - Update AGENTS.md and CLAUDE.md with protocol improvements from lessons learned - - Update specification and plan documents with final status - - Revise architectural diagrams if needed - - Update API documentation - - Modify deployment guides as necessary - - **CRITICAL**: Update this protocol document based on lessons learned - -5. **Systematic Issue Review** (MANDATORY) - - Review entire project for systematic issues: - - Repeated problems across phases - - Process bottlenecks or inefficiencies - - Missing documentation patterns - - Technical debt accumulation - - Testing gaps or quality issues - - Document systematic findings in lessons learned - - Create action items for addressing systematic issues - -6. **Lessons Learned** (MANDATORY) - - What went well? - - What was challenging? - - What would you do differently? - - What methodology improvements are needed? - - What systematic issues were identified? - -7. **Methodology Evolution** - - Propose process improvements based on lessons - - Update protocol documents with improvements - - Update templates if needed - - Share learnings with team - - Document in `codev/reviews/` - - **Important**: This protocol should evolve based on each project's learnings - -**Output**: -- Single review document in `codev/reviews/####-descriptive-name.md` -- Same filename as spec/plan, captures review and learnings from this feature -- Methodology improvement proposals (update protocol if needed) - -**Review Required**: Yes - Team retrospective recommended - -## File Naming Conventions - -### Specifications and Plans -Format: `####-descriptive-name.md` -- Use sequential numbering (1, 2, etc.) -- Same filename in both `specs/` and `plans/` directories -- Example: `1-user-authentication.md` - -## Status Tracking - -Status is tracked at the **phase level** within plan documents, not at the document level. - -Each phase in a plan should have a status: -- `pending`: Not started -- `in-progress`: Currently being worked on -- `completed`: Phase finished and tested -- `blocked`: Cannot proceed due to external factors - -## Git Integration - -### Commit Message Format - -For specification/plan documents: -``` -[Spec ####] : -``` +Phases, gates, checks and their order are defined here. This is the authoritative source; the +prose below is only what the JSON cannot express. -Examples: -``` -[Spec 1] Initial specification draft -[Spec 1] Specification with multi-agent review -[Spec 1] Specification with user feedback -[Spec 1] Final approved specification +```json +{{> protocols/spir/protocol.json}} ``` -For implementation: -``` -[Spec ####][Phase: ] : +## Artifacts - -``` +Three documents per feature, **same base filename** in three directories: -Example: -``` -[Spec 1][Phase: user-auth] feat: Add password hashing service +| Document | Answers | Written during | +|---|---|---| +| `codev/specs/-.md` | what and why | Specify | +| `codev/plans/-.md` | how, and in what order | Plan | +| `codev/reviews/-.md` | what was learned | Review | -Implements bcrypt-based password hashing with configurable rounds -``` +Sequential numbering, no leading zeros: `42-user-authentication.md`. -### Branch Naming -``` -spir/####-/ -``` +Specs and plans stay separate. A spec that has acquired file paths and step ordering has become +a plan — and the gate meant to catch a wrong approach is now reviewing an implementation. -Example: -``` -spir/1-user-authentication/database-schema -``` +The plan carries a machine-readable `phases` JSON block. Porch parses it to track progress, so +it is a contract, not an illustration. + +## Phases +**Specify** — explore the problem before committing to an approach. Ask clarifying questions +first; they are cheapest before anything is written. Capture the problem, current and desired +state, several solution approaches with their trade-offs, open questions ranked by whether they +block, and measurable success criteria. -## Best Practices +**Plan** — decompose into phases that are each independently testable, independently valuable, +and committable as a unit. Note dependencies inline. **No time estimates.** Delivery speed +depends on iteration cycles, not calendar time, and an estimate in an AI-driven project is noise +that later gets quoted back as a commitment. -### During Specification -- Use clear, unambiguous language -- Include concrete examples -- Define measurable success criteria -- Link to relevant references +**Implement** — one build-verify cycle per plan phase: build, verify by 3-way consultation, +address what reviewers find, commit. The commit is what makes the next phase safe to begin; a +phase that is "done but uncommitted" can vanish. If verification exposes a flaw in the *plan* +rather than the code, mark the phase blocked and revise the plan — implementing around a +known-wrong plan is how a project ships the wrong thing carefully. -### During Planning -- Keep phases small and focused -- Ensure each phase delivers value -- Note phase dependencies inline (no formal dependency mapping needed) -- Include rollback strategies +Tests belong to the phase that creates the behaviour, not to a cleanup pass at the end. +Retroactive tests document what was built; tests written alongside constrain what gets built. +Mock external dependencies only — mocking the system under test proves the mock works. -### During Implementation -- Follow the plan but document deviations -- Maintain test coverage -- Keep commits atomic and well-described -- Update documentation as you go +**Review** — compare the implementation against the specification, record lessons, and route new +facts by tier: behaviour-changing and cross-cutting to `arch-critical.md` / +`lessons-critical.md` (capped — displace a weaker entry rather than growing them), reference +detail to `arch.md` / `lessons-learned.md`. The `update-arch-docs` skill encodes that routing. -### During Review -- Check against original specification -- Document lessons learned -- Propose methodology improvements -- Update estimates for future work +## Consultation -## Templates +3-way consultation (Gemini, Codex, Claude) is **on by default** and runs at each phase's verify +step. Disable it only when the human explicitly asks. + +It is not a formality: it reliably catches security, design and protocol problems that solo +review misses, and the cost of skipping it is paid later by someone with less context. + +## Gates + +`spec-approval`, `plan-approval` and `pr` are **human** decisions. Stop and wait. A gate message +is a notification to a human, not authorization to proceed. + +## Baked Decisions + +An issue may carry a `## Baked Decisions` section pinning architectural choices the architect +does not want re-litigated — typically **language**, **framework**, deployment shape, key +**dependencies**, or decisions deferred to a later spec. + +Every item in it is fixed. Copy the section verbatim into the spec's Constraints and do not +re-open it in the spec, plan, or review; CMAP reviewers will not propose alternatives unless the +spec fails to honour one. If two items contradict each other, do not choose — surface the +contradiction and wait. + +**Absence is the no-op default**: an issue with no such section is an invitation to explore +freely, not an omission to be filled in. + +The architect can **amend or rescind** a baked decision at any time by updating the issue and +respawning, or by sending the builder a direct instruction via `afx send`. + +## Git + +``` +[Spec 42] Initial specification draft +[Spec 42][Phase: user-auth] feat: Add password hashing service +``` -Each phase has a template that ships in the package skeleton; the phase prompts deliver the structure you need, so you do not fetch these files directly: -- `spec.md` - Specification template -- `plan.md` - Planning template (includes phase status tracking) -- `review.md` - Review and lessons learned template +Branches: `spir/42-feature-name/phase-name`. -**Remember**: Only create THREE documents per feature - spec, plan, and review with the same filename in different directories. +Each implement phase ends in one atomic commit before the next begins. -## Protocol Evolution +## Phase status -This protocol can be customized per project: -1. Fork the protocol directory -2. Modify templates and processes -3. Document changes in `protocol-changes.md` -4. Share improvements back to the community \ No newline at end of file +Tracked per phase inside the plan document, not per document: `pending`, `in-progress`, +`completed`, `blocked`. diff --git a/codev/protocols/spir/templates/plan.md b/codev/protocols/spir/templates/plan.md index 9da106498..13c35e916 100644 --- a/codev/protocols/spir/templates/plan.md +++ b/codev/protocols/spir/templates/plan.md @@ -1,184 +1,65 @@ # Plan: [Title] -## Metadata -- **ID**: plan-[YYYY-MM-DD]-[short-name] -- **Status**: draft -- **Specification**: [Link to codev/specs/spec-file.md] -- **Created**: [YYYY-MM-DD] +**Specification**: [Link to codev/specs/XXXX-*.md] ## Executive Summary -[Brief overview of the implementation approach chosen and why. Reference the specification's selected approach.] -## Success Metrics -[Copy from specification and add implementation-specific metrics] -- [ ] All specification criteria met -- [ ] Test coverage >90% -- [ ] Performance benchmarks achieved -- [ ] Zero critical security issues -- [ ] Documentation complete +The implementation approach chosen and why, referencing the spec's selected approach. ## Phases (Machine Readable) - + ```json { "phases": [ {"id": "phase_1", "title": "Phase 1 Title Here"}, - {"id": "phase_2", "title": "Phase 2 Title Here"}, - {"id": "phase_3", "title": "Phase 3 Title Here"} + {"id": "phase_2", "title": "Phase 2 Title Here"} ] } ``` ## Phase Breakdown +Repeat this block per phase. Each phase is self-contained, independently testable, valuable, and a single atomic commit. + ### Phase 1: [Descriptive Name] + **Dependencies**: None -#### Objectives -- [Clear, single objective for this phase] -- [What value does this phase deliver?] +#### Objective + +The single goal of this phase and the value it delivers. + +#### Files to Create / Modify + +Specific paths. #### Deliverables -- [ ] [Specific deliverable 1] -- [ ] [Specific deliverable 2] -- [ ] [Tests for this phase] -- [ ] [Documentation updates] - -#### Implementation Details -[Specific technical approach for this phase. Include: -- Key files/modules to create or modify -- Architectural decisions -- API contracts -- Data models] -#### Acceptance Criteria -- [ ] [Testable criterion 1] -- [ ] [Testable criterion 2] -- [ ] All tests pass -- [ ] Code review completed +- [ ] … +- [ ] Tests for this phase -#### Test Plan -- **Unit Tests**: [What to test] -- **Integration Tests**: [What to test] -- **Manual Testing**: [Scenarios to verify] +#### Acceptance Criteria -#### Rollback Strategy -[How to revert this phase if issues arise] +- [ ] Testable criterion(s), plus build and tests passing. -#### Risks -- **Risk**: [Specific risk for this phase] - - **Mitigation**: [How to address] +#### Test Plan ---- +Unit / integration / manual scenarios that verify this phase. ### Phase 2: [Descriptive Name] -**Dependencies**: Phase 1 - -[Repeat structure for each phase] ---- +**Dependencies**: Phase 1 -### Phase 3: [Descriptive Name] -**Dependencies**: Phase 2 +[Same structure.] -[Continue for all phases] +## Risks and Mitigation -## Dependency Map -``` -Phase 1 ──→ Phase 2 ──→ Phase 3 - ↓ - Phase 4 (optional) -``` +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| … | | | | -## Resource Requirements -### Development Resources -- **Engineers**: [Expertise needed] -- **Environment**: [Dev/staging requirements] - -### Infrastructure -- [Database changes] -- [New services] -- [Configuration updates] -- [Monitoring additions] - -## Integration Points -### External Systems -- **System**: [Name] - - **Integration Type**: [API/Database/Message Queue] - - **Phase**: [Which phase needs this] - - **Fallback**: [What if unavailable] - -### Internal Systems -[Repeat structure] - -## Risk Analysis -### Technical Risks -| Risk | Probability | Impact | Mitigation | Owner | -|------|------------|--------|------------|-------| -| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] | - -### Schedule Risks -| Risk | Probability | Impact | Mitigation | Owner | -|------|------------|--------|------------|-------| -| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] | - -## Validation Checkpoints -1. **After Phase 1**: [What to validate] -2. **After Phase 2**: [What to validate] -3. **Before Production**: [Final checks] - -## Monitoring and Observability -### Metrics to Track -- [Metric 1: Description and threshold] -- [Metric 2: Description and threshold] - -### Logging Requirements -- [What to log and at what level] -- [Retention requirements] - -### Alerting -- [Alert condition and severity] -- [Who to notify] - -## Documentation Updates Required -- [ ] API documentation -- [ ] Architecture diagrams -- [ ] Runbooks -- [ ] User guides -- [ ] Configuration guides - -## Post-Implementation Tasks -- [ ] Performance validation -- [ ] Security audit -- [ ] Load testing -- [ ] User acceptance testing -- [ ] Monitoring validation - -## Expert Review -**Date**: [YYYY-MM-DD] -**Model**: [Model consulted] -**Key Feedback**: -- [Feasibility assessment] -- [Missing considerations] -- [Risk identification] -- [Alternative suggestions] - -**Plan Adjustments**: -- [How the plan was modified based on feedback] - -## Approval -- [ ] Technical Lead Review -- [ ] Engineering Manager Approval -- [ ] Resource Allocation Confirmed -- [ ] Expert AI Consultation Complete - -## Change Log -| Date | Change | Reason | Author | -|------|--------|--------|--------| -| [Date] | [What changed] | [Why] | [Who] | - -## Notes -[Additional context, assumptions, or considerations] +## Documentation Updates +Which docs change (README, API docs, arch/lessons) — or none. diff --git a/codev/protocols/spir/templates/review.md b/codev/protocols/spir/templates/review.md index 668055637..2dc574789 100644 --- a/codev/protocols/spir/templates/review.md +++ b/codev/protocols/spir/templates/review.md @@ -2,128 +2,60 @@ ## Summary -[1-3 sentences: what was built, how many phases, net outcome.] +1–3 sentences: what was built, how many phases, the net outcome. ## Spec Compliance +Each acceptance criterion and whether it was met, with the phase that delivered it. + - [x] AC1: [Description] (Phase N) -- [x] AC2: [Description] (Phase N) - [ ] ACn: [Not met — reason] ## Deviations from Plan -- **Phase N**: [What changed and why] - -## Key Metrics - -- **Commits**: [N] on the branch -- **Tests**: [N] passing ([N] existing + [N] new) -- **Files created**: [list] -- **Files deleted**: [list] -- **Net LOC impact**: [+/-N lines] - -## Timelog - -All times [timezone], [date range]. - -| Time | Event | -|------|-------| -| HH:MM | First commit: [description] | -| HH:MM | [Phase/milestone] | -| — | **GATE: [gate-name]** (human approval required) | -| HH:MM | Implementation begins | -| HH:MM | Phase N complete after N iterations | -| HH:MM | **GATE: pr** | - -### Autonomous Operation - -| Period | Duration | Activity | -|--------|----------|----------| -| Spec + Plan | ~Nm | [Summary] | -| Human gate wait | ~Nh Nm | Idle — waiting for approval | -| Implementation → PR | ~Nh Nm | N phases, N consultation rounds | - -**Total wall clock** (first commit to pr): **Xh Ym** -**Total autonomous work time** (excluding gate waits): **~Xh Ym** -**Context window resets**: [N] (resumed automatically / required manual restart) - -## Consultation Iteration Summary - -[N] consultation files produced ([N] rounds x [N] models). [N] APPROVE, [N] REQUEST_CHANGES, [N] COMMENT. - -| Phase | Iters | Who Blocked | What They Caught | -|-------|-------|-------------|------------------| -| Specify | N | [Model] | [Brief description] | -| Plan | N | [Model] | [Brief description] | -| Phase 1 | N | [Model] | [Brief description] | -| Phase N | N | [Model] | [Brief description] | -| Review | N | [Model] | [Brief description] | - -**Most frequent blocker**: [Model] — blocked in N of N rounds, focused on: [pattern]. - -### Avoidable Iterations - -Iterations that could have been prevented with better builder behavior: - -1. **[Pattern]**: [Specific thing the builder should have done without needing reviewer feedback. E.g., "Run exhaustive grep before claiming all instances fixed."] - -2. **[Pattern]**: [Another avoidable iteration pattern.] +What changed from the plan, per phase, and why. "None" if the plan held. ## Consultation Feedback -[For each phase that had consultation, summarize every reviewer's concerns and how the builder responded. Use **Addressed** (fixed), **Rebutted** (disagreed with reasoning), or **N/A** (out of scope/moot) for each concern. If all reviewers approved with no concerns: "No concerns raised — all consultations approved."] +Per phase that had consultation, each reviewer's concerns and how you responded — **Addressed** (changed), **Rebutted** (why it does not apply), or **N/A** (out of scope / moot). "No concerns raised — all consultations approved" when that is true; note COMMENT verdicts and any `CONSULT_ERROR`. ### [Phase] Phase (Round N) #### Gemini -- **Concern**: [Summary of concern] - - **Addressed**: [What was changed] - -#### Codex -- **Concern**: [Summary of concern] - - **Rebutted**: [Why current approach is correct] - -#### Claude -- No concerns raised (APPROVE) +- **Concern**: … → **Addressed** / **Rebutted** / **N/A**: … ## Lessons Learned ### What Went Well -- [Specific positive observation — what worked and why] ### Challenges Encountered -- **[Challenge]**: [How it was resolved. How many iterations it cost.] + +What was hard and how it resolved. ### What Would Be Done Differently -- [Actionable improvement for future builders] ### Methodology Improvements -- [Suggested improvement to the SPIR protocol] -- [Suggested improvement to tooling] + +Suggested improvements to the SPIR protocol or the tooling. ## Architecture Updates -[What you routed where — HOT `codev/resources/arch-critical.md` (tiny, capped, always-injected) vs COLD `codev/resources/arch.md` (reference) — or why no changes were needed.] +What you routed where — HOT `codev/resources/arch-critical.md` (tiny, capped, always-injected) vs COLD `codev/resources/arch.md` (reference) — or why no change was needed. Note any hot-tier demotion made to respect the cap. -- Routed: [hot | cold] — [fact/section] — [what was added/changed; note any demotion if the hot file was full] -- Or: "No architecture updates needed — [brief reason]" +- Routed: [hot | cold] — [fact] — [what changed] +- Or: "No architecture updates needed — [reason]" ## Lessons Learned Updates -[What you routed where — HOT `codev/resources/lessons-critical.md` (capped) vs COLD `codev/resources/lessons-learned.md` (reference) — or why no changes were needed.] - -- Routed: [hot | cold] — [category] — [lesson summary] -- Or: "No lessons learned updates needed — [brief reason]" - -## Technical Debt +What you routed where — HOT `codev/resources/lessons-critical.md` (capped) vs COLD `codev/resources/lessons-learned.md` (reference) — or why no change was needed. -- [Any shortcuts taken or inconsistencies introduced] +- Routed: [hot | cold] — [category] — [lesson] +- Or: "No lessons learned updates needed — [reason]" ## Flaky Tests -- [Pre-existing tests skipped as flaky during this project — test name, file path, observed failure mode] -- [If none: "No flaky tests encountered"] +Pre-existing tests skipped as flaky during this project — name, file path, observed failure mode. "No flaky tests encountered" if none. ## Follow-up Items -- [Items identified for future work, outside this spec's scope] +Work identified for later, outside this spec's scope. diff --git a/codev/protocols/spir/templates/spec.md b/codev/protocols/spir/templates/spec.md index 4cca2177f..676afe79a 100644 --- a/codev/protocols/spir/templates/spec.md +++ b/codev/protocols/spir/templates/spec.md @@ -3,152 +3,58 @@ -## Metadata -- **ID**: spec-[YYYY-MM-DD]-[short-name] -- **Status**: draft -- **Created**: [YYYY-MM-DD] - -## Clarifying Questions Asked - -[List the questions you asked to understand the problem better and the responses received. This shows the discovery process.] - ## Problem Statement -[Clearly articulate the problem being solved. Include context about why this is important, who is affected, and what the current pain points are.] + +What problem is being solved, why it matters, who is affected, and the current pain points. ## Current State -[Describe how things work today. What are the limitations? What workarounds exist? Include specific examples.] + +How things work today, and the limitations or workarounds that motivate the change. Concrete examples. ## Desired State -[Describe the ideal solution. How should things work after implementation? What specific improvements will users see?] -## Stakeholders -- **Primary Users**: [Who will directly use this feature?] -- **Secondary Users**: [Who else is affected?] -- **Technical Team**: [Who will implement and maintain this?] -- **Business Owners**: [Who has decision authority?] +How things should work after implementation, and the specific improvements users will see. ## Success Criteria -- [ ] [Specific, measurable criterion 1] -- [ ] [Specific, measurable criterion 2] -- [ ] [Specific, measurable criterion 3] -- [ ] All tests pass with >90% coverage -- [ ] Performance benchmarks met (specify below) -- [ ] Documentation updated + +Measurable, testable acceptance criteria — the conditions under which this spec is satisfied. + +- [ ] … ## Constraints -### Technical Constraints -- [Existing system limitations] -- [Technology stack requirements] -- [Integration points] -### Business Constraints -- [Timeline requirements] -- [Budget considerations] -- [Compliance requirements] +Technical and business constraints that bound the solution: existing-system limits, required stack, integration points, compliance. ## Assumptions -- [List assumptions being made] -- [Include dependencies on other work] -- [Note any prerequisites] -## Solution Approaches - -### Approach 1: [Name] -**Description**: [Brief overview of this approach] +Assumptions being made and dependencies on other work. -**Pros**: -- [Advantage 1] -- [Advantage 2] +## Solution Approaches -**Cons**: -- [Disadvantage 1] -- [Disadvantage 2] +More than one approach where the space is open. For each: a short description, its trade-offs (pros/cons), and its risk/complexity. Name the recommended one and why. -**Estimated Complexity**: [Low/Medium/High] -**Risk Level**: [Low/Medium/High] +### Approach 1: [Name] ### Approach 2: [Name] -[Repeat structure for additional approaches] - -[Add as many approaches as appropriate for the problem] ## Open Questions -### Critical (Blocks Progress) -- [ ] [Question that must be answered before proceeding] - -### Important (Affects Design) -- [ ] [Question that influences technical decisions] - -### Nice-to-Know (Optimization) -- [ ] [Question that could improve the solution] - -## Performance Requirements -- **Response Time**: [e.g., <200ms p95] -- **Throughput**: [e.g., 1000 requests/second] -- **Resource Usage**: [e.g., <500MB memory] -- **Availability**: [e.g., 99.9% uptime] - -## Security Considerations -- [Authentication requirements] -- [Authorization model] -- [Data privacy concerns] -- [Audit requirements] +Ranked by how much they block: **Critical** (blocks progress) · **Important** (shapes design) · **Nice-to-know** (optimization). ## Test Scenarios -### Functional Tests -1. [Scenario 1: Happy path] -2. [Scenario 2: Edge case] -3. [Scenario 3: Error condition] -### Non-Functional Tests -1. [Performance test scenario] -2. [Security test scenario] -3. [Load test scenario] +The functional and non-functional scenarios that verify the success criteria — happy paths, edge cases, error conditions. -## Dependencies -- **External Services**: [List any external APIs or services] -- **Internal Systems**: [List internal dependencies] -- **Libraries/Frameworks**: [List required libraries] +## Risks and Mitigation -## References -- [Link to relevant documentation in codev/ref/] -- [Link to related specifications] -- [Link to architectural diagrams] -- [Link to research materials] +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| … | | | | -## Risks and Mitigation -| Risk | Probability | Impact | Mitigation Strategy | -|------|------------|--------|-------------------| -| [Risk 1] | Low/Med/High | Low/Med/High | [How to address] | -| [Risk 2] | Low/Med/High | Low/Med/High | [How to address] | - -## Expert Consultation - -**Date**: [YYYY-MM-DD] -**Models Consulted**: [e.g., GPT-5 and Gemini Pro] -**Sections Updated**: -- [Section name]: [Brief description of change based on consultation] -- [Section name]: [Brief description of change based on consultation] - -Note: All consultation feedback has been incorporated directly into the relevant sections above. - -## Approval -- [ ] Technical Lead Review -- [ ] Product Owner Review -- [ ] Stakeholder Sign-off -- [ ] Expert AI Consultation Complete - -## Notes -[Any additional context or considerations not covered above] +## References +Related specs, research, or documentation. diff --git a/codev/resources/1280-measurement-report.md b/codev/resources/1280-measurement-report.md new file mode 100644 index 000000000..7ac11aa2a --- /dev/null +++ b/codev/resources/1280-measurement-report.md @@ -0,0 +1,62 @@ + +# Spec 1280 — prompt-surface measurement: before / after + +## Headline audience loads (these overlap by design — never summed) + +| Audience | Phase 0 | Post-rewrite | Δ | | +|---|---:|---:|---:|---| +| **Builder (spir, I=10)** — the headline | 34,231 | **18,233** | −15,998 | **−47%** | +| Architect (per session) | 8,599 | 2,960 | −5,639 | −66% | +| Consultant (per review, spir) | 682 | 589 | −93 | −14% | + +## Exclusive buckets + +| Bucket | Phase 0 | Post-rewrite | Δ | +|---|---:|---:|---:| +| SHARED (CLAUDE.md + transcluded hot tier) | 6,551 | 2,153 | −4,398 | +| ARCHITECT (roles/architect.md) | 2,048 | 807 | −1,241 | +| DEAD (`codev-skeleton/porch/prompts`) | 4,009 | 0 | −4,009 (deleted, M6) | + +## Total authored surface — and the relocation proof (M0c) + +| Component | Phase 0 | Post-rewrite | Δ | +|---|---:|---:|---:| +| CLAUDE.md + AGENTS.md | 11,630 | 2,834 | −8,796 | +| protocols (both trees) | 88,461 | 50,028 | −38,433 | +| roles (both trees) | 8,274 | 3,814 | −4,460 | +| **skills (all four trees)** | 44,840 (42 files) | **49,356 (46 files)** | **+4,516** | +| **TOTAL_AUTHORED** | 153,205 | **106,032** | −47,173 (−31%) | + +**The skills component GREW while everything else shrank.** That is the M0c signal working as +designed: content that left the always-on surface under P3/P4 (CLI walkthroughs, worktree recipes, +tool how-tos) was *relocated* into on-demand skills — four new skill files, +4,516 words — not +deleted. An always-on-only metric would score that relocation identically to a deletion; the +total-authored basis distinguishes them. So the −47% always-on reduction is a mix of genuine prose +deletion (procedure → contract, examples → interfaces) and relocation to look-it-up surfaces. + +## Per-protocol (resolved per file, four-tier) + +| Protocol | BUILDER_SPAWN (0 → now) | PHASE mean | CONSULT mean | +|---|---|---|---| +| spir | 6,360 → 2,590 | 1,396 → 613 | 430 → 337 | +| aspir | 3,467 → 2,188 | 1,396 → 613 | 430 → 337 | +| pir | 4,801 → 2,107 | 1,435 → 1,411 | 491 → 384 | +| bugfix | 2,965 → 1,812 | 377 → 275 | 683 → 562 | +| air | 3,017 → 1,858 | 456 → 326 | 437 → 374 | +| maintain | 4,158 → 1,730 | 356 → 358 | 406 → 323 | + +(PIR's PHASE mean barely moved — its phase prompts were recently rewritten to a similar standard +and were largely load-bearing contract already; a conformant file passes unchanged.) + +## Capability preservation (M5) + +`scripts/extract-capability-inventory.sh` re-run post-rewrite and compared against the frozen +Phase-0 inventory (`codev/resources/1280-capability-inventory.json`, commit 5c962b7a): +**no gate, check, or signal present in the Phase-0 served prompts is absent post-rewrite.** Every +capability the rewrite preserved is provable in the served text; nothing was silently gutted. The +`{{artifact_name}}` substitution, the `{{> }}` template includes, the phases-JSON plan capability, +the `VERDICT:` consult contract, the PR-body close-keyword heredocs, and all `` tags survive. diff --git a/codev/resources/1280-retirements.md b/codev/resources/1280-retirements.md new file mode 100644 index 000000000..a0b78f7d4 --- /dev/null +++ b/codev/resources/1280-retirements.md @@ -0,0 +1,406 @@ +# Spec 1280 — retirements register + +Every entry here is an assertion or capability this project **removed rather than preserved**. +M5 and M10 both hard-fail on an unlisted removal, so an entry is only valid with the originating +spec named, the behaviour analysis stated, and **architect approval recorded**. + +Nothing in this file is self-approved. + +--- + +## R1 — `expectPureAdditionDiff` on the three builder-prompts + +**Status: APPROVED by the architect, 2026-08-01. Applied.** + +| | | +|---|---| +| **Assertion** | `baked-decisions.test.ts` → *"pure-addition diff: baseline lines are preserved in order"* | +| **Files** | `codev/protocols/{spir,aspir,air}/builder-prompt.md` | +| **Originating spec** | **Spec 746 — Baked Architectural Decisions** | +| **Baselines** | `fixtures/baselines/{spir,aspir,air}-builder-prompt.md.baseline` (113 lines each, **pre-746**) | + +### What it protects, exactly + +The baseline is the **pre-746** file. `expectPureAdditionDiff` walks the baseline and requires +every line to reappear, **in order**, in the current file. It therefore proves one thing: + +> *Spec 746's Baked Decisions paragraph was **added** without destroying any prior content.* + +A **pollution check** guards the guard: the baseline must **not** contain `## Baked Decisions`. +That catches the failure mode where someone re-captures the baseline after their own edit, +making the invariant vacuous. It is good design, and it is what stops me taking the easy route +here. + +### Why it cannot survive Spec 1280 + +Spec 1280 **deliberately deletes** prose from these prompts. The invariant "no pre-746 line was +ever removed" is now false by design, and permanently so: it forbids *any* future rewrite of +these files, not just this one. It was built for an additive change and cannot express a +subtractive one. + +Re-baselining to the current file does not rescue it — the new baseline would contain +`## Baked Decisions`, and 746's pollution check would (correctly) fail. **Silencing that check to +make the re-baseline pass would gut the anti-vacuity property**, which is the more valuable half +of 746's protection. I am not proposing that. + +### Does the protected behaviour survive? + +**Partly, and the split matters:** + +| 746 protected | Survives? | Evidence | +|---|---|---| +| Baked Decisions **content present** in all three prompts | **YES — unchanged** | `## Baked Decisions` heading, the `do not autonomously` carveout, the contradiction-handling wording, and mirror-parity across `codev/` ↔ skeleton all still assert and **pass** | +| **No prior content deleted** | **NO — deliberately** | This is the project | + +So 746's *substance* is intact and still guarded. What is being retired is the **no-deletion** +property, which Spec 1280 exists to violate. + +### Correction to this document + +An earlier revision of this entry described the replacement guard as *"implemented, inert until +approved"*. **It was not implemented** — it was designed and described. The architect read and +approved this file partly on its contents, so the overstatement is corrected here rather than +quietly fixed. The replacement ships as its own commit, separate from the retirement, per the +approval's third condition. + +### Replacement guard (ships separately) + +`spec-1280-prompt-deletion-guard.test.ts` — the same machinery, re-anchored: + +- **Post-1280 baselines**, captured from the rewritten prompts. +- Pure-addition against those, so **future** silent deletion is still caught — the guard keeps + working going forward, it just stops asserting a state this project intentionally left. +- Its own anti-vacuity check, inverted for the new era: the post-1280 baseline **must** contain + `## Baked Decisions`. If a later edit strips 746's content and someone re-baselines to hide + it, that check fails. + +Net effect: 746 keeps its content guarantee and gains a deletion guard that survives rewrites, +instead of one that forbids them. + +### Behaviour-re-asserted mapping (approval condition 2) + +One row per retired assertion. "Still asserted by" names the *surviving* test that carries the +behaviour, so a future reader can check the claim rather than trust it. + +| Retired assertion | Behaviour it carried | Survives? | Still asserted by | +|---|---|---|---| +| `codev SPIR builder-prompt: post-edit file is a pure-addition diff of its baseline` | (a) 746's paragraph present; (b) no pre-746 line ever deleted | (a) **yes** / (b) **no, by design** | (a) `contains the "## Baked Decisions" heading`, `uses the carveout phrasing "do not autonomously"`, contradiction-handling and mirror-parity assertions — all passing unmodified | +| `codev ASPIR builder-prompt: post-edit file is a pure-addition diff of its baseline` | same | same | same, plus `bugfix-619-aspir-prompt.test.ts` (`Follow the ASPIR protocol`, no `protocol.md` reference) | +| `codev AIR builder-prompt: post-edit file is a pure-addition diff of its baseline` | same | same | same | + +**Anti-vacuity preserved**: the pollution check (`baseline does NOT contain '## Baked +Decisions'`) is **untouched and still passing**. It is the half of 746's protection that stops a +future builder silently re-baselining away the guarantee, and retiring the pure-addition half +does not weaken it. + +**Not retired, explicitly**: the identical `expectPureAdditionDiff` guards over `PHASE_2_FILES` +(drafting prompts) and `PHASE_3_FILES` (reviewer prompts) remain in force. This retirement is +scoped to the three builder-prompt instances only. + +### Architect decision + +- [x] **APPROVED — 2026-08-01.** Grounds, recorded as given: + 1. The invariant is **construction-time scaffolding that hardened into a change-freeze** — it + proved 746's paragraph was added non-destructively *at the moment of addition*, but as a + standing assertion it forbids any future deletion-rewrite of those files forever, which is + **not a behaviour 746 ever claimed to protect**. + 2. 746's actual protection — the Baked Decisions sections present and substantive, plus the + anti-vacuity pollution check — **survives in the assertions that still pass unmodified**. + 3. The analysis that re-baselining guts the anti-vacuity half is **verified sound**, so + retirement-with-trace is strictly more honest than the silent re-baseline a less careful + builder would have shipped. + +--- + +## R2 — `expectPureAdditionDiff` on the two SPIR/ASPIR `specify.md` drafting prompts + +**Status: APPROVED by Waleed (human decision, relayed by the architect), 2026-08-04. Applied.** + +This is the retirement **R1 explicitly foresaw**: R1 closed by scoping itself to the three +builder-prompts and stating *"the identical `expectPureAdditionDiff` guards over `PHASE_2_FILES` +(drafting prompts) and `PHASE_3_FILES` (reviewer prompts) remain in force."* Phase 5 is the phase +that rewrites `specify.md`, so its `PHASE_2_FILES` pure-addition guard now hits the same wall. + +| | | +|---|---| +| **Assertion** | `baked-decisions.test.ts` → Phase 2 *"pure-addition diff: baseline lines preserved in order"* | +| **Files (2 of 3)** | `codev/protocols/{spir,aspir}/prompts/specify.md` | +| **NOT in scope** | `codev/protocols/air/prompts/implement.md` — Phase 5 does not touch it; its baseline stays in force | +| **Originating spec** | **Spec 746 — Baked Architectural Decisions** | +| **Baselines** | `fixtures/baselines/{spir,aspir}-specify.md.baseline` (**pre-746**) | + +### Why it cannot survive Spec 1280 (same shape as R1) + +The baseline is the **pre-746** `specify.md`, carrying the whole verbose "Process" walkthrough +(the numbered steps, "Check for Existing Spec (ALWAYS DO THIS FIRST)", etc.). Phase 5's P1/P2 +rewrite **deletes that prose by design**, converting step-by-step procedure into a +"What must be true when you finish" contract. So "no pre-746 line was ever removed" is now false +by design, and permanently — it forbids any future rewrite of `specify.md`, exactly the +change-freeze failure mode R1 named. Re-baselining is rejected for R1's reason: the new baseline +would contain `Baked Decisions`, and 746's pollution check (`spir-specify.md.baseline` must NOT +contain `Baked Decisions`) would correctly fail; silencing it would gut the anti-vacuity half. + +### Does the protected behaviour survive? + +**Yes — the Baked Decisions substance is intact and still guarded.** The wording was restored to +the canonical carveout form in this same phase, so every *behaviour* assertion passes unmodified: + +| 746 protected | Survives? | Evidence (all passing) | +|---|---|---| +| Baked Decisions **content present** in specify.md | **YES** | grep: `Baked Decisions`, `do not autonomously`, `contradict`+`pause`+`flag`, `afx send` — all pass on both trees | +| clause **byte-identical across codev/ ↔ skeleton** | **YES** | Phase 2 mirror-parity assertions pass | +| baseline **anti-vacuity** (pollution check) | **YES — untouched** | `spir-specify.md.baseline does NOT contain "Baked Decisions"` still passes | +| **no prior content deleted** | **NO — by design** | this is the phase | + +### Replacement guard (ships on approval, separate commit — mirrors R1) + +Extend the existing `spec-1280-prompt-deletion-guard.test.ts` (R1's replacement) to cover the two +post-1280 `specify.md` files: + +- **Post-1280 baselines** captured from the rewritten `specify.md` prompts. +- Pure-addition against those, so **future** silent deletion of the Baked Decisions content is + still caught going forward. +- Inverted anti-vacuity: the post-1280 baseline **must** contain `Baked Decisions`; a later edit + that strips 746's content and re-baselines to hide it fails the guard. + +Net effect identical to R1: 746 keeps its content guarantee and gains a deletion guard that +survives rewrites, instead of one that forbids them. + +### Behaviour-re-asserted mapping + +| Retired assertion | Behaviour it carried | Survives? | Still asserted by | +|---|---|---|---| +| `codev SPIR specify.md: post-edit file is a pure-addition diff of its baseline` | (a) 746's clause present; (b) no pre-746 line deleted | (a) **yes** / (b) **no, by design** | (a) Phase 2 grep (`Baked Decisions`, `do not autonomously`, `contradict`+`pause`+`flag`, `afx send`) + mirror-parity — all passing | +| `codev ASPIR specify.md: post-edit file is a pure-addition diff of its baseline` | same | same | same | + +**Anti-vacuity preserved**: the pollution check is untouched and passing. **Still in force, +explicitly**: the `PHASE_2_FILES` pure-addition guard over `air/implement.md`, and all +`PHASE_3_FILES` reviewer-prompt guards. This proposal is scoped to the two specify.md instances +Phase 5 actually rewrote. + +### Architect decision + +- [x] **APPROVED — Waleed, 2026-08-04** (human call, relayed by the architect; retirement decisions + on 1280 get a human decision even when they mirror an approved precedent). Grounds: R2 is the + retirement R1 explicitly foresaw and scoped out ("`PHASE_2_FILES` guards remain in force"), and + its analysis mirrors R1's approved grounds — construction-time additive scaffolding that hardened + into a change-freeze, with 746's substance surviving in the grep / mirror-parity / pollution + assertions that still pass, and the anti-vacuity half preserved. Applied in two commits (retirement, + then replacement guard), mirroring R1's split. + +--- + +## R3 — `expectPureAdditionDiff` on `air/implement.md` (the third and last PHASE_2 file) + +**Status: APPROVED by Waleed (human decision, relayed by the architect), 2026-08-06. Applied. The +same decision PRE-APPROVED THE CLASS for the remaining PHASE_3 retirements (phases 7–9) — see the +"Class pre-approval" box below.** + +The third instance of the pattern R1 foresaw and scoped out. R1 retired the PHASE_1 builder-prompts +and left PHASE_2 in force; R2 retired two of PHASE_2's three files (spir/aspir specify.md); R3 is the +remaining one. **After R3 there are no PHASE_2 pure-addition guards left** — PHASE_3 (reviewer / +consult-type prompts) is Phases 7–9 and stays in force until those phases touch it. + +| | | +|---|---| +| **Assertion** | `baked-decisions.test.ts` → Phase 2 *"pure-addition diff: baseline lines preserved in order"* | +| **File (the last of 3)** | `codev/protocols/air/prompts/implement.md` | +| **Originating spec** | **Spec 746 — Baked Architectural Decisions** | +| **Baseline** | `fixtures/baselines/air-implement.md.baseline` (**pre-746**) | + +### Why it cannot survive Spec 1280 (same shape as R1/R2) + +The baseline is the **pre-746** `air/implement.md` with the full numbered "Process" walkthrough. +Phase 6 rewrites it to a "What must be true when you finish" contract (P1), deleting that prose, so +"no pre-746 line was ever removed" is false by design. Even the P4 git-add cleanup alone would trip +it — any deletion does. Re-baselining is rejected for R1/R2's reason: the new baseline would contain +`Baked Decisions`, which 746's pollution check (`air-implement.md.baseline` must NOT contain it) +correctly forbids; silencing that would gut the anti-vacuity half. + +### Does the protected behaviour survive? + +**Yes.** The Baked Decisions clause is kept in the rewrite with the canonical literals, so every +behaviour assertion passes unmodified: + +| 746 protected | Survives? | Evidence (passing) | +|---|---|---| +| Baked Decisions **content present** in air/implement.md | **YES** | Phase 2 grep: `Baked Decisions`, `do not autonomously`, `contradict`+`pause`+`flag`, `afx send` | +| clause **byte-identical across codev/ ↔ skeleton** | **YES** | Phase 2 mirror-parity for air implement.md | +| baseline **anti-vacuity** (pollution check) | **YES — untouched** | `air-implement`-relevant pollution guard still passes | +| **no prior content deleted** | **NO — by design** | this is the phase | + +### Replacement guard (ships on approval, separate commit — mirrors R1/R2) + +Extend `spec-1280-prompt-deletion-guard.test.ts` with a post-1280 baseline for `air/implement.md`, +pure-addition against it, inverted anti-vacuity (the baseline **must** contain `Baked Decisions`). + +### Behaviour-re-asserted mapping + +| Retired assertion | Behaviour it carried | Survives? | Still asserted by | +|---|---|---|---| +| `codev AIR implement.md: post-edit file is a pure-addition diff of its baseline` | (a) 746's clause present; (b) no pre-746 line deleted | (a) **yes** / (b) **no, by design** | (a) Phase 2 grep (`Baked Decisions`, `do not autonomously`, `contradict`+`pause`+`flag`, `afx send`) + mirror-parity — passing | + +**Still in force, explicitly**: all `PHASE_3_FILES` reviewer/consult-type pure-addition guards +(untouched until Phases 7–9 rewrite them). + +### A process question for the human, raised not assumed + +R3 is the third identical retirement (R1→R2→R3), and Phases 7–9 will produce the same for each +PHASE_3 consult-type file rewritten. Rather than one approval per file, you may prefer to **pre-approve +the class** — "any Spec 1280 rewrite that deletes pre-746 prose from a Spec 746 baked-decisions file +is an approved retirement, provided (a) the behaviour grep + mirror-parity still pass and (b) a +post-1280 replacement guard with inverted anti-vacuity ships in the same PR." That would let the +remaining phases proceed without a per-file gate while keeping the same evidentiary bar. Entirely your +call — I am not assuming it; R3 is written up in full either way. + +### Architect / human decision + +- [x] **APPROVED — Waleed, 2026-08-06** (human call, relayed by the architect). Grounds mirror R1/R2: + the retirement R1 foresaw and scoped out, behaviour surviving in the grep / mirror-parity / pollution + assertions that still pass, anti-vacuity preserved. Applied in two commits (retirement, then + replacement guard), mirroring R1/R2's split. + +--- + +## Class pre-approval — foreseen PHASE_3 retirements (phases 7–9) + +**Granted by Waleed 2026-08-06, alongside R3.** R1→R2→R3 retired every `PHASE_2` baked-decisions +pure-addition guard. The `PHASE_3` reviewer / consult-type files carry the identical guard and will +trip it identically when phases 7–9 rewrite them. Rather than a per-file blocking gate, this class is +**pre-approved** — subject to three invariants that are now **conditions, not conventions**: + +1. **Behaviour survives with canonical wording.** The Baked Decisions grep for that file + (`Baked Decisions`, `do not autonomously`, contradiction handling, `afx send`, plus the + consult-type `COMMENT`/`REQUEST_CHANGES` distinction) stays green after the rewrite. +2. **Replacement guard ships in the mirrored separate commit.** A post-1280 baseline + inverted + anti-vacuity added to `spec-1280-prompt-deletion-guard.test.ts`, in its own commit, exactly as + R1/R2/R3 did. +3. **Full audit trail.** Each class-approved retirement still gets its own numbered writeup in this + register **and** appears in its phase manifest. The audit trail stays complete; only the per-item + blocking wait is removed. + +**Enforcement**: the architect still verifies each at M11. **A violation of any invariant voids the +class approval for that item** — it reverts to needing an explicit per-item decision. This box is the +authority the phases 7–9 retirements cite; each still records its own numbered entry here. + +--- + +## R4 — `expectPureAdditionDiff` on spir `spec-review.md` + `plan-review.md` (first PHASE_3 files) + +**Status: CLASS PRE-APPROVED (see box above), Phase 7, 2026-08-06. Applied.** The first two +`PHASE_3` files. The other four (aspir spec/plan-review, air impl/pr-review) stay in force until +Phases 8–9 rewrite them. + +| | | +|---|---| +| **Assertion** | `baked-decisions.test.ts` → Phase 3 *"pure-addition diff: baseline lines preserved in order"* | +| **Files (2 of 6)** | `codev/protocols/spir/consult-types/{spec-review,plan-review}.md` | +| **Originating spec** | **Spec 746 — Baked Architectural Decisions** | +| **Baselines** | `fixtures/baselines/spir-{spec,plan}-review.md.baseline` (**pre-746**) | + +### Class-invariant compliance (the three conditions) + +1. **Behaviour grep green.** Both files keep a `## Baked Decisions` section with `do not autonomously`, + the `COMMENT` vs `REQUEST_CHANGES` distinction, and contradiction→`clarify` handling — the Phase 3 + grep + mirror-parity assertions pass unmodified. +2. **Replacement guard in a mirrored commit.** Post-1280 baselines for both files + inverted + anti-vacuity added to `spec-1280-prompt-deletion-guard.test.ts`, in its own commit. +3. **Audit trail.** This entry + the phase-7 manifest row. + +### Why it cannot survive Spec 1280 (same shape as R1–R3) + +Phase 7's P1/P2 rewrite deletes the pre-746 rubric prose, so "no pre-746 line was ever removed" is +false by design. Re-baselining is rejected for the same reason: the new baseline would contain +`Baked Decisions`, which 746's pollution check forbids. + +### Behaviour-re-asserted mapping + +| Retired assertion | Behaviour | Survives? | Still asserted by | +|---|---|---|---| +| `codev SPIR spec-review: post-edit file is a pure-addition diff of its baseline` | (a) 746 clause present; (b) no pre-746 line deleted | (a) **yes** / (b) **no, by design** | (a) Phase 3 grep (`Baked Decisions`, `do not autonomously`, `COMMENT`+`REQUEST_CHANGES`, `contradict`+`clarify`) + mirror-parity — passing | +| `codev SPIR plan-review: post-edit file is a pure-addition diff of its baseline` | same | same | same | + +**Still in force**: aspir spec/plan-review + air impl/pr-review PHASE_3 pure-addition guards. + +--- + +## R5 — the repo-wide manifest-COMPLETENESS scan (T16) + +**Status: APPROVED by Waleed (human ruling, relayed by the architect), 2026-08-06. Applied — its own +commit.** Distinct in kind from R1–R4: this retires **one of Spec 1280's own guards**, not a Spec 746 +assertion. + +| | | +|---|---| +| **Assertion** | `spec-1280-phase-manifest.test.ts` → *"every prompt-bearing file THIS PROJECT changed appears in some manifest"* | +| **Originating spec** | **Spec 1280** (this project, M11) | + +### What it protected + +That no prompt-bearing file 1280 changed could be rewritten without appearing in a per-phase manifest, +so the architect's M11 inspection could never miss a changed file. It scanned `origin/main..HEAD` + +`git status` for prompt-bearing paths and diffed them against the manifest rows. + +### Why it is retired + +It lived in the **shared** test suite, so it ran on every PR in the repo, not just 1280's. Even after +being scoped by `[Spec 1280]` commit provenance, its uncommitted-file check still evaluated on other +branches and **caught Mohid's #1330**, which had to strip its `CLAUDE.md`/`AGENTS.md` edits to pass CI. +A guard that taxes concurrent work it does not govern costs more than the mechanical enforcement is +worth. (This is the *second* cross-project misfire of this same guard — Spec 1307 was the first — which +is the signal that the mechanism, not just its predicate, was wrong.) + +### What survives + +- **The manifests themselves** — every phase still ships a complete `phase-N-*.md` with all four fields. +- **The M11 inspection contract** — the architect still inspects the old-vs-new diff of every changed + file against its manifest row. The completeness guarantee is now the builder's diligence + human + inspection, exactly as before the CI check existed. +- **The manifest FORMAT checks** — the four-required-fields and ≤12-per-batch tests remain in + `spec-1280-phase-manifest.test.ts`. They read only this project's manifest directory, so they validate + 1280's manifests without diffing the repo or taxing any other PR. + +Only the CI tripwire is gone. + +--- + +## R6 — `expectPureAdditionDiff` on the last four PHASE_3 files (aspir spec/plan-review, air impl/pr-review) + +**Status: CLASS PRE-APPROVED (see the "Class pre-approval" box), Phase 8, 2026-08-06. Applied.** The +final four `PHASE_3` baked-decisions files. **After R6, every PHASE_2 and PHASE_3 pure-addition guard +in Spec 746 is retired** (PHASE_1 under R1, PHASE_2 under R2+R3, PHASE_3 under R4+R6). + +| | | +|---|---| +| **Assertion** | `baked-decisions.test.ts` → Phase 3 *"pure-addition diff: baseline lines preserved in order"* | +| **Files (4)** | `codev/protocols/aspir/consult-types/{spec-review,plan-review}.md`, `codev/protocols/air/consult-types/{impl-review,pr-review}.md` | +| **Originating spec** | **Spec 746 — Baked Architectural Decisions** | +| **Baselines** | `fixtures/baselines/{aspir-spec-review,aspir-plan-review,air-impl-review,air-pr-review}.md.baseline` (**pre-746**) | + +### Class-invariant compliance + +1. **Behaviour grep green.** All four keep a `## Baked Decisions` section with `do not autonomously`, + the `COMMENT`/`REQUEST_CHANGES` distinction, and contradiction→`clarify` handling — Phase 3 grep + + mirror-parity pass unmodified. +2. **Replacement guard in a mirrored commit.** Post-1280 baselines for all four + inverted anti-vacuity + in `spec-1280-prompt-deletion-guard.test.ts`. +3. **Audit trail.** This entry + the phase-8 manifest row. + +### Why it cannot survive Spec 1280 + +Phase 8's P1/P2 rewrite deletes the pre-746 rubric prose (aspir mirrors the spir rewrite; air is +rewritten in place), so "no pre-746 line was ever removed" is false by design. Re-baselining is +rejected for R1–R4's reason (the new baseline would contain `Baked Decisions`, which the pollution +check forbids). + +### Behaviour-re-asserted mapping + +| Retired assertion | Survives? | Still asserted by | +|---|---|---| +| `codev ASPIR spec-review: … pure-addition diff` | (a) yes / (b) no, by design | Phase 3 grep + mirror-parity for aspir spec-review — passing | +| `codev ASPIR plan-review: … pure-addition diff` | same | aspir plan-review grep + mirror-parity | +| `codev AIR impl-review: … pure-addition diff` | same | air impl-review grep + mirror-parity | +| `codev AIR pr-review: … pure-addition diff` | same | air pr-review grep + mirror-parity | + +**Loop kept, not deleted**: with all six PHASE_3 files retired, the pure-addition `describe` keeps a +documenting test so it re-activates for any future PHASE_3 file and does not error as an empty suite. diff --git a/codev/resources/lessons-learned.md b/codev/resources/lessons-learned.md index f5bbf344a..54668871b 100644 --- a/codev/resources/lessons-learned.md +++ b/codev/resources/lessons-learned.md @@ -492,6 +492,8 @@ Generalizable wisdom extracted from review documents, ordered by impact. Updated - [From 863] React's `dangerouslySetInnerHTML` re-commits the element's innerHTML on *every* re-render, silently wiping any DOM children you injected imperatively into that same element. The artifact-canvas renders parsed markdown into the body via `dangerouslySetInnerHTML`, then injected inline comment cards as DOM children of the parsed blocks; the cards flashed on first paint and vanished on the next render (a refreshKey bump), while the React-owned minimap survived untouched — that asymmetry located the bug in the React-owned subtree, not the injection logic (a faithful jsdom repro of the injection round-trip kept the card every time, proving the defect was browser-render-only). Fix: stop letting React own that subtree — set `ref.innerHTML = html` imperatively inside a `[html]`-keyed `useEffect`, then inject the non-React DOM after, so React never re-commits those children (the standard escape hatch for mixing hand-built DOM into a React tree). Rule of thumb: never imperatively mutate the children of a node React controls via `dangerouslySetInnerHTML` — render everything through React, or own the whole subtree imperatively, never both. +- [From #1280] "Trust the authoritative source, not the convenient signal" — the always-on hot lesson ("summaries are evidence, not ground truth") earned a concrete catalog in this one project. The prompt-trimming rewrite verified thousands of pinned test strings; roughly a dozen times a *convenient* signal disagreed with the *authoritative* one, and the convenient one was wrong: a green test tick that had run against `origin/main…HEAD` before the work was committed (so it passed vacuously); a `pipefail`+`grep -q` pipe that reported success on empty input; a `git checkout` that "succeeded" but silently didn't switch branches (revealed only because the run then reported 16 commits on a branch that should have had zero); a case-sensitive `grep -F` that "found nothing" while the case-insensitive test it was mimicking passed; a manifest row whose annotation-in-the-path-cell made the parser skip it. Each time the fix was the same: read the raw thing the test reads, in the form it reads it, before believing the summary. Two mechanical corollaries that recur: (a) **commit → build → run → read the run → claim**, quoting the SHA the run executed against — never state anything about a run still in flight or a pre-commit run; (b) after any convergence, **mutation-test the guard both ways** (make it fail as expected, then restore) — a green tick is not evidence a guard bites, and a scoping fix that silently disables a guard is the vacuous pass all over again. + --- *Last updated: 2026-04-17 (Maintenance run 0007 — v3.0.0 pre-release)* diff --git a/codev/resources/scar-rules.yaml b/codev/resources/scar-rules.yaml new file mode 100644 index 000000000..25cda2adf --- /dev/null +++ b/codev/resources/scar-rules.yaml @@ -0,0 +1,83 @@ +# Scar-rule registry (Spec 1280, rebuilt in Phase 9 from the Spec 1252 registry). +# +# A scar rule is a prohibition written after a specific incident where an agent +# destroyed work or bypassed a human decision. The eight rules below are kept +# VERBATIM (Spec 1280 Baked Decision 2 — the one deliberate exception to P7: +# judgment replaces defensive padding, but scar rules guard irreversible acts +# where the cost of being wrong once is unbounded). +# +# `must_appear_on` was RE-DERIVED against the post-1280 surface: the P1/P4 +# rewrites removed the git-add prohibition from most prompts (roles/builder.md +# now owns it), and the dead codev-skeleton/porch/prompts/ tree was deleted, so +# the pre-rewrite lists are stale. Each list below is exactly where its canonical +# appears today. All eight survive on the primary always-on surface (CLAUDE.md + +# AGENTS.md) — the carriage guarantee that matters. +# +# ENFORCEMENT (spec-1280-scar-rules.test.ts / T4): +# - the count is pinned at 8 and the ids are pinned; +# - each rule's `canonical` must appear byte-identically in every file listed +# under `must_appear_on` (rewording any copy fails the build); +# - changing a canonical requires editing this registry AND every listed +# surface in the same commit — a loud, reviewable act. + +scar_rules: + - id: git-add-explicit + canonical: "Never `git add -A` / `--all` / `.` — stage each file explicitly by path." + must_appear_on: + - AGENTS.md + - CLAUDE.md + - codev-skeleton/protocols/maintain/protocol.md + - codev-skeleton/roles/builder.md + - codev/protocols/maintain/protocol.md + - codev/roles/builder.md + + - id: never-destroy-worktrees + canonical: "Never destroy builder worktrees (`git worktree remove`, `git branch -D` on builder branches, `afx cleanup` + respawn). Use `afx spawn --resume`; if it fails, ask the human — what is expendable is never your call." + must_appear_on: + - AGENTS.md + - CLAUDE.md + + - id: no-destructive-git + canonical: "Never run `git reset --hard`, `git checkout -- .`, `git clean -fd`, or `git stash` without explicit human permission — they destroy uncommitted work." + must_appear_on: + - AGENTS.md + - CLAUDE.md + + - id: human-gates + canonical: "Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization." + must_appear_on: + - AGENTS.md + - CLAUDE.md + - codev-skeleton/roles/builder.md + - codev/roles/builder.md + + - id: no-hand-edit-status + canonical: "Never hand-edit `status.yaml` — only porch commands modify project state." + must_appear_on: + - AGENTS.md + - CLAUDE.md + - codev-skeleton/protocols/spir/builder-prompt.md + - codev-skeleton/roles/builder.md + - codev/protocols/spir/builder-prompt.md + - codev/roles/builder.md + + - id: afx-from-root + canonical: "Run `afx` commands only from the main workspace root, never from inside a builder worktree — spawning from a worktree nests builders and breaks the workspace." + must_appear_on: + - AGENTS.md + - CLAUDE.md + - codev-skeleton/roles/architect.md + - codev/roles/architect.md + + - id: shellper-verified-orphan + canonical: "Never kill a shellper process without verifying it is an orphan (match each PID to its workspace via Tower) — an 'extra' shellper may be a live architect session." + must_appear_on: + - AGENTS.md + - CLAUDE.md + + - id: tower-restart-permission + canonical: "Never restart or stop Tower without explicit human permission — it kills every running builder session." + must_appear_on: + - AGENTS.md + - CLAUDE.md + diff --git a/codev/reviews/1280-prompt-surface-judgment-not-ru.md b/codev/reviews/1280-prompt-surface-judgment-not-ru.md new file mode 100644 index 000000000..6d493ec45 --- /dev/null +++ b/codev/reviews/1280-prompt-surface-judgment-not-ru.md @@ -0,0 +1,132 @@ +# Review: Spec 1280 — prompt-surface, judgment not rules + +Closes #1280 + +## Summary + +Rewrote Codev's always-on prompt surface from *rules* to *judgment*, following the seven principles +of the "judgment not rules" blog post. Ten implement phases across both trees (`codev/` + +`codev-skeleton/`): CLAUDE/AGENTS + skills, the three roles, ten `protocol.md`, nine +`builder-prompt.md`, the SPIR/ASPIR/PIR phase prompts, the light-protocol phase prompts + SPIR +templates, all consult-types, the scar-rule registry, and the deletion of the dead +`porch/prompts/` tree. The always-on builder surface (spir, I=10) fell **34,231 → 18,233 words +(−47%)** and the total authored surface **153,205 → 106,032 (−31%)**, with **every capability +preserved** (M5) and **every principle conformance inspected** by the architect (M11). + +**Acceptance basis (charter amendment, 2026-08-01): principle conformance is pass/fail; size is +reporting-only.** No word target was chased. A file conformant at more words passes. + +## Spec Compliance + +- **P1 (rules → contract)** — procedure narration became "what must be true when you finish" + contracts across every prompt. Every remaining rule is one a frontier model would get wrong + without it (scope restrictions, single-pass consultation semantics, gate-not-prose merge auth). +- **P2 (examples → interfaces)** — annotated example templates became heading interfaces + (spec.md 632→246, plan.md 649→201, review.md 641→293); "include examples" lines deleted. +- **P3 / P4 (progressive disclosure / stop repeating)** — CLI how-tos and worktree recipes relocated + to skills; repeated prohibitions (git-add, flaky tests, consult, status.yaml) dropped from prompts + where `roles/builder.md` now owns them. **Proven relocation, not deletion (M0c):** the skills + component *grew* 42→46 files (+4,516w) while everything else shrank. +- **P5 (auto-memory)** — declared N/A project-wide (no auto-memory surface in Codev's prompts). +- **P6 (rich references)** — prose restating machine-readable truth became references: the plan + template points at its phases-JSON, `spec-review` points at the delivered spec template instead of + hardcoding its heading list. +- **P7 (unhobbling) + the scar exception** — defensive padding for weaker models deleted, **except + the eight ratified scar rules**, kept verbatim and now enforced by the rebuilt registry + T4. +- **M5 (no capability lost)** — `extract-capability-inventory.sh` vs the frozen Phase-0 inventory: + no gate/check/signal present in the Phase-0 served prompts is absent post-rewrite. See + `codev/resources/1280-measurement-report.md`. +- **M6 (dead-tree removal)** — `codev-skeleton/porch/prompts/` (10 files) deleted after an + untruncated repo-wide search confirmed no runtime consumer. +- **M10 (retirements)** — six retirements, each with an originating spec, a behaviour-survival + analysis, a replacement guard, and architect/human approval, in `codev/resources/1280-retirements.md`. +- **M11 (per-file manifest inspection)** — a manifest per implement phase; the architect inspected + the old-vs-new diff of every changed file. + +## Consultation Feedback + +This project ran under **architect M11 inspection + a human-gated retirement model**, not porch's +per-phase 3-way consultation. The architect inspected each phase's manifest and independently +re-ran the guard suite; Waleed made every retirement decision. The equivalent adversarial pressure +came from the test suite: ~4,180 assertions, including per-file guards (bugfix-685 close-keywords, +bugfix-742 protocol divergence, #335 CMAP ordering, template-delivery, review-prompt-routing, +baked-decisions, and the T4 scar registry), each of which caught real regressions during the +rewrite (documented in the phase manifests and the thread). + +### Integration review (PR #1362, 2-way CMAP — codex REQUEST_CHANGES / claude COMMENT) + +The architect ran a 2-way CMAP at the PR and verified each finding against the worktree. Four +pre-merge findings, all **Addressed** (commit `f81d4720`): + +- **Addressed** — merge-ownership contradiction: `spir/aspir review.md` said "do not merge your own + PR (the architect integrates)", contradicting `roles/architect.md`. Reconciled to "merge your own + PR only after the human approves the `pr` gate". +- **Addressed** — gate-ownership scoping: `builder.md`'s "you run `porch approve`" now defers to the + protocol's prompts on who types it (PIR routes it to the human reviewer). +- **Addressed** — RESEARCH json/md disagreement: `protocol.json` runs `models: ["codex"]` for + investigation while the prose promised three; the prose now defers to the embedded state machine as + authoritative and states the current reduced reality (agy/hermes lanes degraded). +- **Addressed** — `CLAUDE.md`/`AGENTS.md` named `team` + `forge` skills that don't ship (#1318 drift); + dropped, so the new prose stops making an active false claim to adopters. + +The T9/T10 deferrals were **ruled acceptable** as documented (they run at integration / local-install, +alongside 1307's verify probes). The codex "replacement-guard recreates a freeze" critique was +accepted-by-design: the freeze now ships *with* its documented retirement path. Non-blocking +follow-ups filed: `release/protocol.md` staleness and a maintain/templates two-tree divergence. + +## Retirements (M10) + +Six, all in `codev/resources/1280-retirements.md`: +- **R1** — pure-addition guard on the three builder-prompts (Spec 746). Approved 2026-08-01. +- **R2** — same guard on the two SPIR/ASPIR `specify.md`. Approved by Waleed 2026-08-04. +- **R3** — same on `air/implement.md` (last PHASE_2 file). Approved by Waleed; the approval also + **pre-approved the class** for the remaining PHASE_3 retirements on three binding invariants + (behaviour grep green, replacement guard shipped, full audit trail). +- **R4** — spir `spec-review`/`plan-review` (first PHASE_3 files). Class-approved. +- **R6** — the last four PHASE_3 files (aspir spec/plan-review, air impl/pr-review). Class-approved. +- **R5** — the repo-wide manifest-completeness CI scan (T16), removed by Waleed's ruling because it + taxed concurrent PRs (it forced #1330 to strip edits). The manifests and the M11 inspection + contract survive; only the CI tripwire is gone. + +Each baked-decisions retirement shipped a **replacement guard** (`spec-1280-prompt-deletion-guard.test.ts`, +post-1280 baselines + inverted anti-vacuity), mutation-verified in both directions. + +## Measurement + +Full before/after, per-audience, and the M0c relocation proof in +`codev/resources/1280-measurement-report.md`. Headline: builder always-on −47%, architect −66%, +total authored −31%, dead tree −4,009. + +## Architecture Updates + +No architecture updates needed — Spec 1280 rewrote prompt *content* under a fixed structure; it did +not change any module boundary, the four-tier resolver, porch's planner/executor split, or the +state model. The system-shape facts in `arch-critical.md` are unchanged and still accurate. + +## Lessons Learned Updates + +Routed **cold** (`codev/resources/lessons-learned.md`): "trust the authoritative source, not the +convenient signal" — a concrete catalog of ~a dozen instances in this project where a convenient +signal (a vacuous green tick, a `pipefail`+`grep -q` pipe, a silent `git checkout`, a case-sensitive +grep, an annotation-in-the-path-cell) disagreed with the authoritative one and was wrong, plus the +two mechanical corollaries (commit→run→read→claim quoting the SHA; mutation-test guards both ways). +The hot tier already carries the principle ("summaries are evidence, not ground truth"), so the +project-specific instances went to cold, respecting the hot-tier cap. + +## Deferred to integration (cannot run from a builder worktree) + +- **T9 — live spawn probe.** Spawning a builder must happen from the **main workspace root**; doing + it from inside this worktree would nest builders (a scar rule). Run at integration: + `afx spawn ` on the rewritten surface, confirm the spawn prompt carries the full artifact + contract and `porch next` returns a well-formed task. +- **T10 — full rollback rehearsal.** Group purity is verified structurally (each phase's rewrite + commit is `.md`-only, retirements are register + test, replacement guards are baseline + test — no + commit mixes groups). Actually reverting each rollback group G1–G7 and re-running the suite green + needs multi-commit reverts across phases and destructive git in the active worktree; run it at + integration on a throwaway checkout. + +## Flaky Tests + +No flaky tests encountered. The `packages/codev` suite is deterministic and green at HEAD +(4,184 passed / 48 skipped). The broader monorepo has pre-existing unrelated failures (e.g. +`artifact-canvas` DOMPurify) untouched by this markdown-and-tests-only work. diff --git a/codev/roles/architect.md b/codev/roles/architect.md index 56cac231d..41dc0d17f 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -1,348 +1,98 @@ # Role: Architect -The Architect is the **project manager and gatekeeper** who decides what to build, spawns builders, approves gates, and ensures integration quality. +You decide what gets built, spawn builders, approve gates, and own integration quality. You do +not implement — builders do that in isolated worktrees. -> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands. +## What you own -## Key Concept: Spawning Builders +1. **What to build** — features, priorities, GitHub Issues as the project registry. +2. **Spawning** — one builder per project, in a worktree branched from HEAD. +3. **Gates** — in strict mode, reviewing the spec and plan before the builder proceeds. +4. **Integration review** — whether a PR fits the architecture, at a depth matched to its risk. +5. **Closing the loop** — closing the issue when the PR merges, and cleaning up the worktree. -Builders work autonomously in isolated git worktrees. The Architect: -1. **Decides** what to build -2. **Spawns** builders via `afx spawn` -3. **Approves** gates (spec-approval, plan-approval) when in strict mode -4. **Reviews** PRs for integration concerns +## Spawning -### Two Builder Modes +| Mode | Flag | What it means | +|---|---|---| +| **Strict** (default) | none | Porch orchestrates: automated gates, 3-way consultation, enforced phase transitions. Most likely to finish without intervention. | +| **Soft** | `--soft` | The builder follows the protocol itself; you verify compliance. Use when you want closer oversight. | -| Mode | Command | Use When | -|------|---------|----------| -| **Strict** (default) | `afx spawn XXXX --protocol spir` | Porch orchestrates - runs autonomously to completion | -| **Soft** | `afx spawn XXXX --protocol spir --soft` | AI follows protocol - you verify compliance | +`--protocol` is **required** for numbered spawns (`--task`, `--shell` and `--worktree` spawns +are the exceptions). -**Strict mode** (default): Porch orchestrates the builder with automated gates, 3-way consultations, and enforced phase transitions. More likely to complete autonomously without intervention. +**Builders branch from HEAD, so commit first.** Uncommitted specs, plans and framework updates +are invisible to the builder. `afx spawn` refuses a dirty worktree; `--force` overrides it and +gives the builder a tree missing your uncommitted work. -**Soft mode**: Builder reads and follows the protocol document, but you monitor progress and verify the AI is adhering to the protocol correctly. Use when you want more hands-on oversight. +Commands and flags live in the `afx` skill — check it rather than guessing. -### Pre-Spawn Checklist +## Gates -**Before every `afx spawn`, complete these steps:** +The builder stops and waits. Read the artifact in its worktree with an absolute path, decide — +then **relay the decision; the builder runs the command.** -1. **`git status`** — Ensure worktree is clean (no uncommitted changes) -2. **Commit if needed** — Builders branch from HEAD; uncommitted specs/plans are invisible -3. **`afx spawn N --protocol `** — `--protocol` is **REQUIRED** (spir, aspir, air, bugfix, etc.) - -The spawn command will refuse if the worktree is dirty (override with `--force`, but your builder won't see uncommitted files). - -## Key Tools - -### Agent Farm CLI (`afx`) - -```bash -afx spawn 1 --protocol spir # Strict mode (default) - porch-driven -afx spawn 1 --protocol spir -t "feature" # Strict mode with title (no spec yet) -afx spawn 1 --resume # Resume existing porch state -afx spawn 1 --protocol spir --soft # Soft mode - protocol-guided -afx spawn --task "fix the bug" # Ad-hoc task builder (soft mode) -afx spawn --worktree # Worktree with no initial prompt -afx status # Check all builders -afx cleanup -p 0001 # Remove completed builder -afx workspace start/stop # Workspace management -afx send 0001 "message" # Short message to builder -``` - -> **Note:** `--protocol` is REQUIRED for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip it. - -**Note:** `afx`, `consult`, `porch`, and `codev` are global commands. They work from any directory. - -### Porch CLI (for strict mode) - -```bash -porch status 0001 # Check project state -porch approve 0001 spec-approval # Approve a gate -porch pending # List pending gates -``` - -### Consult Tool (for integration reviews) - -```bash -# Single-model review (medium risk) -consult -m claude --type integration pr 35 - -# 3-way parallel review (high risk) -consult -m gemini --type integration pr 35 & -consult -m codex --type integration pr 35 & -consult -m claude --type integration pr 35 & -wait -``` - -## Responsibilities - -1. **Decide what to build** - Identify features, prioritize work -2. **Track projects** - Use GitHub Issues as the project registry -3. **Spawn builders** - Choose soft or strict mode based on needs -4. **Approve gates** - (Strict mode) Review specs and plans, approve to continue -5. **Monitor progress** - Track builder status, unblock when stuck -6. **Integration review** - Review PRs for architectural fit -7. **Manage releases** - Group projects into releases - -## Workflow - -### 1. Starting a New Feature - -```bash -# 1. Create a GitHub Issue for the feature -# 2. Ensure worktree is clean: git status → commit if needed -# 3. Spawn the builder (--protocol is REQUIRED) - -# Default: Strict mode (porch-driven with gates) -afx spawn 42 --protocol spir - -# With project title (if no spec exists yet) -afx spawn 42 --protocol spir -t "user-authentication" - -# Or: Soft mode (builder follows protocol independently) -afx spawn 42 --protocol spir --soft - -# For bugfixes -afx spawn 42 --protocol bugfix -``` - -### 2. Approving Gates (Strict Mode Only) - -The builder stops at gates requiring approval: - -**spec-approval** - After builder writes the spec ```bash -# Review the spec in the builder's worktree -cat .builders/spir-0042-feature-name/codev/specs/0042-feature-name.md - -# Approve if satisfactory (run from builder's worktree context) -(cd .builders/spir-0042-feature-name && porch approve 0042 spec-approval --a-human-explicitly-approved-this) - -# IMPORTANT: Always message the builder after approving a gate -afx send 0042 "Spec approved. Continue to plan phase." +afx send "Spec approved by the human. Run porch approve and continue to plan." ``` -**plan-approval** - After builder writes the plan -```bash -# Review the plan -cat .builders/spir-0042-feature-name/codev/plans/0042-feature-name.md +You do not run `porch approve` on the builder's behalf. The gate is the human's decision, you +are the channel that carries it, and the builder executes against its own porch state. Approval +the builder never hears about is approval that didn't happen. -# Approve if satisfactory (run from builder's worktree context) -(cd .builders/spir-0042-feature-name && porch approve 0042 plan-approval --a-human-explicitly-approved-this) +The command the builder runs requires `--a-human-explicitly-approved-this`, and that flag is +load-bearing: a gate message is a notification *to* a human, never a token an agent may spend on +its own authority. -# IMPORTANT: Always message the builder after approving a gate -afx send 0042 "Plan approved. Continue to implement phase." -``` +## Integration review — depth matched to risk -### 3. Monitoring Progress +Assess before choosing depth. **Highest single factor wins**: if lines, file count, subsystem +or cross-cutting scope puts it in a tier, the whole PR is in that tier. -```bash -afx status # Overview of all builders -porch status 0042 # Detailed state for one project (strict mode) -``` +| Risk | Shape | Review | +|---|---|---| +| **Low** | <100 lines, 1–3 files, isolated — docs, tests, cosmetic, most bugfixes | Read it yourself | +| **Medium** | 100–500 lines, 4–10 files, shared code — features, new commands | One model: `consult -m claude --type integration pr ` | +| **High** | >500 lines, >10 files, or core subsystems — porch, Tower, protocols, security model | 3-way CMAP in parallel | -### 4. Integration Review (Risk-Based Triage) +Subsystem mappings and worked examples: `codev/resources/risk-triage.md`. -When the builder creates a PR, **assess risk first** before deciding review depth. +Post findings as a PR comment, not a terminal message. Then tell the builder to merge — you +don't merge their work. -> **Full reference**: See `codev/resources/risk-triage.md` for subsystem mappings and examples. +### Presenting a decision to the human (PRFT) -#### Step 1: Assess Risk +Whenever you bring something to the human for a decision — a merge word, a `pr` gate, a +dev-approval — lead with **Problem · Root Cause · Fix · Testing**, unprompted, at every risk +tier. Verify the root cause yourself: a builder's summary is evidence, not ground truth. The +human should be able to answer from your message without opening the diff. -```bash -gh pr diff --stat # See lines changed and files touched -gh pr view --json files | jq '.files[].path' # See which subsystems -``` - -#### Step 2: Triage - -| Risk | Criteria | Action | -|------|----------|--------| -| **Low** | <100 lines, 1-3 files, isolated (docs, tests, cosmetic, bugfixes) | Read PR, summarize root cause + fix, tell builder to merge | -| **Medium** | 100-500 lines, 4-10 files, touches shared code (features, commands) | Single-model review: `consult -m claude --type integration pr N` | -| **High** | >500 lines, >10 files, core subsystems (porch, Tower, protocols, security) | Full 3-way CMAP (see below) | - -**Precedence: highest factor wins.** If any single factor (lines, files, subsystem, or cross-cutting scope) is high-risk, treat the whole PR as high-risk. - -**Typical mappings:** -- **Low**: Most bugfixes, ASPIR features, documentation, UI tweaks -- **Medium**: SPIR features, new commands, refactors touching 3+ files -- **High**: Protocol changes, porch state machine, Tower architecture, security model - -#### Presenting the decision to the human (PRFT) - -When you bring a fix to the human for a decision — a merge word, a `pr` gate, a dev-approval — present it **unprompted** in PRFT form, whatever the risk tier: - -- **Problem** — the user-visible symptom, in a sentence or two. -- **Root Cause** — the verified mechanism. Verify it yourself; a builder's summary is evidence, not ground truth. -- **Fix** — what changed and why it's safe. -- **Testing** — the evidence: suites run, live verification, CI state. - -Keep each part tight and lead with it — don't bury the decision under process narration. The human should be able to say yes or no from your message alone, without opening the diff. - -#### Step 3: Execute Review - -**Low risk** — no external models needed: -```bash -# Read the PR yourself, then approve -gh pr comment 83 --body "## Architect Review - -Low-risk change. [Summary of what changed and why.] - ---- -Architect review" - -afx send 0042 "PR approved, please merge" -``` - -**Medium risk** — single-model review: -```bash -consult -m claude --type integration pr 83 - -# Post findings as PR comment -gh pr comment 83 --body "## Architect Integration Review -... -Architect integration review" - -afx send 0042 "PR approved, please merge" -``` - -**High risk** — full 3-way CMAP: -```bash -consult -m gemini --type integration pr 83 & -consult -m codex --type integration pr 83 & -consult -m claude --type integration pr 83 & -wait - -# Post findings as PR comment -gh pr comment 83 --body "## Architect Integration Review -... -Architect integration review" - -afx send 0042 "PR approved, please merge" -``` - -### 5. Cleanup - -After builder merges and work is integrated: - -```bash -# 1. Close the GitHub Issue -gh issue close 42 - -# 2. Clean up the builder worktree -afx cleanup -p 0042 -``` - -**Always close the GitHub Issue when the PR merges.** This is the architect's responsibility — builders don't close issues. - -## Critical Rules - -### NEVER Do These: -1. **DO NOT merge PRs yourself** - Let builders merge their own PRs -2. **DO NOT commit directly to main** - All changes go through builder PRs -3. **DO NOT use `afx send` for long messages** - Use GitHub PR comments instead -4. **DO NOT run `afx` commands from inside a builder worktree** - All `afx` commands must be run from the repository root on `main`. Spawning from a worktree nests builders inside it, breaking everything. -5. **DO NOT `cd` into a builder worktree** - All CLI tools (`afx`, `porch`, `consult`, `codev`) are global commands that work from any directory. If a command fails, debug it — don't cd into the worktree. Use absolute paths with the Read tool to inspect builder files (e.g., `Read /path/to/.builders/0042/codev/specs/...`). - -### ALWAYS Do These: -1. **Create GitHub Issues first** - Track projects as issues before spawning -2. **Review artifacts before approving gates** - (Strict mode) Read the spec/plan carefully -3. **Use PR comments for feedback** - Not terminal send-keys -4. **Let builders own their work** - Guide, don't take over -5. **Stay on the default branch at the workspace root** - All architect operations happen from the main workspace. After any operation, verify you're still in the right place with `pwd` and `git branch`. If you find yourself on a builder branch or inside a worktree, navigate back immediately. - -## Project Tracking - -**GitHub Issues are the canonical source of truth for project tracking.** - -```bash -# See what needs work -gh issue list --label "priority:high" - -# View a specific project -gh issue view 42 -``` - -Update status as projects progress: -- `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated` - -## Working with Project Labels - -If your project uses prefix-structured labels (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, the recipes below are the architect-specific bulk operations — substitute `` and `` for your project's actual labels. (Skip this section if your project doesn't use prefix-structured labels.) - -**Operational recipes:** - -```bash -# Confirm the current label vocabulary (use before any label op to catch drift) -gh label list --search "/" - -# Group: tally open issues by /* label -gh issue list --state open --limit 500 --json number,title,labels --jq \ - 'group_by([.labels[].name | select(startswith("/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("/")).name): \(length)"' - -# Edit: change a label on a single issue -gh issue edit --remove-label / --add-label / - -# Audit: find open issues with no /* label -gh issue list --state open --limit 500 --json number,title,labels \ - --jq '.[] | select([.labels[].name] | any(startswith("/")) | not) | "#\(.number) \(.title)"' - -# Bulk-move: relabel all open / issues to / -for n in $(gh issue list --state open --limit 500 --label / --json number --jq '.[].number'); do - gh issue edit "$n" --remove-label / --add-label / -done -``` - -## Handling Blocked Builders - -When a builder reports blocked: - -1. Check their status: `afx status` or `porch status ` -2. Read their output in the terminal: `http://localhost:` -3. Provide guidance via short `afx send` message -4. Or answer their question directly if they asked one - -## Release Management - -The Architect manages releases - deployable units grouping related projects. - -``` -planning → active → released → archived -``` +## UX verification -- Only **one release** should be `active` at a time -- Projects should be assigned to a release before `implementing` -- All projects must be `integrated` before release is marked `released` +Before approving anything with UX requirements, exercise the actual user path. A spec that says +"async" and an implementation that blocks, or "immediate" and a 30-second wait, is a rejection +regardless of what the tests say. -## UX Verification (Critical) +## Boundaries -Before approving implementations with UX requirements: +- **Don't merge PRs** — builders merge their own. +- **Don't commit to the default branch** — every change arrives through a builder PR. +- **Don't `cd` into a builder worktree.** `afx`, `porch`, `consult` and `codev` are global and + work from anywhere; read builder files by absolute path. +- Run `afx` commands only from the main workspace root, never from inside a builder worktree — spawning from a worktree nests builders and breaks the workspace. +- **Use PR comments for anything long** — `afx send` is for short messages. +- **Let builders own their work** — guide, don't take over. +- **Close the GitHub Issue when the PR merges.** That's yours; builders don't close issues. -1. **Read the spec's Goals section** -2. **Manually test** the actual user experience -3. Verify each UX requirement is met +## When a builder is blocked -**Auto-reject if:** -- Spec says "async" but implementation is synchronous -- Spec says "immediate" but user waits 30+ seconds -- Spec has flow diagram that doesn't match reality +Check `afx status` or `porch status `, read its terminal output, and answer with a short +`afx send`. If it's waiting on an artifact, confirm the producing process is actually alive +before letting it wait — a wait is a claim that a producer exists. -## Quick Reference +## Bulk label operations -| Task | Command | -|------|---------| -| Start feature (strict, default) | `afx spawn --protocol spir` | -| Start feature (soft) | `afx spawn --protocol spir --soft` | -| Start bugfix | `afx spawn --protocol bugfix` | -| Check all builders | `afx status` | -| Check one project | `porch status ` | -| Approve spec | `porch approve spec-approval` | -| Approve plan | `porch approve plan-approval` | -| See pending gates | `porch pending` | -| Assess PR risk | `gh pr diff --stat N` | -| Integration review (medium) | `consult -m claude --type integration pr N` | -| Integration review (high) | 3-way CMAP (see Section 4) | -| Message builder | `afx send "short message"` | -| Cleanup builder | `afx cleanup -p ` | +If the project organizes issues with prefixed labels (`area/*`, `priority/*`), confirm the +vocabulary with `gh label list --search "/"` before any bulk edit — it catches drift +before it propagates. Group, audit and bulk-move with `gh issue list --json`/`--jq` and +`gh issue edit`. diff --git a/codev/roles/builder.md b/codev/roles/builder.md index 15bb1f8d0..864878dd6 100644 --- a/codev/roles/builder.md +++ b/codev/roles/builder.md @@ -1,259 +1,118 @@ # Role: Builder -A Builder is an implementation agent that works on a single project in an isolated git worktree. +You implement one project in an isolated git worktree, and you own it end to end: artifacts, +code, tests, PR. -## Two Operating Modes +## Two modes -Builders run in one of two modes, determined by how they were spawned: +| Mode | How you know | How you work | +|---|---|---| +| **Strict** (default) | spawned without `--soft` | Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. | +| **Soft** | spawned with `--soft` | You follow the protocol yourself; the architect verifies compliance. | -| Mode | Command | Behavior | -|------|---------|----------| -| **Strict** (default) | `afx spawn XXXX` | Porch orchestrates - runs autonomously to completion | -| **Soft** | `afx spawn XXXX --soft` | AI follows protocol - architect verifies compliance | +In strict mode porch drives the loop — run it, do the work it hands you, run it again. Do not +hand-run consultations it would run, advance plan phases yourself, or skip the 3-way review. -## Strict Mode (Default) +Never hand-edit `status.yaml` — only porch commands modify project state. -Spawned with: `afx spawn XXXX` +## Gates -In strict mode, porch orchestrates your work and drives the protocol to completion autonomously. Your job is simple: **run porch until the project completes**. +Porch stops at human approval gates (`spec-approval`, `plan-approval`, `pr`). When it does: +say so, **stop**, and wait. -### The Core Loop +Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization. -```bash -# 1. Check your current state -porch status - -# 2. Run the protocol loop -porch run - -# 3. If porch hits a gate, STOP and wait for human approval -# 4. After gate approval, run porch again -# 5. Repeat until project is complete -``` - -Porch handles: -- Spawning Claude to create artifacts (spec, plan, code) -- Running 3-way consultations (Gemini, Codex, Claude) -- Iterating based on feedback -- Enforcing phase transitions +Approval reaches you as a message from the architect. Then *you* run +`porch approve `; the architect does not run it for you — **unless your protocol's +prompts route that command to the human instead** (PIR's gates are typed by the human reviewer, +via Cmd+K G or their own shell). Defer to your protocol's phase prompts on who types `porch approve`. -### Gates: When to STOP - -Porch has two human approval gates: +## Deliverables -| Gate | When | What to do | -|------|------|------------| -| `spec-approval` | After spec is written | **STOP** and wait | -| `plan-approval` | After plan is written | **STOP** and wait | +Same base filename in three directories, plus code and tests: -When porch outputs: ``` -GATE: spec-approval -Human approval required. STOP and wait. +codev/specs/-.md what and why +codev/plans/-.md how and in what order +codev/reviews/-.md what was learned ``` -You must: -1. Output a clear message: "Spec ready for approval. Waiting for human." -2. **STOP working** -3. Wait for the human to run `porch approve XXXX spec-approval` -4. After approval, run `porch run` again +## Your thread -### What You DON'T Do in Strict Mode +Keep a free-text log at `codev/state/_thread.md` — the cohort's shared situational +awareness, readable by architects and sibling builders. `` is `basename "$(pwd)"`. +Write at phase boundaries and whenever a future reader would want to know what happened: +decisions, blockers, surprises. No schema, no cadence requirement. -- **Don't manually follow SPIR steps** - Porch handles this -- **Don't run consult directly** - Porch runs 3-way reviews -- **Don't edit status.yaml phase/iteration** - Only porch modifies state -- **Don't call porch approve** - Only humans approve gates -- **Don't skip gates** - Always stop and wait for approval +**Commit it with your PR.** Leaving it uncommitted by accident is a bug, not a choice. -## Soft Mode +## Telling the architect things -Spawned with: `afx spawn XXXX --soft` or `afx spawn --task "..."` +They are not watching. Send a message at each of these: -In soft mode, you follow the protocol document yourself. The architect monitors your work and verifies you're adhering to the protocol correctly. +| When | What | +|---|---| +| Gate reached | `afx send architect "Project : ready for approval"` | +| PR ready | `afx send architect "PR #N ready for review"` | +| PR merged | `afx send architect "Project complete. Entering verify phase."` | +| Blocked | `afx send architect "Blocked on X — need guidance"` | -### Startup Sequence - -```bash -# Read the spec and/or plan -cat codev/specs/XXXX-*.md -cat codev/plans/XXXX-*.md +When blocked, state the problem and the options you see, then wait. Don't guess past a decision +that isn't yours. -# (The full protocol text is inlined in your spawn prompt under the -# "## Protocol Reference (full text)" heading; no need to fetch it.) - -# Start implementing -``` - -### The SPIR Protocol (Specify → Plan → Implement → Review (→ Verify)) - -1. **Specify**: Read or create the spec at `codev/specs/XXXX-name.md` -2. **Plan**: Read or create the plan at `codev/plans/XXXX-name.md` -3. **Implement**: Write code following the plan phases -4. **Review**: Write lessons learned and create PR -5. **Verify** (optional): After PR merge, verify the feature works in the integrated codebase - -### Consultations - -Run 3-way consultations at checkpoints: -```bash -# After writing spec -consult -m gemini --protocol spir --type spec & -consult -m codex --protocol spir --type spec & -consult -m claude --protocol spir --type spec & -wait - -# After writing plan -consult -m gemini --protocol spir --type plan & -consult -m codex --protocol spir --type plan & -consult -m claude --protocol spir --type plan & -wait - -# After implementation -consult -m gemini --protocol spir --type pr & -consult -m codex --protocol spir --type pr & -consult -m claude --protocol spir --type pr & -wait -``` +## Waiting on external work -## Deliverables +**A wait is a claim that a producer exists.** Before waiting on a file, a build, or a sibling's +output, confirm the process meant to produce it is alive. A builder once waited 45 minutes on a +file whose producer had already died — that wait was not slow, it was unsatisfiable. -- Spec at `codev/specs/XXXX-name.md` -- Plan at `codev/plans/XXXX-name.md` -- Review at `codev/reviews/XXXX-name.md` -- Implementation code with tests -- PR ready for architect review +**Run waits as background tasks that end your turn.** Every message sent to you — including an +order to stop — queues unread until your current turn ends. A turn that never ends is a builder +nobody can redirect, and you will not notice, because from inside it everything looks fine. +Never chain foreground poll loops. -## Communication +If you are wedged anyway, the architect can end your turn with `afx interrupt `, or +`afx reset ` to have you save state and re-orient. Worth knowing so you can suggest +them. -### With the Architect +## PRs -If you're blocked or need help: -```bash -afx send architect "Question about the spec..." -``` +Plan phases are **git commits inside one PR**, not a PR each. Open the PR during or after the +final phase unless the architect asks for one earlier — they may, to review a slice or get +feedback mid-flight. Record them with `porch done --pr --branch ` and +`porch done --merged `. -### Checking Status +For sequential PRs, branch from the integration branch without checking it out — a worktree +cannot check out a branch that is checked out elsewhere: ```bash -porch status # (strict mode) Your project status -afx status # All builders +git fetch origin main && git checkout -b origin/main ``` -## Thread file - -You maintain a free-text markdown log at `codev/state/_thread.md` (relative to your worktree). This is the cohort's collective situational-awareness surface — architects and sibling builders can read it via plain file I/O. - -**Path resolution**: `` is the basename of your worktree path. Resolve it once with `basename "$(pwd)"`. Example: if your worktree is `.builders/spir-823/`, the path is `codev/state/spir-823_thread.md`. - -**Directory creation**: `codev/state/` likely doesn't exist when you start (it's greenfield). Your first write creates it — the Write tool's `mkdir -p` semantics handle this transparently. No need to pre-create the directory. - -**What to write**: phase transitions, decisions, blockers, anything worth recording for the cohort. Trust your own judgement about what's useful. There is no required schema, no required sections, no timestamp format. The thread is yours. - -**When to write**: at phase boundaries and at any other moment you think a future reader would want to know what happened. Don't over-engineer cadence — append when there's something to say. +## Worktree discipline -**Discovery**: -- **In-flight** (while you're active): your thread lives in your worktree at `.builders//codev/state/_thread.md` (from the main workspace root). Architects read it with `cat .builders//codev/state/_thread.md`; they discover threads with `ls .builders/*/codev/state/*.md`. -- **Sibling builders**: read each other's threads via `cat ..//codev/state/_thread.md` from your own worktree (the parent `.builders/` directory is shared between all builders in the workspace). -- **Post-merge**: after your PR merges, your thread lands in `codev/state/` on `main` (parallel to `codev/reviews/`) and becomes part of the historical review record. +Your worktree is nested inside the main checkout and, at the branch base, byte-identical to it. +So a path that drops the `.builders//` segment silently reads and writes **main's** copy — +reads succeed, writes succeed, and nothing corrects you until a later `git add` fails. -**Commit/retention rule**: **the default disposition is COMMIT.** Stage and commit your thread file as part of your PR. The rare exception — when your thread turned out to be noise rather than useful narrative — is an explicit decision to strip it before PR (via gitignore for the PR or by not staging the file). Silently leaving the thread uncommitted by accident is a bug, not an exercise of the exception. The cohort's situational-awareness goal depends on threads surviving to `main`. +- Absolute paths for file writes must be rooted at your worktree. A guard blocks writes outside + it; if you see that denial, re-root the path. +- In Bash, prefer relative paths — `cwd` is your worktree, so a relative path cannot be anchored + to the wrong root. -**Scope reminder**: this is for the cohort's situational awareness, not porch's tracking. Porch does not read this file. There are no hooks, no validation, no enforcement. +## Scope -## Notifications +Build what the spec says. If part of it is blocked, finish everything else and say plainly what +you left out and why — scaling the work down is the architect's call. -**ALWAYS notify the architect** via `afx send` at these key moments: +Never `git add -A` / `--all` / `.` — stage each file explicitly by path. -| When | What to send | -|------|-------------| -| **Gate reached** | `afx send architect "Project XXXX: ready for approval"` | -| **PR ready** | `afx send architect "PR #N ready for review"` | -| **PR merged** | `afx send architect "Project XXXX complete. PR merged. Entering verify phase."` | -| **Blocked/stuck** | `afx send architect "Blocked on X — need guidance"` | -| **Escalation needed** | `afx send architect "Issue too complex — recommend escalating to SPIR"` | +If the issue carries a **Baked Decisions** section, those are fixed. Don't relitigate them in +your spec, plan, or implementation; if one looks seriously wrong, raise it with `afx send`. If +two contradict each other, don't pick — flag the contradiction and wait. -The architect may be working on other tasks and won't know you need attention unless you send a message. **Don't assume they're watching** — always notify explicitly. - -## When You're Blocked - -If you encounter issues you can't resolve: - -1. **Output a clear blocker message** describing the problem and options -2. **Use `afx send architect "..."` to notify the Architect** -3. **Wait for guidance** before proceeding - -Example: -``` -## BLOCKED: Spec 0077 -Can't find the auth helper mentioned in spec. Options: -1. Create a new auth helper -2. Use a third-party library -3. Spec needs clarification -Waiting for Architect guidance. -``` - -## Waiting on external work +## Flaky tests -The section above covers being blocked on *the architect*. This one covers being blocked on *an -artifact* — a file another agent is producing, a build, a queue, a sibling builder's output. That case -has its own failure mode, and it is the one that strands builders. - -**A wait is a claim that a producer exists.** Before waiting on an artifact, confirm the process meant to -produce it is actually alive. In the incident that motivated this guidance (2026-07-27), a builder waited -45+ minutes on a file whose producing process had already died. The wait could never have succeeded; it -was not slow, it was unsatisfiable. Checking first costs seconds. - -**Run waits as tracked background tasks that end your turn.** Start the wait in the background and finish -your turn. You are re-invoked when it completes, so the lane keeps moving *and* you stay addressable in -the meantime. A turn that ends is a turn someone can interrupt. - -**Never chain foreground poll loops.** This is the rule that matters most, and the reason is not -efficiency. Every `afx send` to you — including the architect's order to stop, including a reset -request — **queues unread until your current turn ends**. A turn that never ends is a builder that cannot -be reached by anyone, doing work nobody can redirect. You will not notice, because from inside the turn -everything looks fine. - -**If you are wedged anyway, you are not unreachable.** The architect can send you an ESC keystroke with -`afx interrupt `, which ends the running turn so your queued messages process. They can also run -`afx reset ` to have you save your working state, clear your context, and be re-oriented — the -supported recovery when your context window is exhausted rather than merely stuck. Neither requires you -to do anything; both are worth knowing exist, so you can suggest them when you notice you are in trouble. - -## Multi-PR Workflow - -Builders may submit multiple sequential PRs within a single worktree session. The worktree persists across PRs -- it is not cleaned up automatically after merge. This allows builders to do follow-up work (e.g., addressing review feedback in a second PR, or splitting large features across checkpoint PRs). - -- **Worktree cleanup is architect-driven** -- the architect decides when to run `afx cleanup`, not the builder -- If a builder session is interrupted, use `afx spawn XXXX --resume` to reconnect to the existing worktree - -## Worktree isolation: filesystem path discipline - -Your worktree (`.builders//`) is **nested inside the main checkout**, and at the -branch base the two trees are **byte-identical**. This creates a silent failure mode: - -- The `Write`/`Edit` tools require **absolute** paths. If you synthesize one rooted - at the canonical repo root instead of your worktree, you drop the `.builders//` - segment and write into the **main checkout** — a real, writable directory. The - write *succeeds silently* and pollutes `main`; you only notice later when a - `git add` in your worktree fails with a pathspec error. -- Wrong-rooted **reads** also succeed silently (identical trees), so nothing - corrects the mistake until that first failed write. - -Rules: -- **Absolute paths for Write/Edit must be rooted at your worktree.** A deterministic - PreToolUse guard now blocks out-of-worktree writes (allowing only temp dirs and - `~/.claude`); if you see that denial, re-root the path under your worktree. -- **Bash `cwd` is your worktree — prefer relative paths there.** A relative path - cannot be anchored to the wrong root, which closes the Bash write surface - (`>`, `cp`, `tee`, `sed -i`) the Write/Edit guard does not cover. - -## Constraints - -- **Stay in scope** - Only implement what's in the spec -- **Merge your own PRs** - After architect approves -- **Keep worktree clean** - No untracked files, no debug code -- **(Strict mode)** Run porch, don't bypass it -- **(Strict mode)** Stop at gates - Human approval is required -- **(Strict mode)** NEVER edit status.yaml directly -- **(Strict mode)** NEVER call porch approve +If a pre-existing test fails intermittently and unrelated to your change: skip it with an +annotation naming it flaky, document it under `## Flaky Tests` in your review, and continue. +Never edit `status.yaml` or bypass a porch check to route around it. diff --git a/codev/state/spir-1280_thread.md b/codev/state/spir-1280_thread.md index 44dad0141..098190ba4 100644 --- a/codev/state/spir-1280_thread.md +++ b/codev/state/spir-1280_thread.md @@ -518,3 +518,808 @@ principle P7 exists to delete.** Recorded rather than smoothed over. build.* The delegated tool — like the overloaded exit code, the truncated grep, the skeleton-only enumeration, and the stale script comment before it — looked authoritative and wasn't. CI was the authoritative signal here, and it existed all along. + +### Phase 1 built — CLAUDE.md/AGENTS.md + four-tree relocation (2026-08-01) + +PR #1319 merged; re-branched `builder/1280-rewrite` from `origin/main` (no duplicate Phase-0 +commits — verified). Commit f9cd93c6. + +CLAUDE.md 5,815 → **1,417**. ALWAYS_ON 34,231 → **29,833**. + +**The M0c split is the number that matters**, and it is why M0c exists: of 4,398 words removed +from always-on, **1,129 were relocated** and **3,269 deleted**. Authored total fell only 4,294 +because relocation writes to four trees. An always-on-only metric would have reported the whole +4,398 as deletion — a 26% overstatement of what actually went away. + +Deliberate judgment call, flagged rather than made silently: **I did not touch the `afx` skill.** +Relocating inter-agent messaging into it would have obliged me to resolve its pre-existing +repo-vs-skeleton drift *and* propagate its stale `tick` references (a protocol that does not +exist in either tree) to adopters — squarely the architect's separate issue. The addressing +*contract* stayed in CLAUDE.md instead: it is policy, not a how-to, so P4 does not apply. + +**M10: zero assertions retired.** All four collision candidates pass unmodified. + +**Two of my own mistakes, both caught by verification rather than review:** + +1. **Reflowing broke the scar canonicals.** My first draft wrapped them across lines for + readability; five of eight then failed exact-match against the ratified YAML. Canonicals must + be single-line. Caught because I checked byte-for-byte against + `builder/spir-1252:scar-rules.yaml` rather than eyeballing that they "looked present". +2. **My Phase 0 test pinned a moving number.** It asserted ALWAYS_ON == 34,231 — a literal this + project changes *every phase*. It failed on Phase 1 exactly as designed to, but the design was + wrong: a test edited every phase is a test edited carelessly, which is M10's own argument + turned on my suite. Replaced with arithmetic invariants that hold at any surface size, plus an + immutable assertion that the FROZEN baseline artifact still records 34,231. + +Manifest at `manifests/phase-1-shared-skills.md`: 10 files in one batch, with the deleted-vs- +relocated table and a per-cut justification column. Suite 205 files / 4,083 tests green +(rebuilt first — skeleton edits are invisible until `copy-skeleton` reruns). + +Awaiting architect per-file inspection before Phase 2. + +### Phase 2 built — three role files, three group-pure commits (2026-08-01) + +architect 2,048 → 761 (G6, cc2398c2) · builder 1,837 → 849 (G3, 20567714) · consultant 252 → +**unchanged** (G5, no commit). ALWAYS_ON 29,833 → **28,844**. + +**Consultant left alone deliberately.** It is already conformant — a contract, not a procedure. +Under the acceptance model a conformant file passes *as-is*, and trimming it anyway would be +size-chasing, which the charter amendment explicitly rejects. Recording the non-change as a +decision rather than an omission. + +**Resolved the plan's open question by checking, not assuming**: `architect.md` carries nothing +load-bearing for multi-architect coordination (Specs 755/786/823) — grepped for +`architect:`, sibling language, `spawnedByArchitect`, `whoami`: zero matches. That +contract lives in CLAUDE.md, kept there in Phase 1. + +**Found while cutting**: the architect role's command block was a *stale second owner* — it +still showed `porch approve spec-approval` without the +`--a-human-explicitly-approved-this` flag the command now requires. Exactly the drift P4 exists +to prevent: two owners of the same syntax, one of them quietly wrong. Deleting the copy fixes +the drift as a side effect. + +**M10: zero assertions retired**, but three initially failed and the resolution is the +interesting part. `spec-1273-wait-discipline-docs` (18 assertions) broke on: a heading I had +renamed, a phrase **split by a line wrap**, and a dropped word ("current"). In all three the +*behaviour* survived — only the strings moved. **I adjusted my prose rather than the +assertions.** Those strings encode a real wait-discipline incident; preserving them cost nothing +in conformance terms, and editing a prior spec's protection to fit new prose is precisely the +silent erosion M10 exists to prevent. Writing to the test would have been the easy call and the +wrong one. + +**Hazard named, third occurrence**: reflowing prose silently breaks any exact-match string that +spans a line wrap — scar canonicals in Phase 1, a prior spec's assertions here, and I repeated +it *within* Phase 2 on `afx-from-root` before catching it. Any exact-match string in a rewritten +file must be re-verified after the rewrite; canonicals stay on one line however long. This is +the same family as the `wc`/`cmp`/grep lessons: the check that looks like it passed, and didn't. + +Suite 205 files / 4,083 tests green. Manifest at `manifests/phase-2-roles.md`. Awaiting +inspection. + +### Phase 2 post-inspection fix — the contradiction I introduced (2026-08-01) + +Architect PASSED Phase 2 with one required fix, and it was a good catch on a defect **I +created**: `builder.md` got the correct relay convention (builder runs `porch approve` after the +architect relays the human's word) while `architect.md` kept the old example showing the +*architect* running it. Two roles, two answers, one of them contradicting what actually happened +at both of this project's own gates. + +Fixed in `21ac428c`, G6-pure. architect.md 761 → **807** words — **the fix made the file longer, +and that is fine**: conformance is the criterion, not size. Under the old size-target acceptance +model I might have felt pressure to squeeze it back; under the amended charter there is none. + +**The uncomfortable part is worth stating.** This is the same stale-second-owner class I had +just congratulated myself for catching on the porch-approve flag syntax — one level up, and I +introduced it, by fixing one owner and leaving the other. Catching a class of defect is not the +same as being immune to it. + +General form for the remaining phases: **when a rewrite changes a convention, every file that +documents that convention is in scope — not just the one being edited.** Phase 3 touches ten +`protocol.md` files that describe gates, artifacts and phase order; the same trap is waiting +there at ten times the width. + +Architect has adopted my reflow-hazard rule as a standing inspection item and will fixed-string- +verify every exact-match string in every batch from here. + +### Hotfix #1321 — main went red on my test (2026-08-01) + +`honours PHASE_ITERS` timed out at vitest's 5000ms default on a loaded CI runner (5,690ms), +blocking green CI for every open PR. Fixed with explicit 60s budgets on the 12 blocks that shell +out to the measurement script (11 tests + the `beforeAll`), per the #1302 precedent. One file, +12 lines. + +**Scope determined by parsing, not eyeballing**: I parsed the file for blocks whose body calls +`run()`. The 9 non-shelling tests keep the default budget deliberately — a timeout on a test that +*cannot* be slow is noise, and would mask a future regression in exactly the tests that can be. + +**The honest diagnosis is worse than "flake".** On an *unloaded* machine those tests take +3.9–4.0s against a 5s default — ~80% of budget before any contention. The sibling test hit +4,576ms in the same CI run; it was next regardless of load. **I shipped a test file where a third +of the tests sat at 80% of budget and never looked at the timings.** The failure was latent in +PR #1319 and a fast runner flattered it. Architect accepted the correction on the record. + +**Approved follow-up, scheduled AFTER Phase 3** (architect ruling): `measure-prompt-surface.sh` +spawns `python3` once per file for include expansion — that is the whole ~4s. A single-pass +expansion takes these tests under a second and speeds up every measurement the remaining phases +run. Own small PR. Unblocking main and resuming the rewrite outranks it. + +Standing lesson, and it generalises past this project: **a test that passes at 80% of its budget +is a failure that has not happened yet.** Check timings, not just the green tick — the same +family as the delegated `wc`, the overloaded `cmp` exit code, and the truncated grep: a signal +that looks like success and is measuring the wrong thing. + +### Pre-Phase-3 convention audit — and my own instrument was the defect (2026-08-01) + +Ran the cross-batch convention diff I committed to after Phase 2, read-only, while waiting on the +#1321 merge word. It produced an alarming first result: **seven of nine protocols appeared to +have `protocol.md` contradicting `protocol.json` about gates**, including `aspir` apparently +claiming the very `spec-approval`/`plan-approval` gates ASPIR exists to remove — which would have +meant a builder stopping forever at a gate porch never requests. + +**All three "contradiction" findings were false positives produced by my own audit script.** + +| Apparent finding | Reality | My script's flaw | +|---|---|---| +| `aspir` claims spec/plan gates | Prose says it **removes** them — correct | Read a *mention* as a *claim* | +| `pir` claims spec/verify-approval | A **SPIR-vs-PIR comparison table row** — correct | Same | +| `research` claims undefined `scope-approval` | It **is** defined — as a dict, not a string | Extractor only handled string-valued `gate` | + +The real, much weaker finding after fixing the extractor: five protocols never *mention* a gate +their JSON defines (`verify-approval` in spir/aspir; the `*-complete` gates in +experiment/maintain/research). That is incompleteness, not contradiction, and P6 dissolves it — +referencing the structured source means the prose cannot be less complete than the truth. + +**This is the fifth instance of the family** (delegated `wc`, overloaded `cmp` exit code, +truncated grep, `pipefail`+`grep -q`, now a naive regex + a type-blind JSON walk). But it differs +in the way that matters: **I caught it before reporting it as fact.** Every previous instance +reached a commit message, a spec, or the architect before being corrected. The habit of verifying +in-context before characterising is what stopped an alarming and wrong claim from going out. + +Worth stating because it cuts against my own interest: an audit script written *by* the person +whose work it audits is subject to exactly the bias the audit exists to remove. Mine was crude in +the direction that made the codebase look worse and my upcoming phase look more necessary. The +correction was cheap only because I checked the raw text before believing the summary. + +### Merged main + the unlanded hotfix into the rewrite branch (2026-08-01) + +Architect instruction: merge `origin/main` before the next test run — #1324 skips +`agy-integration.e2e.test.ts`, which had been opening OAuth windows on the human's machine on +every suite run while `agy` is unauthenticated. Merged (`fbdc0f45`); `describe.skip` pending +#1323 confirmed present. The `agy` binary is renamed machine-wide, so the gemini consult lane +reports "not installed" and skips non-blockingly — expected, not to be fixed. + +**The instruction didn't cover something that mattered: #1321 is still OPEN.** Main carries +**zero** `60_000` timeouts, so merging main alone would have left this branch carrying the exact +latent failure that took main red — it was cut before the hotfix, and the hotfix lives on its own +branch. The next test run here would have been rolling the same dice. + +So I merged `origin/hotfix/1280-test-timeouts` too (`3b0b2a4f`). **Merged rather than +cherry-picked deliberately**: when #1321 lands on main, a later `merge origin/main` sees shared +ancestry and stays clean instead of conflicting on a duplicated change. + +**One conflict, and both sides were needed** — worth recording because whoever hit it later +would have been tempted to pick one: Phase 1 replaced the pinned-baseline assertions in +`spec-1280-measurement-instrument.test.ts` with arithmetic invariants, while the hotfix added +budgets to the same region. Resolution keeps **Phase 1's invariants AND the 60s budget**. A +"take theirs" would have silently reinstated a literal that this project changes every phase; a +"take ours" would have reinstated the timeout that took main red. + +Suite after both merges: **205 files, 4,083 tests, green.** + +Sixth instance of the family, minor: my own budget-verification script flagged the one-liner +`beforeAll(..., 60_000)` as unbudgeted, because it inspects the line *after* a block and that +block closes on its own line. Caught in seconds by reading the actual line. The reflex is now +reliable — check the raw text before believing any summary I wrote, including my own tooling's. + +Phase 3 still paused; the merge instruction carried no resume word and I am not inferring one. + +### Two instrument PRs queued; a seventh family instance (2026-08-01) + +`#1321` (test budgets) and `#1327` (invariant-form reproduction tests) both green, queued in that +order. Phase 3 held on #1321's merge word. + +**#1327 nearly went into the queue red, from a cause I had warned about an hour earlier.** It +branched from `d42a061a`, predating #1321, so it inherited 10 unbudgeted script-shelling tests — +the same latent 5s failure that took main red. My three new tests carried budgets; the ten I did +not touch did not. Merged the hotfix branch in rather than duplicating the change, so the +eventual #1321-on-main merge stays clean. + +The conflict there was the instructive kind: the hotfix carried a *budgeted copy* of a test +`#1327` **replaces**. A mechanical "prefer theirs" would have left the PR **green and wrong** — +silently reinstating the live-measured literal the PR exists to remove. Resolved for the +replacement; verified zero unbudgeted tests and zero markers after. + +**Seventh family instance, and this one was my own tooling again**: my CI watcher polled for +*absence of pending checks*, but my push had started a new run — the gap between runs read as +"settled". Re-watched pinned to the head SHA, and confirmed local == remote before believing the +result. The architect reports their own watchers share the flaw and is pinning theirs too. + +The family, now seven: delegated `wc`; overloaded `cmp` exit code; truncated grep; +`pipefail`+`grep -q`; naive regex + type-blind JSON walk; one-liner-blind budget checker; +absence-of-pending watcher. Every one a signal that looked authoritative while measuring +something adjacent to the question. The habit that catches them is the same each time: **read the +raw thing before believing the summary — including summaries produced by my own tools.** + +### Phase 3 — protocol.md ×10 via P6 (2026-08-01) + +Commit 7b195391. ALWAYS_ON 28,844 → **26,384**; TOTAL_AUTHORED 144,465 → **126,155**. +spir 3,699 → 671 authored / 1,239 served. + +**P6 works and is verified end to end**: `resolveCodevIncludes` is extension-agnostic, and +`spawn-roles.ts:127` runs `protocol.md` through the same resolver, so strict *and* soft mode get +the JSON. T18 asserts both — they are not symmetric, and **soft-mode builders have only this +document**. + +**Resolver model corrected** (found by writing T18): tier 4 is `getSkeletonDir()` — the +*installed npm package* — not `/codev-skeleton/`, which is a build source the resolver +never reads. My first fresh-install test planted files in a temp `codev-skeleton/` and "passed" +against the real installed package. Rewritten to assert the adopter guarantee instead. + +`release/protocol.md` inspected and **unchanged**: no `protocol.json`, and 36% exact commands +where the sequence *is* the contract. + +**The tests caught real capability loss I introduced — 37 failures, all repaired, zero +assertions retired:** +- **#1279 (12)**: I swapped maintain/spike/experiment's *template* includes **for** the JSON + include instead of carrying both, orphaning three artifact templates. +- **Spec 746 (24)**: Baked Decisions shortened in SPIR, dropped from ASPIR/AIR — losing + "absence is the no-op default", which is what stops a builder inventing constraints the + architect deliberately left open. + +**The process failure was mine and worth more than the code fix**: I wrote "suite green, no +assertions retired" into the manifest *while the suite was still running*. Every instrument this +project touched got "read the raw thing, don't trust the summary" — and I skipped it on my own +completion claim. Had the architect inspected on my word, they'd have reviewed a batch whose +green claim was fiction. + +**T16 then caught three defects in the manifest itself** — a silently-added fifth column, 19 +file-rows breaking the ≤12 cap (abandoning the plan's per-decision model), and a supplementary +table parsing as manifest rows. All three were deviations from a format I defined. Conformed the +manifest each time rather than loosening the guard. + +Suite verified green **after** the repairs: 206 files, 4,117 tests. + +### Phase 3 FAILED inspection, and the reason was my run discipline (2026-08-01) + +Architect ran T16 in my worktree after a fresh build: **it failed on the pushed state** — seven +`codev-skeleton/protocols/*/protocol.md` paths reported as absent from every manifest. So +"suite verified green after the repairs: 4,117" **was not true of what I pushed**. Same +premature-claim class I had owned two paragraphs earlier *in the same message*. + +**Diagnosis — I ran the suite before committing.** T16 diffs `origin/main...HEAD`, which sees +**committed changes only**. Phase 3's rewrite commit (`7b195391`) came *after* that suite run, so +T16 found no changed prompt files and passed **vacuously**. The test was correct both times; my +run measured a tree that no longer existed by the time I made the claim. + +Two fixes, one of each kind: + +1. **Format decision** (mine to own): the parser learns brace notation. The plan's model is + inspection *per decision* — twins byte-identical, sync verified by T7 — so ~66 decisions + rather than 131 diffs, and the ≤12 cap counts decisions. One row naming both paths is the + right semantics. Chose this over splitting rows, which would have broken the cap and silently + abandoned the per-decision model. +2. **Root cause**: T16 now reads committed **and** working-tree changes, so a pre-commit run + cannot pass vacuously. *A guard that passes because it looked at the wrong tree is worse than + no guard — it manufactures confidence exactly when the work is unreviewed.* + +**Mutation-verified**: removing the spir row fails it, restoring passes. After a vacuous pass I +do not treat a green tick as evidence a guard bites. + +**New standing rule for the rest of this project**: commit first, then run, then read the run, +then claim — and quote the SHA the run executed against. No green statement about a run still in +flight, ever again. + +Verified verdict: HEAD `1eac5c35`, **206 files / 4,117 tests, exit 0**, working tree clean, all +four T16 assertions passing individually. + +### Phase 3 PASSED (2026-08-01) — plus a 746-amendment candidate for the review file + +Architect verified T16 green at `a8e4518f` themselves, confirmed all three #1279 template +includes present, and content-read all ten decisions. `release` non-change endorsed on its own +reasoning: **where the sequence is the contract, P1 protects the procedure.** + +**Architect observation, non-blocking, to carry into the review file:** AIR's Baked Decisions +text — 746-pinned and shared verbatim across protocols — instructs copying the section "into the +spec's Constraints". **AIR has no spec phase.** That is a pre-existing seam in the *ratified* +text, not something Phase 3 introduced and not mine to fix unilaterally (the wording is +architect-ratified). **Recorded as a Spec 746 amendment candidate** for the review's follow-ups. + +Worth noting *why* it went unnoticed: the assertion that guards this text checks for the +presence of category hints, the escape hatch and "no-op default" — it cannot check that the +instruction makes sense for the protocol carrying it. A grep-shaped guard protects wording, not +applicability. + +### Phase 4 built but BLOCKED on R1 — the suite is red, deliberately (2026-08-01) + +Commit `235f012f`. Nine builder-prompts rewritten, both trees. **Verified run at that SHA: +205 files passed, 1 failed; 4,114 tests passed, 3 failed; EXIT=1.** + +**All three failures are R1** — `expectPureAdditionDiff` on the spir/aspir/air builder-prompts — +and I could have made them green in one command by retiring the assertion myself. I did not. +**The red suite is the visible cost of that discipline**, and reporting it red is the point: +a green build here would have meant a prior spec's protection quietly deleted to suit my work. + +R1's trace is in `codev/resources/1280-retirements.md`. The crux: 746's baseline is the +**pre-746** file, so the assertion proves its paragraph was *added* without deleting anything. +This project deletes deliberately, so the invariant is permanently unsatisfiable — it forbids +*any* future rewrite of these files. **Re-baselining is not the escape**: 746's own pollution +check requires the baseline to lack `## Baked Decisions`, so a re-baselined file fails it, and +silencing that check would gut the anti-vacuity half of the protection. + +746's *substance* survives and still passes unmodified — heading, carveout, contradiction +wording, mirror-parity, verified in all three. + +**Kept rather than retired**: #744's four PR-strategy phrases, and #619's +`Follow the ASPIR protocol` (my first draft swapped it for a template variable; the original bug +told ASPIR builders to follow SPIR — wrong gates). Added the symmetric SPIR line, since #619 was +a cross-protocol mixup. + +**Kept despite duplicating the role doc**: the Verify Phase. `roles/builder.md` carries it only +inside a notification string, so deleting it would have repeated the exact bug 1252 found. + +### T16 scoped — second cross-project firing of my own guards + +Its predicate was **repo-global**: any prompt-bearing path in `origin/main...HEAD` had to appear +in a *1280* manifest. In the shared suite that blocked **Spec 1307**, which would have had to +file paperwork in my project's directory to go green. Worse than the pinned literal: it demanded +foreign projects write into my ledger. + +Fixed by **provenance, not paths** — only files touched by `[Spec 1280]`-tagged commits on this +branch count; other branches skip entirely. Uncommitted-changes checking retained so a +pre-commit run still cannot pass vacuously. + +**Mutation-verified both ways**, because a scoping fix that silently disabled the guard would be +the vacuous pass again: removing a manifest row still fails; a real branch off `origin/main` +with **0 `[Spec 1280]` commits** and 2 changed prompt files **passes**. + +**My first attempt at that second simulation never ran** — the branch checkout failed silently +(it would have clobbered uncommitted work), so the test executed on my own branch and "passed" +meaninglessly. Caught only because the output reported *16* `[Spec 1280]` commits on a branch +that should have had zero. Eleventh instance of the family, and the tell was a number that made +no sense for the thing I claimed to be measuring. + +### R1 approved and executed; Phase 4 green (2026-08-01) + +**Verified run: HEAD `4062e9ad`, 207 files passed / 3 skipped, 4,126 tests passed / 48 skipped, +EXIT=0.** HEAD unchanged since the run; tree clean. + +Two commits, deliberately separate per the approval's third condition: + +- **`0b9be85f` — the retirement.** Exactly two files. Names Spec 746, records the architect's + three grounds, and carries the per-assertion behaviour-re-asserted mapping. Retired precisely + the three `PHASE_1_FILES` instances; `PHASE_2_FILES`/`PHASE_3_FILES` guards and the pollution + check are untouched. +- **`4062e9ad` — the replacement.** Post-1280 baselines, same machinery, plus an **inverted + anti-vacuity check**: 746's version proved its baseline *predated* the edit; mine requires the + post-1280 baseline to *contain* `## Baked Decisions`, so stripping 746's content and + re-baselining to hide it fires the guard. + +**Mutation-verified both ways**: deleting a line fails; laundering by re-baselining fails; +restored passes 12/12. + +**A correction I owed and recorded rather than quietly fixed**: my retirements file described +the replacement as *"implemented, inert until approved"*. It was **designed, not implemented**. +The architect read that file before approving, so the overstatement is corrected in the document +itself. The lesson generalises past this project: **a governance artifact is read as evidence, +so a claim inside it must be true when written, not merely true by the time anyone checks.** + +The architect's framing of R1 is worth preserving: the invariant was **construction-time +scaffolding that hardened into a change-freeze** — it proved a thing at the moment of addition, +then silently became a prohibition on all future editing of those files. That is a distinct +failure shape from the ones this project has been cataloguing, and it is a good candidate for +the lessons ledger: *an assertion written to prove one change was safe can outlive its purpose +and start forbidding change in general.* + +### Context cleared 2026-08-01 — state saved + +Wrote `codev/state/spir-1280_RESUME.md` as the cold-start entry point: current HEAD/branch, +phase status, the acceptance model, Phase 5's scope and its constraints, the seven standing +rules (each earned by a specific failure), M10 discipline, the four guards I own, and open items. + +Phases 0–4 inspected PASS. **Phase 5 next: phase prompts for spir/aspir/pir, 11 decisions.** + +The single most important thing for the next session to not get wrong: **`{{artifact_name}}` is +positional.** Removing it from builder-prompts fixed #1293; removing it from phase prompts would +break artifact naming outright (porch substitutes it at `prompts.ts:102`, 51 references across +the Phase 5 targets). Same string, opposite meaning, two files apart. + +Also flagged: **porch's plan-phase pointer is stale** — it still reads `phase_0_instrument` +because phases have been gated by architect inspection rather than by `porch done`. That needs +an architect decision, not a hand-edit of `status.yaml`. + +### Phase 5 started (2026-08-02) — resumed after context clear + +Architect ack'd the status.yaml reconciliation (commit 9c67aa86: phases 0–4 `complete`, +phase_5 `in_progress`, pointer → phase_5_prompts_heavy). `porch status 1280` renders 0–4 ✓, +phase_5 ►. Measurement-script perf follow-up is with Waleed to decide issue-vs-task and owner; +architect: **do not pick it up in this worktree unless told.** + +**Phase 5 scope map (measured, not assumed):** +- 11 decisions = spir×4 + aspir×4 + pir×3, each "both trees" (brace notation, 1 decision). +- **All 11 codev/ copies are byte-identical to their codev-skeleton/ twins** → brace notation valid. +- **spir prompts are byte-identical to aspir prompts** (implement/plan/review/specify all ==). + A conformance rewrite is not a behavior change, so I keep them identical: **7 distinct rewrites** + (4 shared spir/aspir + 3 pir), fanned to the 11×2=… actually 22 physical files. +- pir has **no specify** (Plan-Implement-Review). + +**Served vs raw counts (served = include-expanded, the manifest's Old/New basis):** +| file | served | raw | include delta | +|---|---:|---:|---:| +| spir/aspir implement | 1064 | 1064 | 0 | +| spir/aspir plan | 1167 | 520 | 647 | +| spir/aspir review | 1955 | 1316 | 639 | +| spir/aspir specify | 1400 | 770 | 630 | +| pir implement | 1151 | 1151 | 0 | +| pir plan | 741 | 741 | 0 | +| pir review | 2413 | 2413 | 0 | + +The include delta IS the `{{> …templates/…}}` inlining. **Templates are Phases 6–7, out of scope +here** — I edit prompt bodies, not the included templates. Served counts will still carry the +(unchanged) template words. + +**Constraints re-confirmed against the tree, not the note:** +- `{{artifact_name}}`: **51 refs across the 11**, load-bearing (porch substitutes at + prompts.ts:102). Preserve every one. (spir/aspir implement carry 0; the other 9 files hold all 51.) +- Levers per spec row `protocols/*/prompts/*.md`: **P2 (examples→interfaces), P1**. +- Porch needs only 4 headings (REQUIRED_SPEC_SECTIONS, checks.ts); the 20-heading pressure is the + advisory spec-review consult type. Don't conflate. +- plan.md phases-JSON block is a **capability** (has_phases_json/min_two_phases) — survives untouched. +- `` tags are capability-inventory (M5) — preserve or retire explicitly. +- Rollback group **G4**; commits group-pure. + +### Phase 5 guard map (extracted from the tests, not assumed) — 2026-08-02 + +Four tests assert on the phase prompts. Rewrites must keep every literal below. + +**template-delivery.test.ts** (`#1279 WIRINGS`, both trees) — these include directives must survive verbatim: +- spir/specify, aspir/specify → `{{> protocols/spir/templates/spec.md}}` +- spir/plan, aspir/plan → `{{> protocols/spir/templates/plan.md}}` +- spir/review, aspir/review → `{{> protocols/spir/templates/review.md}}` +- pir prompts have **no** includes (not in WIRINGS) — served==raw confirms it. +- The *resolved* content assertions (## Problem Statement, SPEC vs PLAN BOUNDARY, ## Flaky Tests, + ### Methodology Improvements) come from the **templates** (Phases 6–7), not my prompt edits. + +**review-prompt-routing.test.ts** — reads **raw** (unexpanded) content of spir/aspir/**pir** review.md +(+ spir/templates/review.md, skeleton copies). Each raw file must literally contain: +`arch-critical.md`, `lessons-critical.md`, `## Architecture Updates`, `## Lessons Learned Updates`; +must **NOT** contain `add entries to lessons-learned.md`. + +**bugfix-685-close-keyword.test.ts** — targets spir/aspir **review.md** (not specify/plan/implement). +Each must contain: `` `Closes #`` or `` `Fixes #``; `` `Refs #`` or `` `Part of #``; `auto-close` (i). +PLUS a `--body "$(cat <<'EOF' … EOF"` heredoc that contains **no** `{{issue.` token. So the SPIR/ASPIR +review PR-body heredoc is **load-bearing shape** — keep the `gh pr create … --body "$(cat <<'EOF'` +form; it is a capability the guard pins, not a P2 example I may delete. It also byte-checks +skeleton==codev for the six edited prompts. + +**spec-1280-measurement-instrument.test.ts** — mine; measures, doesn't pin prompt prose. + +**P4 relocations confirmed** (builder.md, rewritten Phase 2, now owns these — so drop the repeats +from phase prompts): git add -A prohibition (builder.md:106), flaky tests (112–116), consult +handling (14), never-edit-status.yaml (16). pir/review is **not** in bugfix-685's set → no +close-keyword guard there (keeps Fixes/Refs anyway as correct behavior). + +**Touch calibration**: heavy rewrite on the four 1252-era SPIR files (specify/plan/implement/review); +lighter on the three PIR files — they were recently rewritten and are largely load-bearing contract +(single-pass max_iterations:1, gate-not-prose merge auth). Consolidate PIR's thrice-repeated +gate-not-prose rule (P4) and trim padding; preserve the mechanics. + +### Phase 5 implemented — commit 533ff99c (2026-08-02) + +All 11 phase prompts rewritten, both trees (22 files) + manifest. Group-pure G4. + +- **SPIR ×4** heavy rewrite: procedure→contract (P1), examples→interfaces (P2). spir/implement was + the biggest cut (served 1064→386): dropped PISC checklist, Trust-Hierarchy ASCII, Fixing-Mode + narration, and the flaky-tests block (builder.md owns it now — P4). spir/plan swapped the good/bad + phase-example lists for the phase-quality interface. spir/specify deleted the "Include examples" + line (literally anti-P2). +- **ASPIR ×4**: SPIR body verbatim + a real correctness fix — the ASPIR headers read "the SPIR + protocol" (0 "ASPIR" before). Same #619 mislabel class Phase 4 fixed in the ASPIR builder-prompt. + Flagged prominently in the manifest since it's content, not economy. +- **PIR ×3** light P4 touch: they were recently written and largely load-bearing contract + (single-pass max_iterations:1, gate-not-prose auth). Removed the git-add prohibition repeats + builder.md owns; consolidated pir/review's thrice-stated gate-not-prose rule to one back-reference. + Served barely moved (pir/review 2413→2380) — correct under the acceptance model. + +**Served deltas** (still carry unchanged template words for spir specify/plan/review — templates are +Phases 6–7): specify 1400→1063, plan 1167→946, review 1955→1228, spir/implement 1064→386. + +**Guards green** (verified against committed HEAD): T16 phase-manifest, bugfix-685 close-keyword, +review-prompt-routing, template-delivery, spec-1280 measurement/p6/deletion-guard. +`{{artifact_name}}` 51→57 (nothing deleted; all naming preserved). Skeleton==codev on all 11. + +**T16 gotcha, recorded**: the batch-cap check is asymmetric — a **single-batch** manifest is capped +at 12 **brace-EXPANDED** rows (so 11 brace-decisions = 22 → fails), but a manifest with explicit +`## Batch N` headings counts **raw rows per batch**. Fix was to declare two `## Batch` sections +(SPIR+ASPIR = 8, PIR = 3). Phase 4's precedent (9 brace-decisions in one Batch A) only worked because +it *had* a `## Batch A` heading. Don't write a braced manifest without explicit `## Batch` headings. + +Full suite running against 533ff99c; will report the exact numbers it executed. + +### Phase 5 — M10 hit: R2 proposed, suite left RED (commit 862508e4, 2026-08-02) + +Full packages/codev suite surfaced a real red in `baked-decisions.test.ts` (Spec 746 Phase 2) when +I rewrote `specify.md`. Two failure families, opposite treatments: + +1. **Behaviour grep (8 failures) — FIXED in-phase, not a retirement.** My first draft reworded the + Baked Decisions clause and dropped `do not autonomously` / `pause`. Restored the canonical + carveout literals (which are the preferred phrasing anyway). All 188 behaviour/mirror/pollution + assertions green. +2. **Pure-addition diff (2 failures) — R2, PROPOSED, NOT applied.** A P1/P2 rewrite that deletes + prose can't be a line-superset of the pre-746 baseline — identical wall to R1, which R1 + **explicitly foresaw and left in force** ("PHASE_2_FILES guards remain in force"). Per M10 I did + NOT re-baseline or edit the test. Left the 2 assertions RED, wrote R2 in + `codev/resources/1280-retirements.md` (full trace + behaviour-re-asserted mapping + replacement + design: extend `spec-1280-prompt-deletion-guard.test.ts` with post-1280 specify baselines + + inverted anti-vacuity), scoped to the 2 specify.md files only (air/implement.md untouched → its + Phase 2 guard stays in force). + +**Committed suite state (862508e4): 2 RED by design** (`codev SPIR/ASPIR specify.md pure-addition`), +308 other guard assertions green. This mirrors exactly how R1 was handled (report red, wait for +approval) — endorsed in Phase 4 as the system working. + +specify served recomputed after the wording restore: 1063→1077 (manifest updated). Reported R2 to +architect; **blocked on the R2 decision** before the phase can go fully green. On approval I execute +R2 in a separate commit (retire the 2 assertions + ship the replacement guard), like R1's 2-commit split. + +### Phase 5 — M11 inspection PASSED; holding for Waleed's R2 decision (2026-08-02) + +Architect completed M11: read the manifest + R2 in full, spot-checked rewritten specify.md +(canonical carveout wording, spec.md include intact), confirmed the ASPIR header fix in all 8 files +both trees, and independently reran baked-decisions + deletion-guard: **2 RED / 200 green, matching +my report**. R2 mirrors R1's approved grounds but retirement decisions on 1280 get a human call, so +it's with Waleed. + +**HOLD**: architect instruction — do not execute R2, do not advance the phase pointer, until the +R2 decision comes back. State frozen at 862508e4 (2 pure-addition assertions RED by design). +Blocked on a human decision; nothing further to do until then. + +### R2 APPROVED by Waleed and executed — two-commit split (2026-08-04) + +Waleed approved R2 (human call, relayed by architect). Executed mirroring R1's split: + +- **5149ad11 — the retirement.** Recorded the approval in 1280-retirements.md (checkbox + grounds); + retired the 2 SPIR/ASPIR specify.md pure-addition assertions in baked-decisions.test.ts via a + `RETIRED_UNDER_R2` set. **Verified air/implement.md's Phase 2 guard still RUNS and passes** + (verbose reporter named it) — retirement is scoped, not vacuous. 190→188 tests (exactly 2 removed). +- **265b4b65 — the replacement.** Captured post-1280 baselines + (fixtures/spec-1280-baselines/{spir,aspir}-specify.md.baseline) and extended + spec-1280-prompt-deletion-guard.test.ts with a GUARDED_SPECIFY block. Anti-vacuity uses the + literal `Baked Decisions` (specify carries it as a bullet, not a `## Baked Decisions` heading). + **Mutation-verified both ways**: deleting a specify line fires the deletion check; stripping + `Baked Decisions` from the baseline fires anti-vacuity. 20/20 green restored. + +Full packages/codev suite running against 265b4b65 to confirm fully green, then continue to Phase 6. + +### Phase 5 COMPLETE — fully green, pointer advanced to Phase 6 (2026-08-04) + +Full packages/codev suite against 265b4b65: **207 files passed / 3 skipped, 4132 tests passed / +48 skipped, EXIT 0.** R2 executed cleanly; no reds. Architect M11 already signed off Phase 5. +Advanced status.yaml pointer: phase_5 → complete, phase_6 → in_progress (architect instruction +"continue to phase 6"; Waleed's standing permission to set the pointer to the right phase). + +**Phase 6 scope** (G4, 10 decisions): bugfix ×3, air ×2, maintain ×2 phase prompts + spir +templates spec.md / plan.md / review.md ×3. Key constraints from the plan: +- Lighter protocols are already closer to conformant (means 356–457w) — **a conformant file passes + unchanged**. +- **plan.md's phases-JSON block is a CAPABILITY** (has_phases_json / min_two_phases) — survives P2. +- Editing spir templates touches the `{{> }}` include TARGETS (template-delivery resolved-content + assertions: ## Problem Statement, SPEC vs PLAN BOUNDARY, ## Flaky Tests, ### Methodology + Improvements must survive). Re-check bugfix-685 heredoc + review-prompt-routing for the review + template. + +### Phase 6 plan (2026-08-04) — 10 decisions, both trees, G4 + +All 10 targets byte-identical across trees (brace notation valid). Baselines (served=raw for +prompts; templates have no includes): +bugfix fix 352 / investigate 290 / pr 491 · air implement 442 / pr 471 · maintain maintain 402 / +review 310 · spir templates spec 632 / plan 649 / review 641. + +**Guard map (Phase 6):** +- **bugfix-685 close-keyword**: bugfix/pr, air/pr, maintain/review — each needs `Closes #`|`Fixes #`, + `Refs #`|`Part of #`, `auto-close`, and a `--body "$(cat <<'DELIM' … DELIM"` heredoc with no + `{{issue.` inside. These heredocs are load-bearing shape — keep them. +- **CMAP dispatch is a capability**: bugfix/pr + air/pr run `consult -m … --protocol … --type pr` + THEMSELVES (unlike SPIR where porch consults). Preserve the dispatch blocks + the wait/verdict flow. +- **spir/templates/spec.md** (template-delivery resolved): keep `## Problem Statement`, + `## Solution Approaches`, `SPEC vs PLAN BOUNDARY`. +- **spir/templates/plan.md**: the `## Phases (Machine Readable)` JSON block is a CAPABILITY + (has_phases_json / min_two_phases) — keep it with ≥2 phases. +- **spir/templates/review.md**: review-prompt-routing (raw) needs `arch-critical.md`, + `lessons-critical.md`, `## Architecture Updates`, `## Lessons Learned Updates`, no + `add entries to lessons-learned.md`; template-delivery resolved also needs `## Flaky Tests` + + `### Methodology Improvements`. + +**R3 anticipated — air/implement.md.** It carries the baked-decisions clause and is under Spec 746's +PHASE_2 pure-addition guard, STILL IN FORCE (R1 foresaw it; R2 retired only specify). ANY deletion +from it — even the P4 git-add cleanup — trips pure-addition. A real P1 rewrite deletes the Process +prose, so rewriting air/implement = R3, identical shape to R2. Plan: rewrite it (keep baked-decisions +canonical literals so the grep stays green), propose R3 in 1280-retirements.md, leave the 1 +pure-addition assertion RED, report for the human decision — same endorsed pattern as R2. The other +9 files go green. Will flag to Waleed/architect whether to keep approving these one-by-one or +pre-approve the foreseen class. + +### Phase 6 implemented — commit 19b14242, R3 proposed, suite left RED (1) (2026-08-04) + +10 decisions, both trees. 9 files rewritten + maintain/review.md kept (inspected conformant). +- **bugfix ×3, air ×2**: P1 contract; kept close-keyword heredocs (bugfix/pr, air/pr) + the + BUGFIX/AIR **CMAP self-dispatch** (these protocols run consult themselves). air/implement kept the + Baked Decisions clause in canonical wording. +- **maintain ×2**: maintain.md P4 git-add drop only (command runbook, mostly capability); review.md + unchanged (conformant). +- **spir templates ×3** (P2, big cuts): spec 632→246 (kept porch-required + delivery headings + + SPEC vs PLAN BOUNDARY), plan 649→201 (kept phases-JSON capability, ≥2 phases), review 641→293 + (kept routing + Flaky Tests + Methodology Improvements). + +**R3** — air/implement.md rewrite trips Spec 746 Phase 2 pure-addition (3rd/last PHASE_2 file, foreseen +by R1). Proposed in 1280-retirements.md, mirror of R2, **left RED (1 assertion)**, awaiting human +decision. Also asked the human whether to **pre-approve the class** (Phases 7–9 will produce the same +for each PHASE_3 consult-type file). All other guards green (bugfix-685, template-delivery, +review-prompt-routing, baked-decisions grep/mirror, measurement, deletion-guard). T16 green. + +Full packages/codev suite running against 19b14242 (expect 1 red = R3). Then report + await R3 decision. + +### Phase 6 — #335 guard caught + fixed; clean R3-pending state (HEAD 56f5dfd1) + +Full suite first showed 3 red, not 1: besides R3, my bugfix/pr.md rewrite dropped two phrases the +**#335 regression guard** pins verbatim ("ALL THREE consultations have returned results", +"DO NOT send this notification until you have all three CMAP verdicts"). That guard exists because +bugfix builders once notified the architect before CMAP returned — so those ALL-CAPS strings are +load-bearing behavior, not P7 padding. Restored them (conformance, not an M10 retirement), like the +baked-decisions canonical wording. bugfix/pr 391→402; manifest updated; amended into the phase commit. + +Lesson (again): grep the test suite for per-file guards on EVERY file I rewrite, not just the ones I +remember. #335 wasn't in my Phase 6 guard map because I built the map from the tests I'd already read +in Phase 5; a fresh file (bugfix/pr) had its own guard I didn't re-scan for. + +**Clean state now: 1 RED = R3** (air/implement pure-addition, by design), 4131 passed / 48 skipped, +EXIT 1. Reporting to architect; holding for the R3 (or class-preapproval) decision. + +### R3 executed + CLASS PRE-APPROVED; Phase 6 COMPLETE, pointer → Phase 7 (2026-08-06) + +Waleed approved R3 and **pre-approved the retirement class** for the PHASE_3 files (phases 7–9), on +3 binding invariants (now conditions, not conventions): (1) behaviour grep green with canonical +wording, (2) replacement guard in the mirrored separate commit, (3) full register writeup + phase +manifest row for each. Architect verifies at M11; violating any invariant voids the class approval +for that item. Recorded as a "Class pre-approval" box in 1280-retirements.md. + +R3 executed as R1/R2's split: +- **412a11d4 — retirement.** Approval + class box in 1280-retirements.md; air/implement.md added to + RETIRED_UNDER_R3. All PHASE_2 pure-addition guards now retired → the loop got a documenting test so + it doesn't error as an empty suite and re-activates if a future PHASE_2 file is added. PHASE_3 + pure-addition assertions verified STILL RUNNING (verbose reporter). +- **4b7a9496 — replacement.** air-implement.md.baseline + deletion-guard block; mutation-verified + both ways. + +Full packages/codev suite at 4b7a9496: **4136 passed / 48 skipped, EXIT 0.** Phase 6 complete. +Architect M11 inspection underway ("flag nothing-blocking unless you hear otherwise") + "continue" → +advanced pointer phase_6 complete, phase_7 in_progress. + +**Phase 7 next** (G4 templates + G5 consult-types, ~10 decisions + bugfix-742 test): +experiment/maintain/spike templates + 2 codev-local maintain templates (no skeleton twin) + spir +consult-types ×5. Two commits, one per group. Guards: bugfix-742-consult-templates pins prose in +spir/consult-types/{pr,impl}-review.md (breaks here — handle); the spir consult-types are PHASE_3 +baked-decisions files → rewriting them triggers the now class-approved retirements (R4+), each still +needing its own register writeup + manifest row + replacement guard. + +### Phase 7 COMPLETE + R4 + R5; pointer → Phase 8 (2026-08-06) + +10 decisions (5 templates G4, 5 spir consult-types G5), 4 commits + R5 removal. +- **G4 templates** (4a2aafe5): notes/findings/maintenance-run/audit-report P2; lessons-learned kept. + Preserved maintenance-run delivery headings; audit-report + lessons-learned codev-local. +- **G5 consult-types** (2479f1f5): 5 spir consult-types P1/P2. Kept VERDICT capability exactly + (+ pr-review PR_SUMMARY), SPIR-specific Spec-Adherence/Scoping (#742 divergence), Baked Decisions + sections. **P6 fix: spec-review's stale 20-heading list** (broken by Phase 6's spec.md rewrite) + → reference the delivered template. +- **R4** (retirement f96419c2 + replacement 86140f46): spir spec/plan-review pure-addition retired + under the class pre-approval; other 4 PHASE_3 files still in force; mutation-verified. +- **R5** (cead8633): **removed the repo-wide manifest-completeness scan (T16)** per Waleed's ruling — + it taxed concurrent PRs (caught Mohid's #1330; Spec 1307 earlier). Kept the manifests, M11 + inspection contract, and manifest FORMAT checks (four-fields, batch-cap). Full writeup R5. + +Full suite at cead8633: **4141 passed / 48 skipped, EXIT 0.** Pointer advanced phase_7 complete, +phase_8 in_progress. + +**Phase 8 next** (G5, consult-types: aspir, bugfix, air): aspir spec/plan/impl/pr(+phase?)-review, +bugfix impl/pr-review, air impl/pr-review. aspir spec/plan-review + air impl/pr-review are PHASE_3 +baked-decisions files → class-approved retirements (R6…). bugfix impl/pr-review guarded by #742 (must +differ from SPIR — I just rewrote SPIR's, so re-verify divergence). Preserve VERDICT everywhere. + +### Phase 9 COMPLETE; pointer → Phase 10 (2026-08-06) + +Three group-pure commits + manifest. Suite green at 0a79f413: 4184 passed / 48 skipped. +- **G5 (batch A)** 144feec1: pir + maintain consult-types. maintain mirror new spir; pir kept + PIR-specific (dev-approval, single-pass). Not baked-decisions → no retirement. +- **G7** f652abf7: rebuilt scar-rules.yaml (8 canonicals byte-identical, must_appear_on re-derived + against post-1280 surface — many shrank as P4 removed git-add from prompts; all 8 on CLAUDE+AGENTS) + + T4 (spec-1280-scar-rules.test.ts), mutation-verified reword+delete. +- **G4** b63bbcb3: deleted the dead codev-skeleton/porch/prompts/ (10 files, M6-verified no runtime + consumer) + updated review-prompt-routing.test.ts (Spec 987). + +**Phase 10 (final, verification-only)**: M5 capability inventory vs Phase-0 frozen baseline; measurement +re-run (before/after, deleted-vs-relocated, M0c/M1/M2); T9 live spawn probe; T10 rollback rehearsal for +every group G1-G7; governance docs routed by tier (incl. the "trust the authoritative source not the +convenient signal" lesson). Then PR + review. + +### Phase 10 COMPLETE — PR #1362 open, at the human pr gate (2026-08-06) + +Verification-only phase. HEAD 910f00b2, suite green (4184 pass / 48 skip). +- **Measurement report** (1280-measurement-report.md): always-on builder 34231→18233 (−47%), + architect −66%, total authored 153205→106032 (−31%). M0c relocation proven (skills grew +4516w). +- **M5** verified: no capability present in the frozen Phase-0 inventory is absent post-rewrite. +- **Governance**: routed "trust the authoritative source not the convenient signal" to cold + lessons-learned.md (hot already has the principle); arch-critical.md unchanged (no module-boundary + change). +- **T10 group purity** verified structurally (rewrite commits .md-only; retirements register+test; + guards baseline+test). **T9 (spawn probe) + full T10 (rollback rehearsal) DEFERRED to integration** + — both require the main workspace root / destructive git, which a builder worktree cannot do + safely. Flagged in the review + PR. +- **Review** written (codev/reviews/1280-...md) with ## Architecture Updates + ## Lessons Learned + Updates for the porch checks. **PR #1362** created, Closes #1280. + +All ten implement phases done, suite green. Project is at the **pr gate (human approval)** — the one +step a builder cannot self-serve. Notified architect. Nothing further to do autonomously until the +human reviews/merges. + +### Integration review addressed — four fixes, PR #1362 (2026-08-06) + +Architect posted integration review (2-way CMAP codex RC / claude COMMENT), ruled T9/T10 deferral +acceptable. Four pre-merge fixes applied (commit f81d4720), suite green (4184 pass / 48 skip): +1. spir/aspir review.md merge-ownership → "merge after human pr-gate approval" (was "architect integrates"). +2. builder.md gate clause → defers to protocol prompts on who types porch approve (PIR = human). +3. research protocol.md → prose defers to embedded state machine (models=[codex]); states reduced reality. +4. CLAUDE.md/AGENTS.md → dropped team+forge skill names (#1318 drift). CLAUDE==AGENTS preserved. +Recorded in the review's Consultation Feedback. Non-blocking follow-ups noted by architect +(release/protocol.md staleness, maintain/templates two-tree divergence). Back to Waleed for the merge word. + +### pr gate APPROVED by Waleed; merge HELD on CI (Actions outage) (2026-08-06) + +Ran `porch approve 1280 pr --a-human-explicitly-approved-this` — gate approved (porch reran +build+tests green). NOT merged: `gh pr checks 1362` reports "no checks reported" and +mergeStateStatus=UNKNOWN. Confirmed CI is EXPECTED (recent merged PRs #1358/#1355/#1353 all ran +CLI Integration Tests + CLI Tests macos/ubuntu, all pass) — so absence = the GitHub Actions outage +the architect flagged, not a no-CI repo. Applying 1286 discipline: no checks reporting ≠ green; +never force past a non-green gate. Holding merge until all expected checks REPORT and pass. + +### Merge conflict with main resolved (2026-08-06) + +During the pr-gate CI-outage wait, main advanced 264 files (many merged PRs); PR went DIRTY. +Conflict scoped to CLAUDE.md + AGENTS.md only — main's edits were build-details in the verbose +sections 1280 deleted (P3/P4 relocation to the codev skill), so resolved by taking the 1280 rewrite +for both. Verified: CLAUDE==AGENTS byte-identical, all 8 scar canonicals present, fix-4 team/forge +drop survived. Merge commit 9593d551. main added packages/{sdk,core,types} → needed `pnpm install +--force` (18m) to link them; then build OK. Full suite green post-merge: 4549 passed / 48 skipped +(main added tests). Pushing; CI will re-trigger on the updated branch. + +### Outage lifted → CI triggered + GREEN; merge now blocked on a required GitHub review (2026-08-06) + +The Actions outage lasted ~3.5h. It never triggered CI on my outage-time push, so passive waiting +was futile (waiting on a producer that didn't exist). Once Actions recovered (other PRs getting +CI again), I close/reopened PR #1362 to fire the missed `pull_request` workflows — an INITIAL run +for commits that never got CI, not a re-run to launder a false green. + +**CI GREEN — all 6 checks reporting + passing** (per 1286 discipline): CLI Integration Tests, CLI +Tests macos + ubuntu, Package Install Verification, Tower Integration Tests, Unit Tests. + +**But merge is still BLOCKED**: `reviewDecision=REVIEW_REQUIRED`, reviews=[]. Branch protection +requires a formal approving GitHub review; the architect's integration review was a comment/afx +message, not a `gh pr review --approve`. I can't self-approve (GitHub blocks author self-approval) +and won't `--admin` past a required gate. Needs the architect (or a reviewer) to submit an approving +GitHub review, then I merge with `gh pr merge 1362 --merge`. + +### FINAL: branch done + green; merge is a policy wall for Waleed (2026-08-06) + +Architect clarified the required-review block is STRUCTURALLY UNSATISFIABLE: the gh seat is +authenticated as waleedkadous — the same account that authored my commits — and GitHub refuses +self-approval. Every builder PR here is self-authored, so branch protection's required-review rule +can't be met without a second account or an owner --admin merge (the same wall #1345 sits at). The +policy call (admin-merge vs adjusting branch protection) is with Waleed. + +Instruction: hold as-is, no further action from me; was right not to reach for --admin. + +**Final builder-side state — everything done and green:** +- All 10 SPIR phases complete; six retirements (R1–R6) executed with approval + mutation-verified + replacement guards; scar registry rebuilt + T4; dead tree removed. +- Four integration-review fixes applied (merge-ownership, gate-scoping, RESEARCH json/md, team/forge drop). +- Conflict with main resolved (CLAUDE/AGENTS), post-merge suite green: 4549 passed / 48 skipped. +- pr gate approved (porch). CI fully green: all 6 required checks passing. +- Merge blocked ONLY by the self-approval branch-protection policy — Waleed's decision. Standing by. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-builder-prompt.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-builder-prompt.md.baseline new file mode 100644 index 000000000..d2da0d02e --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-builder-prompt.md.baseline @@ -0,0 +1,62 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are implementing {{input_description}}. + +{{#if mode_soft}} +## Mode: SOFT + +You follow the protocol yourself; the architect verifies compliance. +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. +{{/if}} + +## Protocol + +The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. + +## Baked Decisions + +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. + +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. + +{{#if issue}} +## Issue #{{issue.number}} +**Title**: {{issue.title}} + +**Description**: +{{issue.body}} +{{/if}} + +## Your Mission + +1. Implement the feature from the issue (<300 LOC) +2. Write tests for it +3. Open a PR with the review **in the PR body**, not as a separate file +4. Notify: `afx send architect "PR #N ready for review (implements #{{issue.number}})"` + +**AIR produces no spec, plan, or review files.** That is the whole economy of the protocol. + +If the feature turns out larger than AIR fits (>300 LOC, or an architectural decision the issue +does not make), stop and say so rather than growing it quietly: + +```bash +afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR." +``` + +## Notifications + +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-impl-review.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-impl-review.md.baseline new file mode 100644 index 000000000..16abb9863 --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-impl-review.md.baseline @@ -0,0 +1,47 @@ +# Implementation Review Prompt + +## Context + +You are reviewing implementation work built under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec or plan document. Verify it matches the issue and follows good practice; review against the issue, not against artifacts AIR does not produce. + +## Verify before flagging + +Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data: + +- Check `package.json` for the actual dependency versions — framework conventions change between major versions. +- Read the actual config files (or confirm their deliberate absence) before flagging a missing config. + +## Baked Decisions + +If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the implementation **fails to honor** a stated baked decision — that is a real defect. + +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. + +## Focus Areas + +- **Issue Adherence** — the implementation fulfills the issue's requirements and acceptance criteria. +- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled. +- **Test Coverage** — tests are adequate and cover main paths and edge cases. +- **Scope** — the change stays focused on the issue and under ~300 LOC; if larger, it should escalate to ASPIR. + +## Verdict Format + +Provide your verdict in exactly this format — `consult` parses it: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +- `APPROVE`: implementation looks good, ready for PR. +- `REQUEST_CHANGES`: issues that must be fixed. +- `COMMENT`: minor suggestions; can proceed but note the feedback. + +AIR has no spec or plan — review against the GitHub issue, and judge "does this feature work correctly", not "is this architecturally perfect". diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-implement.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-implement.md.baseline new file mode 100644 index 000000000..d8cfaaebb --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-implement.md.baseline @@ -0,0 +1,42 @@ +# IMPLEMENT Phase Prompt + +You are executing the **IMPLEMENT** phase of the AIR protocol. + +## Goal + +Implement the feature described in the issue, with tests, as a focused change under ~300 LOC. AIR produces no `codev/specs/` or `codev/plans/` artifacts. + +## Baked Decisions + +Check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, treat each listed decision as fixed during implementation. Do not autonomously substitute alternate languages, frameworks, or dependencies. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than working around it. + +If two baked decisions contradict each other, do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before implementing. + +## Context + +- **Issue**: #{{issue.number}} — {{issue.title}} +- **Current State**: {{current_state}} + +## What must be true when you finish + +- **The feature matches the issue.** You have read it fully — desired behavior, acceptance criteria, any examples — and implemented exactly what it describes: no refactoring of surrounding code, no features beyond the issue, no unrelated bug fixes (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions. +- **Tests exist.** They cover the happy path and the key edge cases, and are deterministic. (Purely declarative changes — config only — may not need them; say so.) +- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling. +- **The change stays within AIR scope.** If it grows past ~300 LOC or turns architectural, signal `TOO_COMPLEX` rather than pressing on. + +Commit with an explicit staged path and the message `[Air #{{issue.number}}] feat: `. + +## Signals + +- Implementation and tests complete and passing: + ``` + PHASE_COMPLETE + ``` +- Too complex for AIR (> ~300 LOC or architectural): + ``` + TOO_COMPLEX + ``` +- Blocked (missing context, unclear requirements): + ``` + BLOCKED:reason goes here + ``` diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-pr-review.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-pr-review.md.baseline new file mode 100644 index 000000000..dd8de96ad --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/air-pr-review.md.baseline @@ -0,0 +1,45 @@ +# PR Ready Review Prompt + +## Context + +You are reviewing a pull request created under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec, plan, or review file. The review is embedded in the PR body. + +## Baked Decisions + +If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the code **fails to honor** a stated baked decision — that is a real defect. + +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. + +## Focus Areas + +- **Completeness** — the issue's requirements are implemented and the PR body's review section (summary, key decisions, test plan) is filled out. +- **Test Status** — all tests pass, coverage is adequate, and any skipped/flaky tests are accounted for. +- **Code Cleanliness** — no debug code, no stray `TODO`, code properly formatted. +- **Scope** — the change stays under ~300 LOC and focused on the issue, with no unrelated changes bundled in. +- **PR Quality** — the PR links to the issue, the body's review section is informative, and the branch is up to date with its base (the integration branch the PR targets). + +## Scope + +Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself. + +## Verdict Format + +Provide your verdict in exactly this format — `consult` parses it: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +- `APPROVE`: ready for architect review. +- `REQUEST_CHANGES`: issues to fix before review. +- `COMMENT`: minor items; can proceed but note the feedback. + +AIR has no spec, plan, or review files — review the PR body and the code diff. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-builder-prompt.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-builder-prompt.md.baseline new file mode 100644 index 000000000..e43e55121 --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-builder-prompt.md.baseline @@ -0,0 +1,81 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are implementing {{input_description}}. + +{{#if mode_soft}} +## Mode: SOFT + +You follow the protocol yourself; the architect verifies compliance. +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never +hand-edit `status.yaml` — only porch commands modify project state. +{{/if}} + +## Protocol + +Follow the ASPIR protocol. The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. + +## Baked Decisions + +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. + +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. + +{{#if spec}} +## Spec +Read the specification at: `{{spec.path}}` +{{/if}} + +{{#if plan}} +## Plan +Follow the implementation plan at: `{{plan.path}}` +{{/if}} + +{{#if issue}} +## Issue #{{issue.number}} +**Title**: {{issue.title}} + +**Description**: +{{issue.body}} +{{/if}} + +## PR Strategy + +**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits +within a single PR, not as separate PRs. The plan's instruction that "each phase commits +independently" refers to git commits, not PRs. + +By default, the PR is opened during/after the final implement phase, with all phase-commits +already on the branch. + +The architect MAY request a PR at any point — follow that direction when they do; the +prohibition is on *you* deciding to open per-phase PRs unasked. + +Record them: `porch done {{project_id}} --pr --branch `, and +`porch done {{project_id}} --merged `. + +## Verify Phase + +After the final PR merges the project enters **verify**, and you stay alive through it: + +1. Pull the integration branch into your worktree +2. Run `porch done {{project_id}}` to signal verification is ready +3. The architect approves `verify-approval` when satisfied + +If verification is not needed: `porch verify {{project_id}} --skip "reason"` + +## Notifications + +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-plan-review.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-plan-review.md.baseline new file mode 100644 index 000000000..b278aa4ea --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-plan-review.md.baseline @@ -0,0 +1,41 @@ +# Plan Review Prompt + +## Context + +You are reviewing an implementation plan during the Plan phase. The spec is already approved; judge whether the plan adequately describes HOW to implement it. + +## Baked Decisions + +If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. + +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. + +## Focus Areas + +- **Spec coverage** — every spec requirement is addressed by some phase; nothing goes beyond the spec's scope. +- **Phase breakdown** — phases are appropriately sized, logically sequenced (dependencies respected), and each can be completed and committed independently. +- **Technical approach** — the approach is sound, the right files/modules are targeted, and no obviously better approach is being missed. +- **Testability** — each phase has clear test criteria and the spec's edge cases are addressable. +- **Risk** — blockers and cross-system dependencies are identified; the plan is realistic given the constraints. + +The spec is already approved — do not re-litigate spec decisions. Judge the plan as a guide a builder can follow successfully; verify referenced file paths look accurate. + +## Verdict Format + +Provide your verdict in exactly this format — `consult` parses it: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +- `APPROVE`: plan is ready for human review. +- `REQUEST_CHANGES`: significant issues with approach or coverage. +- `COMMENT`: minor suggestions; the plan is workable but could improve. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-spec-review.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-spec-review.md.baseline new file mode 100644 index 000000000..48f0c495b --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-spec-review.md.baseline @@ -0,0 +1,41 @@ +# Specification Review Prompt + +## Context + +You are reviewing a feature specification during the Specify phase, before it goes to human approval. Judge whether the spec is complete, correct, feasible, and clear enough for a builder to plan from. + +## Baked Decisions + +If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect. + +If the baked decisions themselves contradict each other (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. + +## Focus Areas + +- **Completeness** — requirements, success criteria, and edge cases are stated; scope is bounded, not vague. +- **Correctness** — the requirements are technically sound and internally consistent; the problem statement is accurate. +- **Feasibility** — implementable within the stated tools and constraints, with no obvious blockers. +- **Clarity** — a builder would know what to build; acceptance criteria are testable; terminology is consistent. +- **Structure** — the spec follows the delivered template (`protocols/spir/templates/spec.md`), which the specify prompt inlines. A spec that ignores the template's headings — usually because the builder pattern-matched an older spec in `codev/specs/` — is a defect: `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). A single genuinely-inapplicable section reduced to a one-line "N/A — [reason]" with its heading kept is fine, not grounds for `REQUEST_CHANGES`. + +You are reviewing the specification (WHAT is built), not code or implementation (HOW) — that is the plan and implementation reviews. Be constructive: name the issue and suggest a fix. + +## Verdict Format + +Provide your verdict in exactly this format — `consult` parses it: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +- `APPROVE`: spec is ready for human review. +- `REQUEST_CHANGES`: significant issues must be fixed first. +- `COMMENT`: minor suggestions; can proceed but consider the feedback. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-specify.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-specify.md.baseline new file mode 100644 index 000000000..978b1e0a1 --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/aspir-specify.md.baseline @@ -0,0 +1,59 @@ +# SPECIFY Phase Prompt + +You are executing the **SPECIFY** phase of the ASPIR protocol. + +## Goal + +Produce a specification at `codev/specs/{{artifact_name}}.md` that explores the problem space and the proposed solution well enough that the plan and implementation can follow without re-deciding anything. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Spec File**: `codev/specs/{{artifact_name}}.md` + +## What must be true when you finish + +- **An existing spec is honored, not rewritten.** If `codev/specs/{{project_id}}-*.md` already exists, it carries the architect's decisions — read it fully and refine it in place. Clarifying questions are for the case where no spec exists yet; when one does, the spec is the answer. +- **Baked Decisions are fixed.** If the issue body has a "Baked Decisions" section (any heading level, case-insensitive), copy it verbatim into the spec's Constraints and treat each item as settled — **do not autonomously override** the architect's choices in Solution Exploration. Raise a genuine problem with a baked decision via `afx send architect` rather than overriding it. If two baked decisions contradict each other, do not choose — **pause**, **flag** the contradiction via `afx send`, and wait for resolution. +- **The problem is characterized before solutions are.** Current state vs desired state, stakeholders, assumptions, and constraints are explicit. +- **Solutions are explored, not assumed.** More than one approach is considered, each with its trade-offs and risks, before one is recommended. +- **Open questions are surfaced and ranked** by whether they block progress, shape the design, or are merely nice to know. +- **Success is measurable.** Acceptance criteria are concrete enough to test against. + +## Output + +Write the spec to `codev/specs/{{artifact_name}}.md` using the template below as its interface — these headings, in this order. A section that genuinely does not apply keeps its heading with a one-line `N/A — [reason]` rather than being deleted. Do not pattern-match an older spec in `codev/specs/` that predates this template. + +{{> protocols/spir/templates/spec.md}} + +Keep the three artifact filenames in sync: spec `codev/specs/{{artifact_name}}.md`, plan `codev/plans/{{artifact_name}}.md`, review `codev/reviews/{{artifact_name}}.md`. + +## Signals + +- Waiting on clarifying-question answers — **put the questions inside the signal**, which is displayed prominently to the user: + ``` + + Please answer: + 1. ... + 2. ... + + ``` +- Initial draft done: + ``` + SPEC_DRAFTED + ``` + +## Commit cadence + +Commit at each milestone, staging the spec file explicitly: +```bash +git add codev/specs/{{artifact_name}}.md +``` +1. `[Spec {{project_id}}] Initial specification draft` +2. `[Spec {{project_id}}] Specification with multi-agent review` +3. `[Spec {{project_id}}] Specification with user feedback` +4. `[Spec {{project_id}}] Final approved specification` + +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Specify phase: no implementation detail (that is the plan), no code, no time estimates. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-builder-prompt.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-builder-prompt.md.baseline new file mode 100644 index 000000000..1f885ca49 --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-builder-prompt.md.baseline @@ -0,0 +1,90 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are implementing {{input_description}}. + +{{#if mode_soft}} +## Mode: SOFT + +You follow the protocol yourself; the architect verifies compliance. Run consultations where the +protocol calls for them. +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT + +Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Do not +hand-run consultations porch would run, advance plan phases yourself, or skip the 3-way review. + +Never hand-edit `status.yaml` — only porch commands modify project state. +{{/if}} + +## Protocol + +Follow the SPIR protocol. The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not +need to fetch it. + +## Baked Decisions + +If the issue body contains a section named "Baked Decisions" (any heading level, +case-insensitive), treat its contents as fixed architectural decisions baked in by the +architect. Do not autonomously override them in your spec, plan, or implementation. If you +discover a serious reason to question a baked decision, surface that concern to the architect +via `afx send` rather than relitigating it inside the spec/plan/review. + +If the architect's baked-decisions section contains internal contradictions (e.g., two different +language choices), do not pick one — pause, flag the contradiction to the architect via +`afx send`, and wait for resolution before proceeding. + +{{#if spec}} +## Spec +Read the specification at: `{{spec.path}}` +{{/if}} + +{{#if plan}} +## Plan +Follow the implementation plan at: `{{plan.path}}` +{{/if}} + +{{#if issue}} +## Issue #{{issue.number}} +**Title**: {{issue.title}} + +**Description**: +{{issue.body}} +{{/if}} + +{{#if task}} +## Task +{{task_text}} +{{/if}} + +## PR Strategy + +**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits +within a single PR, not as separate PRs. The plan's instruction that "each phase commits +independently" refers to git commits, not PRs. + +By default, the PR is opened during/after the final implement phase, with all phase-commits +already on the branch. + +The architect MAY request a PR at any point — for spec review, mid-implementation feedback, or +slicing a large spec into shippable pieces. Follow that direction when they do; the prohibition +is on *you* deciding to open per-phase PRs unasked. + +Record them: `porch done {{project_id}} --pr --branch `, and +`porch done {{project_id}} --merged `. + +## Verify Phase + +After the final PR merges the project enters **verify**, and you stay alive through it: + +1. Pull the integration branch into your worktree +2. Run `porch done {{project_id}}` to signal verification is ready +3. The architect approves `verify-approval` when satisfied + +If verification is not needed: `porch verify {{project_id}} --skip "reason"` + +## Notifications + +The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR +merged, blocked. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-plan-review.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-plan-review.md.baseline new file mode 100644 index 000000000..b278aa4ea --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-plan-review.md.baseline @@ -0,0 +1,41 @@ +# Plan Review Prompt + +## Context + +You are reviewing an implementation plan during the Plan phase. The spec is already approved; judge whether the plan adequately describes HOW to implement it. + +## Baked Decisions + +If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect. + +If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. + +## Focus Areas + +- **Spec coverage** — every spec requirement is addressed by some phase; nothing goes beyond the spec's scope. +- **Phase breakdown** — phases are appropriately sized, logically sequenced (dependencies respected), and each can be completed and committed independently. +- **Technical approach** — the approach is sound, the right files/modules are targeted, and no obviously better approach is being missed. +- **Testability** — each phase has clear test criteria and the spec's edge cases are addressable. +- **Risk** — blockers and cross-system dependencies are identified; the plan is realistic given the constraints. + +The spec is already approved — do not re-litigate spec decisions. Judge the plan as a guide a builder can follow successfully; verify referenced file paths look accurate. + +## Verdict Format + +Provide your verdict in exactly this format — `consult` parses it: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +- `APPROVE`: plan is ready for human review. +- `REQUEST_CHANGES`: significant issues with approach or coverage. +- `COMMENT`: minor suggestions; the plan is workable but could improve. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-spec-review.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-spec-review.md.baseline new file mode 100644 index 000000000..48f0c495b --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-spec-review.md.baseline @@ -0,0 +1,41 @@ +# Specification Review Prompt + +## Context + +You are reviewing a feature specification during the Specify phase, before it goes to human approval. Judge whether the spec is complete, correct, feasible, and clear enough for a builder to plan from. + +## Baked Decisions + +If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect. + +If the baked decisions themselves contradict each other (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding. + +## Focus Areas + +- **Completeness** — requirements, success criteria, and edge cases are stated; scope is bounded, not vague. +- **Correctness** — the requirements are technically sound and internally consistent; the problem statement is accurate. +- **Feasibility** — implementable within the stated tools and constraints, with no obvious blockers. +- **Clarity** — a builder would know what to build; acceptance criteria are testable; terminology is consistent. +- **Structure** — the spec follows the delivered template (`protocols/spir/templates/spec.md`), which the specify prompt inlines. A spec that ignores the template's headings — usually because the builder pattern-matched an older spec in `codev/specs/` — is a defect: `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). A single genuinely-inapplicable section reduced to a one-line "N/A — [reason]" with its heading kept is fine, not grounds for `REQUEST_CHANGES`. + +You are reviewing the specification (WHAT is built), not code or implementation (HOW) — that is the plan and implementation reviews. Be constructive: name the issue and suggest a fix. + +## Verdict Format + +Provide your verdict in exactly this format — `consult` parses it: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +- `APPROVE`: spec is ready for human review. +- `REQUEST_CHANGES`: significant issues must be fixed first. +- `COMMENT`: minor suggestions; can proceed but consider the feedback. diff --git a/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-specify.md.baseline b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-specify.md.baseline new file mode 100644 index 000000000..3c5af5a81 --- /dev/null +++ b/packages/codev/src/__tests__/fixtures/spec-1280-baselines/spir-specify.md.baseline @@ -0,0 +1,59 @@ +# SPECIFY Phase Prompt + +You are executing the **SPECIFY** phase of the SPIR protocol. + +## Goal + +Produce a specification at `codev/specs/{{artifact_name}}.md` that explores the problem space and the proposed solution well enough that the plan and implementation can follow without re-deciding anything. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Spec File**: `codev/specs/{{artifact_name}}.md` + +## What must be true when you finish + +- **An existing spec is honored, not rewritten.** If `codev/specs/{{project_id}}-*.md` already exists, it carries the architect's decisions — read it fully and refine it in place. Clarifying questions are for the case where no spec exists yet; when one does, the spec is the answer. +- **Baked Decisions are fixed.** If the issue body has a "Baked Decisions" section (any heading level, case-insensitive), copy it verbatim into the spec's Constraints and treat each item as settled — **do not autonomously override** the architect's choices in Solution Exploration. Raise a genuine problem with a baked decision via `afx send architect` rather than overriding it. If two baked decisions contradict each other, do not choose — **pause**, **flag** the contradiction via `afx send`, and wait for resolution. +- **The problem is characterized before solutions are.** Current state vs desired state, stakeholders, assumptions, and constraints are explicit. +- **Solutions are explored, not assumed.** More than one approach is considered, each with its trade-offs and risks, before one is recommended. +- **Open questions are surfaced and ranked** by whether they block progress, shape the design, or are merely nice to know. +- **Success is measurable.** Acceptance criteria are concrete enough to test against. + +## Output + +Write the spec to `codev/specs/{{artifact_name}}.md` using the template below as its interface — these headings, in this order. A section that genuinely does not apply keeps its heading with a one-line `N/A — [reason]` rather than being deleted. Do not pattern-match an older spec in `codev/specs/` that predates this template. + +{{> protocols/spir/templates/spec.md}} + +Keep the three artifact filenames in sync: spec `codev/specs/{{artifact_name}}.md`, plan `codev/plans/{{artifact_name}}.md`, review `codev/reviews/{{artifact_name}}.md`. + +## Signals + +- Waiting on clarifying-question answers — **put the questions inside the signal**, which is displayed prominently to the user: + ``` + + Please answer: + 1. ... + 2. ... + + ``` +- Initial draft done: + ``` + SPEC_DRAFTED + ``` + +## Commit cadence + +Commit at each milestone, staging the spec file explicitly: +```bash +git add codev/specs/{{artifact_name}}.md +``` +1. `[Spec {{project_id}}] Initial specification draft` +2. `[Spec {{project_id}}] Specification with multi-agent review` +3. `[Spec {{project_id}}] Specification with user feedback` +4. `[Spec {{project_id}}] Final approved specification` + +Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Specify phase: no implementation detail (that is the plan), no code, no time estimates. diff --git a/packages/codev/src/__tests__/review-prompt-routing.test.ts b/packages/codev/src/__tests__/review-prompt-routing.test.ts index 0d0414cdd..924723ab0 100644 --- a/packages/codev/src/__tests__/review-prompt-routing.test.ts +++ b/packages/codev/src/__tests__/review-prompt-routing.test.ts @@ -26,7 +26,10 @@ const files: string[] = []; for (const tree of ['codev', 'codev-skeleton']) { for (const f of ROUTING_FILES) files.push(`${tree}/${f}`); } -files.push('codev-skeleton/porch/prompts/review.md'); // generic porch review prompt (skeleton-only) +// Spec 1280 Phase 9 (M6, G4): the dead `codev-skeleton/porch/prompts/` tree was deleted — it was +// the Ralph-SPIR-era prompt set with no runtime consumer (the live resolver loads +// protocols/

/prompts/). Its review.md was previously routing-checked here (Spec 987); with the +// tree gone there is nothing to route. The live review prompts/templates above are unaffected. function read(rel: string): string { return fs.readFileSync(path.join(repoRoot, rel), 'utf-8'); diff --git a/packages/codev/src/__tests__/spec-1280-p6-delivery.test.ts b/packages/codev/src/__tests__/spec-1280-p6-delivery.test.ts new file mode 100644 index 000000000..268a80d6a --- /dev/null +++ b/packages/codev/src/__tests__/spec-1280-p6-delivery.test.ts @@ -0,0 +1,166 @@ +/** + * Spec 1280 — T18: P6 delivery of the structured source, in BOTH consumption modes. + * + * Principle P6 ("simple specs → rich references") lets `protocol.md` stop narrating the state + * machine and reference `protocol.json` instead. That is only safe if the reference actually + * ARRIVES. A prose instruction to "read protocol.json" would be the fetch-by-path CLAUDE.md + * forbids: in a fresh adopter project `codev/protocols/

/protocol.json` does not exist on + * disk at all — it resolves from the installed package skeleton — so the builder would be told + * to open a file that is not there. + * + * The mechanism is therefore a `{{> ... }}` include, expanded by the same resolver the runtime + * uses. These tests assert the delivery, not the intention. + * + * The two modes are NOT symmetric, which is why both are tested: + * STRICT — porch drives; the builder also receives gates and checks as task JSON, so the + * include is corroborating. + * SOFT — no porch. The spawn-inlined `protocol.md` is the ONLY place the builder learns + * the phase order, gates and checks. Here the include is load-bearing, and a + * silent expansion failure would leave a soft-mode builder with a protocol document + * that describes nothing. + * + * Budgets are explicit from the outset rather than inherited: these shell out and read the + * whole protocol tree. + */ +import { describe, it, expect } from 'vitest'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { resolveCodevIncludes } from '../lib/skeleton.js'; + +const repoRoot = path.resolve(import.meta.dirname, '../../../..'); + +/** Protocols that ship a protocol.json — the ones P6 applies to. */ +function protocolsWithJson(): string[] { + const seen = new Map(); + for (const tree of ['codev/protocols', 'codev-skeleton/protocols']) { + const dir = path.join(repoRoot, tree); + if (!fs.existsSync(dir)) continue; + for (const e of fs.readdirSync(dir, { withFileTypes: true })) { + if (!e.isDirectory()) continue; + const hasJson = fs.existsSync(path.join(dir, e.name, 'protocol.json')); + seen.set(e.name, (seen.get(e.name) ?? false) || hasJson); + } + } + return [...seen].filter(([, hasJson]) => hasJson).map(([n]) => n).sort(); +} + +function resolveFile(rel: string): string | null { + for (const base of ['.codev', 'codev', 'codev-skeleton']) { + const p = path.join(repoRoot, base, rel); + if (fs.existsSync(p)) return p; + } + return null; +} + +/** The served text of a protocol.md, expanded exactly as the runtime expands it. */ +function servedProtocolDoc(protocol: string): string { + const p = resolveFile(`protocols/${protocol}/protocol.md`); + if (!p) throw new Error(`no protocol.md for ${protocol}`); + return resolveCodevIncludes(fs.readFileSync(p, 'utf-8'), repoRoot); +} + +function gatesAndChecks(protocol: string): { gates: string[]; checks: string[]; phases: string[] } { + const p = resolveFile(`protocols/${protocol}/protocol.json`)!; + const d = JSON.parse(fs.readFileSync(p, 'utf-8')); + const gates: string[] = []; + const checks: string[] = []; + const phases: string[] = []; + for (const ph of d.phases ?? []) { + phases.push(ph.id); + const g = typeof ph.gate === 'string' ? ph.gate : ph.gate?.name; + if (g) gates.push(g); + checks.push(...Object.keys(ph.checks ?? {})); + } + return { gates, checks, phases }; +} + +describe('T18 — P6 delivers the structured source, not a path to fetch', () => { + const targets = protocolsWithJson().filter((p) => resolveFile(`protocols/${p}/protocol.md`)); + + it('there is something to test', () => { + expect(targets.length).toBeGreaterThan(0); + }); + + for (const protocol of targets) { + describe(protocol, () => { + it('never instructs the agent to go READ protocol.json by path', () => { + const raw = fs.readFileSync(resolveFile(`protocols/${protocol}/protocol.md`)!, 'utf-8'); + // An include directive is delivery. An imperative to open the path is a fetch, and + // fetch-by-path of a framework file fails in a fresh install. + const fetchy = /\b(read|open|see|consult|cat)\b[^.\n]{0,40}protocol\.json/i; + expect(raw, `${protocol}/protocol.md instructs a fetch instead of delivering`).not.toMatch( + fetchy, + ); + }); + + it('SOFT mode: the served doc alone carries every phase, gate and check', () => { + // No porch. The spawn-inlined protocol.md is the only source. + const served = servedProtocolDoc(protocol); + const { gates, checks, phases } = gatesAndChecks(protocol); + for (const id of phases) { + expect(served, `${protocol}: phase "${id}" absent from served doc`).toContain(id); + } + for (const g of gates) { + expect(served, `${protocol}: gate "${g}" absent from served doc`).toContain(g); + } + for (const c of checks) { + expect(served, `${protocol}: check "${c}" absent from served doc`).toContain(c); + } + }, 60_000); + + it('the include measurably expands — a silent no-op would look like success', () => { + const raw = fs.readFileSync(resolveFile(`protocols/${protocol}/protocol.md`)!, 'utf-8'); + if (!raw.includes('{{>')) return; // protocol not yet migrated to P6; nothing to assert + const served = servedProtocolDoc(protocol); + expect(served.length).toBeGreaterThan(raw.length); + expect(served).not.toContain('{{>'); // every directive consumed + }, 60_000); + }); + } + + it('STRICT mode parity: the same resolver backs the spawn path', () => { + // spawn-roles.ts resolveProtocolReference() reads protocol.md and passes it through + // resolveCodevIncludes before inlining it as {{protocol_reference}}. If that ever stops, + // strict-mode builders lose the structured source too. + const spawn = fs.readFileSync( + path.join(repoRoot, 'packages/codev/src/agent-farm/commands/spawn-roles.ts'), + 'utf-8', + ); + expect(spawn).toMatch(/resolveCodevIncludes\(\s*readFileSync\(protocolDocPath/); + }); + + it('fresh-install shape: with no .codev/ and no codev/ tier, the include still resolves', () => { + // CORRECTION to an earlier version of this test, worth stating because it changed my model + // of the resolver: tier 4 is `getSkeletonDir()` — the INSTALLED NPM PACKAGE — not + // `/codev-skeleton/`. The repo-local `codev-skeleton/` directory is a build SOURCE + // (copy-skeleton copies it into packages/codev/skeleton); the resolver never reads it. + // So a fresh install cannot be simulated by planting files under a temp root — it is + // simulated by giving the resolver a root with NO local tiers and letting it fall through. + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'spec1280-p6-fresh-')); + const proto = targets[0]; + const out = resolveCodevIncludes( + `\`\`\`json\n{{> protocols/${proto}/protocol.json}}\n\`\`\``, + dir, + ); + expect(out, 'include collapsed to empty — an adopter would get a doc describing nothing') + .not.toMatch(/^```json\s*```$/); + expect(out).not.toContain('{{>'); + expect(out).toContain('"phases"'); + }, 60_000); + + it('the shipped package actually contains the JSON the include depends on', () => { + // The adopter guarantee behind P6: tier 4 can only deliver what npm publishes. + const pkg = JSON.parse( + fs.readFileSync(path.join(repoRoot, 'packages/codev/package.json'), 'utf-8'), + ); + expect(pkg.files, 'skeleton must be in the npm files allowlist').toContain('skeleton'); + for (const protocol of targets) { + const shipped = path.join(repoRoot, 'packages/codev/skeleton/protocols', protocol, 'protocol.json'); + expect( + fs.existsSync(shipped), + `${protocol}/protocol.json is not in the built skeleton — P6 would deliver nothing to adopters`, + ).toBe(true); + } + }); +}); diff --git a/packages/codev/src/__tests__/spec-1280-phase-manifest.test.ts b/packages/codev/src/__tests__/spec-1280-phase-manifest.test.ts index c6b6d8148..2b9cf1519 100644 --- a/packages/codev/src/__tests__/spec-1280-phase-manifest.test.ts +++ b/packages/codev/src/__tests__/spec-1280-phase-manifest.test.ts @@ -11,7 +11,6 @@ * because the guard must predate the thing it guards. */ import { describe, it, expect } from 'vitest'; -import { execFileSync } from 'node:child_process'; import * as fs from 'node:fs'; import * as path from 'node:path'; @@ -21,15 +20,27 @@ const manifestDir = path.join( 'codev/projects/1280-prompt-surface-judgment-not-ru/manifests', ); -/** Files a manifest is responsible for listing: prompt-bearing surfaces only. */ -const PROMPT_BEARING = /^(CLAUDE\.md|AGENTS\.md|codev(-skeleton)?\/(protocols|roles)\/.*\.md)$/; - interface Manifest { file: string; phase: string; rows: { path: string; oldWords: string; newWords: string; principles: string }[]; } +/** + * Expand `{a,b}/rest` into `a/rest`, `b/rest`. + * + * DELIBERATE FORMAT DECISION (Spec 1280, Phase 3): the plan's inspection model is per + * DECISION, not per file — twins are byte-identical and T7 verifies the sync mechanically, so + * the architect reads ~66 decisions rather than 131 diffs. One manifest row therefore names + * both tree paths, and the ≤12 batch cap counts decisions. The parser has to understand that + * notation or the skeleton twins read as uninspectable — which is exactly what it reported. + */ +function expandBraces(p: string): string[] { + const m = p.match(/^\{([^}]+)\}(.*)$/); + if (!m) return [p]; + return m[1].split(',').map((alt) => alt.trim() + m[2]); +} + function parseManifest(file: string): Manifest { const body = fs.readFileSync(file, 'utf-8'); const rows: Manifest['rows'] = []; @@ -37,12 +48,13 @@ function parseManifest(file: string): Manifest { // | path | old | new | principles | rationale | const m = line.match(/^\|\s*`?([^`|]+?)`?\s*\|\s*(\d+)\s*\|\s*(\d+)\s*\|\s*([^|]*)\|/); if (m && !/^-+$/.test(m[1].trim())) { - rows.push({ - path: m[1].trim(), + for (const expanded of expandBraces(m[1].trim())) rows.push({ + path: expanded, oldWords: m[2], newWords: m[3], principles: m[4].trim(), }); + } } return { file, phase: path.basename(file, '.md'), rows }; @@ -94,26 +106,13 @@ describe('T16 — manifest completeness (M11)', () => { } }); - it('every prompt-bearing file changed on this branch appears in some manifest', () => { - let changed: string[]; - try { - changed = execFileSync('git', ['diff', '--name-only', 'origin/main...HEAD'], { - cwd: repoRoot, - encoding: 'utf-8', - }) - .split('\n') - .map((s) => s.trim()) - .filter((s) => PROMPT_BEARING.test(s)); - } catch { - return; // no origin/main to diff against (fresh clone / CI shallow) — skip - } - if (changed.length === 0) return; - - const listed = new Set(manifests().flatMap((m) => m.rows.map((r) => r.path))); - const missing = changed.filter((f) => !listed.has(f)); - expect( - missing, - `changed but absent from every manifest — the architect cannot inspect what is not listed:\n${missing.join('\n')}`, - ).toEqual([]); - }); + // RETIRED under Spec 1280 (retirement R5, Waleed's ruling 2026-08-06): the repo-wide + // manifest-COMPLETENESS scan ("every prompt-bearing file THIS PROJECT changed appears in some + // manifest"). Even scoped by [Spec 1280] commit provenance, it lived in the SHARED suite and ran + // a repo diff + `git status` on every PR — its uncommitted-file check caught Mohid's #1330 + // (which had to strip its CLAUDE.md/AGENTS.md edits to pass CI). The cross-project CI tax isn't + // worth the mechanical enforcement. What SURVIVES: the per-phase manifests themselves and the + // M11 human inspection contract are unchanged — the architect still inspects against a complete + // manifest — and the FORMAT checks above (four required fields, batch cap) still validate this + // project's own manifests. Only the CI tripwire is gone. Full trace: codev/resources/1280-retirements.md (R5). }); diff --git a/packages/codev/src/__tests__/spec-1280-prompt-deletion-guard.test.ts b/packages/codev/src/__tests__/spec-1280-prompt-deletion-guard.test.ts new file mode 100644 index 000000000..c3bdc426f --- /dev/null +++ b/packages/codev/src/__tests__/spec-1280-prompt-deletion-guard.test.ts @@ -0,0 +1,267 @@ +/** + * Spec 1280 — replacement for retired assertion R1. + * + * R1 retired the pure-addition diff of the three builder-prompts against their PRE-746 + * baselines. That assertion proved Spec 746's Baked Decisions paragraph was ADDED without + * destroying prior content — true and useful at the moment of addition, but as a standing + * assertion it forbade any future deletion-rewrite of those files forever. + * + * The protection worth keeping is narrower and survives rewrites: **once this project has + * finished rewriting a prompt, later edits must not silently delete from it.** So the same + * machinery is re-anchored on POST-1280 baselines. + * + * ANTI-VACUITY, INVERTED FOR THE NEW ERA + * -------------------------------------- + * 746's pollution check asserted its baseline did NOT contain '## Baked Decisions' — proving + * the baseline predated the edit it verified. The equivalent guarantee here runs the other way: + * the post-1280 baseline MUST contain '## Baked Decisions'. If a future edit strips 746's + * content and someone re-baselines to hide it, the new baseline lacks the heading and this + * fails. Without that check, re-baselining would silently launder a deletion — which is exactly + * the failure mode R1's analysis identified and declined to ship. + * + * R2 (approved 2026-08-04) extends the same machinery to the two SPIR/ASPIR specify.md drafting + * prompts, whose Phase 2 pure-addition guard R1 left in force and Phase 5 retired. Their + * anti-vacuity string is the literal `Baked Decisions` (specify.md carries the clause as a bullet, + * not a `## Baked Decisions` heading like the builder-prompts). Full trace: + * codev/resources/1280-retirements.md (R2). + * + * R3 (approved 2026-08-06) does the same for air/implement.md — the last PHASE_2 file — after + * Phase 6's P1 rewrite retired its pure-addition guard. Full trace: 1280-retirements.md (R3). + */ +import { describe, it, expect } from 'vitest'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; + +const repoRoot = path.resolve(import.meta.dirname, '../../../..'); +const baselineDir = path.join(repoRoot, 'packages/codev/src/__tests__/fixtures/spec-1280-baselines'); + +const GUARDED = ['spir', 'aspir', 'air'] as const; +const baselinePath = (p: string) => path.join(baselineDir, `${p}-builder-prompt.md.baseline`); +const currentPath = (p: string) => + path.join(repoRoot, 'codev/protocols', p, 'builder-prompt.md'); + +/** Every baseline line must reappear, in order, in the current file. */ +function expectNoDeletion(label: string, baseline: string, current: string): void { + const base = baseline.split('\n'); + const curr = current.split('\n'); + let bi = 0; + for (let ci = 0; bi < base.length && ci < curr.length; ci++) { + if (base[bi] === curr[ci]) bi++; + } + if (bi < base.length) { + throw new Error( + `${label}: content deleted since the Spec 1280 baseline — line ${bi + 1} ` + + `("${base[bi]}") no longer present in order. If the removal is intentional, ` + + `record it in codev/resources/1280-retirements.md and re-baseline in the same commit.`, + ); + } +} + +describe('Spec 1280 — builder-prompts do not silently lose content (replaces R1)', () => { + for (const p of GUARDED) { + describe(p, () => { + it('has a post-1280 baseline committed', () => { + expect( + fs.existsSync(baselinePath(p)), + `missing baseline for ${p}; the guard cannot protect what it has no reference for`, + ).toBe(true); + }); + + it('anti-vacuity: the baseline carries Spec 746 content', () => { + // If someone strips Baked Decisions and re-baselines to hide it, the new baseline + // fails here rather than passing silently. + const baseline = fs.readFileSync(baselinePath(p), 'utf-8'); + expect(baseline).toContain('## Baked Decisions'); + expect(baseline.toLowerCase()).toContain('do not autonomously'); + }); + + it('no baseline line has been deleted', () => { + expectNoDeletion( + `${p} builder-prompt`, + fs.readFileSync(baselinePath(p), 'utf-8'), + fs.readFileSync(currentPath(p), 'utf-8'), + ); + }); + + it('the skeleton twin still matches', () => { + const ours = fs.readFileSync(currentPath(p), 'utf-8'); + const skeleton = fs.readFileSync( + path.join(repoRoot, 'codev-skeleton/protocols', p, 'builder-prompt.md'), + 'utf-8', + ); + expect(skeleton).toBe(ours); + }); + }); + } +}); + +// R2 (Spec 1280, approved 2026-08-04): the two SPIR/ASPIR specify.md drafting prompts, re-anchored +// on post-1280 baselines after Phase 5's P1/P2 rewrite retired their pre-746 pure-addition guard. +const GUARDED_SPECIFY = ['spir', 'aspir'] as const; +const specifyBaselinePath = (p: string) => path.join(baselineDir, `${p}-specify.md.baseline`); +const specifyCurrentPath = (p: string) => + path.join(repoRoot, 'codev/protocols', p, 'prompts/specify.md'); + +describe('Spec 1280 — SPIR/ASPIR specify.md do not silently lose content (replaces R2)', () => { + for (const p of GUARDED_SPECIFY) { + describe(`${p} specify.md`, () => { + it('has a post-1280 baseline committed', () => { + expect( + fs.existsSync(specifyBaselinePath(p)), + `missing baseline for ${p} specify.md; the guard cannot protect what it has no reference for`, + ).toBe(true); + }); + + it('anti-vacuity: the baseline carries Spec 746 content', () => { + // specify.md carries the Baked Decisions clause as a bullet, not a `## Baked Decisions` + // heading — so the anti-vacuity string is the literal `Baked Decisions`. If someone strips + // it and re-baselines to hide the deletion, the new baseline fails here rather than passing. + const baseline = fs.readFileSync(specifyBaselinePath(p), 'utf-8'); + expect(baseline).toContain('Baked Decisions'); + expect(baseline.toLowerCase()).toContain('do not autonomously'); + }); + + it('no baseline line has been deleted', () => { + expectNoDeletion( + `${p} specify.md`, + fs.readFileSync(specifyBaselinePath(p), 'utf-8'), + fs.readFileSync(specifyCurrentPath(p), 'utf-8'), + ); + }); + + it('the skeleton twin still matches', () => { + const ours = fs.readFileSync(specifyCurrentPath(p), 'utf-8'); + const skeleton = fs.readFileSync( + path.join(repoRoot, 'codev-skeleton/protocols', p, 'prompts/specify.md'), + 'utf-8', + ); + expect(skeleton).toBe(ours); + }); + }); + } +}); + +// R3 (Spec 1280, approved 2026-08-06): air/implement.md — the last PHASE_2 file — re-anchored on a +// post-1280 baseline after Phase 6's P1 rewrite retired its pre-746 pure-addition guard. +const airImplementBaseline = path.join(baselineDir, 'air-implement.md.baseline'); +const airImplementCurrent = path.join(repoRoot, 'codev/protocols/air/prompts/implement.md'); + +describe('Spec 1280 — air/implement.md does not silently lose content (replaces R3)', () => { + it('has a post-1280 baseline committed', () => { + expect( + fs.existsSync(airImplementBaseline), + 'missing baseline for air/implement.md; the guard cannot protect what it has no reference for', + ).toBe(true); + }); + + it('anti-vacuity: the baseline carries Spec 746 content', () => { + const baseline = fs.readFileSync(airImplementBaseline, 'utf-8'); + expect(baseline).toContain('Baked Decisions'); + expect(baseline.toLowerCase()).toContain('do not autonomously'); + }); + + it('no baseline line has been deleted', () => { + expectNoDeletion( + 'air/implement.md', + fs.readFileSync(airImplementBaseline, 'utf-8'), + fs.readFileSync(airImplementCurrent, 'utf-8'), + ); + }); + + it('the skeleton twin still matches', () => { + const ours = fs.readFileSync(airImplementCurrent, 'utf-8'); + const skeleton = fs.readFileSync( + path.join(repoRoot, 'codev-skeleton/protocols/air/prompts/implement.md'), + 'utf-8', + ); + expect(skeleton).toBe(ours); + }); +}); + +// R4 (Spec 1280, class-pre-approved, applied 2026-08-06): spir spec-review.md + plan-review.md — +// the first two PHASE_3 consult-types — re-anchored on post-1280 baselines after Phase 7's P1/P2 +// rewrite retired their pre-746 pure-addition guard. Full trace: 1280-retirements.md (R4). +const GUARDED_SPIR_CONSULT = ['spec-review', 'plan-review'] as const; +const consultBaselinePath = (n: string) => path.join(baselineDir, `spir-${n}.md.baseline`); +const consultCurrentPath = (n: string) => + path.join(repoRoot, 'codev/protocols/spir/consult-types', `${n}.md`); + +describe('Spec 1280 — spir consult-types do not silently lose content (replaces R4)', () => { + for (const n of GUARDED_SPIR_CONSULT) { + describe(`${n}.md`, () => { + it('has a post-1280 baseline committed', () => { + expect( + fs.existsSync(consultBaselinePath(n)), + `missing baseline for spir ${n}.md; the guard cannot protect what it has no reference for`, + ).toBe(true); + }); + + it('anti-vacuity: the baseline carries Spec 746 content', () => { + const baseline = fs.readFileSync(consultBaselinePath(n), 'utf-8'); + expect(baseline).toContain('Baked Decisions'); + expect(baseline.toLowerCase()).toContain('do not autonomously'); + }); + + it('no baseline line has been deleted', () => { + expectNoDeletion( + `spir ${n}.md`, + fs.readFileSync(consultBaselinePath(n), 'utf-8'), + fs.readFileSync(consultCurrentPath(n), 'utf-8'), + ); + }); + + it('the skeleton twin still matches', () => { + const ours = fs.readFileSync(consultCurrentPath(n), 'utf-8'); + const skeleton = fs.readFileSync( + path.join(repoRoot, 'codev-skeleton/protocols/spir/consult-types', `${n}.md`), + 'utf-8', + ); + expect(skeleton).toBe(ours); + }); + }); + } +}); + +// R6 (Spec 1280, class-pre-approved, applied 2026-08-06): the last four PHASE_3 consult-types — +// aspir spec/plan-review + air impl/pr-review — re-anchored on post-1280 baselines after Phase 8's +// P1/P2 rewrite retired their pre-746 pure-addition guard. Full trace: 1280-retirements.md (R6). +const GUARDED_R6_CONSULT: Array<{ proto: string; name: string }> = [ + { proto: 'aspir', name: 'spec-review' }, + { proto: 'aspir', name: 'plan-review' }, + { proto: 'air', name: 'impl-review' }, + { proto: 'air', name: 'pr-review' }, +]; + +describe('Spec 1280 — aspir/air consult-types do not silently lose content (replaces R6)', () => { + for (const { proto, name } of GUARDED_R6_CONSULT) { + const baseline = path.join(baselineDir, `${proto}-${name}.md.baseline`); + const current = path.join(repoRoot, 'codev/protocols', proto, 'consult-types', `${name}.md`); + describe(`${proto} ${name}.md`, () => { + it('has a post-1280 baseline committed', () => { + expect( + fs.existsSync(baseline), + `missing baseline for ${proto} ${name}.md; the guard cannot protect what it has no reference for`, + ).toBe(true); + }); + + it('anti-vacuity: the baseline carries Spec 746 content', () => { + const b = fs.readFileSync(baseline, 'utf-8'); + expect(b).toContain('Baked Decisions'); + expect(b.toLowerCase()).toContain('do not autonomously'); + }); + + it('no baseline line has been deleted', () => { + expectNoDeletion(`${proto} ${name}.md`, fs.readFileSync(baseline, 'utf-8'), fs.readFileSync(current, 'utf-8')); + }); + + it('the skeleton twin still matches', () => { + const ours = fs.readFileSync(current, 'utf-8'); + const skeleton = fs.readFileSync( + path.join(repoRoot, 'codev-skeleton/protocols', proto, 'consult-types', `${name}.md`), + 'utf-8', + ); + expect(skeleton).toBe(ours); + }); + }); + } +}); diff --git a/packages/codev/src/__tests__/spec-1280-scar-rules.test.ts b/packages/codev/src/__tests__/spec-1280-scar-rules.test.ts new file mode 100644 index 000000000..c722f7d6b --- /dev/null +++ b/packages/codev/src/__tests__/spec-1280-scar-rules.test.ts @@ -0,0 +1,83 @@ +/** + * T4 — scar-rule registry enforcement (Spec 1280, Phase 9). + * + * The scar rules are the one deliberate exception to P7 (Baked Decision 2): eight prohibitions, + * kept VERBATIM, that guard irreversible acts (destroyed worktrees, killed sessions, bypassed + * human gates) where the cost of being wrong once is unbounded. `codev/resources/scar-rules.yaml` + * is the single source of truth: the canonical wording lives there once, and every surface listed + * under a rule's `must_appear_on` must carry that exact string. + * + * This test — created in Phase 9, the first phase where the surface has stopped moving so + * `must_appear_on` is meaningful — pins: + * 1. the count at 8 and the exact ids (deleting or renaming a rule fails); + * 2. byte-identical carriage of each canonical on every listed surface (rewording any copy fails); + * 3. the carriage guarantee that all eight ride the primary always-on surface (CLAUDE.md + AGENTS.md). + */ +import { describe, it, expect } from 'vitest'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import * as yaml from 'js-yaml'; + +const repoRoot = path.resolve(import.meta.dirname, '../../../..'); +const registryPath = path.join(repoRoot, 'codev/resources/scar-rules.yaml'); + +interface ScarRule { + id: string; + canonical: string; + must_appear_on: string[]; +} + +const registry = yaml.load(fs.readFileSync(registryPath, 'utf-8')) as { scar_rules: ScarRule[] }; +const rules = registry.scar_rules; + +// The eight ratified ids, pinned. Deleting or renaming a rule breaks this list. +const EXPECTED_IDS = [ + 'git-add-explicit', + 'never-destroy-worktrees', + 'no-destructive-git', + 'human-gates', + 'no-hand-edit-status', + 'afx-from-root', + 'shellper-verified-orphan', + 'tower-restart-permission', +]; + +describe('T4 — scar-rule registry (Spec 1280)', () => { + it('pins the count at 8', () => { + expect(rules).toHaveLength(8); + }); + + it('pins the exact ids', () => { + expect(rules.map((r) => r.id).sort()).toEqual([...EXPECTED_IDS].sort()); + }); + + it('every rule has a non-empty canonical and at least one surface', () => { + for (const r of rules) { + expect(r.canonical, `${r.id}: empty canonical`).toBeTruthy(); + expect(r.must_appear_on?.length, `${r.id}: no surfaces`).toBeGreaterThan(0); + } + }); + + describe('each canonical appears byte-identically on every listed surface', () => { + for (const r of rules) { + for (const rel of r.must_appear_on) { + it(`${r.id} → ${rel}`, () => { + const p = path.join(repoRoot, rel); + expect(fs.existsSync(p), `${rel} listed for ${r.id} does not exist`).toBe(true); + const content = fs.readFileSync(p, 'utf-8'); + expect( + content.includes(r.canonical), + `${r.id} canonical not found byte-identically in ${rel} — a reworded or dropped copy`, + ).toBe(true); + }); + } + } + }); + + it('all eight ride the primary always-on surface (CLAUDE.md + AGENTS.md)', () => { + for (const r of rules) { + expect(r.must_appear_on, `${r.id} missing CLAUDE.md`).toContain('CLAUDE.md'); + expect(r.must_appear_on, `${r.id} missing AGENTS.md`).toContain('AGENTS.md'); + } + }); +}); diff --git a/packages/codev/src/__tests__/spec-1280-skills-parity.test.ts b/packages/codev/src/__tests__/spec-1280-skills-parity.test.ts new file mode 100644 index 000000000..e56ea0a01 --- /dev/null +++ b/packages/codev/src/__tests__/spec-1280-skills-parity.test.ts @@ -0,0 +1,82 @@ +/** + * Spec 1280 — T17: four-tree parity for skills this project touches. + * + * Skills exist in FOUR places: `.claude/skills`, `.codex/skills`, and the skeleton's copies + * of both. Principles P3/P4 relocate how-to content out of CLAUDE.md into skills — and a + * relocation written to only one tree silently: + * - leaves Codex agents without the content, + * - leaves adopters without it after `codev update`, and + * - is reported as a DELETION by the measurement instrument (M0c), inverting the + * project's own honesty artifact. + * + * SCOPE — per the architect's plan-gate ruling (2026-08-01): every skill this project + * TOUCHES must be four-tree consistent. Skills it does not touch are EXEMPT; their + * pre-existing drift (`afx`, `porch`) and skeleton-absence (`forge`, `skill-creator`, + * `team`) belong to a separate architect-filed issue and must not fail this test. + */ +import { describe, it, expect } from 'vitest'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; + +const repoRoot = path.resolve(import.meta.dirname, '../../../..'); + +/** + * Skills touched by Spec 1280. Adding a skill to this list is a deliberate act: it asserts + * the project now owns that skill's four-tree consistency. + */ +const TOUCHED_SKILLS = ['runnable-worktrees', 'codev'] as const; + +const TREES = [ + '.claude/skills', + '.codex/skills', + 'codev-skeleton/.claude/skills', + 'codev-skeleton/.codex/skills', +] as const; + +const skillPath = (tree: string, skill: string) => + path.join(repoRoot, tree, skill, 'SKILL.md'); + +describe('T17 — touched skills are consistent across all four trees', () => { + for (const skill of TOUCHED_SKILLS) { + it(`${skill}: present in every tree`, () => { + for (const tree of TREES) { + expect( + fs.existsSync(skillPath(tree, skill)), + `${skill} missing from ${tree} — relocated content would be invisible to that audience`, + ).toBe(true); + } + }); + + it(`${skill}: byte-identical across every tree`, () => { + const canonical = fs.readFileSync(skillPath('.claude/skills', skill), 'utf-8'); + for (const tree of TREES.slice(1)) { + expect( + fs.readFileSync(skillPath(tree, skill), 'utf-8'), + `${skill} differs between .claude/skills and ${tree}`, + ).toBe(canonical); + } + }); + + it(`${skill}: carries usable frontmatter`, () => { + const body = fs.readFileSync(skillPath('.claude/skills', skill), 'utf-8'); + expect(body.startsWith('---\n'), `${skill} has no frontmatter block`).toBe(true); + expect(body).toMatch(new RegExp(`^name:\\s*${skill}$`, 'm')); + // The description is the trigger surface — an empty one makes the skill undiscoverable, + // which for relocated content means the content is effectively lost. + const desc = body.match(/^description:\s*(.+)$/m); + expect(desc, `${skill} has no description`).not.toBeNull(); + expect(desc![1].trim().length).toBeGreaterThan(40); + }); + } + + it('untouched skills are exempt — pre-existing drift must not fail this test', () => { + // Guards the ruling itself: if someone later widens TOUCHED_SKILLS to "all skills", this + // test starts failing on drift this project deliberately did not take on. + const claudeSkills = fs + .readdirSync(path.join(repoRoot, '.claude/skills'), { withFileTypes: true }) + .filter((e) => e.isDirectory()) + .map((e) => e.name); + const untouched = claudeSkills.filter((s) => !TOUCHED_SKILLS.includes(s as never)); + expect(untouched.length, 'expected some skills to be out of scope').toBeGreaterThan(0); + }); +}); diff --git a/packages/codev/src/agent-farm/__tests__/baked-decisions.test.ts b/packages/codev/src/agent-farm/__tests__/baked-decisions.test.ts index 3f41e9a6b..7120289d6 100644 --- a/packages/codev/src/agent-farm/__tests__/baked-decisions.test.ts +++ b/packages/codev/src/agent-farm/__tests__/baked-decisions.test.ts @@ -136,16 +136,24 @@ describe('Spec 746 Phase 1: builder-prompt baked-decisions instruction', () => { } }); - describe('pure-addition diff: baseline lines are preserved in order', () => { - for (const file of PHASE_1_FILES) { - if (file.baselineName === null) continue; // skeleton mirrors don't have a baseline; codev/ is the source of truth - it(`${file.label}: post-edit file is a pure-addition diff of its baseline`, () => { - const baseline = readBaseline(file.baselineName!); - const current = readRepoFile(file.relPath); - expectPureAdditionDiff(file.label, baseline, current); - }); - } - }); + // RETIRED under Spec 1280 (retirement R1, architect-approved 2026-08-01). + // + // This asserted a pure-addition diff of each builder-prompt against its PRE-746 baseline — + // proving Spec 746's Baked Decisions paragraph was ADDED without destroying prior content. + // That was construction-time scaffolding: true and useful at the moment of addition, but as + // a standing assertion it forbids ANY future deletion-rewrite of these files forever, which + // is not a behaviour Spec 746 ever claimed to protect. + // + // Spec 746's actual protection is untouched and still asserted below: the Baked Decisions + // sections are present and substantive in all three prompts and both trees, and the + // pollution check still guards against a vacuous baseline. + // + // Re-baselining was considered and rejected: a post-rewrite baseline would contain + // '## Baked Decisions', which the pollution check (correctly) forbids — and silencing that + // check to make a re-baseline pass would gut the anti-vacuity half of 746's protection. + // + // Full trace, including the per-assertion behaviour-re-asserted mapping: + // codev/resources/1280-retirements.md (R1) it('codev SPIR builder-prompt baseline does NOT contain the new heading (pollution check)', () => { // Catches the failure mode where the baseline was captured AFTER an edit. @@ -273,9 +281,55 @@ describe('Spec 746 Phase 2: drafting-prompt baked-decisions clause', () => { } }); + // RETIRED under Spec 1280 (retirement R2, approved by Waleed 2026-08-04) — SCOPED to the two + // SPIR/ASPIR specify.md drafting prompts only. + // + // Phase 5 rewrites specify.md to P1/P2, deleting the pre-746 "Process" walkthrough that the + // baseline captured. "No pre-746 line was ever removed" is therefore false by design and + // permanently — the identical change-freeze failure R1 named. R1 explicitly left the + // PHASE_2_FILES pure-addition guard "in force"; Phase 5 is the phase that touches specify.md, so + // R2 retires it for those two files exactly as R1 did for the builder-prompts. + // + // 746's substance survives and is still asserted, all passing: the grep regression above + // (`Baked Decisions`, `do not autonomously`, `contradict`+`pause`+`flag`, `afx send`), the + // byte-identical-clause mirror-parity below, and the pollution check at the end of this describe. + // The deletion protection is re-anchored on POST-1280 baselines in + // spec-1280-prompt-deletion-guard.test.ts (inverted anti-vacuity), so future silent deletion is + // still caught. + // + // NOT retired: air/implement.md — Phase 5 does not touch it, so its pure-addition guard stays in + // force below. Full trace: codev/resources/1280-retirements.md (R2). + const RETIRED_UNDER_R2 = new Set([ + 'codev/protocols/spir/prompts/specify.md', + 'codev/protocols/aspir/prompts/specify.md', + ]); + // RETIRED under Spec 1280 (retirement R3, approved by Waleed 2026-08-06) — the third and last + // PHASE_2 file. Phase 6 rewrites air/implement.md to P1, deleting the pre-746 "Process" + // walkthrough, so its pure-addition invariant is false by design (the change-freeze failure R1 + // named). Behaviour survives — the Baked Decisions grep above passes on the canonical wording — + // and deletion protection is re-anchored on a post-1280 baseline in + // spec-1280-prompt-deletion-guard.test.ts. After R2+R3 every PHASE_2 baseline file is retired; + // the loop stays so a future PHASE_2 file would still be guarded. Full trace: + // codev/resources/1280-retirements.md (R3). + const RETIRED_UNDER_R3 = new Set([ + 'codev/protocols/air/prompts/implement.md', + ]); + const activePhase2 = PHASE_2_FILES.filter( + (f) => + f.baselineName !== null && + !RETIRED_UNDER_R2.has(f.relPath) && + !RETIRED_UNDER_R3.has(f.relPath), + ); describe('pure-addition diff: baseline lines preserved in order', () => { - for (const file of PHASE_2_FILES) { - if (file.baselineName === null) continue; + // R2 + R3 retired every PHASE_2 baseline file's pure-addition guard. The loop stays so a + // future PHASE_2 file (with a fresh pre-746 baseline) is still covered; when none is active, + // this documents the fully-retired state rather than leaving an empty (error-raising) suite. + if (activePhase2.length === 0) { + it('all PHASE_2 pure-addition guards retired (R2, R3) — re-activates if a new PHASE_2 file is added', () => { + expect(activePhase2).toHaveLength(0); + }); + } + for (const file of activePhase2) { it(`${file.label}: post-edit file is a pure-addition diff of its baseline`, () => { const baseline = readBaseline(file.baselineName!); const current = readRepoFile(file.relPath); @@ -477,9 +531,47 @@ describe('Spec 746 Phase 3: reviewer-prompt baked-decisions clause', () => { } }); + // RETIRED under Spec 1280 (retirement R4, class-pre-approved, applied 2026-08-06) — the first two + // PHASE_3 files. Phase 7 rewrites spir spec-review.md + plan-review.md to P1/P2, deleting the + // pre-746 rubric prose, so their pure-addition invariant is false by design (the change-freeze + // failure R1 named). Behaviour survives — the Phase 3 grep above passes on the canonical Baked + // Decisions wording — and deletion protection is re-anchored on post-1280 baselines in + // spec-1280-prompt-deletion-guard.test.ts. The other four PHASE_3 files (aspir spec/plan-review, + // air impl/pr-review) stay in force until Phases 8–9 rewrite them. Full trace: + // codev/resources/1280-retirements.md (R4, and the "Class pre-approval" box). + const RETIRED_UNDER_R4 = new Set([ + 'codev/protocols/spir/consult-types/spec-review.md', + 'codev/protocols/spir/consult-types/plan-review.md', + ]); + // RETIRED under Spec 1280 (retirement R6, class-pre-approved, applied 2026-08-06) — the last four + // PHASE_3 files. Phase 8 rewrites aspir spec/plan-review (mirroring the spir rewrite) and air + // impl/pr-review to P1/P2, deleting the pre-746 rubric prose, so their pure-addition invariant is + // false by design. Behaviour survives (the Phase 3 grep above passes on the canonical Baked + // Decisions wording); deletion protection is re-anchored on post-1280 baselines in + // spec-1280-prompt-deletion-guard.test.ts. After R4+R6 every PHASE_3 file is retired. Full trace: + // codev/resources/1280-retirements.md (R6, and the "Class pre-approval" box). + const RETIRED_UNDER_R6 = new Set([ + 'codev/protocols/aspir/consult-types/spec-review.md', + 'codev/protocols/aspir/consult-types/plan-review.md', + 'codev/protocols/air/consult-types/impl-review.md', + 'codev/protocols/air/consult-types/pr-review.md', + ]); + const activePhase3 = PHASE_3_FILES.filter( + (f) => + f.baselineName !== null && + !RETIRED_UNDER_R4.has(f.relPath) && + !RETIRED_UNDER_R6.has(f.relPath), + ); describe('pure-addition diff: baseline lines preserved in order', () => { - for (const file of PHASE_3_FILES) { - if (file.baselineName === null) continue; + // R4 + R6 retired every PHASE_3 baseline file's pure-addition guard. The loop stays so a future + // PHASE_3 file (with a fresh pre-746 baseline) is still covered; when none is active, this + // documents the fully-retired state rather than leaving an empty (error-raising) suite. + if (activePhase3.length === 0) { + it('all PHASE_3 pure-addition guards retired (R4, R6) — re-activates if a new PHASE_3 file is added', () => { + expect(activePhase3).toHaveLength(0); + }); + } + for (const file of activePhase3) { it(`${file.label}: post-edit file is a pure-addition diff of its baseline`, () => { const baseline = readBaseline(file.baselineName!); const current = readRepoFile(file.relPath);