add /ctx-task-out — close the spec→implement gap in the canonical chain

docs/home/common-workflows.md

@@ -355,6 +355,7 @@ These have no CLI equivalent. They require the agent's reasoning.
 | `/ctx-prompt-audit`       | Analyze prompting patterns for improvement                                              |
 | `/ctx-plan`               | Stress-test an existing plan through adversarial interview                              |
 | `/ctx-plan-import`       | Import Claude Code plan files into project specs                                        |
+| `/ctx-task-out`           | Decompose a committed spec into a per-milestone implementation plan                     |
 | `/ctx-implement`          | Execute a plan step-by-step with verification                                           |
 | `/ctx-worktree`           | Manage parallel agent worktrees                                                         |
 | `/ctx-journal-enrich`     | Add metadata, tags, and summaries to journal entries                                    |

docs/operations/integrations.md

@@ -321,6 +321,7 @@ These are invoked in Claude Code with `/skill-name`.
 | Skill               | Description                                      |
 |---------------------|--------------------------------------------------|
 | `/ctx-loop`         | Generate a Ralph Loop iteration script           |
+| `/ctx-task-out`     | Decompose a committed spec into a milestone plan |
 | `/ctx-implement`    | Execute a plan step-by-step with checks          |
 | `/ctx-plan-import` | Import Claude Code plan files into project specs |
 | `/ctx-worktree`     | Manage git worktrees for parallel agents         |

docs/recipes/design-before-coding.md

@@ -23,22 +23,25 @@ the next session has no idea why things are shaped this way.
 ```text
 /ctx-brainstorm          # explore the design space
 /ctx-spec                # write the spec document
-/ctx-task-add            # break it into tasks
+/ctx-task-out            # decompose into a milestone plan
 /ctx-implement           # execute step-by-step
 ```
 
 Four skills, used in sequence. Each produces an artifact that feeds
-the next.
+the next. For specs small enough to implement in one session, the
+spec doubles as the plan: skip `/ctx-task-out` and break the work
+into TASKS.md entries with `/ctx-task-add` instead.
 
 ## Commands and Skills Used
 
-| Tool                | Type  | Purpose                                         |
-|---------------------|-------|-------------------------------------------------|
-| `/ctx-brainstorm`   | Skill | Structured design dialogue: explore approaches  |
-| `/ctx-spec`         | Skill | Scaffold and fill out a spec from the template  |
-| `/ctx-task-add`     | Skill | Add implementation tasks to TASKS.md            |
-| `/ctx-implement`    | Skill | Execute a plan step-by-step with verification   |
-| `/ctx-decision-add` | Skill | Record design choices made during brainstorming |
+| Tool                | Type  | Purpose                                            |
+|---------------------|-------|----------------------------------------------------|
+| `/ctx-brainstorm`   | Skill | Structured design dialogue: explore approaches     |
+| `/ctx-spec`         | Skill | Scaffold and fill out a spec from the template     |
+| `/ctx-task-out`     | Skill | Decompose a spec into `specs/plans/<milestone>.md` |
+| `/ctx-task-add`     | Skill | Add implementation tasks to TASKS.md               |
+| `/ctx-implement`    | Skill | Execute a plan step-by-step with verification      |
+| `/ctx-decision-add` | Skill | Record design choices made during brainstorming    |
 
 ## The Workflow
 
@@ -109,9 +112,10 @@ and won't accept "none" without a challenge.
 Sections that don't apply can be skipped. The result is a complete spec
 at `specs/{feature-name}.md`.
 
-### Step 3: Break into Tasks
+### Step 3: Task Out the Work
 
