tercel/code-forge/plan

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

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

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 spec creation to spec-forge. This maintains the separation of concerns: spec-forge owns specification, code-forge owns implementation planning.

A raw prompt carries no requirements behind it. Planning straight from a sentence means implementing behavior nobody has specified — field rules, error handling, and permissions all get invented during implementation, and afterwards there is no document to settle whether the result is correct. The delegation below exists to produce that document first.

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

docs/features/*.md is produced by `spec-forge:tech-design` (its Step 7 emits one feature spec per component in §8.1, plus overview.md with the dependency graph and execution order). There is no standalone spec-forge:feature skill — it was folded into tech-design.

Use AskUserQuestion to pick the delegation depth:

• Full chain — `/spec-forge {slug}` (recommended when the work is more than a small, well-understood change): runs [idea] → [decompose] → [prd] → srs → tech-design → review, producing docs/{slug}/srs.md as the requirements contract before any design exists. Plans generated afterwards are traceable to FR-*/NFR-* IDs, and code-forge:tdd derives tests from the SRS acceptance criteria.
• Design only — `spec-forge:tech-design` (faster, for a small change whose requirements are genuinely obvious): skips the requirements contract. The design's §3.5–§3.7 come from answers to clarifying questions rather than a specified requirement set, so nothing downstream can be traced to a requirement ID.

For the design-only path, launch Agent(subagent_type="general-purpose"):

• Sub-agent prompt: "Invoke the spec-forge:tech-design skill for '{slug}'. The user's requirement is: '{original prompt text}'. Standalone mode — no upstream SRS or PRD exists. Ask only the clarification questions whose answers materially change the design, and record every inference as an explicit stated assumption the user can correct. IMPORTANT: run Step 7 so feature specs are generated in docs/features/ along with overview.md."
• Wait for completion → verify docs/{slug}/tech-design.md exists and that docs/features/ gained specs with a matching overview.md