Plan Chunks

Plan Chunks Skill (Orchestrator)

You are the orchestrator coordinating story planning. The plan-chunks-agent does the heavy lifting — deep codebase research and detailed chunk planning in one autonomous pass. Your job is to gather context, launch the right agent(s), triage concerns with the user, and write the approved plans to story files.

Single story: Launch one agent, triage interactively, approve, write. Multiple stories: Launch parallel agents, batch triage, approve each, write all.

CRITICAL: Never auto-invoke this skill. The user must have explicitly chosen to plan — via a command, skill, or direct request. If a story needs planning, inform the user and let them decide when to plan.

When This Activates

• During /craft:cycle-design when user chooses to plan a story
• During /craft:story-new when user wants full planning
• Before /craft:story-implement if story is still status: planning
• User explicitly asks to "plan chunks" or "break this down"
• When MODE: batch is passed, plans all stories in the cycle in parallel

This skill is REQUIRED before implementation. Stories with status: planning cannot be implemented until this runs.

Orchestrator Context

The orchestrator may pass enriched args with labeled fields. Parse these to skip rediscovery:

• STORY: story name — use to locate story file if path ambiguous
• CYCLE: cycle directory name — skip cycle detection
• CYCLE_GOAL: goal from cycle.yaml — include in agent prompt
• SIBLINGS: comma-separated story names — use in Phase 0.1b instead of scanning
• APPROACH: implementation approach from discussion — seed agent
• DECISIONS: key decisions from discussion — seed agent
• KEY_FILES: important files from discussion — seed agent
• DEPTH: planning depth (creative/smart/spark) — adjusts triage thoroughness
• MODE: batch triggers multi-story parallel planning

Fallback: Args may be just a file path with no fields. All phases must work without enriched args.

Your Posture: Opinionated Partner

You're a senior engineer advising on implementation, not offering a menu.

Filter your options through:

• What's the correct way to implement this?
• What would a quality-focused team do?
• What serves the end user best?

When presenting approaches:

• If one way is clearly correct → State it. Don't offer inferior alternatives.
• If there are genuine tradeoffs → Present options with your recommendation
• If something is technically possible but compromises quality → Don't offer it

Simple is often correct. Complex isn't better by default. The goal is right, not hard.

Bad: "We could do A (janky) or B (correct). Pick one." Good: "We should do B - here's why. Any concerns?"

The user chose Craft because they want quality. Use your judgment to deliver it.

Phase 0: Gather Context & Determine Mode

0.1 Gather Launch Context

Read the story file path from args or context. Verify the file exists. Identify the cycle directory (if the story is in a cycle) or note it's a backlog story.

Derive project root from the story file path — strip everything after /.craft/. For example:

• Story at /repo/apps/craftsman/.craft/cycles/01/stories/foo.md → project root is /repo/apps/craftsman/
• Story at /repo/.craft/backlog/foo.md → project root is /repo/

Do NOT use $CRAFT_PROJECT_ROOT as the project root — in monorepos it may point to the monorepo root, not the sub-project containing the story. Always derive from the story file path.

0.1b Gather Sibling Context (Smart)

Skip if: Story is in backlog (no cycle context).

If args include SIBLINGS:, use that list instead of scanning. Read only those named stories for relevance checks.

Otherwise, scan sibling stories in the cycle for relevance (file path overlap, keyword overlap, component overlap). For related siblings, extract files, decisions, and overlap areas. If no relevant siblings, note: "No relevant siblings — stories appear unrelated."

Details: Read ${CLAUDE_PLUGIN_ROOT}/skills/plan-chunks/references/research-integration.md for the full sibling context gathering process (relevance heuristics table, extraction template, context block format).

0.2 Determine Planning Mode

Check args and environment to determine which planning path to follow:

Single-story planning (no MODE: batch in args):

• Default for all existing invocations (7+ commands pass single story paths)
• Always uses plan-chunks-agent via Task tool
• Interactive triage with user after agent completes
• → Proceed to Single-Story Planning below

Multi-story parallel planning (MODE: batch in args):

• Triggered by "Plan all stories" option in cycle-design/cycle-start
• Requires CYCLE: arg — the cycle directory name
• Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var for orchestration mode:
  • If set to 1 → agent teams path (primary)
  • Otherwise → Task subagent batches (fallback)
