claude-code-pilot 3.1.1 → 3.3.0

package/src/pilot/references/gates.md

@@ -0,0 +1,70 @@
+# Gates Taxonomy
+
+Canonical gate types used across GSD workflows. Every validation checkpoint maps to one of these four types.
+
+---
+
+## Gate Types
+
+### Pre-flight Gate
+**Purpose:** Validates preconditions before starting an operation.
+**Behavior:** Blocks entry if conditions unmet. No partial work created.
+**Recovery:** Fix the missing precondition, then retry.
+**Examples:**
+- Plan-phase checks for REQUIREMENTS.md before planning
+- Execute-phase validates PLAN.md exists before execution
+- Discuss-phase confirms phase exists in ROADMAP.md
+
+### Revision Gate
+**Purpose:** Evaluates output quality and routes to revision if insufficient.
+**Behavior:** Loops back to producer with specific feedback. Bounded by iteration cap.
+**Recovery:** Producer addresses feedback; checker re-evaluates. The loop also escalates early if issue count does not decrease between consecutive iterations (stall detection). After max iterations, escalates unconditionally.
+**Examples:**
+- Plan-checker reviewing PLAN.md (max 3 iterations)
+- Verifier checking phase deliverables against success criteria
+
+### Escalation Gate
+**Purpose:** Surfaces unresolvable issues to the developer for a decision.
+**Behavior:** Pauses workflow, presents options, waits for human input.
+**Recovery:** Developer chooses action; workflow resumes on selected path.
+**Examples:**
+- Revision loop exhausted after 3 iterations
+- Merge conflict during worktree cleanup
+- Ambiguous requirement needing clarification
+
+### Abort Gate
+**Purpose:** Terminates the operation to prevent damage or waste.
+**Behavior:** Stops immediately, preserves state, reports reason.
+**Recovery:** Developer investigates root cause, fixes, restarts from checkpoint.
+**Examples:**
+- Context window critically low during execution
+- STATE.md in error state blocking /ccp:next
+- Verification finds critical missing deliverables
+
+---
+
+## Gate Matrix
+
+| Workflow | Phase | Gate Type | Artifacts Checked | Failure Behavior |
+|----------|-------|-----------|-------------------|------------------|
+| plan-phase | Entry | Pre-flight | REQUIREMENTS.md, ROADMAP.md | Block with missing-file message |
+| plan-phase | Step 12 | Revision | PLAN.md quality | Loop to planner (max 3) |
+| plan-phase | Post-revision | Escalation | Unresolved issues | Surface to developer |
+| execute-phase | Entry | Pre-flight | PLAN.md | Block with missing-plan message |
+| execute-phase | Completion | Revision | SUMMARY.md completeness | Re-run incomplete tasks |
+| verify-work | Entry | Pre-flight | SUMMARY.md | Block with missing-summary |
+| verify-work | Evaluation | Escalation | Failed criteria | Surface gaps to developer |
+| next | Entry | Abort | Error state, checkpoints | Stop with diagnostic |
+
+---
+
+## Implementing Gates
+
+Use this taxonomy when designing or auditing workflow validation points:
+
+- **Pre-flight** gates belong at workflow entry points. They are cheap, deterministic checks that prevent wasted work. If you can verify a precondition with a file-existence check or a config read, use a pre-flight gate.
+- **Revision** gates belong after a producer step where quality varies. Always pair them with an iteration cap to prevent infinite loops. The cap should reflect the cost of each iteration -- expensive operations get fewer retries.
+- **Escalation** gates belong wherever automated resolution is impossible or ambiguous. They are the safety valve between revision loops and abort. Present the developer with clear options and enough context to decide.
+- **Abort** gates belong at points where continuing would cause damage, waste significant resources, or produce meaningless output. They should preserve state so work can resume after the root cause is fixed.
+
+**Selection heuristic:** Start with pre-flight. If the check happens after work is produced, it is a revision gate. If the revision loop cannot resolve the issue, escalate. If continuing is dangerous, abort.

package/src/pilot/references/mandatory-initial-read.md

