/plan-chunks

name: plan-chunks
description: This skill should be used when the user asks to "plan chunks", "break this down", "plan the implementation", or when a story has status planning and needs implementation details before building. Required before any story can be implemented. Transforms story sparks into detailed chunk-by-chunk implementation plans with full technical specifics, file lists, and risk analysis. Supports parallel planning of multiple stories via batch mode.
version: 3.0.0
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Task", "Skill", "SendMessage"]

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 m