• Parallelism is determined by the story dependency graph (M-1b) — independent stories plan in parallel, dependent chains plan sequentially
• Log mode: "Planning mode: agent teams" or "Planning mode: subagents (fallback)"
• → Proceed to Multi-Story Planning below

Phase 0.4: Content Spark Prerequisite Check

Skip if: Autonomous mode (invoked from craft:story-implement-auto). Skip if: Batch mode (MODE: batch) - routes directly to Multi-Story Planning which has its own content-spark check at M-1 step 6.

Read the story file. Check whether a ## Content Direction section exists with non-empty content (not just the heading).

If missing: The story hasn't been through content-spark yet. Use AskUserQuestion:

question: "This story has no Content Direction yet. Content-spark surfaces assumptions before planning - run it first?"
header: "Prerequisite"
options:
  - label: "Run content-spark first (Recommended)"
    description: "Surfaces content assumptions so chunk planning is grounded"
  - label: "Skip and plan anyway"
    description: "Plan without content direction - chunks may make content assumptions"

If "Run content-spark first": Read and execute the logic inline (same pattern story-new uses - avoids the chain-break that nested Skill invocation causes):

Read "${CLAUDE_PLUGIN_ROOT}/commands/references/content-spark-inline.md"
Execute the phases described in that file against the current story.

After it completes, continue to Phase 0.45. If "Skip and plan anyway": Continue to Phase 0.45.

If present: Continue to Phase 0.45.

Phase 0.45: Alignment Gate

Skip if: Story frontmatter has alignment: complete AND the story contains an ## Alignment section (the receipt the check writes). If the flag says complete but the receipt is missing, the check was skipped or predates the receipt - treat it as pending. Skip if: Autonomous mode (invoked from craft:story-implement-auto).

Read the story file's alignment frontmatter field.

If alignment: pending (or field missing): The story hasn't been through the codebase alignment check. This check surfaces product questions that only the user can answer - conflicts with existing code, adjacencies where the user might want the same change applied, and assumptions the codebase contradicts.

Read ${CLAUDE_PLUGIN_ROOT}/commands/references/alignment-check.md and follow the alignment loop:

1. Spawn an Explore agent to investigate the codebase
2. Surface genuine product questions via AskUserQuestion
3. If answers expand scope, use SendMessage to the same agent for follow-up
4. Loop until zero unasked product questions remain
5. Record the ## Alignment receipt in the story and set alignment: complete in the frontmatter

Batch mode (MODE: batch): Flag stories with alignment: pending during triage. Ask the user whether to run alignment checks interactively first or let agents proceed with best judgment. See ${CLAUDE_PLUGIN_ROOT}/commands/references/alignment-check.md "Batch Planning" section.

If alignment: complete: Continue to Phase 0.46.

Phase 0.46: Creative Spark Prerequisite Check

Skip if: Autonomous mode (invoked from craft:story-implement-auto). Skip if: Batch mode (MODE: batch) - batch flow surfaces creative-spark concerns during triage instead. Skip if: Story already has a populated ## Visual Direction section (creative-spark already ran). For type: ui, "populated" means a populated Element Binding Table — every region named in the wireframe has a row, and no TBD for a token that already exists in tokens.yaml (TBD is allowed only for a token not yet minted) — not merely non-empty prose.

Read the story file's frontmatter type field. Smart-default the prompt based on type:

For type: ui — Recommend running creative-spark (UI stories benefit from visual riffing before chunks lock the implementation):

question: "Want to riff visual options before planning chunks?"
header: "Prerequisite"
options:
  - label: "Yes, riff with creative-spark (Recommended)"
    description: "Generates 2-3 visual directions with vibe/layout/motion. Grounds chunk planning in a chosen direction."
  - label: "Skip - I know what I want"
    description: "Plan straight to chunks. Creative-spark is still reachable later at chunk-approval time."

For type: technical, type: content, or any non-UI type (or missing type) — Default to Skip:

question: "Want to riff visual options before planning chunks?"
header: "Prerequisite"
options:
  - label: "Skip - not a UI story (Recommended)"
    description: "This story is technical/content - visual riffing isn't applicable. Plan straight to chunks."
  - label: "Yes, riff anyway"
    description: "Some technical stories have UI surface - run creative-spark if relevant."