@@ -0,0 +1,2 @@
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.

package/src/pilot/references/mvp-concepts.md

@@ -0,0 +1,49 @@
+# MVP Concepts — index
+
+Cross-reference for the six MVP-related reference files. Each file has a single, narrow purpose. This index exists so future readers (and agents resolving `@`-refs) can find the right file without grepping the directory.
+
+Canonical domain terms for the concepts named below live in [CONTEXT.md](../../CONTEXT.md) under "Domain terms" — start there if you need a precise definition.
+
+## File map
+
+| File | Purpose | Loaded by |
+|---|---|---|
+| `references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `ccp-planner` agent when `MVP_MODE=true` |
+| `references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `ccp-planner` agent when the Walking Skeleton gate fires |
+| `references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `ccp:mvp-phase` workflow during interactive prompting; `ccp-planner` when emitting the `## Phase Goal` header |
+| `references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `ccp:mvp-phase` workflow when the user story exceeds size threshold |
+| `references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `ccp-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
+| `references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `ccp-verifier` agent when the phase under verification has `mode: mvp` |
+
+## Concept-to-file map
+
+If you're looking for the canonical statement of a concept, this is where to find it:
+
+- **MVP Mode resolution chain** — `workflows/plan-phase.md` Step 1 (CLI flag → roadmap → config → false). Mirrored in `execute-phase.md` and `verify-work.md`.
+- **`**Mode:** mvp` parser** — parsed by the planner workflow when MVP mode is active in ROADMAP.md. Workflows compare against the parser output, never re-parse.
+- **User Story regex** — `/^As a .+, I want to .+, so that .+\.$/` — applied at runtime by `ccp-verifier` (the user-story-format guard) and `ccp:mvp-phase` (interactive validation).
+- **Behavior-Adding Task predicate** — `references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `ccp-executor`.
+- **Walking Skeleton gate condition** — `workflows/plan-phase.md` (Phase 1 + new project + `--mvp` + no prior summaries → emit `SKELETON.md`).
+- **MVP+TDD Gate** (RED→GREEN enforcement) — `references/execute-mvp-tdd.md`.
+- **MVP-mode UAT framing** (user-flow first, technical deferred) — `references/verify-mvp-mode.md`.
+- **Per-phase mode authoring** — `workflows/mvp-phase.md` (writes `**Mode:** mvp` to ROADMAP.md after collecting the user story).
+- **Project-wide mode prompt at init** — `workflows/new-project.md` (Vertical MVP vs Horizontal Layers question).
+
+## Interactions worth knowing
+
+- **`--mvp` and `--prd <file>` together on Phase 1.** Both paths converge at the planner spawn. The PRD express path creates `CONTEXT.md` from the PRD file and continues to the research step; the Walking Skeleton gate fires independently when Phase 1 + new project + `--mvp`. The planner therefore receives both `WALKING_SKELETON=true` and PRD-derived context. This is intentional: the PRD informs what the skeleton should prove.
+- **`MVP_MODE` is all-or-nothing per phase, not per task.** A phase is either MVP-mode or standard. Mixed-mode phases are not supported (PRD #2826 Q1).
+- **`TDD_MODE` is independent of `MVP_MODE`.** TDD can be on without MVP, MVP can be on without TDD. Only the *intersection* (both true) activates the MVP+TDD Gate.
+- **The `ccp-roadmapper` agent makes the MVP/standard decision once at project init** based on `PROJECT_MODE`. Per-phase opt-in/out happens later via `/ccp:mvp-phase` or `/ccp:edit-phase`.
+
+## Tests
+
+Structural contract tests for each integration site live under `tests/`:
+
+- `plan-phase-mvp-flag.test.cjs` — plan-phase MVP_MODE resolution chain
+- `planner-mvp-mode.test.cjs` — ccp-planner agent MVP section
+- `mvp-phase-command.test.cjs`, `mvp-phase-integration.test.cjs`, `mvp-phase-spidr.test.cjs` — `/ccp:mvp-phase`
+- `execute-mvp-tdd-gate.test.cjs`, `executor-mvp-tdd-section.test.cjs` — MVP+TDD Gate
+- `verifier-mvp-section.test.cjs`, `verify-mvp-uat.test.cjs` — verifier UAT framing
+- `new-project-mvp-prompt.test.cjs` — mode prompt at init
+- `progress-mvp-display.test.cjs`, `stats-mvp-display.test.cjs`, `graphify-mvp-viz.test.cjs` — discovery surfaces

package/src/pilot/references/planner-graphify-auto-update.md

@@ -0,0 +1,67 @@
+# Graphify Auto-Update — Status Surfacing
+
+> Documents how `ccp-planner` and `ccp-phase-researcher` surface the opt-in graphify auto-update state (issue #3347). The status surface lives inside `graphifyStatus()` in `pilot/bin/lib/graphify.cjs`; no planner-side prompt changes are required.
+
+## Why this exists
+
+The graph at `.planning/graphs/graph.json` is consumed automatically (every `ccp-planner` and `ccp-phase-researcher` step) but produced manually (`/ccp:graphify build` per session at best). Without auto-update, the producer-consumer gap silently widens with every commit. The existing `stale: true` annotation tells the consumer the mtime is old; it cannot tell the consumer whether the auto-build hook has been running, just failed, or is in flight.
+
+When `graphify.auto_update: true`, the bundled `hooks/ccp-graphify-update.sh` PostToolUse hook fires after HEAD-advancing git operations on the default branch and dispatches `graphify update .` in a detached subprocess. The hook writes a status file synchronously before detach; the detached process rewrites it on completion.
+
+## The status file
+
+`.planning/graphs/.last-build-status.json`:
+
+```json
+{
+  "ts": "2026-05-15T14:02:23Z",
+  "status": "running" | "ok" | "failed",
+  "exit_code": null | <int>,
+  "duration_ms": null | <int>,
+  "head_at_build": "<commit-sha>",
+  "graphify_version": null | "<version>"
+}
+```
+
+The hook writes `status: "running"` synchronously **before** detach, so the next planner invocation can see the in-flight signal even if `graphify update .` has not finished. The detached `hooks/lib/ccp-graphify-rebuild.sh` rewrites the file to `ok` or `failed` on completion (with `exit_code` and `duration_ms`).
+
+## How the planner surfaces it (zero new prompt content)
+
+`graphifyStatus()` in `pilot/bin/lib/graphify.cjs` reads `.last-build-status.json` and folds the `running` / `failed` states into the existing `stale: true` signal:
+
+```javascript
+const autoUpdateStale =
+  lastBuildAutoUpdate &&
+  (lastBuildAutoUpdate.status === 'failed' || lastBuildAutoUpdate.status === 'running');
+
+return {
+  ...
+  stale: age > STALE_MS || Boolean(autoUpdateStale),
+  ...
+  last_build_auto_update: lastBuildAutoUpdate || null,
+};
+```
+
+The planner and researcher already run `node ... graphify status` inside their `<step name="load_graph_context">` blocks and already have the rule:
+
+> If the status response has `stale: true`, note for later: "Graph is `{age_hours}h` old — treat semantic relationships as approximate."
+
+That rule now fires correctly in three additional cases:
+
+| Trigger | What user sees |
+|---------|----------------|
+| Auto-build status = `failed` | Existing "treat as approximate" note fires (because `stale: true`). The full `last_build_auto_update` object is in the JSON for callers that want exit-code / duration / commit-sha context. |
+| Auto-build status = `running` | Same — the next planner invocation knows the graph is mid-rebuild and treats it as approximate until the detached process completes. |
+| Auto-build status = `ok` AND mtime < 24h | Annotation is silent — the graph is fresh and the most recent auto-build succeeded. |
+
+The file-missing case is silent (the operator either has not opted in or has not yet triggered a HEAD-advancing git op since enabling).
+
+## Why this design
+
+- **No planner-side prompt changes.** Folding into `stale: true` reuses the existing rule, which means no new content in `agents/ccp-planner.md` (which is already at the `< 48K` decomposition limit per `DEFECT.AGENT-FILE-SIZE-CAP-BREACH`).
+- **Tests catch regressions on the seam.** `tests/feat-3347-graphify-auto-update-config.test.cjs` pins `graphifyStatus` behavior for status=`failed` / `running` / `ok` / file-missing.
+- **Backwards compatible.** Callers that don't read `last_build_auto_update` see the same shape as before, with `stale` reflecting both mtime AND auto-build state. No consumer breakage.
+
+## Opt-in reminder
+
+The auto-update mechanism is opt-in (`graphify.auto_update: false` by default per issue #3347). Users who haven't opted in will never produce this file. `graphifyStatus()` returns `last_build_auto_update: null` and falls back to the mtime-only `stale` rule.

package/src/pilot/references/planner-human-verify-mode.md

@@ -0,0 +1,57 @@
+# Planner — Human Verification Mode
+
+> Loaded by `ccp-planner` when deciding whether to emit `<task type="checkpoint:human-verify">` tasks. Read `workflow.human_verify_mode` from `.planning/config.json` (default `end-of-phase` since #3309).
+
+## The two modes
+
+### `end-of-phase` (default — issue #3309)
+
+Do **not** emit any `<task type="checkpoint:human-verify">` tasks. Every mid-flight halt costs a full executor cold-start (CLAUDE.md, MEMORY.md, STATE.md, plan re-read on respawn) because subagent context is discarded across the pause; a plan with N human-verify checkpoints pays the cold-start cost N+1 times — measured at "tens of thousands of tokens" per round-trip on real projects. This is the default for that reason.
+
+Instead, fold each would-be verification step into the relevant `auto` task using a `<verify><human-check>` sub-block:
+
+```xml
+<task type="auto">
+  <name>Wire dashboard route</name>
+  <files>app/dashboard/page.tsx, app/api/dashboard/route.ts</files>
+  <action>...</action>
+  <verify>
+    <automated>npm test -- --filter=dashboard</automated>
+    <human-check>
+      <test>Visit http://localhost:3000/dashboard</test>
+      <expected>Sidebar left, content right on desktop &gt;1024px; collapses to hamburger at 768px</expected>
+      <why_human>Visual layout — grep cannot verify breakpoint behavior</why_human>
+    </human-check>
+  </verify>
+  <done>Layout renders correctly across breakpoints</done>
+</task>
+```
+
+The verifier (Step 8) harvests every `<verify><human-check>` block at end-of-phase and consolidates them into the existing `human_needed` → HUMAN-UAT.md path in `workflows/execute-phase.md`. The user reviews everything in one batch instead of paying a cold-start cost per item.
+
+### `mid-flight` (opt-back-in — pre-#3309 behavior)
+
+Set `ccp config-set workflow.human_verify_mode mid-flight` to restore the canonical mid-flight pattern: emit `<task type="checkpoint:human-verify">` tasks at the points where human confirmation is required, and the executor halts at each one to ask the user.
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Dev server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    1. Visit /dashboard
+    2. Sidebar collapses at 768px
+  </how-to-verify>
+  <resume-signal>"approved" or describe issues</resume-signal>
+</task>
+```
+
+Choose `mid-flight` when you genuinely need the work to stop before any subsequent task runs (e.g., the next task depends on visual confirmation of the previous one), and you accept the cold-start cost as the price of that hard barrier.
+
+## What is *not* affected
+
+`checkpoint:decision` and `checkpoint:human-action` tasks are still emitted in `end-of-phase` mode. Those gate the work itself (a choice the executor needs from the user, or an auth step only the user can perform), not post-hoc verification of completed work. Only `checkpoint:human-verify` is suppressed.
+
+## Compatibility with other modes
+
+- **`workflow.tdd_mode`**: orthogonal. TDD tasks still emit `tdd="true"` and `<behavior>`; the `<verify>` block carries the human-check sub-element when `human_verify_mode = end-of-phase`.
+- **`MVP_MODE`**: orthogonal. Vertical-slice ordering is unchanged. The first task remains a failing end-to-end test; later auto tasks may carry `<verify><human-check>` instead of standalone checkpoint tasks.
+- **`workflow.auto_advance` / `_auto_chain_active`**: in mid-flight mode these auto-approve checkpoint:human-verify halts. In end-of-phase mode there are no halts to auto-approve, so the flags have no effect on this code path.

