cclaw-cli 0.15.0 → 0.15.1

package/dist/content/stages/brainstorm.d.ts

@@ -0,0 +1,2 @@
+import type { StageSchemaInput } from "./schema-types.js";
+export declare const BRAINSTORM: StageSchemaInput;

package/dist/content/stages/brainstorm.js

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// BRAINSTORM — reference: superpowers brainstorming
+// ---------------------------------------------------------------------------
+export const BRAINSTORM = {
+    stage: "brainstorm",
+    skillFolder: "brainstorming",
+    skillName: "brainstorming",
+    skillDescription: "Design-first stage. Explore context, understand intent through collaborative dialogue, propose distinct approaches, and lock an approved direction before scope/design work.",
+    hardGate: "Do NOT invoke implementation skills, write code, scaffold projects, or mutate product behavior until a concrete direction is approved by the user.",
+    ironLaw: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY APPROVED DIRECTION — SILENCE IS NOT APPROVAL.",
+    purpose: "Turn an initial idea into an approved design direction through natural collaborative dialogue — understanding the problem before proposing solutions.",
+    whenToUse: [
+        "Starting a new feature or behavior change",
+        "Requirements are ambiguous or trade-offs are unclear",
+        "Before any implementation-stage command or architecture commitment"
+    ],
+    whenNotToUse: [
+        "A valid approved direction already exists and only execution remains",
+        "The request is a pure release/finalization action with no new product decisions",
+        "The task is retrospective only (post-ship audit with no new solution choices)"
+    ],
+    checklist: [
+        "**Explore project context** — check files, docs, recent commits to understand what already exists.",
+        "**Assess scope** — if the request covers multiple independent subsystems, flag it and help decompose before deep-diving. Each sub-project gets its own brainstorm cycle.",
+        "**Ask clarifying questions** — one at a time, understand purpose, constraints, and success criteria. Prefer multiple choice when possible. Each question should change what we build, not just gather trivia.",
+        "**Propose 2-3 architecturally distinct approaches** — with real trade-offs and your recommendation. Lead with the recommended option and explain why.",
+        "**Present design by sections** — scale each section to its complexity. Ask after each section whether it looks right so far. Cover: architecture, key components, data flow.",
+        "**Write artifact** to `.cclaw/artifacts/01-brainstorm.md`.",
+        "**Self-review** — scan for placeholders/TODOs, check internal consistency, verify scope is focused, resolve any ambiguity.",
+        "**User reviews artifact** — ask the user to review the written artifact and explicitly approve or request changes.",
+        "**Handoff** — only then complete stage and point to `/cc-next`."
+    ],
+    interactionProtocol: [
+        "Explore what exists before asking what to build — check project files first.",
+        "If the idea is vague or could mean many different things, your FIRST question narrows to a specific kind of project. Do not ask detail questions until the project type is clear.",
+        "Ask exactly one question per turn. Prefer multiple choice. No bundled questions.",
+        "After 2-3 questions, summarize your emerging understanding before continuing so the user can correct course early.",
+        "Each question should change a concrete design decision. Litmus test: if the two most likely answers do not lead to different architectures, make the choice yourself and state it.",
+        "Present design in sections scaled to their complexity — a few sentences for simple aspects, detailed for nuanced ones. Get approval after each section.",
+        "When proposing approaches, lead with your recommendation and explain why.",
+        "State explicitly what is being approved when requesting approval.",
+        "Run a brief self-review (placeholders, contradictions, scope, ambiguity) before presenting the artifact.",
+        "**STOP.** Wait for explicit user approval after writing the artifact. Do NOT auto-advance."
+    ],
+    process: [
+        "Explore project context: check files, docs, recent activity.",
+        "Assess scope: flag if request is too broad, help decompose first.",
+        "Ask clarifying questions one at a time — focus on purpose, constraints, success criteria.",
+        "Propose 2-3 architecturally distinct approaches with trade-offs and a recommendation.",
+        "Present design sections incrementally, get approval after each.",
+        "Write approved direction to `.cclaw/artifacts/01-brainstorm.md`.",
+        "Self-review: placeholder scan, internal consistency, scope check, ambiguity check.",
+        "Request explicit user approval of the artifact.",
+        "Handoff to scope only after approval is explicit."
+    ],
+    requiredGates: [
+        { id: "brainstorm_context_explored", description: "Project context (files, docs, existing patterns) was checked before asking questions." },
+        { id: "brainstorm_idea_understood", description: "Agent and user share the same understanding of the problem, constraints, and success criteria." },
+        { id: "brainstorm_approaches_compared", description: "2-3 architecturally distinct approaches were compared with real trade-offs and a recommendation." },
+        { id: "brainstorm_direction_approved", description: "User approved a concrete direction and what exactly was approved is stated." },
+        { id: "brainstorm_artifact_reviewed", description: "User reviewed the written brainstorm artifact and confirmed readiness." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
+        "Project context was explored (files, docs, or recent activity referenced).",
+        "Clarifying questions and their answers are captured.",
+        "2-3 approaches with trade-offs and recommendation are recorded.",
+        "Approved direction and approval marker are present.",
+        "Assumptions and open questions are captured (or explicitly marked as none)."
+    ],
+    inputs: ["problem statement", "constraints", "success criteria"],
+    requiredContext: [
+        "existing project context and patterns",
+        "current behavior of affected area",
+        "business and delivery constraints"
+    ],
+    researchPlaybooks: [
+        "research/repo-scan.md",
+        "research/learnings-lookup.md"
+    ],
+    outputs: [
+        "approved design direction",
+        "alternatives with trade-offs",
+        "brainstorm artifact"
+    ],
+    blockers: [
+        "no explicit approval",
+        "critical ambiguity unresolved",
+        "project context not explored"
+    ],
+    exitCriteria: [
+        "approved design direction documented",
+        "required gates marked satisfied",
+        "no implementation action taken",
+        "artifact reviewed by user"
+    ],
+    antiPatterns: [
+        "Asking questions without exploring existing project context first",
+        "Asking bundled or purely informational questions that don't change decisions",
+        "Proposing cosmetic option variants instead of architecturally distinct approaches",
+        "Jumping directly into implementation",
+        "Requesting approval without stating what decision is being approved"
+    ],
+    redFlags: [
+        "No project context exploration before questions",
+        "Questions that only gather preferences without design impact",
+        "Options that are variants of one approach, not distinct alternatives",
+        "Approval requested without explicit decision context"
+    ],
+    policyNeedles: [
+        "Explore project context",
+        "One question at a time",
+        "2-3 architecturally distinct approaches",
+        "State what is being approved",
+        "Self-review before handoff",
+        "Do NOT implement, scaffold, or modify behavior"
+    ],
+    artifactFile: "01-brainstorm.md",
+    next: "scope",
+    reviewSections: [],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [],
+        writesTo: [".cclaw/artifacts/01-brainstorm.md"],
+        traceabilityRule: "Scope and design decisions must trace back to explored context and approved brainstorm direction."
+    },
+    artifactValidation: [
+        { section: "Context", required: true, validationRule: "Must reference project state and relevant existing code or patterns." },
+        { section: "Problem", required: true, validationRule: "Must define what we're solving, success criteria, and constraints." },
+        { section: "Clarifying Questions", required: true, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
+        { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs and recommendation." },
+        { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, rationale, and explicit approval marker." },
+        { section: "Design", required: true, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
+        { section: "Assumptions and Open Questions", required: true, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }
+    ]
+};

package/dist/content/stages/design.d.ts

@@ -0,0 +1,2 @@
+import type { StageSchemaInput } from "./schema-types.js";
+export declare const DESIGN: StageSchemaInput;

package/dist/content/stages/design.js

@@ -0,0 +1,215 @@
+// ---------------------------------------------------------------------------
+// DESIGN — reference: gstack Eng review
+// ---------------------------------------------------------------------------
+export const DESIGN = {
+    stage: "design",
+    skillFolder: "engineering-design-lock",
+    skillName: "engineering-design-lock",
+    skillDescription: "Engineering lock-in stage. Build a concrete technical spine before spec and planning, with section-by-section interactive review.",
+    hardGate: "Do NOT write implementation code. This stage produces design decisions and architecture documents only. No code changes, no scaffolding, no test files.",
+    ironLaw: "NO DESIGN DECISION WITHOUT A LABELED DIAGRAM, A REJECTED ALTERNATIVE, AND A NAMED FAILURE MODE.",
+    purpose: "Lock architecture, data flow, failure modes, and test/performance expectations through rigorous interactive review.",
+    whenToUse: [
+        "After scope contract approval",
+        "Before writing final spec and execution plan",
+        "When architecture risks need explicit treatment"
+    ],
+    whenNotToUse: [
+        "Scope mode and boundaries are still unresolved",
+        "The change is docs-only or metadata-only with no architecture impact",
+        "Implementation has already started and requires review instead of design lock"
+    ],
+    checklist: [
+        "Trivial-Change Escape Hatch — If scope artifact shows ≤3 files, zero new interfaces, and no cross-module data flow, skip full review sections. Produce a mini-design: one paragraph of rationale, list of changed files, one risk to watch. Proceed to spec.",
+        "Design Doc Check — read existing design docs, scope artifact, brainstorm artifact. If a design doc exists that covers this area, check for 'Supersedes:' and use the latest. Use upstream artifacts as source of truth.",
+        "Codebase Investigation — Before any design decision, read the actual code in the blast radius. List every file that will be touched, its current responsibilities, and existing patterns (error handling, naming, test style). Design must conform to discovered patterns, not impose new ones without justification.",
+        "Step 0: Scope Challenge — what existing code solves sub-problems? Minimum change set? Complexity check: 8+ files or 2+ new services = complexity smell → flag for possible scope reduction.",
+        "Search Before Building — For each technical choice (library, pattern, architecture), search for existing solutions. Label findings: Layer 1 (exact match), Layer 2 (partial match, needs adaptation), Layer 3 (inspiration only), EUREKA (unexpected perfect solution). Default to existing before custom.",
+        "Architecture Review — system design, component boundaries, data flow, scaling, security architecture. For each new codepath: one realistic production failure scenario. **Mandatory:** produce at least one architecture diagram (ASCII, Mermaid, or tool-generated) showing component boundaries and data flow direction. Apply the **Visual Communication rules** (see below) — an unlabeled or generic diagram is worse than no diagram, because it pretends to encode decisions it does not.",
+        "Code Quality Review — code organization, DRY violations, error handling patterns, over/under-engineering assessment.",
+        "Test Review — diagram every new flow, data path, error path. For each: what test type covers it? Does one exist? What is the gap? Produce test plan artifact.",
+        "Performance Review — N+1 queries, memory concerns, caching opportunities, slow code paths. What breaks at 10x load? At 100x?",
+        "Parallelization Strategy — If multiple independent modules, produce dependency table: which can be built in parallel? Where are conflict risks? Flag shared-state modules.",
+        "Unresolved Decisions — List any design decisions that could not be resolved in this session. For each: what information is missing? Who can provide it? What is the default if no answer comes?",
+        "Distribution Check — If the plan creates new artifact types (packages, CLI tools, configs), document the build/publish story. How does it reach the user?",
+        "Deferred Items Cross-Reference — Collect every item explicitly deferred during design review. Each must appear in the Unresolved Decisions table or in the upstream scope artifact's deferred list. No deferred item may exist only in conversation — it must be written down."
+    ],
+    interactionProtocol: [
+        "Review architecture decisions section-by-section.",
+        "For EACH issue found in a review section, present it ONE AT A TIME. Do NOT batch multiple issues.",
+        "For each issue: use the Decision Protocol — describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that best covers architecture, data-flow, failure-modes, test, and perf review concerns for the issue with the lowest risk. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "Only proceed to the next review section after ALL issues in the current section are resolved.",
+        "If a section has no issues, say 'No issues found' and move on.",
+        "Do not skip failure-mode mapping.",
+        "For design baseline approval: present the full baseline. **STOP.** Do NOT proceed until user explicitly approves the design.",
+        "Take a firm position on every recommendation. Do NOT hedge with 'it depends' or 'you could do either'. State your opinion, then justify it.",
+        "Use pushback patterns for weak framing: if the user says 'it's just a small change', respond with 'small changes to shared interfaces have outsized blast radius — let's map it'. If 'we'll refactor later', respond with 'later never comes — show me the refactor ticket or do it now'.",
+        "When the user's proposed architecture is suboptimal, say so directly. Offer the alternative with concrete trade-offs, do not bury criticism in praise.",
+        "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity."
+    ],
+    process: [
+        "Read upstream artifacts (brainstorm, scope).",
+        "Investigate codebase: read files in blast radius, catalogue current patterns and responsibilities.",
+        "Run Step 0 scope challenge: existing code leverage, minimum change set, complexity check.",
+        "Walk through each review section interactively.",
+        "Define architecture boundaries and ownership.",
+        "Describe data flow and state transitions with edge paths.",
+        "Map failure modes and recovery strategy.",
+        "Define test coverage strategy and performance budget.",
+        "Produce required outputs: NOT-in-scope section, What-already-exists section, diagrams, failure mode table.",
+        "Produce completion dashboard: list every review section with status (clear / issues-found-resolved / issues-open), count of decisions made, and list of unresolved items.",
+        "Write design lock artifact for downstream spec/plan."
+    ],
+    requiredGates: [
+        { id: "design_codebase_investigated", description: "Blast-radius files read and current patterns catalogued." },
+        { id: "design_scope_challenge_done", description: "Step 0 scope challenge completed with existing-code mapping." },
+        { id: "design_architecture_locked", description: "Architecture boundaries are explicit and approved." },
+        { id: "design_data_flow_mapped", description: "Data/state flow includes edge-case paths." },
+        { id: "design_failure_modes_mapped", description: "Failure modes and mitigations are documented." },
+        { id: "design_test_and_perf_defined", description: "Test strategy and performance budget are defined." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/03-design.md`.",
+        "Failure-mode table exists with mitigations.",
+        "Test strategy includes unit/integration/e2e expectations.",
+        "NOT-in-scope section produced.",
+        "What-already-exists section produced.",
+        "Completion dashboard lists every review section status, decision count, and unresolved items (or 'None')."
+    ],
+    inputs: ["scope contract", "system constraints", "non-functional requirements"],
+    requiredContext: [
+        "existing architecture and boundaries",
+        "operational constraints",
+        "security and reliability expectations"
+    ],
+    researchPlaybooks: [
+        "research/framework-docs-lookup.md",
+        "research/best-practices-lookup.md"
+    ],
+    outputs: [
+        "architecture lock",
+        "risk and failure map",
+        "test and performance baseline",
+        "NOT-in-scope section",
+        "What-already-exists section",
+        "design completion dashboard"
+    ],
+    blockers: [
+        "architecture ambiguity remains",
+        "failure modes not mapped",
+        "test/performance targets missing"
+    ],
+    exitCriteria: [
+        "design baseline approved",
+        "all review sections completed",
+        "required gates marked satisfied",
+        "completion dashboard present with all review-section statuses",
+        "artifact complete for spec handoff"
+    ],
+    antiPatterns: [
+        "Architecture deferred to implementation phase",
+        "Missing data-flow edge cases",
+        "No performance budget for critical path",
+        "Batching multiple design issues into one question",
+        "Skipping review sections because plan seems simple",
+        "Agreeing with user's architecture choice without evaluating alternatives",
+        "Hedging every recommendation with 'it depends' instead of taking a position"
+    ],
+    redFlags: [
+        "No explicit architecture boundary section",
+        "No failure recovery strategy",
+        "No defined test/perf baseline",
+        "Review sections skipped or condensed",
+        "No NOT-in-scope output section",
+        "No What-already-exists output section",
+        "Design decisions made without reading the actual code first"
+    ],
+    policyNeedles: [
+        "Architecture",
+        "Data Flow",
+        "Failure Modes and Mitigation",
+        "Performance Budget",
+        "One issue at a time"
+    ],
+    artifactFile: "03-design.md",
+    next: "spec",
+    reviewSections: [
+        {
+            title: "Architecture Review",
+            evaluationPoints: [
+                "System design and component boundaries",
+                "Dependency graph and coupling concerns",
+                "Data flow patterns and potential bottlenecks",
+                "Scaling characteristics and single points of failure",
+                "Security architecture (auth, data access, API boundaries)",
+                "For each new codepath: one realistic production failure scenario"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Code Quality Review",
+            evaluationPoints: [
+                "Code organization and module structure",
+                "DRY violations — flag aggressively",
+                "Error handling patterns and missing edge cases",
+                "Over-engineered or under-engineered areas",
+                "Existing diagrams in touched files — still accurate?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Test Review",
+            evaluationPoints: [
+                "Diagram every new UX flow, data flow, codepath, background job, integration, error path",
+                "For each: what type of test covers it? Does one exist? What is the gap?",
+                "Coverage expectations: unit, integration, e2e split"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Performance Review",
+            evaluationPoints: [
+                "N+1 queries and database access patterns",
+                "Memory-usage concerns",
+                "Caching opportunities",
+                "Slow or high-complexity code paths",
+                "What breaks at 10x load? At 100x?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Distribution & Delivery Review",
+            evaluationPoints: [
+                "If new artifact types are created (packages, CLI, configs): is the build/publish story documented?",
+                "Are there new dependencies that need version pinning?",
+                "Does the change affect existing consumers (APIs, shared modules)?",
+                "Is backwards compatibility maintained or is a migration needed?"
+            ],
+            stopGate: false
+        }
+    ],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/01-brainstorm.md", ".cclaw/artifacts/02-scope.md"],
+        writesTo: [".cclaw/artifacts/03-design.md"],
+        traceabilityRule: "Every architecture decision must trace to a scope boundary. Every downstream spec requirement must trace to a design decision."
+    },
+    artifactValidation: [
+        { section: "Codebase Investigation", required: true, validationRule: "Must list blast-radius files with current responsibilities and discovered patterns." },
+        { section: "Search Before Building", required: true, validationRule: "For each technical choice: Layer 1 (exact match), Layer 2 (partial match), Layer 3 (inspiration), EUREKA labels with reuse-first default." },
+        { section: "Architecture Boundaries", required: true, validationRule: "Must list component boundaries with ownership." },
+        { section: "Architecture Diagram", required: true, validationRule: "At least one diagram (ASCII, Mermaid, or image) showing component boundaries and data flow direction. Diagram must: (1) label every node with a concrete component name (no generic 'Service A/B'), (2) label every arrow with the action or message (no unlabeled arrows), (3) mark direction of data flow explicitly, (4) distinguish synchronous from asynchronous edges (e.g. solid vs dashed, or `sync:` / `async:` prefix), (5) show at least one failure edge or degraded-mode branch when the system has one." },
+        { section: "Data Flow", required: true, validationRule: "Must include happy path, nil input, empty input, upstream error paths." },
+        { section: "Failure Mode Table", required: true, validationRule: "Each failure mode has: trigger, detection, mitigation, user impact." },
+        { section: "Test Strategy", required: true, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
+        { section: "Performance Budget", required: true, validationRule: "For each critical path: metric name, target threshold, and measurement method." },
+        { section: "What Already Exists", required: true, validationRule: "For each sub-problem: existing code/library found (Layer 1-3/EUREKA label), reuse decision, and adaptation needed." },
+        { section: "NOT in scope", required: true, validationRule: "Work considered and explicitly deferred with one-line rationale." },
+        { section: "Parallelization Strategy", required: false, validationRule: "If multi-module: dependency table, parallel lanes, conflict flags." },
+        { section: "Unresolved Decisions", required: false, validationRule: "If any: what info is missing, who provides it, default if unanswered." },
+        { section: "Interface Contracts", required: false, validationRule: "If present: for each module boundary list produces (outputs) and consumes (inputs) with data types." },
+        { section: "Patterns to Mirror", required: false, validationRule: "If present: list discovered codebase patterns to follow, with file references and rationale for each." },
+        { section: "Completion Dashboard", required: true, validationRule: "Lists every review section with status (clear / issues-found-resolved / issues-open), decision count, and unresolved items (or 'None')." }
+    ],
+    trivialOverrideSections: ["Architecture Boundaries", "NOT in scope", "Completion Dashboard"]
+};

package/dist/content/stages/index.d.ts

@@ -0,0 +1,8 @@
+export { BRAINSTORM } from "./brainstorm.js";
+export { SCOPE } from "./scope.js";
+export { DESIGN } from "./design.js";
+export { SPEC } from "./spec.js";
+export { PLAN } from "./plan.js";
+export { TDD } from "./tdd.js";
+export { REVIEW } from "./review.js";
+export { SHIP } from "./ship.js";

package/dist/content/stages/index.js

@@ -0,0 +1,11 @@
+// Barrel for per-stage StageSchemaInput constants. Keep this file lean — it
+// should be a pure re-export surface so stage-schema.ts can import all stages
+// via a single `import { ... } from "./stages/index.js"`.
+export { BRAINSTORM } from "./brainstorm.js";
+export { SCOPE } from "./scope.js";
+export { DESIGN } from "./design.js";
+export { SPEC } from "./spec.js";
+export { PLAN } from "./plan.js";
+export { TDD } from "./tdd.js";
+export { REVIEW } from "./review.js";
+export { SHIP } from "./ship.js";

package/dist/content/stages/plan.d.ts

@@ -0,0 +1,2 @@
+import type { StageSchemaInput } from "./schema-types.js";
+export declare const PLAN: StageSchemaInput;

package/dist/content/stages/plan.js

@@ -0,0 +1,146 @@
+// ---------------------------------------------------------------------------
+// PLAN
+// ---------------------------------------------------------------------------
+export const PLAN = {
+    stage: "plan",
+    skillFolder: "planning-and-task-breakdown",
+    skillName: "planning-and-task-breakdown",
+    skillDescription: "Execution planning stage with strict confirmation gate before implementation.",
+    hardGate: "Do NOT write code or tests. Planning only. This stage produces a task graph and execution order. WAIT_FOR_CONFIRM before any handoff to implementation.",
+    ironLaw: "EVERY TASK IS 2–5 MINUTES, FULLY SPELLED OUT, AND CARRIES A STABLE ID — NO PLACEHOLDERS, NO ‘ETC.’.",
+    purpose: "Create small executable tasks with dependencies and pause for explicit user confirmation.",
+    whenToUse: [
+        "After spec approval",
+        "Before writing tests or implementation",
+        "When delivery path and dependency order are needed"
+    ],
+    whenNotToUse: [
+        "Specification is unapproved or lacks measurable acceptance criteria",
+        "Execution is already in TDD stage with active slice evidence",
+        "The request is only release packaging with no task decomposition needed"
+    ],
+    checklist: [
+        "Read upstream — load spec, design, and scope artifacts. Cross-reference acceptance criteria.",
+        "Build dependency graph — identify task ordering, parallel opportunities, and blocking dependencies.",
+        "Group tasks into dependency waves — wave N+1 cannot start until wave N has verification evidence.",
+        "Slice into vertical tasks — each task targets 2-5 minutes, produces one testable outcome, and touches one coherent area.",
+        "Attach verification — every task has an acceptance criterion mapping and a concrete verification command.",
+        "Define checkpoints — mark points where progress should be validated before continuing.",
+        "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. **STOP.** Do NOT proceed until user confirms. Then update `flow-state.json` and tell user to run `/cc-next`."
+    ],
+    interactionProtocol: [
+        "Plan in read-only mode relative to implementation.",
+        "Split work into small vertical slices (target 2-5 minute tasks).",
+        "Publish explicit dependency waves with entry and exit checks for each wave.",
+        "Attach verification step to every task.",
+        "Enforce WAIT_FOR_CONFIRM: present the plan summary with options (A) Approve / (B) Revise / (C) Reject.",
+        "**STOP.** Do NOT proceed until user explicitly approves. Then update `flow-state.json` and tell user to run `/cc-next`."
+    ],
+    process: [
+        "Build dependency graph and ordered slices.",
+        "Group slices into execution waves and define gate criteria per wave.",
+        "Define each task with acceptance mapping and verification commands.",
+        "Record checkpoints and blockers.",
+        "Write plan artifact and pause at WAIT_FOR_CONFIRM."
+    ],
+    requiredGates: [
+        { id: "plan_tasks_sliced_2_5_min", description: "Tasks are small, executable slices." },
+        { id: "plan_dependency_graph_written", description: "Dependency graph and order are explicit." },
+        { id: "plan_dependency_waves_defined", description: "Tasks are grouped into executable waves with gate checks." },
+        { id: "plan_verification_steps_defined", description: "Each task has verification guidance." },
+        { id: "plan_acceptance_mapped", description: "Each task maps to a spec acceptance criterion." },
+        { id: "plan_wait_for_confirm", description: "Execution blocked until explicit user confirmation." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/05-plan.md`.",
+        "Task list includes acceptance mapping.",
+        "Dependency graph documented.",
+        "Dependency waves documented with wave-by-wave verification gates.",
+        "WAIT_FOR_CONFIRM status recorded."
+    ],
+    inputs: ["approved spec", "codebase context", "delivery constraints"],
+    requiredContext: [
+        "spec acceptance criteria",
+        "current architecture",
+        "known technical debt and dependencies"
+    ],
+    outputs: ["task graph", "dependency wave plan", "ordered plan", "explicit confirmation checkpoint"],
+    blockers: [
+        "tasks too broad",
+        "dependency uncertainty unresolved",
+        "wave boundaries are unclear",
+        "no explicit confirmation"
+    ],
+    exitCriteria: [
+        "plan quality gates complete",
+        "WAIT_FOR_CONFIRM present and unresolved until user approves",
+        "artifact ready for TDD execution",
+        "acceptance mapping complete"
+    ],
+    antiPatterns: [
+        "Horizontal decomposition without end-to-end slices",
+        "Tasks without verification steps",
+        "Starting execution before approval",
+        "Tasks that touch multiple unrelated areas"
+    ],
+    redFlags: [
+        "No dependency graph",
+        "No WAIT_FOR_CONFIRM marker",
+        "No explicit dependency waves",
+        "Tasks exceed one coherent outcome",
+        "No acceptance mapping"
+    ],
+    policyNeedles: ["WAIT_FOR_CONFIRM", "Task Graph", "Dependency Waves", "Acceptance Mapping", "verification steps"],
+    artifactFile: "05-plan.md",
+    next: "tdd",
+    reviewSections: [
+        {
+            title: "Task Decomposition Audit",
+            evaluationPoints: [
+                "Does every task target a single coherent area (vertical slice)?",
+                "Can each task be completed in 2-5 minutes?",
+                "Does every task have an acceptance criterion link and verification command?",
+                "Are there tasks that touch multiple unrelated areas?",
+                "Would a new engineer understand and start each task within two minutes?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Wave Completeness Audit",
+            evaluationPoints: [
+                "Does every task belong to exactly one wave?",
+                "Does each wave have a verification gate?",
+                "Are wave dependencies explicit and acyclic?",
+                "Is the acceptance mapping complete — every spec criterion covered?",
+                "Are there hidden dependencies between tasks in different waves?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Five-Minute Budget + No-Placeholders Audit",
+            evaluationPoints: [
+                "Does every task carry an explicit minutes estimate (e.g. `[~3m]`) and does every estimate fit the 2-to-5-minute budget? Estimates >5 minutes must be split.",
+                "Are all file paths, test commands, and verification commands copy-pasteable as written — no `TODO`, `TBD`, `FIXME`, `<fill-in>`, `<your-*-here>`, `xxx`, or ellipsis standing in for omitted args?",
+                "Does every acceptance-criterion reference resolve to a real R# / AC-### in the spec (not a blank link)?",
+                "If an estimate is genuinely uncertain (first-time integration, unfamiliar library), is the uncertainty named explicitly and scheduled as a spike task in wave 0, rather than hidden behind a large estimate?"
+            ],
+            stopGate: true
+        }
+    ],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
+        writesTo: [".cclaw/artifacts/05-plan.md"],
+        traceabilityRule: "Every task must trace to a spec acceptance criterion. Every downstream RED test must trace to a plan task."
+    },
+    artifactValidation: [
+        { section: "Dependency Graph", required: true, validationRule: "Ordering and parallel opportunities explicit. No circular dependencies." },
+        { section: "Dependency Waves", required: true, validationRule: "Every task belongs to a wave. Each wave has an exit gate and dependency statement." },
+        { section: "Task List", required: true, validationRule: "Each task row includes ID, description, acceptance criterion, verification command, and effort estimate (S/M/L). Every task must also carry a minutes estimate within the 2-5 minute budget." },
+        { section: "Acceptance Mapping", required: true, validationRule: "Every spec criterion is covered by at least one task." },
+        { section: "Risk Assessment", required: false, validationRule: "If present: per-task or per-wave risk identification with likelihood, impact, and mitigation strategy." },
+        { section: "Boundary Map", required: false, validationRule: "If present: per-wave or per-task interface contracts listing what each task produces (exports) and consumes (imports) from other tasks." },
+        { section: "WAIT_FOR_CONFIRM", required: true, validationRule: "Explicit marker present. Status: pending until user approves." },
+        { section: "No-Placeholder Scan", required: false, validationRule: "If present: confirmation that a text scan for `TODO`, `TBD`, `FIXME`, `<fill-in>`, `<your-*-here>`, `xxx`, or bare ellipses has zero hits in the task list. A placeholder is a deferred decision masquerading as a plan." }
+    ]
+};

package/dist/content/stages/review.d.ts

@@ -0,0 +1,2 @@
+import type { StageSchemaInput } from "./schema-types.js";
+export declare const REVIEW: StageSchemaInput;