plan

name	plan
description	Analyze documentation (or a prompt) and generate an implementation plan with task breakdown, TDD steps, and progress tracking. Use when breaking down a feature, creating tasks from docs or requirements, planning implementation work, or turning a spec into actionable steps.

Code Forge — Plan

⚡ Execution Entry Point

@../shared/execution-entrypoint.md

For this skill: start at Step 0 (Configuration), then Step 0.5 (Project Analysis), then Step 1. If you catch yourself about to say "falling back to manual planning", STOP and go to the indicated step.

---

Generate an implementation plan from a feature document or a requirement prompt.

Iron Law

ALL OUTPUT GOES INTO {output_dir}/{feature-name}/ AS SEPARATE FILES — overview.md, plan.md, tasks/*.md, state.json.

Anti-Rationalization Table

Thought	Reality
"I'll put everything in one plan.md for simplicity"	Multi-file structure is how impl/status/review find individual tasks. One file breaks all downstream skills.
"docs/plan is close enough"	Output dir is {output_dir} (default: planning/). docs/plan, docs/plans are ALL wrong.
"I'll create the tasks inline in plan.md"	Tasks go in tasks/{name}.md as separate files. Step 8 sub-agent creates them.
"Numeric prefixes help with ordering"	Execution order is in overview.md and state.json. Files are setup.md, not 01-setup.md.
"I can skip state.json"	state.json drives impl, status, fix. Without it, no downstream skill works.
"The overview files are optional"	Both project-level and feature-level overview.md are mandatory outputs.
"The input looks like a path but has no @, I'll treat it as a prompt"	Run the Step 2.0 path-like input guard. Paths without @ are almost always user mistakes — ask before proceeding.
"I'll add FE-01- prefixes to feature directories for clarity"	Feature directory names must match the source filename exactly in kebab-case. core-dispatcher, not FE-01-core-dispatcher.
"I'll generate all features as flat files in one directory"	Each feature gets its own subdirectory with the full multi-file structure. Flat files break all downstream skills.
"Step 4.5 reuse discovery is optional, the user just wants the plan"	Step 4.5 is mandatory. Skipping it is the #1 cause of bloat across spec-forge / code-forge / apcore-skills workflows — the planner ends up generating tasks that recreate utilities, helpers, and entire subsystems that already exist.
"I'll just trust the LLM to know what already exists"	The LLM does not know. It must Grep and Read the actual project. Step 4.5 forces this empirically.

When to Use

• Have a feature document that needs to be broken into development tasks
• Have a requirement idea (text prompt) that needs planning
• Need a structured plan with TDD task breakdown
• Use --tmp to avoid adding plan files to the project (writes to .code-forge/tmp/, auto-gitignored)

Workflow

Input → Analysis → Reuse Discovery → Planning → Task Breakdown → Status Tracking

Context Management

Steps 4, 4.5, 7, and 8 are offloaded to sub-agents via the Agent tool to prevent context window exhaustion on large projects. The main context retains only concise summaries returned by each sub-agent, while full document analysis, reuse discovery, file generation, and code implementation happen in isolated sub-agent contexts that are discarded after completion.

Actual execution order: Steps 0 through 13, in sequential order.

Step 9 (overview.md) executes after Steps 7 and 8 because it references task files generated by those steps.

Detailed Steps

@../shared/configuration.md

Step 0.5: Project Analysis

Before planning, understand the project's architecture and tech stack. Read and execute:

@../shared/project-analysis.md

Execute PA.1 (Project Profile), PA.2 (Architecture Analysis), and PA.5 (Existing Test Assessment). This ensures:

• Tasks are structured around the ACTUAL architecture (not assumed layers)
• TDD steps reference the ACTUAL test framework
• Task dependencies reflect REAL module relationships
• Language-specific patterns are accounted for (e.g., Rust trait bounds, Go interfaces)

The Project Context Summary (PA.7) is passed to the sub-agent in Step 4 as part of the context.

---

Plan-specific additions to Step 0:

• 0.2 additional defaults: reference_docs.sources = [], reference_docs.exclude = []
• 0.3 additional validation:
  • reference_docs.sources must be an array of strings (fall back to [] on error)
  • reference_docs.sources entries must NOT contain .. (security risk)
  • reference_docs.sources entries must NOT point to system directories (node_modules/, .git/, build/)
  • reference_docs.exclude must be an array of strings (fall back to [] on error)
• 0.4 additional display: Resolved file creation path: {output_dir}/{feature_name}/
• 0.4 error handling:
  • Config file not found → note "using defaults" and continue
  • Config file parse error → show error, fall back to defaults, continue
  • Invalid config values → show warnings, fall back to defaults for invalid fields, continue
• 0.6 path resolution notes: base_dir empty string means project root; input_dir default: docs/features/; output_dir default: planning/

---

Step 1: Resolve and Summarize Reference Docs

This step only runs when reference_docs.sources is non-empty in the merged configuration.

If reference_docs.sources is empty or not configured, skip directly to Step 2.

1.1 Resolve Glob Patterns

1. Resolve each pattern in config.reference_docs.sources against project_root
2. Apply config.reference_docs.exclude patterns to filter results
3. Auto-exclude {output_dir}/** to prevent circular references
4. Deduplicate results (same file matched by multiple patterns)
5. If 0 files matched → display: Reference docs: 0 files matched for configured patterns. Continuing without reference context. → skip to Step 2
6. If > 30 files matched → display file list, use AskUserQuestion: "Found {N} reference docs. This will spawn {N} parallel sub-agents."
   • "Proceed with all {N} files"
   • "Let me refine the patterns" → show current sources/exclude config, stop and let user update .code-forge.json

1.2 Display Matched Files

Display the matched file list:

Reference docs: {count} files matched
  {path_1}
  {path_2}
  ...

Proceed directly — no confirmation needed (unless > 30 files triggered 1.1 step 6).

1.3 Parallel Sub-agent Summarization

Spawn N parallel sub-agents via Agent tool, one per matched file:

• subagent_type: "general-purpose"
• description: "Summarize reference doc: {filename}"

Each sub-agent prompt:

• The file path (sub-agent reads it from disk)
• Instruction to return ONLY a structured summary in this exact format:

DOC_PATH: {file_path}
DOC_TYPE: <architecture | api | requirements | conventions | data-model | other>
SUMMARY: <2-3 sentence summary of what this document describes>
KEY_DECISIONS: <bulleted list of important technical decisions, constraints, or patterns>
RELEVANCE_TAGS: <comma-separated keywords for matching against feature docs>

Target summary size: ~300-500 bytes per doc.

Error handling: If a sub-agent fails to summarize a file, log a warning and skip that file:

Warning: Failed to summarize {path} — skipping
Reference docs: {success_count} of {total_count} files summarized successfully

1.4 Store Reference Summaries

Collect all successful sub-agent results into a reference_summaries list (ordered by file path). Store in memory for use by Steps 4, 7, and 8.

1.5 Deduplicate Against Input Doc

After the input document path is known (after Step 3), remove it from reference_summaries if present — the feature doc is already read directly by Steps 4 and 7. This deduplication happens lazily: the summaries are stored now, deduplication is applied when injecting into sub-agent prompts.

---

Step 2: Prompt Mode — Delegate to spec-forge:feature

This step only runs when the input is NOT a file path (does NOT start with @).

If the input starts with @, skip directly to Step 3.

2.0 Path-Like Input Guard

Before treating input as a prompt, check if it looks like a file/directory path. If the input matches ANY of these patterns, it is almost certainly a path the user forgot to prefix with @:

• Contains / (e.g., ../apcore-cli, docs/features/auth.md)
• Starts with . (e.g., ./src, ../other-project)
• Ends with .md (e.g., user-auth.md)
• Matches an existing file or directory on disk

Action: Do NOT silently proceed as prompt mode. Instead, use AskUserQuestion:

Your input looks like a file/directory path: "{input}"
Did you mean to use file mode? (paths require an @ prefix)

• Options:
  • "Yes, use as file path" → prepend @ and skip to Step 3
  • "No, treat as text prompt" → continue with Step 2.1

This guard prevents the common mistake of forgetting @, which causes the entire workflow to bypass Directory/File Mode and produce incorrect output.

---

When a user provides a text prompt instead of a file path, code-forge:plan delegates feature spec creation to spec-forge:feature. This maintains the separation of concerns: spec-forge owns specification, code-forge owns implementation planning.

2.1 Generate Slug

Convert the prompt text to a kebab-case slug for the feature name:

• ASCII text: lowercase, replace spaces/special chars with hyphens (e.g., "User Login Feature" → user-login-feature)
• Non-ASCII text (Chinese, Japanese, etc.): use AskUserQuestion to let user confirm or provide a custom slug. Suggest a reasonable English slug based on the prompt meaning.

2.2 Check for Existing Feature Spec

Check if {input_dir}/{slug}.md already exists:

• Exists → use it directly, skip to 2.4
• Does not exist → continue to 2.3

2.3 Auto-Delegate to spec-forge:feature

Invoke spec-forge:feature to generate the feature spec:

Launch Agent(subagent_type="general-purpose"):

• Sub-agent prompt: "Invoke the spec-forge:feature skill for '{slug}'. The user's requirement is: '{original prompt text}'. Use standalone mode — generate the feature spec at docs/features/{slug}.md based on this requirement description. Keep the Q&A minimal since the user already provided context in the prompt."
• Wait for completion → verify docs/features/{slug}.md exists

If spec-forge:feature is not available (skill not installed), fall back to generating a minimal feature document directly:

# {Feature Title}

> Feature spec for code-forge implementation planning.
> Source: auto-generated from prompt
> Created: {date}

## Purpose

{user's original prompt text, verbatim}

## Notes

- Generated from prompt by code-forge (spec-forge:feature not available)
- Consider running `/spec-forge:feature {slug}` for a more detailed spec

2.4 Set File Path

Set {input_dir}/{slug}.md as the current input document path (prefixed with @), then continue to Step 3.

---

Step 3: Validate Input Document

3.1 Check Document Path

User should provide an @ path pointing to a file or directory:

# File mode — plan a single feature
/code-forge:plan @docs/features/user-auth.md

# Directory mode — list features and let user pick
/code-forge:plan @docs/features/
/code-forge:plan @../../aipartnerup/apcore

Note: Use configured path ({input_dir}/). Also accepts spec-forge tech-design files directly: /code-forge:plan @docs/user-auth/tech-design.md

3.1.1 Directory Mode

If the @ path resolves to a directory (not a file):

1. Scan for feature spec files in this order (stop at first match):
   • <path>/docs/features/*.md
   • <path>/features/*.md
   • <path>/*.md
2. Exclude non-feature files from results: filter out overview.md, README.md, index.md, and any file that is clearly not a feature spec (e.g., changelog, license)
3. If no .md files found: display error "No feature specs found in {path}" with the paths tried, then stop
4. If exactly 1 file found: use it directly (skip selection)
5. If multiple files found: display list and use AskUserQuestion to let user select:

   Feature specs found in {path}:
     1. acl-system
     2. core-executor
     3. schema-system
     ...
     N. [Plan all — generate plans for all features sequentially]
   

   • Options: one per file (show filename without .md), plus "Plan all" as the last option
6. Set the selected file as the input document path, then continue to Step 3.2

"Plan all" batch mode: When the user selects "Plan all":

1. Store the full list of feature file paths as batch_queue
2. For each file in batch_queue, execute Steps 3.2 through 13 sequentially (one complete plan per feature)
3. Between features, display a brief progress line: Completed {n}/{total}: {feature_name}. Next: {next_feature_name}
4. After all features are planned, display a batch summary:

   Batch planning complete
   
   Features planned: {total}
     {feature_1} — {task_count} tasks
     {feature_2} — {task_count} tasks
     ...
   
   Project overview: {output_dir}/overview.md
   Next: /code-forge:impl {feature_name}
   

5. The project-level overview (Step 11) is generated/updated after EACH feature, so it always reflects the latest state
6. If a feature fails during planning, log the error, skip it, and continue with the next feature. Display skipped features in the batch summary.
7. Step 5 answer reuse: In batch mode, Step 5 (tech stack, testing strategy, granularity) is only asked for the first feature. Subsequent features reuse the same answers automatically — unless a feature document explicitly specifies a different tech stack, in which case only that question is re-asked for that feature. This avoids asking the same 3 questions N times.
8. Context management: Batch planning accumulates context across features. For batches of more than 5 features, display a warning before starting: "Planning {N} features sequentially. For very large batches (10+), consider splitting into multiple /code-forge:plan invocations to avoid context exhaustion." Proceed regardless — this is informational only.

Path resolution: Both relative and absolute paths are supported. Relative paths are resolved from the current working directory. External project paths (e.g., @../../other-project) are valid — the feature spec does not need to be inside the current project.

3.2-3.4 Validate Document and Handle Errors

Perform these checks on the provided document:

1. File exists — if not found, list available files in {input_dir}/ and suggest corrections (check for typos)
2. File is not empty — if empty, suggest adding requirements content with a minimal example
3. File is Markdown — if not .md, warn and ask whether to continue as plain text

If no document is provided and Step 2 was not triggered: display usage instructions with examples.

On any error: display the issue, suggest a fix, and stop.

3.5 Detect Existing Plan

Check whether <output_dir>/<feature_name>/ already exists:

• Has state.json → Resume mode: show progress summary (task statuses), ask via AskUserQuestion:

  • Continue (recommended) — resume from current progress
  • Restart — delete all files and regenerate
  • View plan — open plan.md
  • Cancel

• Directory exists but no state.json → Conflict mode: warn about existing files, ask:

  • Backup and overwrite — move to .backup/ then regenerate
  • Force overwrite — overwrite directly
  • Cancel — handle manually then rerun

Step 4: Analyze Document Content (via Sub-agent)

Offload to sub-agent to keep the full document content out of the main context.

Spawn an Agent tool call with:

• subagent_type: "general-purpose"
• description: "Analyze feature document"

Sub-agent prompt must include:

• The input document file path (so the sub-agent reads it, NOT the main context)
• Instruction to return ONLY a structured summary
• If reference_summaries is non-empty (from Step 1), include a ## Reference Context section:

  ## Reference Context
  
  The following project documents provide architectural context.
  Use these to align your analysis with existing project decisions and patterns.
  
  {reference_summaries — all summaries concatenated, separated by blank lines}
  

Sub-agent must analyze and return:

1. Feature Name — extracted from the source filename (kebab-case, without .md extension). Always use the filename, never the document title. Example: source file security.md → feature name security, even if the document title is "Security Manager".
2. Technical Requirements — tech stack, frameworks, languages mentioned
3. Functional Scope — 2-3 sentence summary of what needs to be implemented
4. Constraints — performance, security, compatibility requirements
5. Testing Requirements — testing strategy mentioned, or "not specified"
6. Key Components — major modules/components to build (bulleted list)
7. Estimated Complexity — low/medium/high with brief rationale

Main context retains: Only the structured summary returned by the sub-agent (~1-2KB). The full document content stays in the sub-agent's context and is discarded.

Important: Store the returned summary for use in Steps 5 and 7.

Step 4.5: Reuse & Existing-Code Discovery (via Sub-agent)

This step is mandatory. It is the primary defense against incremental bloat. Before any task is generated, the planner MUST verify what already exists in the project that could be reused or extended, so the resulting plan biases toward "extend existing" instead of "add new".

Skipping this step is the most common way that skill-driven planning produces parallel implementations, duplicate utilities, and bloated codebases over time.

Offload to a sub-agent to keep grep output and file reads out of the main context.

Spawn an Agent tool call with:

• subagent_type: "general-purpose"
• description: "Discover reusable code for {feature_name}"

Sub-agent prompt must include:

• The structured summary from Step 4 (Key Components, Functional Scope, Technical Requirements)
• The Project Context Summary (PA.7) from Step 0.5
• The project root path
• Explicit instructions below

Sub-agent must do all of the following and return a structured report:

1. Component-by-component reuse search. For each entry in "Key Components" from the Step 4 summary:

   • Grep the project for similar names, related keywords, and likely synonyms (e.g., for a planned UserAuthService, search for auth, login, session, credential, User.*Service, etc.)
   • Read any matching files at least at signature level
   • Decide one of: REUSE (existing code already does this — do not build it), EXTEND (existing code is close — modify it), NEW (genuinely no overlap — build new)

2. Utility / helper survey. Scan the project for existing utility modules (utils/, lib/, helpers/, common/, shared modules) and list utilities relevant to the planned work. Future tasks must prefer these over reimplementing.

3. Configuration / constants survey. Identify existing configuration files, constants, enums, and environment variables relevant to the feature so the plan extends them rather than introducing parallel knobs.

4. Test scaffolding survey. Identify existing test fixtures, factories, mocks, and helper modules that new tests should reuse.

5. Anti-duplication callouts. Explicitly call out any place where the planned feature, as described in the Step 4 summary, would naively duplicate something that already exists. The plan generator (Step 7) must address each callout.

6. Deletion candidates. While searching, note any existing dead code, stale TODOs, or obsolete helpers in the touched areas. The plan should optionally include a cleanup task.

Sub-agent must return (as response text) this exact structured format:

REUSE_REPORT for {feature_name}

COMPONENT_DECISIONS:
- component: {planned_component_name}
  decision: REUSE | EXTEND | NEW
  existing: {file:line if reuse/extend, or "none" if new}
  rationale: {one sentence}

EXISTING_UTILITIES:
- {file:symbol} — {what it does, why it's relevant}

EXISTING_CONFIG:
- {file:key} — {what it controls}

EXISTING_TEST_SCAFFOLDING:
- {file:symbol} — {fixture/mock/factory description}

ANTI_DUPLICATION_CALLOUTS:
- {planned thing} would duplicate {existing thing at file:line} — {how to avoid}

DELETION_CANDIDATES:
- {file:line} — {dead code / stale TODO description}

NEW_CODE_BUDGET:
- expected_new_files: {N}
- expected_extended_files: {N}
- justification: {one sentence}

Main context retains: Only this report (~2-3KB). Store it as reuse_report for use in Steps 7 and 8.

Hard rule for Steps 7 and 8: The plan and task files generated downstream MUST reference the reuse_report:

• Every component the report marked REUSE becomes a "use existing X" note in the plan, NOT a build task.
• Every component marked EXTEND becomes a task that names the existing file to modify.
• Every ANTI_DUPLICATION_CALLOUT must be addressed in the plan (either by following the callout or by explicitly justifying why a parallel implementation is necessary).
• Every EXISTING_UTILITY, EXISTING_CONFIG, and EXISTING_TEST_SCAFFOLDING entry must be referenced from at least one task that would otherwise have reinvented it.
• If DELETION_CANDIDATES is non-empty, the plan should include a cleanup task (or fold the deletions into adjacent tasks).
• The NEW_CODE_BUDGET becomes the expected upper bound for the implementation. Step 7 should not generate a plan that wildly exceeds it without explicit justification.

Pass reuse_report into the Step 7 and Step 8 sub-agent prompts as a section titled ## Existing Code to Reuse (MANDATORY) followed by the full report. The sub-agents must be told: "You are forbidden from generating tasks that recreate anything listed in this report. If a task seems to need such a thing, the task must instead reference the existing symbol."

---

Step 5: Ask for Additional Information

If not clearly specified in the document, use a single AskUserQuestion combining up to 3 questions. Skip any question already answered by the document:

Question 1: Technology Stack Confirmation

• "Use {extracted_tech} mentioned in document"
• "Use existing project tech stack" — analyze project code, use existing frameworks
• "Custom" — user specifies

Question 2: Testing Strategy

• "Strict TDD (Recommended)" — write tests first for each task
• "Tests After" — implement first, write tests at end
• "Minimal Testing" — test only core logic

Question 3: Task Granularity

• "Fine-grained (5-10 tasks)" — each task 1-2 hours
• "Medium-grained (3-5 tasks)" — each task half day
• "Coarse-grained (2-3 tasks)" — each task 1-2 days

Step 6: Create Directory Structure

Extract feature name from the source filename (convert to kebab-case, strip .md extension). Always use the filename — never derive the feature name from the document title, as titles may differ from filenames.

6.0 Output Path Assertion (Hard Gate)

Before creating any directory or file, run these assertions. If ANY fails, STOP immediately — do not proceed.

ASSERT: resolved output path does NOT contain "docs/plan"
ASSERT: resolved output path does NOT contain "docs/plans"
ASSERT: resolved output path does NOT contain "docs/planning"
ASSERT: resolved output path equals "{project_root}/{output_dir}/{feature_name}/"
        where {output_dir} is the value resolved in Step 0 (default: "planning/")
ASSERT: feature_name does NOT contain numeric prefixes (e.g., "FE-01-", "01-")
ASSERT: feature_name is kebab-case and matches the source document filename
        (e.g., source "core-dispatcher.md" → feature_name "core-dispatcher")

On assertion failure: display the violation and the correct path, then stop. Example:

OUTPUT PATH VIOLATION: about to write to "docs/plans/FE-01-core-dispatcher.md"
Expected: "planning/core-dispatcher/"
Fix: use the resolved output_dir from Step 0 configuration

Output directory: {output_dir} defaults to planning/ — NEVER docs/plan/, docs/plans/, docs/planning/, or any other invented path. If you are about to write to any path other than {output_dir}/{feature_name}/, STOP — you are making a mistake. Always use the resolved output_dir from Step 0 configuration.

Create directory structure and proceed directly — no confirmation needed:

{output_dir}/{feature_name}/
├── overview.md
├── plan.md
├── tasks/
└── state.json

Example with defaults: planning/user-auth/, planning/user-auth/tasks/, etc.

Step 7: Generate plan.md (via Sub-agent)

Offload to sub-agent to keep plan generation output out of the main context.

Spawn an Agent tool call with:

• subagent_type: "general-purpose"
• description: "Generate implementation plan"

Sub-agent prompt must include:

• The input document file path (sub-agent re-reads the original for full context)
• The structured summary from Step 4 (paste it into the prompt)
• The reuse_report from Step 4.5 — paste it verbatim under a ## Existing Code to Reuse (MANDATORY) section, followed by this instruction: "You are forbidden from generating tasks that recreate anything listed in this report. Components marked REUSE become 'use existing X' notes, not build tasks. Components marked EXTEND become tasks that name the existing file to modify. Every ANTI_DUPLICATION_CALLOUT must be addressed. Every EXISTING_UTILITY / EXISTING_CONFIG / EXISTING_TEST_SCAFFOLDING entry must be referenced from at least one task that would otherwise reinvent it. If DELETION_CANDIDATES is non-empty, include a cleanup task. Stay within the NEW_CODE_BUDGET unless you explicitly justify exceeding it."
• The design-first discipline — paste the contents of @../shared/design-first.md under a ## Design Discipline (MANDATORY) section, followed by this instruction: "Generated tasks MUST be shaped by design-first principles. Prefer 'modify existing X' over 'create new Y' wherever the reuse report or your own analysis indicates an existing structure can absorb the change. Tasks that create new files must justify why an existing file cannot host the change. Tasks that introduce new abstractions (base classes, interfaces, plugin systems, factories) must name at least two concrete callers — speculative abstraction is forbidden. Public interfaces stay stable unless the source document explicitly authorizes a break."
• User answers from Step 5 (tech stack choice, testing strategy, task granularity)
• The output file path: {output_dir}/{feature_name}/plan.md
• Instructions to write the plan file AND return a concise task list summary
• If reference_summaries is non-empty, include a ## Reference Context section:

  ## Reference Context
  
  The following project documents provide architectural context.
  Ensure the implementation plan is consistent with existing architecture and conventions.
  
  {reference_summaries — all summaries concatenated, separated by blank lines}
  

Sub-agent must write plan.md with these required sections:

• Goal — one sentence describing what to implement
• Architecture Design — component structure, data flow, technical choices with rationale
• Design Decisions — MANDATORY if the feature touches any high-impact surface (database schema, public API contract, state machine, file format / wire protocol, cross-service dependency). For each such surface, add a ### High-Impact Decision Record: <surface name> subsection containing one short paragraph per question from the High-Impact Change Checklist in @../shared/design-first.md (Necessity / Data characteristics / Volatility / Migration cost / External contract impact / Cheaper alternative). If the feature touches no high-impact surface, write a single line: _No high-impact surfaces touched._
• Task Breakdown — dependency graph (mermaid graph TD) + task list with estimated time and dependencies
• Risks and Considerations — identified technical challenges
• Acceptance Criteria — checklist (tests pass, code review, docs, performance)
• References — related technical docs and examples

Task ID naming rules (critical): Task IDs must be descriptive names without numeric prefixes. Use setup, models, api — NOT 01-setup, 02-models, 03-api. Execution order is controlled by overview.md and state.json, not by filename ordering or numeric prefixes.

Sub-agent must return (as response text, separate from the file it writes) a concise task list summary:

TASK_COUNT: <number>
TASKS:
- <task_id>: <task_title> [depends on: <deps or "none">] (~<estimated_time>)
- <task_id>: <task_title> [depends on: <deps or "none">] (~<estimated_time>)
...
EXECUTION_ORDER: <task_id_1>, <task_id_2>, ...

Main context retains: Only the task list summary (~1-2KB). The full plan content is on disk.

Step 8: Task Breakdown (via Sub-agent)

Offload to sub-agent to keep task file generation out of the main context.

Spawn an Agent tool call with:

• subagent_type: "general-purpose"
• description: "Generate task breakdown files"

Sub-agent prompt must include:

• The plan file path: {output_dir}/{feature_name}/plan.md (sub-agent reads it from disk)
• The task list summary returned by Step 7 (paste it into the prompt)
• The reuse_report from Step 4.5 — paste it verbatim under a ## Existing Code to Reuse (MANDATORY) section. Instruct: "For every task you generate, the 'Files Involved' section must prefer existing files over new ones whenever the reuse report indicates an existing equivalent. Each task's 'Steps' section must explicitly reference the relevant entries from EXISTING_UTILITIES, EXISTING_CONFIG, or EXISTING_TEST_SCAFFOLDING when applicable. Tasks that touch areas containing DELETION_CANDIDATES should fold the deletions in."
• The tasks directory path: {output_dir}/{feature_name}/tasks/
• All the principles and format requirements below
• If reference_summaries is non-empty, include a ## Reference Context section:

  ## Reference Context
  
  The following project documents provide architectural context.
  Ensure task steps follow project conventions and integrate with existing components.
  
  {reference_summaries — all summaries concatenated, separated by blank lines}
  

Sub-agent must create tasks/{name}.md for each task, following these principles:

• TDD first: test → implement → verify
• Concrete steps: include code examples and commands
• Traceable: annotate dependencies (depends on / required by)

Each task file must include:

• Goal — what this task accomplishes
• Files Involved — files to create/modify
• Steps — numbered, with code examples where helpful
• Acceptance Criteria — checklist
• Dependencies — depends on / required by
• Estimated Time
• Design Decisions Reference — if this task implements a high-impact surface change (schema, public API, state machine, file format, cross-service surface) covered by plan.md § Design Decisions, include a one-line pointer: See plan.md § Design Decisions: <surface name> for the High-Impact Decision Record. This lets the impl sub-agent locate the recorded decisions without re-asking. Omit this section for tasks with no high-impact surface.

Naming (critical): Use descriptive filenames: setup.md, models.md, api.md — NO numeric prefixes (01-setup.md, 02-models.md are WRONG). Execution order is defined in overview.md Task Execution Order table and state.json execution_order array, never in filenames.

Sub-agent must return (as response text) the list of generated files:

GENERATED_FILES:
- tasks/<task_id>.md: <task_title>
- tasks/<task_id>.md: <task_title>
...

Main context retains: Only the file list (~0.5KB). All task file content is on disk.

Step 9: Generate overview.md

Execution order: This step executes AFTER Steps 7 and 8. Use the task list summary returned by the Step 7 sub-agent and the file list returned by the Step 8 sub-agent to populate task-related sections.

Generate feature overview with these required sections:

• Overview — extract or summarize from source document
• Scope — included and excluded items
• Technology Stack — language/framework, key dependencies, testing tools
• Task Execution Order — table: #, Task File (linked to ./tasks/), Description, Status
• Progress — total/completed/in_progress/pending counts
• Reference Documents — link to source document

Step 10: Initialize state.json

Fast path: scaffold state.json with the state helper — it computes execution_order by topological sort of the task dependencies, fills the progress block, and stamps created/updated. Resolve <cf_scripts> once (see Locating the script layer in the configuration step), then pipe the task list (a JSON array of {id, title, dependencies, estimated_hours}; file defaults to tasks/{id}.md) on stdin:

echo '[{"id":"setup","title":"Project setup","dependencies":[]}, ...]' \
  | python3 "<cf_scripts>/cf-state.py" init \
      --feature <name> --source-doc <doc> \
      --output "<output_dir>/<name>/state.json"

It errors (non-zero) on a dependency cycle — fix the cycle and re-run. If python3 is unavailable, build state.json by hand with the fields below.

Required fields (the helper produces exactly these):

Field	Description
feature	Feature name (string)
created, updated	ISO timestamps
status	"pending" initially
execution_order	Array of task IDs in execution order
progress	{ total_tasks, completed, in_progress, pending }
tasks	Array of task objects (see below)
metadata	{ source_doc, created_by: "code-forge", version: "1.0" }

Each task object in the tasks array:

Field	Description
id	Task identifier (matches filename without .md)
file	Relative path: tasks/{id}.md
title	Human-readable task title
status	"pending" initially
started_at, completed_at	ISO timestamps or null
assignee	null initially
commits	Empty array [] initially

Step 11: Generate/Update Project-Level Overview

After initializing state.json, generate or update {output_dir}/overview.md — a bird's-eye view of all features.

@../shared/overview-generation.md

11.3 When to Regenerate

• After creating a new feature plan (this step)
• After feature completion

Display: Project overview updated: {output_dir}/overview.md

---

Step 12: Verify Output Structure

Mandatory — do NOT proceed to Step 13 until all checks pass. Fix failures before continuing.

Fast path: run the validator in strict mode (every warning is an error here):

python3 "<cf_scripts>/cf-verify-plan.py" "<output_dir>/<feature>" \
  --output-dir "<output_dir>" --root "<project_root>" --strict

A zero exit means all checks below pass; otherwise fix the reported failures and re-run before continuing. If python3 is unavailable, run the checks by hand.

1. {output_dir}/{feature_name}/ exists
2. plan.md exists and non-empty
3. tasks/ contains .md files with descriptive names (no numeric prefixes)
4. overview.md exists and non-empty
5. state.json is valid JSON with fields: feature, status, execution_order, progress, tasks
6. Task count in state.json matches files in tasks/
7. {output_dir}/overview.md (project-level) exists
8. No files in docs/plan/, docs/plans/, docs/planning/ — move if found

---

Step 13: Display Plan and Next Steps

Output plan summary:

Implementation plan generated

Location: {output_dir}/{feature_name}/
Total Tasks: {count}
Estimated Total Time: {estimate}

Task Overview:
  {id}  - {title}  [{status}]
  ...

Next steps:
  /code-forge:impl {feature_name}                          Execute tasks (TDD)
  /code-forge:status {feature_name}                        View progress

Optional (before implementation):
  /spec-forge:test-cases {feature_name}                    Generate test cases first
  /code-forge:tdd @docs/{feature_name}/test-cases.md       Implement from test cases

Integration with Claude Code Tasks

Optionally synchronize tasks to Claude Code's Task system:

• For each task in execution_order, call TaskCreate with:
  • subject: "<task_id>: <task_title>"
  • description: contents of the task file
  • activeForm: "Implementing <task_title>"

Coordination with Other Skills

• With spec-forge:feature: Generate feature spec first → /code-forge:plan @docs/features/{feature}.md
• With spec-forge tech-design: Plan directly from tech-design → /code-forge:plan @docs/{feature}/tech-design.md
• With /brainstorming: Brainstorm design first → generate feature spec → /code-forge:plan @docs/features/{feature}.md
• With /code-forge:impl: After plan generated → /code-forge:impl {feature} to execute
• With /code-forge:review: After implementation → /code-forge:review {feature} to review

Notes

1. Document Quality: The more detailed the input document, the more accurate the generated plan
2. Prompt Mode: When using prompt mode, the generated document is minimal. Step 4 sub-agent analysis handles expansion.
3. Git Commits: Recommend committing the planning directory and .code-forge.json to Git for team visibility
4. State Files: state.json can be optionally committed or added to .gitignore
5. Task Granularity: Recommend 1-3 hours per task for easy tracking
6. Dependency Management: Dependencies between tasks affect execution order
7. Project Overview: The project-level overview.md in {output_dir}/ is auto-generated and shows all features, dependencies, and recommended implementation order
8. Tool Discovery: .code-forge.json contains a _tool section with the plugin URL — new team members can find and install the tool from there
9. Status Definitions: pending, in_progress, completed, blocked, skipped
10. Directory Structure:

    docs/
    └── features/              # Input: feature specs (owned by spec-forge)
        └── user-auth.md       # Generated by /spec-forge:feature or extracted from tech-design
    
    planning/                  # Output: implementation plans (owned by code-forge)
    ├── overview.md            # Project-level overview (auto-generated)
    └── {feature}/             # Per-feature directory
        ├── overview.md        # Feature overview + task execution order
        ├── plan.md            # Implementation plan
        ├── tasks/             # Task breakdown files
        └── state.json         # Status tracking
    

    This structure is mandatory, not a suggestion. Every file listed above must exist after plan generation completes.
11. Naming Conventions: Feature directories use kebab-case (user-auth). Task files use descriptive names (setup.md). No "claude-" or tool prefixes. Suitable for Git commits.
12. Reference Docs: Configure reference_docs.sources in .code-forge.json to auto-discover project documentation. Each doc is summarized by a parallel sub-agent and injected as context into Steps 4, 7, and 8. Reference context is baked into generated plan.md and task files — downstream skills do not re-read reference docs.

Common Mistakes

• Writing a single document instead of the multi-file structure (overview.md + plan.md + tasks/*.md + state.json)
• Using docs/plan/, docs/plans/, or docs/planning/ instead of {output_dir}
• Putting task content inside plan.md instead of separate tasks/{name}.md files
• Using numeric prefixes on task files (01-setup.md instead of setup.md)
• Using numeric prefixes on feature directories (FE-01-core-dispatcher instead of core-dispatcher)
• Generating flat files instead of per-feature subdirectories with multi-file structure
• Treating a path-like input without @ as a prompt instead of asking the user (Step 2.0 guard)
• Skipping state.json — downstream skills (impl, status, fix, finish) cannot operate without it
• Skipping project-level overview.md (Step 11)
• Running Steps 4, 4.5, 7, 8 inline instead of delegating to sub-agents via Agent tool
• Skipping Step 4.5 reuse discovery — this is the #1 source of incremental bloat across skill-driven workflows
• Generating tasks that recreate symbols listed in reuse_report instead of extending the existing ones
• Proceeding to Step 13 without running Step 12 verification