package/src/pilot/references/planner-mvp-mode.md

@@ -0,0 +1,53 @@
+# Planner — MVP Mode (Vertical Slice Strategy)
+
+> Loaded by `ccp-planner` only when `MVP_MODE=true`. Standard horizontal-layer planning rules continue to apply for all other phases.
+
+## Core Rule
+
+**Decompose by feature slice, not by technical layer.** Every task must move the user-facing capability forward. After each task, a real user can click through more of the feature than they could before.
+
+**Forbidden** in MVP mode:
+- "Create the database schema" as a standalone task
+- "Build the API layer" as a standalone task
+- "Wire up the UI" as a final integration task
+
+**Required** in MVP mode:
+- The first non-test task produces a working end-to-end path. Stubs are allowed for non-critical branches; the happy path must be real.
+- Each subsequent task either adds a new slice OR refines an existing slice (validation, error states, edge cases).
+- The phase goal is framed as a user story: "**As a** [user], **I want to** [do X], **so that** [Y]."
+
+## Task Order Pattern
+
+For a feature `F`:
+
+1. **Failing end-to-end test** for the happy path of `F`.
+2. **Thinnest viable slice** — UI form → API endpoint → DB read/write — that makes the test pass. Hard-coded values, missing validation, no error states are fine here.
+3. **Real data layer** — replace any stubs from Task 2 with real queries.
+4. **Validation + error states** — invalid input, network failure, empty states.
+5. **Production polish** — loading indicators, edge cases, accessibility checks.
+
+Tasks 3-5 are not always all needed; gate by the phase's acceptance criteria.
+
+## Walking Skeleton Mode (`WALKING_SKELETON=true`)
+
+When the orchestrator sets `WALKING_SKELETON=true` (Phase 1 of a new project under `--mvp`), the plan changes shape:
+
+- The "feature" is the application itself. Pick the smallest meaningful capability that proves the full stack works (e.g., "user can sign up and see their name on a dashboard").
+- The plan **must include**:
+  - Project scaffold (framework init, routing, build, lint)
+  - One real DB read/write
+  - One real UI interaction wired to the API
+  - Deployment to a dev environment (or a documented local-run command that exercises the full stack)
+- The plan **must produce** `SKELETON.md` in the phase directory alongside `PLAN.md`. Use the template at `@~/.claude/pilot/references/skeleton-template.md`. `SKELETON.md` records the architectural decisions that subsequent phases will build on (chosen framework, DB, deployment target, auth approach, directory layout).
+
+`SKELETON.md` is the architectural backbone for every later vertical slice; treat it as a contract, not a scratchpad.
+
+## Anti-Patterns to Reject
+
+- **Layer cake disguised as slices.** Three "vertical" tasks where Task 1 is "all the schemas", Task 2 is "all the endpoints", Task 3 is "all the UI" — that is horizontal planning with new labels. Reject.
+- **Skeleton bloat.** Walking Skeleton is the *thinnest* working stack, not "Phase 1 of a normal app." If Skeleton has more than ~5 tasks, you are not skeletonizing.
+- **Premature SPIDR splitting.** SPIDR splitting is the `mvp-phase` command's job (Phase 2 of the PRD), not the planner's. If the phase scope feels too large, surface it via the verification loop, do not split silently.
+
+## Acceptance Test for Your Plan
+
+Before emitting the plan, ask: **after Task N completes, can a real user *do* something they could not do after Task N-1?** If the answer is "no, but the foundation is laid", you have a horizontal task disguised as a slice. Restructure.