-After the spec is written, the skill offers to create tasks:
+After the spec is written, the skill routes by size. A small,
+single-session spec gets tasks in TASKS.md directly:
 
 ```text
 Agent: "Spec written to specs/rss-feed.md. Want me to break this
@@ -133,11 +137,37 @@ Each task is independently completable and references the spec via
 You can also invoke `/ctx-task-add` directly at any point to add
 individual tasks.
 
+A spec that spans multiple milestones (or more than about one
+session of implementation) gets `/ctx-task-out` instead:
+
+```text
+You: /ctx-task-out --spec specs/v1-substrate.md --milestone m0a
+
+Agent: "Open questions check: D-001 (language choice) is blocking
+  for m0a — three tasks would embed an assumption about its
+  answer. Resolve it before I decompose."
+
+You: [resolves D-001 in the spec]
+
+Agent: [writes specs/plans/m0a.md: data model, contracts, test
+  matrix, 24 tasks with falsifiable acceptance criteria]
+       "Plan written. TASKS.md gained 4 epic anchors, each
+       annotated Plan: specs/plans/m0a.md."
+```
+
+The plan document owns the fine-grained tasks; TASKS.md carries
+epic-level anchors only. Two hard gates apply: decomposition
+refuses to run past a blocking open question in the spec, and
+milestone N+1 is not tasked out while milestone N's definition of
+done is unmet.
+
 ### Step 4: Implement Step-by-Step
 
-Pick up tasks with `/ctx-implement`. The skill loads the spec, breaks
-work into atomic steps, and checkpoints after every 3-5 steps with
-a build and test verification:
+Pick up the work with `/ctx-implement`. The skill loads the plan —
+`specs/plans/<milestone>.md` when `/ctx-task-out` produced one, the
+spec itself for small features — breaks it into atomic steps, and
+checkpoints after every 3-5 steps with a build and test
+verification:
 
 ```text
 You: /ctx-implement (specs/rss-feed.md)
@@ -164,7 +194,7 @@ Not every feature needs all four steps. Use your judgment:
 |----------------------------------------|--------------------|
 | Vague idea, multiple valid approaches  | Step 1: Brainstorm |
 | Clear approach, need to document it    | Step 2: Spec       |
-| Spec already exists, need to plan work | Step 3: Tasks      |
+| Spec already exists, need to plan work | Step 3: Task out   |
 | Tasks exist, ready to code             | Step 4: Implement  |
 
 A brainstorm without a spec is fine for small decisions. A spec without
@@ -180,6 +210,7 @@ You don't need skill names. Natural language works:
 | "Let's think through this feature" | `/ctx-brainstorm`    |
 | "Spec this out"                    | `/ctx-spec`          |
 | "Write a design doc for..."        | `/ctx-spec`          |
+| "Task this out"                    | `/ctx-task-out`      |
 | "Break this into tasks"            | `/ctx-task-add`      |
 | "Implement the spec"               | `/ctx-implement`     |
 | "Let's design before we build"     | Starts at brainstorm |
