afc-plan

name	afc:plan
description	Implementation design — plan approach, create file change map, design architecture
argument-hint	[additional context or constraints]
allowed-tools	["Read","Glob","Grep","Write","WebSearch","WebFetch"]
model	sonnet

/afc:plan — Implementation Design

Generates an implementation plan (plan.md) based on the feature specification (spec.md). Ensures quality with convergence-based Critic Loop and runs research in parallel when needed.

Arguments

• $ARGUMENTS — (optional) Additional context or constraints

Project Config (auto-loaded)

!cat .claude/afc.config.md 2>/dev/null || echo "[CONFIG NOT FOUND] .claude/afc.config.md not found. Create it with /afc:init."

Config Load

Always read .claude/afc.config.md first (read manually if not auto-loaded above) — needed for CI Commands (YAML). Architecture, Code Style, and Project Context are auto-loaded via .claude/rules/afc-project.md.

If config file is missing:

1. Ask the user: ".claude/afc.config.md not found. Run /afc:init to set up the project?"
2. If user accepts → run /afc:init, then restart this command with the original $ARGUMENTS
3. If user declines → abort

Execution Steps

1. Load Context

1. Check current branch → BRANCH_NAME
2. Find .claude/afc/specs/{feature}/spec.md:
   • Search under .claude/afc/specs/ for a directory matching the current branch name or $ARGUMENTS
   • If not found: print "spec.md not found. Running /afc:spec to create it first." then execute /afc:spec with $ARGUMENTS. After spec completes, restart this command from the beginning with the original $ARGUMENTS