package/src/pilot/references/project-skills-discovery.md

@@ -0,0 +1,19 @@
+# Project Skills Discovery
+
+Before execution, check for project-defined skills and apply their rules.
+
+**Discovery steps (shared across all GSD agents):**
+1. Check `.claude/skills/` or `.agents/skills/` directory — if neither exists, skip.
+2. List available skills (subdirectories).
+3. Read `SKILL.md` for each skill (lightweight index, typically ~130 lines).
+4. Load specific `rules/*.md` files only as needed during the current task.
+5. Do NOT load full `AGENTS.md` files — they are large (100KB+) and cost significant context.
+
+**Application** — how to apply the loaded rules depends on the calling agent:
+- Planners account for project skill patterns and conventions in the plan.
+- Executors follow skill rules relevant to the task being implemented.
+- Researchers ensure research output accounts for project skill patterns.
+- Verifiers apply skill rules when scanning for anti-patterns and verifying quality.
+- Debuggers follow skill rules relevant to the bug being investigated and the fix being applied.
+
+The caller's agent file should specify which application applies.

package/src/pilot/references/revision-loop.md

@@ -0,0 +1,97 @@
+# Revision Loop Pattern
+
+Standard pattern for iterative agent revision with feedback. Used when a checker/validator finds issues and the producing agent needs to revise its output.
+
+---
+
+## Pattern: Check-Revise-Escalate (max 3 iterations)
+
+This pattern applies whenever:
+1. An agent produces output (plans, imports, gap-closure plans)
+2. A checker/validator evaluates that output
+3. Issues are found that need revision
+
+### Flow
+
+```
+prev_issue_count = Infinity
+iteration = 0
+
+LOOP:
+  1. Run checker/validator on current output
+  2. Read checker results
+  3. If PASSED or only INFO-level issues:
+     -> Accept output, exit loop
+  4. If BLOCKER or WARNING issues found:
+     a. iteration += 1
+     b. If iteration > 3:
+        -> Escalate to user (see "After 3 Iterations" below)
+     c. Parse issue count from checker output
+     d. If issue_count >= prev_issue_count:
+        -> Escalate to user: "Revision loop stalled (issue count not decreasing)"
+     e. prev_issue_count = issue_count
+     f. Re-spawn the producing agent with checker feedback appended
+     g. After revision completes, go to LOOP
+```
+
+### Issue Count Tracking
+
+Track the number of BLOCKER + WARNING issues returned by the checker on each iteration. If the count does not decrease between consecutive iterations, the producing agent is stuck and further iterations will not help. Break early and escalate to the user.
+
+Display iteration progress before each revision spawn:
+`Revision iteration {N}/3 -- {blocker_count} blockers, {warning_count} warnings`
+
+### Re-spawn Prompt Structure
+
+When re-spawning the producing agent for revision, pass the checker's YAML-formatted issues. The checker's output contains a `## Issues` heading followed by a YAML block. Parse this block and pass it verbatim to the revision agent.
+
+```
+<checker_issues>
+The issues below are in YAML format. Each has: dimension, severity, finding,
+affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING
+issues where feasible.
+
+{YAML issues block from checker output -- passed verbatim}
+</checker_issues>
+
+<revision_instructions>
+Address ALL BLOCKER and WARNING issues identified above.
+- For each BLOCKER: make the required change
+- For each WARNING: address or explain why it's acceptable
+- Do NOT introduce new issues while fixing existing ones
+- Preserve all content not flagged by the checker
+This is revision iteration {N} of max 3. Previous iteration had {prev_count}
+issues. You must reduce the count or the loop will terminate.
+</revision_instructions>
+```
+
+### After 3 Iterations
+
+If issues persist after 3 revision cycles:
+
+1. Present remaining issues to the user
+2. Use gate prompt (pattern: yes-no from `references/gate-prompts.md`):
+   question: "Issues remain after 3 revision attempts. Proceed with current output?"
+   header: "Proceed?"
+   options:
+     - label: "Proceed anyway"   description: "Accept output with remaining issues"
+     - label: "Adjust approach"  description: "Discuss a different approach"
+3. If "Proceed anyway": accept current output and continue
+4. If "Adjust approach" or "Other": discuss with user, then re-enter the producing step with updated context
+
+### Workflow-Specific Variations
+
+| Workflow | Producer Agent | Checker Agent | Notes |
+|----------|---------------|---------------|-------|
+| plan-phase | gsd-planner | gsd-plan-checker | Revision prompt via planner-revision.md |
+| execute-phase | gsd-executor | gsd-verifier | Post-execution verification |
+| discuss-phase | orchestrator | gsd-plan-checker | Inline revision by orchestrator |
+
+---
+
+## Important Notes
+
+- **INFO-level issues are always acceptable** -- they don't trigger revision
+- **Each iteration gets a fresh agent spawn** -- don't try to continue in the same context
+- **Checker feedback must be inlined** -- the revision agent needs to see exactly what failed
+- **Don't silently swallow issues** -- always present the final state to the user after exiting the loop