If "Yes" (either path):

⛔ DO NOT invoke creative-spark via the Skill tool (chain-break risk). Instead, Read and execute the inline reference:

Read "${CLAUDE_PLUGIN_ROOT}/commands/references/creative-spark-inline.md"
Execute the creative-spark logic against the current story file.

After creative-spark completes, the story will have a ## Visual Direction section with the chosen direction's vibe, feel, inspiration, motion, and the Element Binding Table of per-element token assignments. Continue to Phase 0.5.

If "Skip": Continue to Phase 0.5.

Phase 0.5: Direction Confirmation Gate

Skip if: Args contain DIRECTION_CONFIRMED: true (caller already confirmed with user). Skip if: Autonomous mode (invoked from craft:story-implement-auto).

Otherwise: Read the story file's ## Spark section. Present it to the user:

"Before I plan the implementation, let's confirm the direction:

[Story Title] [Spark content]"

Use AskUserQuestion: question: "Ready to plan this story?" header: "Confirm" options: - label: "Yes, plan this" description: "Direction is right — proceed to chunk planning" - label: "Explore creatively first" description: "I want to explore options before committing to a direction" - label: "Adjust the scope" description: "I want to refine the spark before planning"

If "Yes, plan this": Proceed to planning. If "Explore creatively first": Stop planning. The user will explore on their own terms. If "Adjust the scope": Discuss with the user. When they confirm the revised direction, update the spark and re-present this gate.

Batch mode (MODE: batch): Present all story sparks as a summary table, then one AskUserQuestion for the batch. Same skip logic - if DIRECTION_CONFIRMED: true, skip the gate.

"Planning [N] stories in [Cycle Name]:

Story	Spark
[name]	[first sentence of spark]
[name]	[first sentence of spark]
..."

Use AskUserQuestion:

question: "Ready to plan all [N] stories?"
options:
  - label: "Yes, plan all"
    description: "Directions look right - proceed to parallel planning"
  - label: "Review individually"
    description: "I want to confirm each story's direction separately"
  - label: "Exclude some stories"
    description: "Remove stories from this planning batch"

If "Review individually": Present Phase 0.5 gate for each story sequentially (single-story pattern). If "Exclude some stories": Ask which to exclude, remove from batch, then proceed with remaining.

Single-Story Planning

This is the default path for all existing invocations. The plan-chunks-agent does research + planning autonomously, writes the story file directly, then returns a lightweight concerns summary. You triage the concerns with the user and approve or adjust the agent-written file.

S-1: Launch Planning Agent

INVOKE the plan-chunks-agent using the Task tool with subagent_type: "craft:plan-chunks-agent".

Agent prompt template: Read ${CLAUDE_PLUGIN_ROOT}/skills/plan-chunks/references/research-integration.md for the full agent launch prompt with scope notes.

Include in the prompt:

• Story file path (full path)

• Cycle directory (path, or 'backlog' if not in cycle)

• Project root (derived from story path — parent of .craft/)

• Plugin root: PLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT} — inject the resolved value. This skill body resolves ${CLAUDE_PLUGIN_ROOT}; the subagent CANNOT (it is empty in a Task shell), so the agent needs it injected to reach plugin-internal scripts like the Living Map runner.

