cclaw-cli 0.4.0 → 0.5.1

package/dist/content/stage-schema.js

@@ -36,38 +36,44 @@ const BRAINSTORM = {
         "The task is purely retrospective after ship with no new design decisions needed"
     ],
     checklist: [
-        "Explore project context — check files, docs, recent commits, existing behavior.",
+        "Explore project context — check files, docs, recent commits, existing behavior. Summarize what you found (even for seemingly simple projects).",
         "Assess scope — if the request describes multiple independent subsystems, flag for decomposition before detailed questions.",
-        "Ask clarifying questions — one at a time, understand purpose, constraints, success criteria. For straightforward requests, ask no more than 1-2 clarifying questions before presenting options.",
-        "Propose 2-3 approaches — with trade-offs and your explicit recommendation with reasoning.",
-        "Present design — in sections scaled to their complexity (few sentences if simple, up to 300 words if nuanced). Get approval after each section.",
+        "Restate the problem — before any questions, summarize what you understood the user wants and why. Ask the user to confirm or correct your understanding.",
+        "Ask clarifying questions — one at a time, understand purpose, constraints, success criteria, target users, and edge cases. Continue until you can confidently describe the solution space. Minimum: understand the WHY, WHO, WHAT, and boundary conditions.",
+        "Propose 2-3 approaches — with real trade-offs (not cosmetic differences) and your explicit recommendation with reasoning. Explain WHY you recommend this option over others.",
+        "Present design — in sections. After each section, explicitly state what you are asking the user to approve: 'Do you approve [specific thing]?' Never ask a bare 'одобряете?/approve?' without context.",
         "Write design doc — save to `.cclaw/artifacts/01-brainstorm.md`.",
         "Self-review — scan for placeholders, TBDs, contradictions, ambiguity, scope creep. Fix inline.",
-        "User reviews written artifact — ask user to review before proceeding. **STOP.** Do NOT proceed until user responds.",
+        "User reviews written artifact — ask user to review the written artifact (not the chat summary). **STOP.** Do NOT proceed until user responds.",
         "Stage complete — update `flow-state.json` per the Stage Completion Protocol. Tell user to run `/cc-next` to continue to scope."
     ],
     interactionProtocol: [
-        "Explore context first (files, docs, existing behavior).",
-        "Ask one clarifying question per message. Do NOT combine questions.",
-        "For approach selection: use the Decision Protocol — present labeled options (A/B/C) with trade-offs and mark one as (recommended). 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.",
+        "Explore context first (files, docs, existing behavior). Share a brief summary of what you found.",
+        "Restate the problem in your own words. Ask user to confirm before proceeding to questions.",
+        "Ask one clarifying question per message. Do NOT combine questions. Continue until you understand purpose, constraints, users, success criteria, and edge cases.",
+        "For approach selection: use the Decision Protocol — present labeled options (A/B/C) with REAL trade-offs (not cosmetic) and mark one as (recommended) with clear reasoning. 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.",
+        "Every approval question MUST state what exactly is being approved: 'Do you approve [the architecture / the API shape / the dependency choice]?' Never ask a bare 'approve?' or 'looks good?'.",
         "Get section-by-section approval before finalizing the design direction.",
         "Run a self-review pass (ambiguity, placeholders, contradictions) before handoff.",
         "**STOP.** Wait for explicit user approval after writing the artifact. Do NOT auto-advance to the next stage."
     ],
     process: [
-        "Capture problem statement, users, constraints, and success criteria.",
+        "Explore project context — files, docs, behavior, recent changes. Share findings.",
+        "Restate the problem — summarize what the user wants and why. Get confirmation.",
+        "Clarify iteratively — ask questions one at a time until you understand WHY, WHO, WHAT, success criteria, and boundaries.",
         "Identify whether request should be decomposed into smaller sub-problems.",
-        "Offer alternatives and recommendation with rationale.",
-        "Present design in sections, ask after each section whether it looks right.",
-        "Write artifact with validated design.",
+        "Offer 2-3 alternatives with real trade-offs and recommendation with rationale.",
+        "Present design in sections. After each section explicitly name what you ask the user to approve.",
+        "Write artifact to `.cclaw/artifacts/01-brainstorm.md`.",
         "Run self-review: placeholder scan, internal consistency, scope check, ambiguity check.",
-        "Ask user to review the written spec. Wait for changes or approval.",
+        "Ask user to review the written artifact. Wait for changes or approval.",
         "Handoff to scope stage only after approval is explicit."
     ],
     requiredGates: [
-        { id: "brainstorm_context_explored", description: "Project context and constraints have been reviewed." },
-        { id: "brainstorm_options_compared", description: "At least two alternatives were compared with trade-offs." },
-        { id: "brainstorm_design_approved", description: "User approved a concrete design direction." },
+        { id: "brainstorm_context_explored", description: "Project context and constraints have been reviewed and summarized." },
+        { id: "brainstorm_problem_restated", description: "Problem was restated in agent's words and user confirmed the understanding." },
+        { id: "brainstorm_options_compared", description: "At least two alternatives were compared with real trade-offs." },
+        { id: "brainstorm_design_approved", description: "User approved a concrete design direction (with explicit statement of what was approved)." },
         { id: "brainstorm_self_review_passed", description: "Design doc passed placeholder/ambiguity/consistency checks." },
         { id: "brainstorm_user_reviewed_artifact", description: "User reviewed the written artifact and confirmed readiness." }
     ],