package/src/pilot/references/skeleton-template.md

@@ -0,0 +1,48 @@
+# SKELETON.md Template
+
+> Emitted by `ccp-planner` when `WALKING_SKELETON=true` (Phase 1 + `--mvp` + new project). Records the architectural decisions the rest of the project will build on.
+
+```markdown
+# Walking Skeleton — [Project Name]
+
+**Phase:** 1
+**Generated:** {ISO date}
+
+## Capability Proven End-to-End
+
+> One sentence: the smallest user-visible capability that exercises the full stack.
+
+Example: "A signed-in user can view their email on a dashboard page served by the deployed app."
+
+## Architectural Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Framework | (e.g., Next.js 15 App Router) | Why this fits the project |
+| Data layer | (e.g., Postgres + Drizzle) | Why |
+| Auth | (e.g., session cookies + bcrypt) | Why |
+| Deployment target | (e.g., Vercel preview) | Why |
+| Directory layout | (e.g., feature-folders under src/features/*) | Why |
+
+## Stack Touched in Phase 1
+
+- [ ] Project scaffold (framework, build, lint, test runner)
+- [ ] Routing — at least one real route
+- [ ] Database — at least one real read AND one real write
+- [ ] UI — at least one interactive element wired to the API
+- [ ] Deployment — running on dev environment OR documented local full-stack run command
+
+## Out of Scope (Deferred to Later Slices)
+
+> Anything that is *not* in the skeleton. Be explicit — this list prevents future phases from re-litigating Phase 1's minimalism.
+
+- (e.g., password reset, email verification, multi-tenancy)
+
+## Subsequent Slice Plan
+
+Each later phase adds one vertical slice on top of this skeleton without altering its architectural decisions:
+
+- Phase 2: [next user capability]
+- Phase 3: [next user capability]
+- ...
+```

