plan git:20260522.5bbef6eA

Immutable. This exact content is served forever at /api/v1/blob/f92ccce26ef36991.

---
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:

```markdown
# {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**:

```bash
# 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

Create `state.json` with these required fields:

| 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.**

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