cclaw-cli 0.3.0 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 **A focused, installer-first workflow that turns AI coding sessions into predictable shipped outcomes.**
 
 `cclaw` gives your agent one clear path:
-**brainstorm -> scope -> design -> spec -> plan -> test -> build -> review -> ship**
+**brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship**
 
 No giant command jungle. No runtime daemon. No process theater.
 Just a disciplined flow that stays lightweight and works across major coding harnesses.
@@ -17,10 +17,9 @@ flowchart LR
     C --> D[Design]
     D --> E[Spec]
     E --> F[Plan]
-    F --> G[Test]
-    G --> H[Build]
-    H --> I[Review]
-    I --> J[Ship]
+    F --> G[TDD]
+    G --> H[Review]
+    H --> I[Ship]
 ```
 
 ```mermaid
@@ -29,7 +28,7 @@ sequenceDiagram
     participant H as Harness
     participant V as cclaw Hooks + Skills
     participant S as State + Learnings
-    U->>H: /cc-brainstorm
+    U->>H: /cc <idea>
     H->>V: Load stage contract + HARD-GATE
     V->>S: Read context (state/learnings)
     V-->>H: Structured execution guidance
@@ -65,7 +64,8 @@ npx cclaw-cli init
 Then run in your harness:
 
 ```text
-/cc-brainstorm
+/cc <idea>
+/cc-next
 ```
 
 Core installer lifecycle:

package/dist/constants.d.ts

@@ -5,8 +5,8 @@ export declare const CCLAW_VERSION = "0.1.1";
 export declare const FLOW_VERSION = "1.0.0";
 export declare const DEFAULT_HARNESSES: HarnessId[];
 export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks"];
-export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", ".claude/commands/cc-*.md", ".cursor/commands/cc-*.md", ".opencode/commands/cc-*.md", ".codex/commands/cc-*.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
+export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".codex/commands/cc-*.md", ".codex/commands/cc.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 export declare const COMMAND_FILE_ORDER: FlowStage[];
-export declare const UTILITY_COMMANDS: readonly ["learn", "autoplan", "next"];
+export declare const UTILITY_COMMANDS: readonly ["learn", "next"];
 export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];
 export type UtilityCommand = (typeof UTILITY_COMMANDS)[number];

package/dist/constants.js