package/src/pilot/references/sketch-interactivity.md

@@ -0,0 +1,41 @@
+# Making Sketches Feel Alive
+
+Static mockups are barely better than screenshots. Every interactive element in a sketch must respond to interaction.
+
+## Required Interactivity
+
+| Element | Must Have |
+|---------|-----------|
+| Buttons | Click handler with visible feedback (state change, animation, toast) |
+| Forms | Input validation on blur, submit handler that shows success state |
+| Lists | Add/remove items, empty state, populated state |
+| Toggles/switches | Working toggle with visible state change |
+| Tabs/nav | Click to switch content |
+| Modals/drawers | Open/close with transition |
+| Hover states | Every clickable element needs a hover effect |
+| Dropdowns | Open/close, item selection |
+
+## Transitions
+
+Add `transition: all 0.15s ease` as a baseline to interactive elements. Subtle motion makes the sketch feel real and helps judge whether the interaction pattern works.
+
+## Fake the Backend
+
+If the sketch shows a "Save" button, clicking it should show a brief loading state then a success message. If it shows a search bar, typing should filter hardcoded results. The goal is to feel the full interaction loop, not just see the resting state.
+
+## State Cycling
+
+If the sketch has multiple states (empty, loading, populated, error), include buttons to cycle through them. Label each state clearly. This lets the user experience how the design handles different data conditions.
+
+## Implementation
+
+Use vanilla JS in inline `<script>` tags. No frameworks, no build step. Keep it simple:
+
+```html
+<script>
+  // Toggle a panel
+  document.querySelector('.panel-toggle').addEventListener('click', (e) => {
+    e.target.closest('.panel').classList.toggle('collapsed');
+  });
+</script>
+```