@@ -104,24 +110,32 @@ const BRAINSTORM = {
         "Asking many questions in one message",
         "Jumping directly into implementation",
         "Combining visual companion offer with a clarifying question",
-        "Invoking implementation skills before writing plans"
+        "Invoking implementation skills before writing plans",
+        "Asking bare 'approve?' or 'одобряете?' without stating WHAT is being approved",
+        "Presenting a single summary and asking for blanket approval instead of section-by-section review",
+        "Rushing through clarification — asking 1-2 generic questions then jumping to design"
     ],
     rationalizations: [
         { claim: "This is too simple for design.", reality: "Simple tasks fail fast when assumptions are wrong; a short design pass prevents rework." },
         { claim: "We can figure it out while coding.", reality: "Coding before alignment creates churn and hidden scope growth." },
         { claim: "There is only one obvious approach.", reality: "Without alternatives, trade-offs stay implicit and risk goes unexamined." },
-        { claim: "The user already knows what they want.", reality: "Unstated assumptions diverge during implementation; explicit design surfaces them early." }
+        { claim: "The user already knows what they want.", reality: "Unstated assumptions diverge during implementation; explicit design surfaces them early." },
+        { claim: "This is straightforward, 1-2 questions are enough.", reality: "Even simple projects have hidden constraints (error handling, edge cases, deployment). A few extra questions now prevent rework later." }
     ],
     redFlags: [
         "No alternatives documented",
         "No explicit approval checkpoint",
         "Implementation-related actions before approval",
         "Self-review skipped or glossed over",
-        "Artifact has TBD or placeholder sections"
+        "Artifact has TBD or placeholder sections",
+        "Fewer than 3 clarifying questions asked for any non-trivial project",
+        "Approval requested without stating what exactly is being approved"
     ],
     policyNeedles: [
+        "Restate problem before questions",
         "One clarifying question per message",
-        "2-3 approaches with trade-offs",
+        "2-3 approaches with real trade-offs",
+        "State what is being approved",
         "Do NOT implement, scaffold, or modify behavior"
     ],
     artifactFile: "01-brainstorm.md",