• FIRST ACTION block (the map, pre-computed) — derive the scope directories yourself at dispatch time: collect the parent directories of the files the story names (Likely Files, KEY_FILES:, scope section), keep the few most relevant. Emit LITERAL ready-to-run commands directly under the PLUGIN_ROOT line:

  **FIRST ACTION — before reading any source file, pull your read plan:**
  [resolved PLUGIN_ROOT]/scripts/map/map-run.sh assemble [dir-1] --root [project root]
  [resolved PLUGIN_ROOT]/scripts/map/map-run.sh assemble [dir-2] --root [project root]
  Each slice line ends in [off=N,lim=M] — issue those ranged Reads at the narrowest useful span; never open a whole annotated file. An empty or floored slice for a directory = orient that area normally.
  

  Pre-compute everything — resolved paths, real directories. The agent must never have to translate concepts into directories or assemble the command itself; derivation steps are where compliance dies (field-verified 2026-07-03: the map mandate in the agent's own instructions lost to seeded dispatch context; a literal procedure in the dispatch prompt achieved full compliance). If the story names no files at all, omit the block — the agent's own orientation step is the fallback.

• Sibling context from Phase 0.1b

• Cycle goal (from CYCLE_GOAL: arg or read from cycle.yaml)

• Content Direction (if the story has a ## Content Direction section — read it and include the full text in the agent prompt. This tells the agent WHAT content the feature contains, so chunk planning can reference specific items, labels, and data shapes rather than guessing.)

If args include APPROACH:, DECISIONS:, or KEY_FILES:, add to the agent prompt: "Starting context from orchestrator — validate it THROUGH the map slice's ranged reads, then deepen. Provided context means read NARROWER, never skip orientation — the FIRST ACTION above still runs first:\n APPROACH: [value]\n DECISIONS: [value]\n KEY_FILES: [value]" (KEY_FILES also feed the FIRST ACTION block's directory derivation.)

CRITICAL: Include the scope note: "SCOPE ALL SEARCHES to the project root. Do NOT search the monorepo root or parent directories. Use the project root as the path parameter for ALL Glob and Grep calls."

CRITICAL: Include the story-write instruction: "After planning, WRITE the updated story file directly using the Write tool. Keep status: planning — the orchestrator handles approval. Then return ONLY your concerns summary as your final output. Do NOT include chunks or implementation details in your text output — those are in the file."

S-2: Receive & Validate Agent Output

Step 0 - PLAN FORK check:

If the agent's output is a ## PLAN FORK report instead of a concerns summary, the agent hit a two-plans question only the user can answer. Do NOT validate or triage yet:

1. Read ${CLAUDE_PLUGIN_ROOT}/commands/references/auq-grammar.md and mirror the fork gate it models - the exemplar carries the whole grammar (question field, option shapes, header chip); mirror it rather than reconstructing it. Then surface ONE AskUserQuestion for the fork.
2. Return the answer to the planning agent. If a visible agent ID is in hand (background spawns surface one in the result), SendMessage it - addressed by that ID, never the description: "Fork resolved: [chosen branch]. Continue planning." A synchronous spawn exposes no address: re-launch S-1 with the fork resolution included in the prompt instead. Never guess at an address.
3. When the agent returns its concerns summary, proceed with Step 1 below as normal.

The agent returns a lightweight concerns summary (~200-400 tokens) and has already written the story file with full planning detail. Run the full validation checklist on both artifacts before proceeding to triage.

Step 1 - Validate the concerns summary (agent's text output):

• Output is non-empty
• ## Overview section present with story file path, chunk count, file count
• ## Flagged Concerns and ## Decisions Made tables present

Step 2 - Validate story file structure (agent's primary artifact):

Read the story file path from the Story file: field in the Overview. Run ALL checks - do not stop at the first failure. Collect every failure into a numbered list.

Step 3 - Route based on validation result:

All checks pass: Proceed to S-3 (Interactive Triage) with the validated plan.

Check 1 fails (no chunks at all): The agent failed entirely. Fall back to manual planning: read the story file yourself, scan the codebase, and plan inline following the approach documented in the plan-chunks-agent's instructions. Do not block planning on agent failure.

Checks 2-7 fail (partial failure - agent wrote chunks but plan is structurally incomplete): Report the specific failures to the user:

"The planning agent produced a plan, but it has structural issues:

1. [failure text]
2. [failure text] ..."

Use AskUserQuestion:

question: "How should we handle these plan issues?"
header: "Plan validation"
options:
  - label: "Retry planning"
    description: "Re-launch the planning agent for this story"
  - label: "Fix manually"
    description: "I'll review and fix the plan issues in the story file"
  - label: "Proceed anyway"
    description: "Accept the plan as-is and move to triage"

If "Retry planning": Re-invoke the plan-chunks-agent (return to S-1). Include in the retry prompt: "Previous plan attempt had structural issues: [failure list]. Ensure the plan includes a ## The Pitch section (sell + conditions table using the exact headers | Condition | Secured by |, every row tagged verified / system-owned / unverifiable), a ## Investigation narrative, refined ## Acceptance criteria (5+ specific items), chunks_total in 2-7 range, and every chunk has Goal, Files, Contracts (every line receipted), and Test cases. Every chunk's Done When must assert the project builds and all tests pass at that checkpoint. Rename and removal work must update ALL call sites - including test files, mocks, and fixtures - within the same chunk; if that cannot fit the chunk limits, flag the story for splitting instead of planning chunks that leave the tree broken between boundaries. The plan must also include a ## Acceptance Pre-Flight table - one row per acceptance vehicle, no UNREACHABLE verdicts (see references/acceptance-walkthrough.md). Risk Tags descriptions must name the implementation mechanism - bare threshold values with no mechanism wording are flagged by check #8."

If "Fix manually": Acknowledge and end - the user will edit the story file directly and re-invoke planning when ready.

If "Proceed anyway": Continue to S-3 with the plan as-is. Note the validation gaps in the triage presentation so the user is aware.

S-3: Interactive Triage

The agent has written the story file and returned flagged concerns, decisions, and validation results. Your job is to triage the concerns summary with the user — surface what needs human judgment.

Before constructing any triage AskUserQuestion (Steps 1-5), Read ${CLAUDE_PLUGIN_ROOT}/commands/references/auq-grammar.md and mirror the worked gate that matches the question - a decision weighing alternatives is a fork; a fact that decides itself is a dead end. The exemplar carries the whole grammar (question field, option shapes, header chip); mirror it rather than reconstructing it from a summary. The grammar governs how options read; it never changes which outcomes an option set offers.

Answer-time write: after each answered triage question (Steps 1-5), apply that answer's edit to the story file immediately - per the write rules in ${CLAUDE_PLUGIN_ROOT}/skills/plan-chunks/references/batch-triage.md ("Story File Writing") - then print one truthful receipt line before the next question renders. A real edit names what changed ("Updated Chunk 3: inline confirmation replaces modal"); a no-op answer prints "kept as planned" and makes no edit. Answers must survive a session that dies mid-triage.

Step 1 — Critical Blockers:

If the concerns summary's Critical Blockers section has entries, surface them immediately before anything else:

"[Story Name] has a blocker: [blocker description]. [Agent's recommendation]."

Use AskUserQuestion per blocker, mirroring the exemplar's fork gate. If the blocker means the story can't be planned, stop and report why. (A blocker with no live alternatives is a dead end - mirror the dead-end gate and ask the story-fate question.)

Step 2 - Flagged Concerns:

Review the Flagged Concerns table. Surface by confidence level - each concern gets its own individual AskUserQuestion (the anti-collapse principle applies here too):

• Low confidence: Individual AskUserQuestion with agent's recommendation + alternative
• Medium confidence: Individual AskUserQuestion with "(Recommended)" label + alternative + "Accept as-is"
• High confidence: Informational only - include in plan presentation as "Risks Acknowledged," don't surface during triage

Step 3 — Design Decision Validation:

Review the Design Decision Validation table from the concerns summary. If any entries are concern or invalid:

Use AskUserQuestion:

question: "[The design decision, what the codebase showed, and the ask - self-contained, e.g. 'The story locked X, but planning found Y - adjust to the agent's fix, or keep X?']"
options:
  - label: "Adjust: [agent's proposed fix] (Recommended)"
    description: "[Why original doesn't work + how this solves it]"
  - label: "Keep original anyway"
    description: "[The honest cost of keeping it, in a phrase]"

If all decisions validated as valid → proceed with no interaction.

Don't silently "fix" design decisions. Surface them explicitly so the user stays in control.

Step 4 — Clarification Decisions:

Review the Decisions Made table from the concerns summary. Route by the Product-stake column (the agent already applied the low-confidence bump):

• ask → individual AskUserQuestion per decision, regardless of the agent's confidence. The question text must be self-contained: what was decided, what it trades off for the user, the agent's reasoning.

Use AskUserQuestion:

question: "[The decision and its user-facing consequence — self-contained]"
options:
  - label: "[Agent's decision] (agent recommends)"
    description: "[Agent's reasoning]"
  - label: "[Alternative]"
    description: "[Different approach]"

• mention → no question. Collect into the "Decisions you'd want to know" block of the plan presentation (S-4) — the "cool, that's nice" tier.
• silent → table only. No surfacing.

(Old-format summaries without a Product-stake column: fall back to confidence routing — low asks, medium/high proceed.)

Step 5 — Cycle Impact:

Check the Cycle Impact section from the concerns summary. If any item is non-"none":

Use AskUserQuestion:

question: "[The cycle impact and its consequence - self-contained, e.g. 'Planning found this story is really three: A, B, C - split it, or continue as one?']"
options:
  - label: "Split this story"
    description: "Actually 2-3 stories: [brief list]"
  - label: "Reorder stories"
    description: "This needs [X] done first"
  - label: "Add new story"
    description: "[New work] should be its own story"
  - label: "Continue as-is"
    description: "I understand, proceed anyway"

(Mark the option matching the agent's recommendation "(Recommended)" and list it first; give each shown option an honest one-line verdict. Show only the options the impact actually argues for.)

Fast path: If no low-confidence items exist across all five steps → report "No risks or concerns flagged — plan looks clean." and skip straight to plan presentation. Don't create artificial interaction.

S-4: Present Plan for Approval

Read the story file the agent wrote using the Read tool. Present the ## Chunks section — this is the full plan with all implementation details. Do NOT present from memory or from the concerns summary.

Format

## Implementation Plan: [Story Name]

**Total:** [N] chunks, [M] files

**Decisions you'd want to know:**
[Mention-tier decisions from the Decisions Made table — what the agent did for the user beyond spec]

**Risks Acknowledged:**
[High-confidence concerns from triage]

**File Impact:**
[From concerns summary's File Impact table]

---

### Chunk 1: [Name]
[Full details from the story file's ## Chunks section]

### Chunk 2: [Name]
[Full details from the story file's ## Chunks section]

...

---

Does this plan look complete?

Use AskUserQuestion:

question: "Does this implementation plan look complete?"
options:
  - label: "Yes, mark ready"
    description: "Plan is solid, approve the story"
  - label: "Explore creatively"
    description: "Invoke creative-spark to riff on the approach"
  - label: "More detail on a chunk"
    description: "A chunk needs more specifics"
  - label: "Adjust the approach"
    description: "I want to change something"

S-5: Finalize Story

The agent already wrote the story file with full detail. Your job depends on the user's response:

If "Yes, mark ready":

Triage answers already landed in the story file at answer time (S-3's answer-time write), so this is a status flip plus final reconciliation - verify nothing answered is missing, then:

${CLAUDE_PLUGIN_ROOT}/hooks/scripts/update-story-status.sh [story-file] ready

If "Explore creatively":

⛔ DO NOT generate creative options directly. You MUST invoke the skill. Write a breadcrumb before invoking to handle the skill-to-skill turn boundary:

cat > "${CRAFT_PROJECT_ROOT:-.}/.craft/.continuation" << CRUMB
ACTION: Re-present plan for approval after creative-spark completes
SKILL: craft:plan-chunks
ARGS: [story-file-path] DIRECTION_CONFIRMED: true
WRITTEN_BY: plan-chunks
TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S)
CRUMB

Then invoke:

Skill tool:
  skill: "craft:creative-spark"
  args: "[story name] — Exploring implementation approach creatively.
  STORY: [story-name]"

After creative-spark completes, re-present the plan for approval.

If "More detail on a chunk":

Read the story file, discuss the specific chunk with the user, then make targeted edits to that chunk section only. Re-present for approval.

If "Adjust the approach":

Read the story file, discuss changes with the user, then make targeted edits based on their feedback. Re-present for approval.

If "This is too big":

Discuss splitting with the user. If splitting, create new story files and redistribute chunks across them.

S-6: Offer Implementation

After the story is marked ready, offer to start implementation:

Use AskUserQuestion:

question: "Story is ready to implement. Start now?"
options:
  - label: "Yes, implement now"
    description: "Begin implementing chunk by chunk"
  - label: "Plan another story first"
    description: "Keep planning before implementing"
  - label: "Come back later"
    description: "I'll implement later"

If "Yes, implement now":

⛔ DO NOT implement directly. You MUST invoke the skill:

Skill tool:
  skill: "craft:craft-story-implement"
  args: "[story-file-path]"

This hands off to the implementation workflow which will invoke the implementer agent for each chunk.

If "Plan another story first": → Return to cycle planning flow

If "Come back later": → Acknowledge and end

Multi-Story Planning

This path is triggered when MODE: batch is in args. It plans all status: planning stories in the cycle in parallel.

M-1: Detect & Prepare Stories

1. Read the cycle directory from CYCLE: arg

2. List all stories: Glob "[cycle_dir]/stories/*.md" → story files

3. Read frontmatter of each — filter to status: planning only

4. If no planning stories found → report "No stories need planning in this cycle." and exit

5. If only 1 planning story → switch to single-story path (no batch overhead needed)

6. Content spark check: For each planning story, check whether it has a ## Content Direction section with non-empty content. If ANY stories are missing it, report them: "These stories haven't been through content-spark yet: [list]." Use AskUserQuestion:

   question: "[N] stories are missing Content Direction. Run content-spark on them before planning?"
   header: "Prerequisite"
   options:
     - label: "Run content-spark first (Recommended)"
       description: "Invoke content-spark on each missing story before batch planning"
     - label: "Skip and plan anyway"
       description: "Plan without content direction - chunks may make content assumptions"
   

   If "Run content-spark first": Read and execute the logic inline for each missing story (same pattern story-new uses - avoids the chain-break that nested Skill invocation causes):

   Read "${CLAUDE_PLUGIN_ROOT}/commands/references/content-spark-inline.md"
   Execute the phases described in that file against each missing story sequentially.
   

   After all complete, continue. If "Skip": Continue.

7. Build sibling context: for each story, read first 30 lines (frontmatter + spark). Create a summary list: [story-name]: [spark first sentence]

8. Read cycle goal from cycle.yaml

9. Report to user: "Found [N] stories to plan in [cycle name]. Analyzing dependencies..."

M-1b: Build Dependency Graph

Parse dependencies from each planning story to determine which can plan in parallel.

1. For each planning story, read the ## Dependencies section:

   • HARD BLOCK: If any story is missing the ## Dependencies section entirely, or has no **Blocked by:** line, STOP. Do not proceed with batch planning. Report: "Story [name] has no dependency declaration. Dependencies must be filled in before batch planning - without them, stories may plan in parallel when they share files, causing stale plans that require full replan and reimplement." Use AskUserQuestion to let the user fill them in or cancel.
   • Extract the **Blocked by:** line
   • Parse story names and statuses. Handle all real-world variations:
     • "none" or "None" → no blockers
     • "story-name" → single blocker
     • "story-name (complete)" → single blocker, already done
     • "story-1, story-2 (complete)" → comma-separated list with mixed statuses

2. Verify Likely Files exist (CODE RED gate):

   For each planning story, check for a ## Likely Files section:

   • CODE RED: If ANY story in the batch is missing ## Likely Files entirely, HARD STOP. Do not proceed.
   • Report: "CODE RED: Story [name] has no Likely Files scan. The orchestrator never checked which files this story touches. Dependency declarations cannot be verified - parallel planning could produce conflicting plans that require full replan and reimplement."
   • Use AskUserQuestion:

   question: "Story [name] has no Likely Files scan. Cannot verify dependencies."
   header: "CODE RED"
   options:
     - label: "Scan now"
       description: "Read the spark and scan the codebase for likely files"
     - label: "Cancel batch"
       description: "Fix story files manually before batch planning"
   

   • If "Scan now": Read the story's Spark and Scope, grep/glob the codebase for matching files, write the ## Likely Files section to the story file (same format as story-new: dated, action-tagged). Then continue.
   • If "Cancel batch": Stop. Do not proceed with batch planning.

3. Verify "Blocked by: None" declarations via file overlap:

   For each story that declares Blocked by: None (or none):

   1. Read its ## Likely Files section. Extract all files tagged modify or create.
   2. Compare against every OTHER story in the batch's modify/create files.
   3. If ANY file appears in both stories' modify/create lists - that's an overlap. Flag it:

   Use AskUserQuestion per overlap:

   question: "[Story X] and [Story Y] both plan to modify `[file]`. [X] declares no blockers. Which depends on which?"
   header: "Overlap"
   options:
     - label: "[X] blocked by [Y]"
       description: "Plan [X] after [Y]"
     - label: "[Y] blocked by [X]"
       description: "Plan [Y] after [X]"
     - label: "Truly independent"
       description: "I've verified these changes don't conflict"
   

   • If user picks a direction: Update the st

…(truncated)