3. Read full spec.md
4. Read .claude/afc/memory/principles.md (if present)
5. Read CLAUDE.md project context
6. Memory loading (skip gracefully if directories are empty or absent):
   • Quality history: if .claude/afc/memory/quality-history/*.json exists, load the most recent 10 files (sorted by filename descending) and display trend: "Last {N} pipelines: avg critic_fixes {X}, avg ci_failures {Y}". Use trends to inform risk assessment.
   • Decisions: if .claude/afc/memory/decisions/ exists, load the most recent 30 files (sorted by filename descending) and check for conflicts with the current feature's design direction.
   • Reviews: if .claude/afc/memory/reviews/ exists, load the most recent 15 files (sorted by filename descending) and scan for recurring finding patterns (same file/category appearing in 2+ reviews). Flag as known risk areas.

2. Clarification Check

• If spec.md contains [NEEDS CLARIFICATION] tags:
  • Warn user: "There are unresolved clarification items. Do you want to continue?"
  • If user chooses to stop → guide to /afc:clarify then abort

3. Phase 0 — Research (ReWOO pattern, if needed)

Extract technical uncertainties from spec.md:

1. Are there libraries/APIs not yet used?
2. Are performance requirements unverified?
3. Is the integration approach with the existing codebase unclear?

If no uncertain items: skip Phase 0.

If there are uncertain items, follow the 3-step ReWOO flow:

Step 1: Plan (enumerate all topics — NO execution yet)

List all research topics as a numbered list:

1. {topic1} — {what we need to know}
2. {topic2} — {what we need to know}
3. {topic3} — {what we need to know}

Step 2: Execute (parallel for independent topics)

• If topics are independent (no result dependency): launch parallel Task() calls in a single message:

  Task("Research: {topic1}", subagent_type: "general-purpose")
  Task("Research: {topic2}", subagent_type: "general-purpose")
  

• If a topic depends on another's result: execute sequentially after the dependency resolves
• For 1-2 topics: resolve directly via WebSearch/codebase exploration (no delegation needed)

Step 3: Solve (consolidate all results)

Collect all results and record in .claude/afc/specs/{feature}/research.md:

## {topic}
**Decision**: {chosen approach}
**Rationale**: {reason}
**Alternatives**: {other approaches considered}
**Source**: {URL or file path}

Step 4: Persist (long-term memory)

Copy research findings to .claude/afc/memory/research/{feature}.md for cross-session reuse. Future pipelines can reference prior research to avoid redundant investigation.

4. Phase 1 — Write Design

Create .claude/afc/specs/{feature}/plan.md following the template in ${CLAUDE_SKILL_DIR}/plan-template.md. Read it first, then generate the plan using that structure. All sections are mandatory unless marked "(omit if not applicable)".

4.5. File Path Verification

After writing plan.md, verify all paths in the File Change Map:

1. For each existing file (Action: modify/delete): confirm the path exists using Glob
2. For each new file (Action: create): confirm the parent directory exists using Glob
3. On mismatch:
   • If the same directory contains a file with a similar name (same extension, ≤2 character difference, and filename is ≥5 characters — short names are too ambiguous for auto-correction) → auto-correct to the real path
   • If multiple similar-named files match → flag as ambiguous (do NOT auto-correct; list candidates and let the critic loop resolve)
   • If a direct sibling directory (same parent) contains the expected file (e.g., src/utils/ vs src/lib/) → auto-correct with the real directory. Do not search across architectural boundaries (e.g., frontend/ vs backend/)
   • If no plausible match exists in the codebase → flag as potentially hallucinated, remove or replace with a verified path
   • Update plan.md with corrected paths before proceeding to Critic Loop
4. Report: Path verification: {M}/{N} paths confirmed ({K} corrected)

5. Critic Loop

Always read ${CLAUDE_SKILL_DIR}/../../docs/critic-loop-rules.md first and follow it.

Run the critic loop until convergence. Safety cap: 5 passes.

Criterion	Validation
COMPLETENESS	Are all requirements (FR-*) from spec.md reflected in the plan? For each implementation file classified as "required" in Test Strategy Code Classification, does the File Change Map include a corresponding test file? Report: {M}/{N} test pairs present.
FEASIBILITY	Is it compatible with the existing codebase? Are dependencies available?
ARCHITECTURE	Does it comply with {config.architecture} rules?
CROSS_CONSISTENCY	Spec↔Plan cross-artifact validation (see checklist below)
RISK	Are there any unidentified risks? Additionally, if .claude/afc/memory/retrospectives/ directory contains files from previous pipeline runs, load the most recent 10 files (sorted by filename descending) and check whether the current plan addresses the patterns recorded there. Tag matched patterns with [RETRO-CHECKED].
PRINCIPLES	Does it not violate the MUST principles in principles.md?

CROSS_CONSISTENCY checklist (mandatory, check all 5):

1. Entity coverage: every entity in spec.md Key Entities table appears in at least one File Change Map row. Report: {M}/{N} entities covered.
2. NFR traceability: every NFR-* in spec.md has a corresponding Architecture Decision, Risk mitigation, or Implementation Context entry. Report: {M}/{N} NFRs traced.
3. Terminology consistency: same concept uses the same name in spec and plan. Flag any drift (e.g., spec says "user profile", plan says "account settings").
4. Constraint propagation: every item in spec.md Constraints section is addressed in Risk & Mitigation or Implementation Context Must NOT. Report: {M}/{N} constraints propagated.
5. Acceptance anchor alignment: Implementation Context Acceptance Anchors faithfully reflect spec.md's acceptance scenarios (no omissions, no misinterpretations).

Follow verdict handling and output format per docs/critic-loop-rules.md.

5.5. ADR Recording (optional)

When the afc-architect agent is available, invoke it to record architecture decisions:

Task("ADR: Record decisions for {feature}", subagent_type: "afc:afc-architect",
  prompt: "Review the plan and record key architecture decisions to your persistent memory.
  Plan sections: Architecture Decision + File Change Map.
  Check for conflicts with existing ADRs. Return: { decisions_recorded: N, conflicts: [] }")

• If conflicts detected → warn user
• If agent unavailable → skip (decisions still exist in plan.md for reference)

5.6. Auto-Checkpoint (standalone only)

When not running inside /afc:auto, save progress for /afc:resume:

• Write/update .claude/afc/memory/checkpoint.md with: branch, last commit, feature name, current phase (plan complete), next step (/afc:implement)
• Skip if running inside auto pipeline (auto manages its own checkpoints via phase transitions)

6. Final Output

Plan generated
├─ .claude/afc/specs/{feature}/plan.md
├─ .claude/afc/specs/{feature}/research.md (if research was performed)
├─ Implementation Context: generated ({W} words)
├─ Critic: converged ({N} passes, {M} fixes, {E} escalations)
└─ Next step: /afc:implement (tasks generated automatically at implement start)

Notes

• "No Change" is a valid outcome: If Approach 0 (status quo) is the best option, recommend it. Do not implement for the sake of implementing.
• Write plan.md to an actionable level. Vague expressions like "handle appropriately" are prohibited.
• File paths in the File Change Map must be based on the actual project structure (no guessing).
• Place files according to {config.architecture} rules; verify by checking existing codebase patterns.
• If there is a conflict with CLAUDE.md project settings, CLAUDE.md takes priority.