package/src/pilot/references/sketch-theme-system.md

@@ -0,0 +1,94 @@
+# Shared Theme System
+
+All sketches share a CSS variable theme so design decisions compound across sketches.
+
+## Setup
+
+On the first sketch, create `.planning/sketches/themes/` with a default theme:
+
+```
+.planning/sketches/
+  themes/
+    default.css         <- all sketches link to this
+  001-dashboard-layout/
+    index.html          <- links to ../themes/default.css
+```
+
+## Theme File Structure
+
+Each theme defines CSS custom properties only — no component styles, no layout rules. Just the visual vocabulary:
+
+```css
+:root {
+  /* Colors */
+  --color-bg: #fafafa;
+  --color-surface: #ffffff;
+  --color-border: #e5e5e5;
+  --color-text: #1a1a1a;
+  --color-text-muted: #6b6b6b;
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+  --color-accent: #f59e0b;
+  --color-danger: #ef4444;
+  --color-success: #22c55e;
+
+  /* Typography */
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+
+  /* Spacing */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+
+  /* Shapes */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+  --shadow-md: 0 4px 6px rgba(0,0,0,0.07);
+  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);
+}
+```
+
+Adapt the default theme to match the mood/direction established during intake. The values above are a starting point — change colors, fonts, spacing, and shapes to match the agreed aesthetic.
+
+## Linking
+
+Every sketch links to the theme:
+
+```html
+<link rel="stylesheet" href="../themes/default.css">
+```
+
+## Creating New Themes
+
+When a sketch reveals an aesthetic fork ("should this feel clinical or warm?"), create both as theme files rather than arguing about it. The user can switch and feel the difference.
+
+Name themes descriptively: `midnight.css`, `warm-minimal.css`, `brutalist.css`.
+
+## Theme Switcher
+
+Include in every sketch (part of the sketch toolbar):
+
+```html
+<select id="theme-switcher" onchange="document.querySelector('link[href*=themes]').href='../themes/'+this.value+'.css'">
+  <option value="default">Default</option>
+</select>
+```
+
+Dynamically populate options by listing available theme files, or hardcode the known themes.