@@ -140,9 +154,11 @@ const BRAINSTORM = {
         traceabilityRule: "Every approved direction must be traceable forward through scope and design. Downstream stages must reference brainstorm decisions."
     },
     artifactValidation: [
-        { section: "Problem Statement", required: true, validationRule: "Must describe the user problem, not the solution." },
-        { section: "Alternatives Table", required: true, validationRule: "At least 2 approaches with trade-offs and recommendation." },
-        { section: "Approved Direction", required: true, validationRule: "Must contain explicit approval marker from user." },
+        { section: "Problem Statement", required: true, validationRule: "Must describe the user problem, not the solution. Include WHO and WHY." },
+        { section: "Known Context", required: true, validationRule: "Files, patterns, constraints discovered during exploration. Evidence that context was actually explored." },
+        { section: "Alternatives Table", required: true, validationRule: "At least 2 approaches with real trade-offs (not cosmetic) and recommendation with reasoning." },
+        { section: "Approved Direction", required: true, validationRule: "Must contain explicit approval marker from user. State what was approved." },
+        { section: "Assumptions & Risks", required: true, validationRule: "Explicit assumptions made during design. Known risks. If none, state 'None'." },
         { section: "Open Questions", required: true, validationRule: "If empty, state 'None' explicitly. Do not omit." }
     ],
     namedAntiPattern: {
@@ -679,7 +695,7 @@ const PLAN = {
     ],
     whenNotToUse: [
         "Specification is unapproved or lacks measurable acceptance criteria",
-        "Execution is already in test/build stages with active slice evidence",
+        "Execution is already in TDD stage with active slice evidence",
         "The request is only release packaging with no task decomposition needed"
     ],
     checklist: [
@@ -760,7 +776,7 @@ const PLAN = {
     ],
     policyNeedles: ["WAIT_FOR_CONFIRM", "Task Graph", "Dependency Waves", "Acceptance Mapping", "verification steps"],
     artifactFile: "05-plan.md",
-    next: "test",
+    next: "tdd",
     cognitivePatterns: [
         { name: "Vertical Slice Thinking", description: "Each task delivers one thin end-to-end slice of value. Horizontal layers (all models, then all controllers) create integration risk. Vertical slices (one feature through all layers) reduce it." },
         { name: "Two-Minute Smell Test", description: "If a competent engineer cannot understand and start a task in two minutes, the task is too large or too vague. Break it down further." },
@@ -782,202 +798,124 @@ const PLAN = {
     ]
 };
 // ---------------------------------------------------------------------------
-// TEST — TDD RED stage
+// TDD — RED → GREEN → REFACTOR cycle (merged test + build)
 // ---------------------------------------------------------------------------
-const TEST = {
-    stage: "test",
-    skillFolder: "red-first-testing",
-    skillName: "red-first-testing",
-    skillDescription: "TDD RED stage. Establish failing tests as proof before implementation changes.",
-    hardGate: "Do NOT change implementation code. This stage writes failing tests ONLY. If you find yourself editing non-test files, STOP — you have left the RED stage.",
-    purpose: "Create RED evidence tied to acceptance criteria before any implementation.",
+const TDD = {
+    stage: "tdd",
+    skillFolder: "test-driven-development",
+    skillName: "test-driven-development",
+    skillDescription: "Full TDD cycle: RED (failing tests), GREEN (minimal implementation), REFACTOR (cleanup). One plan slice at a time with strict traceability.",
+    hardGate: "Do NOT merge, ship, or skip review. Follow RED → GREEN → REFACTOR strictly for each plan slice. Do NOT write implementation code before RED tests exist. Do NOT skip the REFACTOR step.",
+    purpose: "Implement features through the TDD cycle: write failing tests, make them pass with minimal code, then refactor.",
     whenToUse: [
         "After plan confirmation",
-        "After RED evidence from test stage (user runs /cc-next)",
-        "For every behavior change in scope"
+        "For every behavior change in scope",
+        "Before review stage"
     ],
     whenNotToUse: [
         "Plan approval is still pending WAIT_FOR_CONFIRM",
         "The change is docs-only and does not alter behavior",
-        "GREEN implementation has started before RED evidence"
+        "The stage intent is review/ship sign-off rather than implementation"
     ],
     checklist: [
         "Select plan slice — pick one task from the plan. Do not batch multiple tasks.",
         "Map to acceptance criterion — identify the specific spec criterion this test proves.",
-        "Write behavior-focused test — test the expected behavior, not implementation details. Name tests descriptively.",
-        "Run tests and observe failure — tests MUST fail. If they pass, either the behavior already exists or the test is wrong.",
-        "Capture failure output — copy the exact failure output as RED evidence. Record in artifact.",
+        "RED: Write behavior-focused test — test the expected behavior, not implementation details. Tests MUST fail.",
+        "RED: Capture failure output — copy the exact failure output as RED evidence. Record in artifact.",
+        "GREEN: Minimal implementation — write the smallest code change that makes the RED tests pass. No extra features.",
+        "GREEN: Run full suite — execute ALL tests, not just the ones you wrote. The full suite must be GREEN.",
+        "GREEN: Verify no regressions — if any existing test breaks, fix the regression before proceeding.",
+        "REFACTOR: Improve code quality — without changing behavior. Document what you changed and why.",
+        "Record evidence — capture RED failure, GREEN output, and REFACTOR notes in the TDD artifact.",
+        "Annotate traceability — link to plan task ID and spec criterion.",
         "Repeat for each slice — return to step 1 for the next plan slice."
     ],
     interactionProtocol: [
         "Pick one planned slice at a time.",
-        "Write behavior-focused tests before changing implementation.",
+        "Write behavior-focused tests before changing implementation (RED).",
         "Capture and store failing output as RED evidence.",
-        "Do not proceed to build without RED evidence.",
+        "Apply minimal change to satisfy RED tests (GREEN).",
+        "Run full suite, not partial checks, for GREEN validation.",
+        "Refactor without changing behavior and document rationale (REFACTOR).",
+        "Stop if regressions appear and fix before proceeding.",
         "If a test passes unexpectedly, investigate: does the behavior already exist, or is the test wrong?"
     ],
     process: [
         "Select slice and map to acceptance criterion.",
-        "Write test(s) that fail for expected reason.",
+        "Write test(s) that fail for expected reason (RED).",
         "Run tests and capture failure output.",
-        "Record RED evidence in TDD artifact.",
-        "Verify failure reason matches expected missing behavior."
-    ],
-    requiredGates: [
-        { id: "tdd_red_test_written", description: "Failing tests exist before implementation changes." },
-        { id: "tdd_red_failure_captured", description: "Failure output is captured as evidence." },
-        { id: "tdd_trace_to_acceptance", description: "RED tests trace to explicit acceptance criteria." },
-        { id: "tdd_red_failure_reason_verified", description: "Failure is for the expected reason, not an unrelated error." }
-    ],
-    requiredEvidence: [
-        "Artifact updated at `.cclaw/artifacts/06-tdd.md` RED section.",
-        "Failing command output captured.",
-        "Acceptance mapping documented.",
-        "Failure reason analysis recorded."
-    ],
-    inputs: ["approved plan slice", "spec acceptance criterion", "test harness configuration"],
-    requiredContext: ["plan artifact", "spec artifact", "existing test patterns"],
-    outputs: ["failing test set", "captured RED evidence", "ready signal for GREEN stage"],
-    blockers: [
-        "tests pass before behavior change",
-        "failure reason does not match expected behavior",
-        "no evidence recorded"
-    ],
-    exitCriteria: [
-        "RED evidence exists and is traceable",
-        "required gates marked satisfied",
-        "no implementation changes made in this stage",
-        "failure reason verified for each test"
-    ],
-    antiPatterns: [
-        "Writing code before failing test",
-        "Asserting implementation details instead of behavior",
-        "Skipping evidence capture",
-        "Testing multiple slices without recording evidence for each"
-    ],
-    rationalizations: [
-        { claim: "This change is obvious, tests can be added later.", reality: "Without RED proof, regressions hide behind optimistic assumptions." },
-        { claim: "A passing baseline is enough to continue.", reality: "Baseline pass does not prove new behavior requirements." },
-        { claim: "One broad integration test is enough.", reality: "Slice-level RED tests are required for precise failure signal." }
-    ],
-    redFlags: [
-        "No failing test output",
-        "No acceptance linkage",
-        "Implementation edits appear before RED evidence",
-        "Test passes without behavior change"
-    ],
-    policyNeedles: ["RED", "failing test", "acceptance criteria", "no implementation changes"],
-    artifactFile: "06-tdd.md",
-    next: "build",
-    cognitivePatterns: [
-        { name: "Behavior Over Implementation", description: "Tests describe WHAT the system does, not HOW. Test the observable behavior from outside the unit. If you need to test internals, the design needs work." },
-        { name: "Failure-First Thinking", description: "The failing test IS the specification. Until you see the right failure, you do not understand what you are building. Wrong failures are information." },
-        { name: "Proof Before Claim", description: "Do not claim a feature works without evidence. RED output is proof of what is missing. GREEN output is proof it was added. Both are required." }
-    ],
-    reviewSections: [],
-    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
-    crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
-        writesTo: [".cclaw/artifacts/06-tdd.md"],
-        traceabilityRule: "Every RED test traces to a plan task. Every plan task traces to a spec criterion. Evidence chain: spec -> plan -> RED test -> failure output."
-    },
-    artifactValidation: [
-        { section: "RED Evidence", required: true, validationRule: "Failing test output captured per slice." },
-        { section: "Acceptance Mapping", required: true, validationRule: "Each RED test links to a plan task and spec criterion." },
-        { section: "Failure Analysis", required: true, validationRule: "Failure reason matches expected missing behavior." }
-    ],
-    waveExecutionAllowed: true
-};
-// ---------------------------------------------------------------------------
-// BUILD — TDD GREEN + REFACTOR stage
-// ---------------------------------------------------------------------------
-const BUILD = {
-    stage: "build",
-    skillFolder: "incremental-implementation",
-    skillName: "incremental-implementation",
-    skillDescription: "TDD GREEN and REFACTOR stage with strict traceability to plan slices.",
-    hardGate: "Do NOT merge, ship, or skip review. This stage produces GREEN and REFACTOR evidence for one plan slice at a time. If you are touching files unrelated to the current slice, STOP.",
-    purpose: "Implement minimal passing change, run full suite GREEN, then refactor safely.",
-    whenToUse: [
-        "After RED evidence is complete",
-        "For one accepted plan slice at a time",
-        "Before review stage"
-    ],
-    whenNotToUse: [
-        "RED evidence is missing or failure reason is unverified",
-        "Multiple unrelated slices are being merged into one build pass",
-        "The stage intent is review/ship sign-off rather than implementation"
-    ],
-    checklist: [
-        "Minimal GREEN change — implement the smallest code change that makes the RED tests pass. No extra features.",
-        "Run full suite — execute ALL tests, not just the ones you wrote. The full suite must be GREEN.",
-        "Verify no regressions — if any existing test breaks, fix the regression before proceeding.",
-        "Refactor pass — improve code quality without changing behavior. Document what you changed and why.",
-        "Record evidence — capture GREEN output and REFACTOR notes in the TDD artifact.",
-        "Annotate traceability — link the implementation to the plan task ID and spec criterion."
-    ],
-    interactionProtocol: [
-        "Apply minimal change to satisfy RED tests.",
-        "Run full suite, not partial checks, for GREEN validation.",
-        "Refactor without changing behavior and document rationale.",
-        "Stop if regressions appear and return to prior step.",
-        "Record traceability to plan slice explicitly."
-    ],
-    process: [
         "Implement smallest change needed for GREEN.",
         "Run full tests and build checks.",
         "Perform refactor pass preserving behavior.",
-        "Record GREEN and REFACTOR evidence in artifact.",
+        "Record RED, GREEN, and REFACTOR evidence in artifact.",
         "Annotate traceability to plan task and spec criterion."
     ],
     requiredGates: [
-        { id: "build_minimal_change_applied", description: "Implementation matches a single plan slice." },
+        { id: "tdd_red_test_written", description: "Failing tests exist before implementation changes." },
+        { id: "tdd_red_failure_captured", description: "Failure output is captured as evidence." },
+        { id: "tdd_trace_to_acceptance", description: "RED tests trace to explicit acceptance criteria." },
+        { id: "tdd_red_failure_reason_verified", description: "Failure is for the expected reason, not an unrelated error." },
         { id: "tdd_green_full_suite", description: "Full relevant suite passes in GREEN state." },
         { id: "tdd_refactor_completed", description: "Refactor pass completed with behavior preservation verified." },
         { id: "tdd_refactor_notes_written", description: "Refactor decisions and outcomes are documented." },
-        { id: "build_traceable_to_plan", description: "Change traceability to plan slice is explicit." }
+        { id: "tdd_traceable_to_plan", description: "Change traceability to plan slice is explicit." }
     ],
     requiredEvidence: [
-        "Artifact `.cclaw/artifacts/06-tdd.md` includes GREEN and REFACTOR sections.",
-        "Full test/build output recorded.",
-        "Traceability to task identifier is documented.",
-        "Refactor rationale captured."
-    ],
-    inputs: ["RED evidence", "approved plan slice", "coding standards and constraints"],
-    requiredContext: ["tdd artifact", "plan artifact", "spec acceptance criteria"],
-    outputs: ["passing implementation", "refactor evidence", "review-ready change set"],
+        "Artifact updated at `.cclaw/artifacts/06-tdd.md` with RED, GREEN, and REFACTOR sections.",
+        "Failing command output captured (RED).",
+        "Full test/build output recorded (GREEN).",
+        "Acceptance mapping documented.",
+        "Failure reason analysis recorded.",
+        "Refactor rationale captured.",
+        "Traceability to task identifier is documented."
+    ],
+    inputs: ["approved plan slice", "spec acceptance criterion", "test harness configuration", "coding standards and constraints"],
+    requiredContext: ["plan artifact", "spec artifact", "existing test patterns"],
+    outputs: ["failing test set", "passing implementation", "refactor evidence", "review-ready change set"],
     blockers: [
-        "no RED evidence",
+        "tests pass before behavior change (RED failure missing)",
         "full suite not green",
-        "behavior changed during refactor"
+        "behavior changed during refactor",
+        "no evidence recorded"
     ],
     exitCriteria: [
-        "GREEN evidence captured",
+        "RED evidence exists and is traceable",
+        "GREEN evidence captured with full suite pass",
         "REFACTOR evidence captured",
         "required gates marked satisfied",
         "traceability annotated"
     ],
     antiPatterns: [
+        "Writing code before failing test",
+        "Asserting implementation details instead of behavior",
         "Big-bang implementation across multiple slices",
         "Partial test runs presented as GREEN",
+        "Skipping evidence capture",
         "Undocumented refactor changes",
         "Adding features beyond what RED tests require"
     ],
     rationalizations: [
+        { claim: "This change is obvious, tests can be added later.", reality: "Without RED proof, regressions hide behind optimistic assumptions." },
+        { claim: "A passing baseline is enough to continue.", reality: "Baseline pass does not prove new behavior requirements." },
+        { claim: "One broad integration test is enough.", reality: "Slice-level RED tests are required for precise failure signal." },
         { claim: "Refactor can be skipped for speed.", reality: "Skipping refactor accumulates debt and weakens maintainability." },
         { claim: "Only changed tests need to pass.", reality: "Full-suite checks are needed to detect regressions." },
         { claim: "Traceability is implied by commit diff.", reality: "Explicit mapping avoids ambiguity in review and rollback." }
     ],
     redFlags: [
+        "No failing test output (RED missing)",
+        "Implementation edits appear before RED evidence",
         "No full-suite GREEN evidence",
         "No refactor notes",
         "Multiple tasks implemented in one pass without justification",
         "Files changed outside current slice scope"
     ],
-    policyNeedles: ["GREEN", "full test suite", "REFACTOR", "traceable to plan slice"],
+    policyNeedles: ["RED", "GREEN", "REFACTOR", "failing test", "full test suite", "acceptance criteria", "traceable to plan slice"],
     artifactFile: "06-tdd.md",
     next: "review",
     cognitivePatterns: [
+        { name: "Behavior Over Implementation", description: "Tests describe WHAT the system does, not HOW. Test the observable behavior from outside the unit. If you need to test internals, the design needs work." },
+        { name: "Failure-First Thinking", description: "The failing test IS the specification. Until you see the right failure, you do not understand what you are building. Wrong failures are information." },
         { name: "Minimal Viable Change", description: "The best implementation is the smallest one that passes all RED tests. Every extra line is risk. Resist the urge to 'improve while you are here.'" },
         { name: "Regression Paranoia", description: "Assume every change breaks something until the full suite proves otherwise. Partial test runs are lies of omission." },
         { name: "Refactor-as-Hygiene", description: "Refactoring is not optional cleanup — it is the third leg of TDD. GREEN without REFACTOR accumulates mess. REFACTOR without GREEN breaks things." }
@@ -985,11 +923,14 @@ const BUILD = {
     reviewSections: [],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/05-plan.md"],
+        readsFrom: [".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
         writesTo: [".cclaw/artifacts/06-tdd.md"],
-        traceabilityRule: "Every GREEN change traces to a RED test. Every RED test traces to a plan task. Evidence chain must be unbroken."
+        traceabilityRule: "Every RED test traces to a plan task. Every GREEN change traces to a RED test. Every plan task traces to a spec criterion. Evidence chain must be unbroken."
     },
     artifactValidation: [
+        { section: "RED Evidence", required: true, validationRule: "Failing test output captured per slice." },
+        { section: "Acceptance Mapping", required: true, validationRule: "Each RED test links to a plan task and spec criterion." },
+        { section: "Failure Analysis", required: true, validationRule: "Failure reason matches expected missing behavior." },
         { section: "GREEN Evidence", required: true, validationRule: "Full suite pass output captured." },
         { section: "REFACTOR Notes", required: true, validationRule: "What changed, why, behavior preservation confirmed." },
         { section: "Traceability", required: true, validationRule: "Plan task ID and spec criterion linked." }
@@ -1007,13 +948,13 @@ const REVIEW = {
     hardGate: "Do NOT ship, merge, or release until both review layers complete with an explicit verdict. No exceptions for urgency. Critical blockers MUST be resolved before handoff.",
     purpose: "Validate that implementation matches spec and meets quality/security/performance bar through structured two-layer review.",
     whenToUse: [
-        "After build stage completes",
+        "After TDD stage completes",
         "Before any ship action",
         "When release risk must be assessed explicitly"
     ],
     whenNotToUse: [
         "There is no implementation diff to review",
-        "Build stage evidence is missing or stale",
+        "TDD stage evidence is missing or stale",
         "The goal is direct release execution without layered quality checks"
     ],
     checklist: [
@@ -1364,8 +1305,7 @@ const STAGE_SCHEMA_MAP = {
     design: DESIGN,
     spec: SPEC,
     plan: PLAN,
-    test: TEST,
-    build: BUILD,
+    tdd: TDD,
     review: REVIEW,
     ship: SHIP
 };
@@ -1422,21 +1362,12 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             requiresUserGate: false
         }
     ],
-    test: [
-        {
-            agent: "test-author",
-            mode: "mandatory",
-            when: "Always during RED stage.",
-            purpose: "Guarantee failing tests are created before implementation.",
-            requiresUserGate: false
-        }
-    ],
-    build: [
+    tdd: [
         {
             agent: "test-author",
             mode: "mandatory",
-            when: "Always during GREEN + REFACTOR.",
-            purpose: "Keep implementation traceable to RED evidence and full-suite verification.",
+            when: "Always during TDD cycle (RED → GREEN → REFACTOR).",
+            purpose: "Guarantee failing tests, traceable implementation, and full-suite verification.",
             requiresUserGate: false
         },
         {

package/dist/content/start-command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Command contract for /cc — the unified entry point.
+ * No args → behaves like /cc-next (resume or start brainstorm).
+ * With prompt → starts brainstorm with the given idea.
+ */
+export declare function startCommandContract(): string;
+/**
+ * Skill body for /cc — the unified entry point.
+ */
+export declare function startCommandSkillMarkdown(): string;

package/dist/content/start-command.js

@@ -0,0 +1,109 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const START_SKILL_FOLDER = "flow-start";
+const START_SKILL_NAME = "flow-start";
+function flowStatePath() {
+    return `${RUNTIME_ROOT}/state/flow-state.json`;
+}
+/**
+ * Command contract for /cc — the unified entry point.
+ * No args → behaves like /cc-next (resume or start brainstorm).
+ * With prompt → starts brainstorm with the given idea.
+ */
+export function startCommandContract() {
+    const flowPath = flowStatePath();
+    return `# /cc
+
+## Purpose
+
+**The unified entry point for the cclaw flow.**
+
+- \`/cc\` (no arguments) → behaves exactly like \`/cc-next\`: reads flow state and resumes the current stage, or starts brainstorm if the flow is fresh.
+- \`/cc <prompt>\` (with an idea/description) → saves the prompt as brainstorm context and begins the brainstorm stage, regardless of current flow state.
+
+This is the **recommended way to start** working with cclaw. Use \`/cc-next\` for subsequent stage progression.
+
+## HARD-GATE
+
+- **Do not** skip reading \`${flowPath}\` — always check current state before acting.
+- **Do not** start implementation stages directly from \`/cc <prompt>\` — always begin at brainstorm.
+
+## Algorithm
+
+### With prompt (\`/cc <text>\`)
+
+1. Read \`${flowPath}\`.
+2. If flow already has completed stages beyond brainstorm, warn the user that starting a new brainstorm will reset progress. Ask for confirmation before proceeding.
+3. Write the prompt to \`.cclaw/artifacts/00-idea.md\` as the raw idea capture.
+4. Set \`currentStage: "brainstorm"\` in flow state (reset if needed).
+5. Load \`.cclaw/skills/brainstorming/SKILL.md\` and \`.cclaw/commands/brainstorm.md\`.
+6. Execute brainstorm with the prompt as initial context.
+
+### Without prompt (\`/cc\`)
+
+1. Read \`${flowPath}\`.
+2. If flow state is missing → run \`cclaw init\` guidance and stop.
+3. Behave exactly like \`/cc-next\`: check current stage gates, resume if incomplete, advance if complete.
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${START_SKILL_FOLDER}/SKILL.md**
+`;
+}
+/**
+ * Skill body for /cc — the unified entry point.
+ */
+export function startCommandSkillMarkdown() {
+    const flowPath = flowStatePath();
+    return `---
+name: ${START_SKILL_NAME}
+description: "Unified entry point for the cclaw flow. No args = resume/next. With prompt = start brainstorm with idea."
+---
+
+# /cc — Flow Entry Point
+
+## Overview
+
+\`/cc\` is the **starting command** for cclaw. It intelligently routes:
+
+- **No arguments** → acts as \`/cc-next\` (resume current stage or advance to next)
+- **With a prompt** → captures the idea and starts brainstorm
+
+## HARD-GATE
+
+Do **not** silently discard an existing flow when the user provides a prompt. If completed stages exist, inform and confirm before resetting.
+
+## Protocol
+
+### Path A: \`/cc <prompt>\`
+
+1. Read \`${flowPath}\`.
+2. If \`completedStages\` is non-empty:
+   - Inform: "You have an active flow at stage **{currentStage}** with {N} completed stages. Starting a new brainstorm will reset progress."
+   - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
+   - If (B) → switch to Path B behavior.
+3. Write \`${RUNTIME_ROOT}/artifacts/00-idea.md\` with the user's prompt.
+4. Update \`${flowPath}\`: set \`currentStage: "brainstorm"\`, clear \`completedStages\`, reset gate catalog.
+5. Load and execute: \`${RUNTIME_ROOT}/skills/brainstorming/SKILL.md\` + \`${RUNTIME_ROOT}/commands/brainstorm.md\`.
+
+### Path B: \`/cc\` (no arguments)
+
+Delegate entirely to \`/cc-next\` behavior:
+
+1. Read \`${flowPath}\`.
+2. Check gates for \`currentStage\`.
+3. If incomplete → load current stage skill and execute.
+4. If complete → advance to next stage and execute.
+5. If flow is done → report completion.
+
+## When to use \`/cc\` vs \`/cc-next\`
+
+| Scenario | Command |
+|---|---|
+| Starting work for the first time | \`/cc\` or \`/cc <idea>\` |
+| Resuming in a new session | \`/cc\` |
+| Progressing after completing a stage | \`/cc-next\` |
+| Starting with a specific idea | \`/cc <idea>\` |
+
+Both commands read the same \`flow-state.json\`. The difference is that \`/cc <prompt>\` always targets brainstorm, while \`/cc\` and \`/cc-next\` follow the state.
+`;
+}

package/dist/content/subagents.js

@@ -34,7 +34,7 @@ This pattern is intentionally **Superpowers-style**: cheap parallelism where it
 For cclaw flow stages, machine-only specialist work should auto-dispatch without waiting for a manual user request:
 
 - **design/plan:** planner
-- **test/build:** test-author
+- **tdd:** test-author
 - **review:** spec-reviewer + code-reviewer (security-reviewer when trust boundaries moved)
 - **ship:** doc-updater
 
@@ -295,7 +295,7 @@ Implementation that touches shared source trees must remain **sequential** unles
   - **3–4:** appendix / “worth tracking” section (not merge-blocking alone)
   - **1–2:** suppress from primary narrative unless paired with stronger evidence
 
-### Review Army Artifact Contract (required in /cc-review)
+### Review Army Artifact Contract (required in review stage via /cc-next)
 
 Write a structured reconciliation artifact at \`.cclaw/artifacts/07-review-army.json\` using this schema:
 
@@ -620,7 +620,7 @@ Status contract: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED.
 - Controller sequentially dispatches **implementer → reviewer** loops per task.
 - HARD-GATE: paste **self-contained task text**; never point subagents at plan files to “discover” scope.
 - **Spec fixers** are **fresh agents** after failed spec reviews — avoids parent-context pollution.
-- **Machine-only flow checks auto-dispatch** by stage (design/plan/test/build/review/ship) without asking the user to trigger each specialist manually.
+- **Machine-only flow checks auto-dispatch** by stage (design/plan/tdd/review/ship) without asking the user to trigger each specialist manually.
 
 ### Parallel Agents (\`dispatching-parallel-agents\` skill)