Plan

Code Forge — Plan

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

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 (Document or Prompt) → Analysis → Planning → Task Breakdown → Status Tracking

Context Management

Steps 4, 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, 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

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 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)
• 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
• 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 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

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

Create state.json with these required fields:

Each task object in the tasks array:

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.

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
  /code-forge:status {feature_name}   View progress
  cat {output_dir}/{feature_name}/plan.md   View detailed plan

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, fixbug, finish) cannot operate without it
• Skipping project-level overview.md (Step 11)
• Running Steps 4, 7, 8 inline instead of delegating to sub-agents via Agent tool
• Proceeding to Step 13 without running Step 12 verification