package/src/pilot/references/sketch-tooling.md

@@ -0,0 +1,45 @@
+# Sketch Toolbar
+
+Include a small floating toolbar in every sketch. It provides utilities without competing with the actual design.
+
+## Implementation
+
+A small `<div>` fixed to the bottom-right, semi-transparent, expands on hover:
+
+```html
+<div id="sketch-tools" style="position:fixed;bottom:12px;right:12px;z-index:9999;font-family:system-ui;font-size:12px;background:rgba(0,0,0,0.7);color:white;padding:8px 12px;border-radius:8px;opacity:0.4;transition:opacity 0.2s;" onmouseenter="this.style.opacity='1'" onmouseleave="this.style.opacity='0.4'">
+  <!-- Theme switcher -->
+  <!-- Viewport buttons -->
+  <!-- Annotation toggle -->
+</div>
+```
+
+## Components
+
+### Theme Switcher
+
+A dropdown that swaps the theme CSS file at runtime:
+
+```html
+<select onchange="document.querySelector('link[href*=themes]').href='../themes/'+this.value+'.css'">
+  <option value="default">Default</option>
+</select>
+```
+
+### Viewport Preview
+
+Three buttons that constrain the sketch content area to standard widths:
+
+- Phone: 375px
+- Tablet: 768px
+- Desktop: 1280px (or full width)
+
+Implemented by wrapping sketch content in a container and adjusting its `max-width`.
+
+### Annotation Mode
+
+A toggle that overlays spacing values, color hex codes, and font sizes on hover. Implemented as a JS snippet that reads computed styles and shows them in a tooltip. Helps understand visual decisions without opening dev tools.
+
+## Styling
+
+The toolbar should be unobtrusive — small, dark, semi-transparent. It should never compete with the sketch visually. Style it independently of the theme (hardcoded dark background, white text).