@@ -26,9 +26,13 @@ export const REQUIRED_GITIGNORE_PATTERNS = [
     "# cclaw generated artifacts",
     `${RUNTIME_ROOT}/`,
     ".claude/commands/cc-*.md",
+    ".claude/commands/cc.md",
     ".cursor/commands/cc-*.md",
+    ".cursor/commands/cc.md",
     ".opencode/commands/cc-*.md",
+    ".opencode/commands/cc.md",
     ".codex/commands/cc-*.md",
+    ".codex/commands/cc.md",
     ".claude/hooks/hooks.json",
     ".cursor/hooks.json",
     ".codex/hooks.json",
@@ -41,12 +45,11 @@ export const COMMAND_FILE_ORDER = [
     "design",
     "spec",
     "plan",
-    "test",
-    "build",
+    "tdd",
     "review",
     "ship"
 ];
-export const UTILITY_COMMANDS = ["learn", "autoplan", "next"];
+export const UTILITY_COMMANDS = ["learn", "next"];
 export const SUBAGENT_SKILL_FOLDERS = [
     "subagent-dev",
     "parallel-dispatch"

package/dist/content/agents.d.ts

@@ -30,7 +30,7 @@ export declare const CCLAW_AGENTS: AgentDefinition[];
  */
 export declare function agentMarkdown(agent: AgentDefinition): string;
 /**
- * Markdown table mapping Cclaw slash commands to recommended specialist agents.
+ * Markdown table mapping Cclaw stage entry points to specialist agents.
  */
 export declare function agentRoutingTable(): string;
 /**

package/dist/content/agents.js

@@ -41,7 +41,7 @@ export const CCLAW_AGENTS = [
     },
     {
         name: "spec-reviewer",
-        description: "MANDATORY after implementation: MUST BE USED during `/cc-review` (and any review gate) to verify acceptance criteria against the actual codebase — not against claims.",
+        description: "MANDATORY after implementation: MUST BE USED during the review stage (via `/cc-next`) to verify acceptance criteria against the actual codebase — not against claims.",
         tools: ["Read", "Grep", "Glob"],
         model: "balanced",
         activation: "mandatory",
@@ -64,7 +64,7 @@ export const CCLAW_AGENTS = [
     },
     {
         name: "code-reviewer",
-        description: "MANDATORY for all code changes: MUST BE USED during `/cc-review` for any diff/PR-sized work — correctness, maintainability, and ship risk.",
+        description: "MANDATORY for all code changes: MUST BE USED during the review stage (via `/cc-next`) for any diff/PR-sized work — correctness, maintainability, and ship risk.",
         tools: ["Read", "Grep", "Glob"],
         model: "balanced",
         activation: "mandatory",
@@ -128,7 +128,7 @@ export const CCLAW_AGENTS = [
         tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
         model: "balanced",
         activation: "proactive",
-        relatedStages: ["test", "build"],
+        relatedStages: ["tdd"],
         body: [
             "You are a **test-driven development** guide and implementer.",
             "",
@@ -157,7 +157,7 @@ export const CCLAW_AGENTS = [
         tools: ["Read", "Write", "Edit", "Grep", "Glob"],
         model: "fast",
         activation: "proactive",
-        relatedStages: ["build", "ship"],
+        relatedStages: ["tdd", "ship"],
         body: [
             "You are a **documentation and comment maintenance** specialist.",
             "",
@@ -208,20 +208,16 @@ ${taskDelegation}
 `;
 }
 /**
- * Markdown table mapping Cclaw slash commands to recommended specialist agents.
+ * Markdown table mapping Cclaw stage entry points to specialist agents.
  */
 export function agentRoutingTable() {
-    return `| Command | Primary Agent | Supporting Agents |
+    return `| Stage Entry | Primary Agent | Supporting Agents |
 |---|---|---|
-| /cc-brainstorm | planner | — |
-| /cc-scope | planner | — |
-| /cc-design | planner, security-reviewer | — |
-| /cc-spec | planner | spec-reviewer |
-| /cc-plan | planner | — |
-| /cc-test | test-author | — |
-| /cc-build | test-author | doc-updater |
-| /cc-review | spec-reviewer, code-reviewer | security-reviewer |
-| /cc-ship | — | doc-updater |
+| Brainstorm (start with \`/cc <idea>\`) | planner | — |
+| Scope / Design / Spec / Plan (advance via \`/cc-next\`) | planner | security-reviewer on design, spec-reviewer on spec |
+| TDD (via \`/cc-next\`) | test-author | doc-updater |
+| Review (via \`/cc-next\`) | spec-reviewer, code-reviewer | security-reviewer |
+| Ship (via \`/cc-next\`) | — | doc-updater |
 `;
 }
 /**
@@ -235,7 +231,7 @@ Cclaw provides specialist agents under \`.cclaw/agents/\` for targeted delegatio
 ${agentRoutingTable()}
 
 **Activation modes:**
-- **Mandatory:** MUST be used when the related stage runs (spec-reviewer, code-reviewer during /review)
+- **Mandatory:** MUST be used when the related stage runs (spec-reviewer, code-reviewer during review)
 - **Proactive:** Should be used automatically when context matches (planner for complex features, security-reviewer for auth code)
 - **On-demand:** Invoked only when explicitly requested
 

package/dist/content/contracts.js

@@ -1,8 +1,7 @@
-import { nextCclawCommand, stageSchema } from "./stage-schema.js";
+import { stageSchema } from "./stage-schema.js";
 import { stageSkillFolder } from "./skills.js";
 export function commandContract(stage) {
     const schema = stageSchema(stage);
-    const nextCommand = nextCclawCommand(stage);
     const skillPath = `.cclaw/skills/${stageSkillFolder(stage)}/SKILL.md`;
     const reads = schema.crossStageTrace.readsFrom;
     const readsLine = reads.length > 0 ? reads.join(", ") : "(first stage)";
@@ -28,7 +27,7 @@ ${schema.hardGate}
 ## In / Out
 - **Reads:** ${readsLine}
 - **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\` (canonical run copy: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`)
-- **Next:** ${nextCommand}
+- **Next:** \`/cc-next\` (updates flow-state and loads the next stage)
 
 ## Context Hydration (mandatory before stage work)
 1. Read \`.cclaw/state/flow-state.json\` and capture \`activeRunId\`.

package/dist/content/examples.js

@@ -167,7 +167,7 @@ T1 ──▶ T2 ──▶ T3
 ### Risk note
 
 If T3 grows too large, split “transport” vs “UI state machine” into two tasks while keeping the dependency graph acyclic.`,
-    test: `### RED test (Vitest) — written before production code
+    tdd: `### RED test (Vitest) — written before production code
 
 \`\`\`typescript
 import { describe, it, expect } from "vitest";
@@ -204,8 +204,9 @@ Error: Cannot find module '../notificationFeed' imported from src/notificationFe
 ### Common mistakes to avoid
 
 - “GREEN” that secretly imports a helper that already implements the behavior (that is skipping RED).
-- Assertions that pass because the function returns \`undefined\` and the matcher is too loose.`,
-    build: `### GREEN (minimal implementation to pass RED)
+- Assertions that pass because the function returns \`undefined\` and the matcher is too loose.
+
+### GREEN (minimal implementation to pass RED)
 
 \`\`\`typescript
 export type FeedItem = { dedupeKey: string; read: boolean };

package/dist/content/hooks.js

@@ -270,8 +270,7 @@ if [ "$SUGGESTIONS_ENABLED" = "true" ] && [ "$STAGE_MUTED" != "true" ]; then
     design) STAGE_SUGGESTION="Suggestion: map failure modes per new codepath and confirm architecture boundaries before moving forward." ;;
     spec) STAGE_SUGGESTION="Suggestion: ensure every acceptance criterion is measurable and mapped to a concrete test." ;;
     plan) STAGE_SUGGESTION="Suggestion: group tasks into dependency waves and keep WAIT_FOR_CONFIRM pending until approval." ;;
-    test) STAGE_SUGGESTION="Suggestion: RED only in this stage — capture failing output for each selected slice." ;;
-    build) STAGE_SUGGESTION="Suggestion: apply minimal GREEN change, run full suite, then document REFACTOR notes." ;;
+    tdd) STAGE_SUGGESTION="Suggestion: execute RED → GREEN → REFACTOR for each selected slice and capture evidence per cycle." ;;
     review) STAGE_SUGGESTION="Suggestion: run Layer 1 before Layer 2 and reconcile findings into 07-review-army.json." ;;
     ship) STAGE_SUGGESTION="Suggestion: verify preflight + rollback plan before selecting exactly one finalization mode." ;;
     *) STAGE_SUGGESTION="" ;;
@@ -401,7 +400,7 @@ if [ "$STAGE" != "none" ] && [ -n "$STAGE_LEARNING_LINES" ] && command -v jq >/d
 fi
 
 # --- Build context message ---
-CTX="cclaw loaded. Flow: stage=$STAGE ($COMPLETED/9 completed, run=$ACTIVE_RUN). Active run artifacts: ${RUNTIME_ROOT}/runs/$ACTIVE_RUN/artifacts/"
+CTX="cclaw loaded. Flow: stage=$STAGE ($COMPLETED/8 completed, run=$ACTIVE_RUN). Active run artifacts: ${RUNTIME_ROOT}/runs/$ACTIVE_RUN/artifacts/"
 if [ -n "$CONTEXT_MODE_NOTE" ]; then
   CTX="$CTX
 $CONTEXT_MODE_NOTE"
@@ -932,8 +931,7 @@ export default function cclawPlugin(ctx) {
       design: "Suggestion: map failure modes per new codepath and confirm architecture boundaries before moving forward.",
       spec: "Suggestion: ensure every acceptance criterion is measurable and mapped to a concrete test.",
       plan: "Suggestion: group tasks into dependency waves and keep WAIT_FOR_CONFIRM pending until approval.",
-      test: "Suggestion: RED only in this stage — capture failing output for each selected slice.",
-      build: "Suggestion: apply minimal GREEN change, run full suite, then document REFACTOR notes.",
+      tdd: "Suggestion: execute RED → GREEN → REFACTOR for each selected slice and capture evidence per cycle.",
       review: "Suggestion: run Layer 1 before Layer 2 and reconcile findings into 07-review-army.json.",
       ship: "Suggestion: verify preflight + rollback plan before selecting exactly one finalization mode."
     };
@@ -995,7 +993,7 @@ export default function cclawPlugin(ctx) {
     const contextMode = readContextMode();
     const stageSuggestion = readStageSuggestion(stage);
     const stageLearnings = readStageLearnings(stage);
-    const parts = [\`cclaw loaded. Flow: stage=\${stage} (\${completed}/9 completed, run=\${activeRunId}). Active run artifacts: ${RUNTIME_ROOT}/runs/\${activeRunId}/artifacts/\`];
+    const parts = [\`cclaw loaded. Flow: stage=\${stage} (\${completed}/8 completed, run=\${activeRunId}). Active run artifacts: ${RUNTIME_ROOT}/runs/\${activeRunId}/artifacts/\`];
     parts.push(
       contextMode.guide
         ? \`Context mode: \${contextMode.mode} (guide: \${contextMode.guide})\`

package/dist/content/learnings.js

@@ -44,7 +44,7 @@ Treat learnings as durable project memory: patterns, pitfalls, preferences, arch
 **Minimal valid example (conceptual):**
 
 \`\`\`json
-{"ts":"2026-04-11T12:00:00Z","skill":"build","type":"pattern","key":"run-migrations-before-seed","insight":"Seed scripts assume schema v7; run sqlx migrate before npm run seed.","confidence":8,"source":"observed","files":["scripts/seed.ts"]}
+{"ts":"2026-04-11T12:00:00Z","skill":"tdd","type":"pattern","key":"run-migrations-before-seed","insight":"Seed scripts assume schema v7; run sqlx migrate before npm run seed.","confidence":8,"source":"observed","files":["scripts/seed.ts"]}
 \`\`\`
 
 ## Confidence Decay Rules

package/dist/content/meta-skill.js

@@ -19,34 +19,26 @@ This meta-skill helps you discover and apply the right cclaw stage for the curre
 
 ## Skill Discovery Flowchart
 
-When a task arrives, identify the development phase and invoke the matching command:
+Use \`/cc\` to start or \`/cc-next\` to continue:
 
 \`\`\`
 Task arrives
     |
-    +-- Vague idea / needs exploration?  --> /cc-brainstorm
-    +-- Need to shape scope / challenge premises?  --> /cc-scope
-    +-- Have scope, need architecture / design lock?  --> /cc-design
-    +-- Have design, need formal specification?  --> /cc-spec
-    +-- Have spec, need task breakdown / plan?  --> /cc-plan
-    +-- Have plan, need to write tests first?  --> /cc-test
-    +-- Have failing tests, need implementation?  --> /cc-build
-    +-- Have implementation, need review?  --> /cc-review
-    +-- Reviewed and approved, need to ship?  --> /cc-ship
-    |
-    +-- Cross-cutting:
-    |   +-- Want to check/add project learnings?  --> /cc-learn
-    |   +-- Want full brainstorm-to-plan in one shot?  --> /cc-autoplan
-    |
+    +-- New idea / starting fresh?  --> /cc <idea>  (starts brainstorm)
+    +-- Resuming / continuing?  --> /cc  or  /cc-next
+    +-- Want to check/add project learnings?  --> /cc-learn
     +-- No cclaw stage applies?  --> Respond normally
 \`\`\`
 
+Stage progression is handled automatically by \`/cc-next\`. The flow moves through:
+brainstorm → scope → design → spec → plan → tdd → review → ship
+
 ## Flow State Check
 
 Before starting work, ALWAYS:
 
 1. Read \`.cclaw/state/flow-state.json\` for the current stage.
-2. If a stage is active, invoke the matching \`/cc-*\` command.
+2. If a stage is active, continue with \`/cc\` or \`/cc-next\` (do not jump directly to per-stage commands).
 3. If no stage applies (e.g. simple question, unrelated task), respond normally.
 
 ## Activation Rules
@@ -56,25 +48,24 @@ Before starting work, ALWAYS:
 3. **One stage at a time.** Complete the current stage before advancing to the next.
 4. **Gates must pass.** Every stage has required gates — the agent cannot claim completion without satisfying them.
 5. **Artifacts are mandatory.** Each stage writes to \`.cclaw/artifacts/\` and keeps the active run copy in \`.cclaw/runs/<activeRunId>/artifacts/\` — this is the evidence trail.
-6. **When in doubt, start with brainstorm.** If the task is non-trivial and there's no prior artifact, begin with \`/cc-brainstorm\`.
+6. **When in doubt, use \`/cc\`.** If the task is non-trivial and there's no prior artifact, run \`/cc <idea>\` to start brainstorming.
 
 ## Stage Quick Reference
 
-| Stage | Command | HARD-GATE | Artifact |
-|-------|---------|-----------|----------|
-| Brainstorm | \`/cc-brainstorm\` | No implementation planning | \`01-brainstorm.md\` |
-| Scope | \`/cc-scope\` | Challenge premises first | \`02-scope.md\` |
-| Design | \`/cc-design\` | Search before building | \`03-design.md\` |
-| Spec | \`/cc-spec\` | Observable + testable criteria | \`04-spec.md\` |
-| Plan | \`/cc-plan\` | One task = one purpose | \`05-plan.md\` |
-| Test | \`/cc-test\` | RED tests fail first | \`06-tdd.md\` |
-| Build | \`/cc-build\` | Minimal code to pass RED | \`06-tdd.md\` (shared with test) |
-| Review | \`/cc-review\` | Two-layer review | \`07-review.md\` |
-| Ship | \`/cc-ship\` | All tests green on merge | \`08-ship.md\` |
+| Stage | How to enter | HARD-GATE | Artifact |
+|-------|--------------|-----------|----------|
+| Brainstorm | \`/cc <idea>\` (or \`/cc\` on fresh flow) | No implementation planning | \`01-brainstorm.md\` |
+| Scope | via \`/cc-next\` | Challenge premises first | \`02-scope.md\` |
+| Design | via \`/cc-next\` | Search before building | \`03-design.md\` |
+| Spec | via \`/cc-next\` | Observable + testable criteria | \`04-spec.md\` |
+| Plan | via \`/cc-next\` | One task = one purpose | \`05-plan.md\` |
+| TDD | via \`/cc-next\` | RED → GREEN → REFACTOR per slice | \`06-tdd.md\` |
+| Review | via \`/cc-next\` | Two-layer review | \`07-review.md\` |
+| Ship | via \`/cc-next\` | All tests green on merge | \`08-ship.md\` |
 
 ## Skill Loading
 
-Each \`/cc-*\` command loads:
+\`/cc-next\` (and \`/cc\`) automatically loads the right stage files:
 1. **\`.cclaw/skills/<stage>/SKILL.md\`** — the full procedural guide (read this first and follow it)
 2. **\`.cclaw/commands/<stage>.md\`** — thin orchestrator (entry/exit summary, gates, anchors)
 
@@ -118,8 +109,6 @@ Use this loading order to keep context lean while preserving depth:
 ### See also
 - \`.cclaw/skills/session/SKILL.md\` for session start/stop/resume behavior
 - \`.cclaw/skills/learnings/SKILL.md\` for durable memory capture and reuse
-- \`.cclaw/skills/autoplan/SKILL.md\` when user requests multi-stage orchestration
-
 ## Decision Protocol
 
 When a stage requires user input (approval, choice, direction), use this structured pattern:
@@ -143,7 +132,7 @@ When a stage requires user input (approval, choice, direction), use this structu
 ## Failure Modes
 
 Watch for these anti-patterns:
-- **Skipping stages** — jumping from brainstorm to build without design/spec/plan
+- **Skipping stages** — jumping from brainstorm to tdd without design/spec/plan
 - **Ignoring gates** — claiming completion without evidence
 - **Premature implementation** — writing code before RED tests exist
 - **Hollow reviews** — "looks good" without checking spec compliance

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

@@ -1,9 +1,9 @@
 /**
- * Command contract for /cc-next - agent reads flow state, evaluates gates, advances or reports blockers.
- * Wire into install (write to `.cclaw/commands/next.md` + harness shim `cc-next.md`) in a follow-up; not invoked by CLI.
+ * Command contract for /cc-next — the primary progression command.
+ * Reads flow-state, starts the current stage if unfinished, or advances if all gates pass.
  */
 export declare function nextCommandContract(): string;
 /**
- * Skill body for /cc-next - flow logic and continue semantics.
+ * Skill body for /cc-next — the primary flow progression command.
  */
 export declare function nextCommandSkillMarkdown(): string;

package/dist/content/next-command.js

@@ -6,15 +6,12 @@ const NEXT_SKILL_NAME = "flow-next-step";
 function flowStatePath() {
     return `${RUNTIME_ROOT}/state/flow-state.json`;
 }
-function configPathLine() {
-    return `${RUNTIME_ROOT}/config.yaml`;
-}
 function delegationLogPathLine() {
     return `${RUNTIME_ROOT}/runs/<activeRunId>/delegation-log.json`;
 }
 /**
- * Command contract for /cc-next - agent reads flow state, evaluates gates, advances or reports blockers.
- * Wire into install (write to `.cclaw/commands/next.md` + harness shim `cc-next.md`) in a follow-up; not invoked by CLI.
+ * Command contract for /cc-next — the primary progression command.
+ * Reads flow-state, starts the current stage if unfinished, or advances if all gates pass.
  */
 export function nextCommandContract() {
     const flowPath = flowStatePath();
@@ -24,115 +21,133 @@ export function nextCommandContract() {
 
 ## Purpose
 
-Single **continue** command: read flow state, verify **current stage** gate satisfaction, verify any **mandatory delegations**, then either **hand off to the next stage** (load its skill and proceed) or **list blocking gates / pauses** so the user knows what to finish first.
+**The primary progression command.** Read flow state, determine what to do:
+
+- **Current stage not started / in progress** → load its skill and execute it.
+- **Current stage complete (all gates passed)** → advance \`currentStage\` and load the next skill.
+- **Flow complete** → report done.
+
+This is the only progression command the user needs to drive the entire flow. Stage command contracts are internal implementation details loaded by \`/cc-next\`.
 
 ## HARD-GATE
 
 - **Do not** invent gate completion: use only \`${flowPath}\` plus observable evidence in repo artifacts.
-- **Do not** skip stages: the only valid advance is from \`currentStage\` to that stage's configured successor in the flow schema (same order as \`/cc-brainstorm\` -> \`/cc-ship\`).
-- **Do not** treat \`/cc-next\`, \`autoAdvance\`, or user impatience as permission to bypass \`WAIT_FOR_CONFIRM\`, \`Do NOT auto-advance\`, explicit approval pauses, or mandatory delegation requirements from the current stage skill.
-- If the flow is already at the terminal stage with all ship gates satisfied, **report completion** instead of advancing.
+- **Do not** skip stages: advance only from \`currentStage\` to its configured successor.
+- If the flow is at the terminal stage with all ship gates satisfied, **report completion**.
 
 ## Algorithm (mandatory)
 
-1. Read **\`${flowPath}\`** (create parent dirs only if you are also initializing a broken install - otherwise treat missing file as **BLOCKED**: state missing).
-2. Parse JSON. Capture \`currentStage\`, \`activeRunId\` (must be present), and the current run-scoped context.
-3. Load **\`${skillRel}\`** - canonical semantics for gate evaluation and continuation live there.
-4. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema (authoritative list of gate ids).
-5. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state (if missing, treat all gates as unmet).
-6. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
-7. **Unmet** = gates in \`G\` that are not satisfied **or** appear in \`catalog.blocked\`.
-8. Let \`M\` = \`mandatoryDelegations\` for **\`currentStage\`** from the stage schema.
-9. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. A mandatory delegation counts only if that agent is recorded as **completed** or explicitly **waived** by the user. Missing or in-progress entries are blocking.
-10. Respect explicit pause rules from the current stage skill (for example \`WAIT_FOR_CONFIRM\`, \`Do NOT auto-advance\`, or "wait for explicit approval"). \`/cc-next\` is a convenience command, not authorization to bypass confirmation gates.
-11. If **any** unmet gates, blocking pause rules, or missing mandatory delegations remain: print a short **Blocking gates** list (id + human description from schema \`requiredGates\`, plus any missing delegation or approval requirement). Do **not** invoke the next stage skill yet.
-12. If **all** required gates and mandatory delegations are satisfied:
-   - If current stage's \`next\` is **\`done\`**: report **flow complete**; stop.
-   - Otherwise let \`nextStage\` be the schema successor of \`currentStage\`. Load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<nextStage>.md\`** using the real \`skillFolder\` and stage id from the schema for \`nextStage\`, then run that stage's protocol in-agent (equivalent to invoking \`/cc-\` + \`nextStage\`) without asking the user to re-type the slash-command. While doing so, obey the current and next stage skills' explicit pause rules; if either skill says to pause, stop and report readiness instead of auto-continuing through that gate.
+1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
+2. Parse JSON. Capture \`currentStage\`, \`activeRunId\`, and \`stageGateCatalog[currentStage]\`.
+3. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
+4. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
+5. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
+6. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
+7. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if the agent is **completed** or **waived**.
+
+### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
+
+→ Load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<currentStage>.md\`** for the current stage.
+→ Execute that stage's protocol. The stage skill handles the full interaction including STOP points and gate tracking.
+→ When the stage completes, the Stage Completion Protocol in the skill updates \`flow-state.json\` automatically.
+
+### Path B: Current stage IS complete (all gates passed, all delegations satisfied)
+
+→ If current stage's \`next\` is **\`done\`**: report **"Flow complete. All stages finished."** and stop.
+→ Otherwise: load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<nextStage>.md\`** for the successor stage. Execute that stage's protocol.
+
+## Resume Semantics
+
+\`/cc-next\` in a **new session** = resume from where you left off:
+- Flow-state records \`currentStage\` and which gates have passed.
+- The stage skill reads upstream artifacts and picks up context.
+- No special resume command needed — \`/cc-next\` IS the resume command.
 
 ## Primary skill
 
-**${skillRel}** - full protocol, gate/flow tie-in, and interaction with \`autoAdvance\` in **\`${configPathLine()}\`**.
+**${skillRel}** — full protocol and stage table.
 `;
 }
 /**
- * Skill body for /cc-next - flow logic and continue semantics.
+ * Skill body for /cc-next — the primary flow progression command.
  */
 export function nextCommandSkillMarkdown() {
     const flowPath = flowStatePath();
-    const cfgPath = configPathLine();
     const delegationPath = delegationLogPathLine();
-    const stageRows = ["brainstorm", "scope", "design", "spec", "plan", "test", "build", "review", "ship"]
+    const stageRows = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"]
         .map((stage) => {
         const schema = stageSchema(stage);
-        const next = schema.next === "done" ? "(terminal)" : `/cc-${schema.next}`;
+        const next = schema.next === "done" ? "(terminal)" : schema.next;
         const skillMd = `${RUNTIME_ROOT}/skills/${stageSkillFolder(stage)}/SKILL.md`;
-        return `| \`${stage}\` | ${next} | \`${skillMd}\` |`;
+        return `| \`${stage}\` | \`${next}\` | \`${skillMd}\` |`;
     })
         .join("\n");
     return `---
 name: ${NEXT_SKILL_NAME}
-description: "Evaluate current stage gates from flow state; advance to the next /cc-* stage or list blockers."
+description: "The primary progression command. Reads flow state, starts/resumes the current stage or advances to the next one."
 ---
 
-# Flow: /cc-next (gate-aware continuation)
+# /cc-next — Flow Progression
+
+## Overview
 
-## When to use
+\`/cc-next\` is **the only command you need** to drive the entire cclaw flow.
 
-- You want **one command** instead of manually typing the next \`/cc-*\` after a stage.
-- You are unsure whether **current stage gates** are satisfied.
-- The user said **continue**, **next**, or **pick up where we left off**.
+**How it works:**
+1. Reads \`flow-state.json\` to find \`currentStage\`
+2. Checks if all gates for that stage are satisfied
+3. If **not** → loads the stage skill and starts/resumes execution
+4. If **yes** → advances to the next stage and loads its skill
+
+**Resume:** \`/cc-next\` in a new session picks up from where \`flow-state.json\` says you are.
 
 ## HARD-GATE
 
-Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (paths, excerpts) consistent with \`requiredGates\` for \`currentStage\`. If evidence is missing, list the gate as **unmet**. Also treat missing mandatory delegations or unresolved confirmation pauses as blockers even if someone claims the stage is "basically done."
+Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (paths, excerpts). If evidence is missing, list the gate as **unmet**. Do **not** skip stages.
+
+## Algorithm
 
-## Read flow state
+### Step 1: Read state
 
 1. Open **\`${flowPath}\`**.
-2. Record \`currentStage\`, \`activeRunId\`, and \`stageGateCatalog[currentStage]\` (\`required\`, \`passed\`, \`blocked\` arrays).
-3. If the file is missing or invalid JSON -> **BLOCKED** (report; do not advance).
-4. Resolve the current delegation ledger at **\`${delegationPath}\`** using the recorded \`activeRunId\`.
+2. Record \`currentStage\`, \`activeRunId\`, \`stageGateCatalog[currentStage]\`.
+3. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
 
-## Evaluate gates for \`currentStage\`
+### Step 2: Evaluate gates
 
-For each gate id in the stage schema's \`requiredGates\` for \`currentStage\`:
+For each gate id in \`requiredGates\` for \`currentStage\`:
+- **Met** if in \`catalog.passed\` and not in \`catalog.blocked\`.
+- **Unmet** otherwise.
 
-- **Met** if the id is in \`catalog.passed\` and **not** in \`catalog.blocked\`.
-- **Blocked** if the id is in \`catalog.blocked\` (always list these first).
-- **Unmet** if not met (explain what evidence or artifact action is still needed, using the gate's description from the schema).
+Check \`mandatoryDelegations\` via **\`${delegationPath}\`** — satisfied only if **completed** or **waived**.
 
-Also evaluate stage-level transition blockers:
+### Step 3: Act
 
-- Read \`mandatoryDelegations\` from the current stage schema.
-- If any mandatory agent is required, inspect **\`${delegationPath}\`**. Treat that agent as satisfied only if the ledger records it as **completed** or explicitly **waived** by the user.
-- Treat explicit pause rules from the current stage skill (for example \`WAIT_FOR_CONFIRM\`, \`Do NOT auto-advance\`, or "wait for explicit approval") as authoritative. **/cc-next** does not override them.
+**Path A — stage NOT complete (any gate unmet):**
 
-If **any** gate is unmet or blocked, or any mandatory delegation / confirmation pause remains unresolved -> output **Blocking gates** (bulleted: \`id\` or agent name - reason). **Stop** without loading the next stage skill.
+Load the current stage's skill and command contract:
+- \`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`
+- \`${RUNTIME_ROOT}/commands/<currentStage>.md\`
 
-## Advance (all gates satisfied)
+Execute the stage protocol. The stage skill handles interaction, STOP points, gate tracking, and the Stage Completion Protocol (updates \`flow-state.json\` when done).
 
-1. Look up \`currentStage\` in the transition table below. If next is **terminal**, print **Flow complete** and stop.
-2. Let \`nextStage\` be the \`To\` stage. Read **\`${RUNTIME_ROOT}/commands/<nextStage>.md\`** and **\`${RUNTIME_ROOT}/skills/<folder>/SKILL.md\`** for that row.
-3. **Continue semantics:** execute that stage's protocol **in the same session** as a natural handoff (you are now "in" \`nextStage\` until it completes or blocks).
-4. Honor **\`${cfgPath}\`**: \`autoAdvance\` only applies where the stage skill allows it. Explicit pause / confirmation rules in either the current or next stage always win.
-5. If the next stage reaches a confirmation gate or a "do not auto-advance" boundary, stop there and report readiness instead of claiming automatic advancement through that gate.
+**Path B — stage IS complete (all gates met, all delegations done):**
 
-## Stage order (reference)
+If \`next\` is \`done\` → report **"Flow complete. All stages finished."** and stop.
 
-| Stage | Next command | Skill path |
-|---|---|---|
-${stageRows}
+Otherwise load the next stage's skill and command contract, begin execution.
 
-## Relation to per-stage skills
+## Stage order
 
-Wave auto-execute (\`waveExecutionAllowed\`) applies only to **test** and **build** skills after plan approval - see those SKILL.md files. **/cc-next** does not replace RED/GREEN/REFACTOR discipline; it only removes friction **between** stages.
+| Stage | Next | Skill path |
+|---|---|---|
+${stageRows}
 
 ## Anti-patterns
 
 - Advancing when \`blocked\` is non-empty for the current stage.
 - Treating \`passed\` as trusted when artifact evidence contradicts it.
-- Using **/cc-next** to bypass \`WAIT_FOR_CONFIRM\`, explicit approval pauses, or missing mandatory delegations.
 - Skipping **review** or **ship** because "the code looks fine".
+- Loading a stage skill directly instead of using \`/cc-next\` for progression.
 `;
 }