drobins25/craft/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.

Under a Go run (only when ${CLAUDE_PLUGIN_ROOT}/commands/references/go-run.md is in force for this conversation; otherwise nothing in this skill changes): at Phase 0, run python3 "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/go-brief.py" <cycle-dir>. On prompts=answer, every prompt and card in this skill follows go-run.md's ## Known prompts and ## Planning, and the S-6 and BT-7 hand-offs go to its ## At the stage ceiling instead of story-implement, so a run never goes past the stage the Go allows. Any other verdict ends the Go run as go-run.md says, and this skill then asks everything as written.

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.

Tracker issue check: for a story in a cycle, read that cycle directory's cycle.yaml (the story's own cycle, from the story path, or CYCLE: in batch, checked once per batch). If it has a non-empty source_issue, Read ${CLAUDE_PLUGIN_ROOT}/commands/references/tracker-follow.md with that cycle's directory and continue only through its ## Continue, before the goal reads in S-1 and M-1. A backlog story, or a cycle without a source_issue, skips this and nothing below changes.

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 on question cards
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 planning has no visual-riff step. Skip if: type is anything other than ui, or missing - visual riffing does not apply; continue to Phase 0.5 with no prompt. 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.

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 3-4 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."

If "Yes":

⛔ 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: The user's own words in this session asked to plan this story: they invoked /craft:plan-chunks naming it, said "plan this" or similar about it, or answered yes to a question that offered to plan it. That ask is the explicit request this gate exists to secure. It does not count when the story was reached with no ask from the user (an autonomous pick, a chained flow that never asked, or a story picked because none was named). 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]"