@@ -209,8 +240,12 @@ You don't need skill names. Natural language works:
   structured design dialogue
 * [Skills Reference: /ctx-spec](../reference/skills.md#ctx-spec):
   spec scaffolding from template
+* [Skills Reference: /ctx-task-out](../reference/skills.md#ctx-task-out):
+  spec decomposition into a per-milestone plan
 * [Skills Reference: /ctx-implement](../reference/skills.md#ctx-implement):
   step-by-step execution with verification
+* [Scrutinizing a Plan](scrutinizing-a-plan.md): the adversarial
+  interview that belongs between brainstorm and spec
 * [Tracking Work Across Sessions](task-management.md): task lifecycle
   and archival
 * [Importing Claude Code Plans](import-plans.md): turning ephemeral plans

docs/recipes/index.md

@@ -355,11 +355,11 @@ optionally create tasks referencing each imported spec.
 ### [Design Before Coding](design-before-coding.md)
 
 Front-load design with a four-skill chain: **brainstorm** the approach,
-**spec** the design, **task** the work, **implement** step-by-step.
+**spec** the design, **task out** the work, **implement** step-by-step.
 Each step produces an artifact that feeds the next.
 
-**Uses**: `/ctx-brainstorm`, `/ctx-spec`, `/ctx-task-add`,
-`/ctx-implement`, `/ctx-decision-add`
+**Uses**: `/ctx-brainstorm`, `/ctx-spec`, `/ctx-task-out`,
+`/ctx-task-add`, `/ctx-implement`, `/ctx-decision-add`
 
 ---
 

docs/recipes/scrutinizing-a-plan.md

@@ -78,10 +78,16 @@ alternatives have a recall trigger.
 
 ## Output
 
-`/ctx-plan` produces a clearer plan, not a document. Persist the
-deltas via:
-
-- **`/ctx-spec`** if the conclusions belong in a feature spec.
+`/ctx-plan` concludes by offering to write a *debated brief* to
+`.context/briefs/<TS>-<slug>.md`: the bet, the rejections, the
+failure modes, the validation route, and the unwind cost, in your
+words. It deliberately does **not** produce an implementation plan
+or a task list — decomposition happens after the spec, via
+`/ctx-task-out`. Feed the interview's conclusions forward via:
+
+- **`/ctx-spec --brief <path>`** to absorb the brief into a
+  committed spec; multi-milestone specs then flow to
+  `/ctx-task-out` for decomposition.
 - **`/ctx-decision-add`** if a tradeoff resolved into an
   architectural decision.
 - **`/ctx-learning-add`** if you discovered a project-specific

docs/reference/skills.md

@@ -64,7 +64,9 @@ opinionated behavior on top.
 | [`/ctx-link-check`](#ctx-link-check)                   | Audit docs for dead internal and external links                 | user-invocable |
 | [`/ctx-permission-sanitize`](#ctx-permission-sanitize) | Audit Claude Code permissions for security risks                | user-invocable |
 | [`/ctx-brainstorm`](#ctx-brainstorm)                     | Structured design dialogue before implementation                | user-invocable |
+| [`/ctx-plan`](#ctx-plan)                                 | Stress-test a plan through adversarial interview                | user-invocable |
 | [`/ctx-spec`](#ctx-spec)                                 | Scaffold a feature spec from a project template                 | user-invocable |
+| [`/ctx-task-out`](#ctx-task-out)                         | Decompose a committed spec into a per-milestone plan            | user-invocable |
 | [`/ctx-plan-import`](#ctx-plan-import)                 | Import Claude Code plan files into project specs                | user-invocable |
 | [`/ctx-implement`](#ctx-implement)                       | Execute a plan step-by-step with verification                   | user-invocable |
 | [`/ctx-loop`](#ctx-loop)                                 | Generate autonomous loop script                                 | user-invocable |
@@ -477,6 +479,33 @@ stress-test the chosen approach, and present the detailed design.
 "before we build", "what approach should we take?"
 
 **See also**:
+[`/ctx-plan`](#ctx-plan),
+[`/ctx-spec`](#ctx-spec)
+
+---
+
+### `/ctx-plan`
+
+Stress-test a plan through an adversarial interview before it becomes
+a spec. Asks one question at a time across scope, failure modes,
+rejected alternatives, sequencing, reversibility, and hidden
+assumptions — pushing back rather than validating. Stops when the
+user can articulate the bet, the rejections, the top failure modes,
+the cheapest validation, and the unwind cost. Concludes by offering
+to write a *debated brief* to `.context/briefs/<TS>-<slug>.md`, the
+canonical input for `/ctx-spec --brief`. Deliberately does **not**
+produce an implementation plan or task list — that happens two steps
+later, at [`/ctx-task-out`](#ctx-task-out).
+
+**Wraps**: reads code and context files;
+writes `.context/briefs/<TS>-<slug>.md`
+
+**Trigger phrases**: "attack this plan", "poke holes in this",
+"stress-test my plan", "scrutinize this before I commit"
+
+**See also**:
+[Scrutinizing a Plan](../recipes/scrutinizing-a-plan.md),
+[`/ctx-brainstorm`](#ctx-brainstorm),
 [`/ctx-spec`](#ctx-spec)
 
 ---
@@ -517,13 +546,58 @@ filling the gap from inference. If the brief contradicts a
 frozen contract, the contradiction is surfaced to the user
 rather than silently followed.
 
+Both flows end with a **tasking handoff**: specs that span
+multiple milestones (or more than roughly one session of
+implementation) are routed to [`/ctx-task-out`](#ctx-task-out)
+for decomposition; small specs go straight to
+[`/ctx-implement`](#ctx-implement).
+
 **See also**:
 [`/ctx-brainstorm`](#ctx-brainstorm),
 [`/ctx-plan`](#ctx-plan),
+[`/ctx-task-out`](#ctx-task-out),
 [`/ctx-plan-import`](#ctx-plan-import)
 
 ---
 
+### `/ctx-task-out`
+
+Decompose a committed spec into a per-milestone implementation plan
+at `specs/plans/<milestone>.md` — data model, contracts, an
+invariant-test matrix, and typically 15-40 tasks, each with a
+**falsifiable acceptance criterion** (a command to run, a test that
+must pass, an observable behavior). The plan is the document
+[`/ctx-implement`](#ctx-implement) executes. The skill is a
+decomposer, not a designer: disagreements with the spec route back
+through [`/ctx-plan`](#ctx-plan) instead of being relitigated here.
+
+Two **hard gates** refuse rather than degrade:
+
+1. **Blocking-TBD gate**: the spec's open questions are classified
+   as blocking or deferrable for the target milestone; decomposition
+   refuses to proceed past a blocking TBD (a task that would embed
+   an assumption about its answer).
+2. **Rolling-wave gate**: milestone N+1 is not decomposed while
+   milestone N's definition of done is unmet, unless the user
+   overrides explicitly (recorded in the plan header).
+
+TASKS.md receives **epic-level anchors only**, each annotated
+`Plan: specs/plans/<milestone>.md` — the plan owns the fine-grained
+tasks, one-way sync, nothing moved or deleted. Single-session specs
+skip this step entirely: the spec *is* the plan.
+
+**Wraps**: reads the spec, TASKS.md, DECISIONS.md, CONVENTIONS.md;
+writes `specs/plans/<milestone>.md`, appends anchors to TASKS.md
+
+**Trigger phrases**: "task this out", "break down the spec",
+"decompose the spec", "plan out the milestone"
+
+**See also**:
+[`/ctx-spec`](#ctx-spec),
+[`/ctx-implement`](#ctx-implement)
+
+---
+
 ### `/ctx-plan-import`
 
 Import Claude Code plan files (`~/.claude/plans/*.md`) into the project's
@@ -543,13 +617,18 @@ optionally chains to `/ctx-task-add`
 ### `/ctx-implement`
 
 Execute a multi-step plan with build and test verification at each
-step. Loads a plan from a file or conversation context, breaks it
-into atomic steps, and checkpoints after every 3-5 steps.
+step. The canonical input is `specs/plans/<milestone>.md` as written
+by [`/ctx-task-out`](#ctx-task-out), but hand-written plan files and
+plans from conversation context work too. Breaks the plan into
+atomic steps and checkpoints after every 3-5 steps. Handed a bare
+multi-milestone spec instead of a plan, it redirects to
+`/ctx-task-out` rather than decomposing on the fly.
 
 **Wraps**: reads plan file, runs verification commands
 (`go build`, `go test`, etc.)
 
 **See also**:
+[`/ctx-task-out`](#ctx-task-out),
 [Running an Unattended AI Agent](../recipes/autonomous-loops.md)
 
 ---

go.work.sum

@@ -85,12 +85,18 @@ go.opentelemetry.io/contrib/detectors/gcp v1.42.0/go.mod h1:W9zQ439utxymRrXsUOzZ
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
 golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
+golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/telemetry v0.0.0-20260508192327-42602be52be6 h1:HjU6IWBiAgRIdAJ9/y1rwCn+UELEmwV+VsTLzj/W4sE=
 golang.org/x/telemetry v0.0.0-20260508192327-42602be52be6/go.mod h1:Eqhaxk/wZsWEH8CRxLwj6xzEJbz7k1EFGqx7nyCoabE=
+golang.org/x/telemetry v0.0.0-20260610154732-fb80ec83bdd9 h1:FjUup8XrRy7lv+XHONi6KKUSizeF2NnVrTnz/HhbohQ=
+golang.org/x/telemetry v0.0.0-20260610154732-fb80ec83bdd9/go.mod h1:3AWMyWHS+caVoiEXpiq6+tzKA40J4vQT3MYr80ZtQpc=
 golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
 golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
+golang.org/x/term v0.44.0 h1:0rLvDRCtNj0gZkyIXhCyOb2OAzEhLVqc4B+hrsBhrmc=
+golang.org/x/term v0.44.0/go.mod h1:7ze4MdzUzLXpSAoFP1H0bOI9aXDqveSvatT5vKcFh2Y=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
 google.golang.org/appengine v1.6.7 h1:FZR1q0exgwxzPzp/aF+VccGrSfxfPpkBqjIIEq3ru6c=
 google.golang.org/appengine v1.6.7/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCIDZVag1xfc=

internal/assets/claude/skills/ctx-implement/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: ctx-implement
-description: "Execute a plan step-by-step with verification. Use when you have a plan document and need disciplined, checkpointed implementation."
+description: "Execute a plan step-by-step with verification. Use when you have a plan document — canonically specs/plans/<milestone>.md from /ctx-task-out — and need disciplined, checkpointed implementation."
 ---
 
-Take a plan (inline text, file path, or from the conversation)
-and execute it step-by-step with build/test verification between
-steps.
+Take a plan — canonically `specs/plans/<milestone>.md` as written
+by `/ctx-task-out`, though inline text, another file path, or a
+plan from the conversation also work — and execute it
+step-by-step with build/test verification between steps.
 
 ## When to Use
 
+- After `/ctx-task-out` has decomposed a spec into
+  `specs/plans/<milestone>.md` (the canonical input)
 - When the user provides a plan document or file and says
   "implement this"
 - When a multi-step task has been planned and needs disciplined
@@ -20,6 +23,9 @@ steps.
 ## When NOT to Use
 
 - For single-step tasks: just do them directly
+- When handed a bare multi-milestone spec instead of a plan:
+  suggest `/ctx-task-out --spec <path> --milestone <first>`
+  first; decomposing on the fly is what it exists to prevent
 - When the plan is vague or incomplete: use `/ctx-brainstorm`
   first to refine it
 - When the user wants to explore or discuss, not execute
@@ -29,6 +35,7 @@ steps.
 
 ```text
 /ctx-implement
+/ctx-implement specs/plans/m0a.md
 /ctx-implement path/to/plan.md
 /ctx-implement (the plan from our discussion above)
 ```
@@ -38,6 +45,14 @@ steps.
 ### 1. Load the plan
 
 - If a file path is provided, read it
+- If the file is a multi-milestone spec rather than a plan (no
+  task breakdown, no acceptance criteria, spans milestones),
+  redirect: suggest `/ctx-task-out --spec <path> --milestone
+  <first>` and stop rather than improvising a decomposition
+- If the plan's header shows `Status: Blocked`, stop: a
+  deferrable TBD graduated to blocking mid-milestone. Route its
+  resolution (a spec edit or DECISIONS.md entry) and a
+  `/ctx-task-out` amendment run before executing further tasks
 - If inline text is provided, use it directly
 - If neither, look back in the conversation for the most
   recent plan or approved design
@@ -85,6 +100,11 @@ Verify after every individual step before proceeding to the next.
 
 After every 3-5 steps (or after a significant milestone):
 - Summarize what has been completed
+- If executing `specs/plans/<milestone>.md`, check off completed
+  tasks and DoD items in the plan document — it is the execution
+  ledger that `/ctx-task-out`'s rolling-wave gate reads. Never
+  edit a task's acceptance criterion in place; a criterion
+  change goes back through `/ctx-task-out` (amendment mode)
 - Note any deviations from the plan
 - Ask the user if they want to continue, adjust, or stop