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