Spec

---
name: afc:spec
description: "Generate feature specification — write requirements, acceptance criteria, scope"
argument-hint: "[feature description in natural language]"
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - WebSearch
  - WebFetch
model: sonnet
---
# /afc:spec — Generate Feature Specification

> Converts a natural language feature description into a structured specification (spec.md).
> Validates completeness with convergence-based Critic Loop. Operates on pure prompts without external scripts.

## Arguments

- `$ARGUMENTS` — (required) Feature description in natural language

## 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).

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. Set Up Feature Directory

1. Check **current branch** → `BRANCH_NAME`
2. Determine **feature name**:
   - Extract 2-3 key keywords from `$ARGUMENTS`
   - Convert to kebab-case (e.g., "add user authentication" → `user-auth`)
   - Prepend today's date in `YYYY-MM-DD` format (e.g., `2026-03-13-user-auth`)
3. **Create directory**: `.claude/afc/specs/{YYYY-MM-DD}-{feature-name}/` (create parent `.claude/afc/specs/` directory if it does not exist)
4. If already exists, confirm with user: "Overwrite existing spec?"

### 2. Explore Codebase

Before writing the spec, understand the current project structure:

1. Check key directories by `{config.architecture}` layer
2. Explore existing code related to the feature description (Grep/Glob)
3. Identify related type definitions, APIs, and components
4. **Necessity & scope check** — evaluate whether the request warrants a full spec:
   - **Already exists?** If the feature substantially exists → report: "This feature appears to already exist at {path}." Ask user: enhance existing, replace entirely, or abort.
   - **Over-scoped?** If `$ARGUMENTS` implies multiple unrelated concerns or changes that span different architectural boundaries, warn and suggest splitting. Judge by the diversity and independence of concerns, not by file count — a well-organized feature touching many files in one module is fine, while a small change spanning security, database, and UI layers may be over-scoped.
   - **Trivial?** If the change is small enough to implement directly (typo, config value, single-line fix) → suggest: "This can be implemented directly without a full spec. Proceed with direct edit?"
   - If user chooses abort → end with `"No spec generated — {reason}."` and suggest the appropriate alternative.

### 2.5. Research Gate (conditional)

Detect whether `$ARGUMENTS` references external libraries, APIs, or technologies not already present in the codebase:

1. **Scan for external references**: extract library names, API names, protocol names, and framework references from `$ARGUMENTS`
2. **Check codebase presence**: Grep/Glob for each reference in the project
3. **If all references are internal** (found in codebase): skip research, proceed to Step 3
4. **If external references detected**:
   - For each unknown reference, run a focused WebSearch query: `"{library/API name} latest stable version usage guide {current year}"`
   - Optionally use Context7 (`mcp__context7__resolve-library-id` → `mcp__context7__query-docs`) for library-specific documentation
   - Record findings to `.claude/afc/specs/{YYYY-MM-DD}-{feature-name}/research-notes.md` (lightweight spec-scoped notes; distinct from plan phase's `research.md` which covers deep technical research)
   - Also use findings inline as context for spec writing
   - Tag each researched item in spec with `[RESEARCHED]` for traceability

> Research here is **lightweight and spec-scoped** — just enough to write accurate requirements. Deep technical research (alternatives comparison, migration paths) belongs in `/afc:plan` Phase 0.

### 3. Write Spec

Create `.claude/afc/specs/{YYYY-MM-DD}-{feature-name}/spec.md` following the template in `${CLAUDE_SKILL_DIR}/spec-template.md`. Read it first, then generate the spec using that structure.

### 3.5. Inline Clarification (standalone mode only)

After writing the spec, check for `[NEEDS CLARIFICATION]` items:

1. **If no `[NEEDS CLARIFICATION]` items exist**: skip, proceed to Step 4
2. **If items exist and running standalone** (`/afc:spec` directly):
   - Present each ambiguity to the user via AskUserQuestion (max 3 questions per batch)
   - Apply answers directly into spec.md (replace `[NEEDS CLARIFICATION]` with resolved text)
   - If user chooses to defer: leave items as `[NEEDS CLARIFICATION]` and note in final output
3. **If running inside `/afc:auto`**: skip this step entirely (auto.md handles auto-resolution in Phase 1)

> This replaces the previous pattern of always deferring to `/afc:clarify`. Standalone spec now resolves ambiguities immediately when the user is present. `/afc:clarify` remains available for revisiting specs later.

### 4. Retrospective Check

If `.claude/afc/memory/retrospectives/` directory exists, load the **most recent 10 files** (sorted by filename descending) and check:
- Were there previous `[AUTO-RESOLVED]` items that turned out wrong? Flag similar patterns.
- Were there scope-related issues in past specs? Warn about similar ambiguities.

### 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** | Does every User Story have acceptance scenarios? Are any requirements missing? |
| **MEASURABILITY** | Are the success criteria measurable, not subjective? |
| **INDEPENDENCE** | Are implementation details (code, library names) absent from the spec? |
| **EDGE_CASES** | Are at least 2 edge cases identified? Any missing boundary conditions? |
| **TESTABILITY** | Does every System Requirement follow one of the 5 EARS patterns (WHEN/WHILE/IF/WHERE/SHALL)? Does each EARS requirement have a mapped TC (`→ TC: should_...`)? If not → FAIL and auto-fix: rewrite to EARS + generate TC mapping. |

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

### 5.5. Auto-Checkpoint (standalone only)

When not running inside `/afc:auto`, save progress for `/afc:resume`:
- Create `.claude/afc/memory/` directory if it does not exist (`mkdir -p .claude/afc/memory/`)
- Write/update `.claude/afc/memory/checkpoint.md` with: branch, last commit (or "none" if empty repo), feature name, current phase (spec complete), next step (`/afc:plan`)
- Skip if running inside auto pipeline (auto manages its own checkpoints via phase transitions)

### 6. Final Output

```
Spec generated
├─ .claude/afc/specs/{YYYY-MM-DD}-{feature-name}/spec.md
├─ User Stories: {count}
├─ Requirements: FR {count}, NFR {count}
├─ Research: {N} external references researched / skipped (all internal)
├─ Clarified: {N} items resolved inline / {M} deferred
├─ Unresolved: {[NEEDS CLARIFICATION] count}
└─ Next step: /afc:plan (unresolved items will be flagged at plan start)
```

## Notes

- Do **not** write implementation details in the spec. Expressions like "manage with Zustand" belong in plan.md.
- Specify **actual paths** for entities related to existing code.
- If `$ARGUMENTS` is empty, ask user for a feature description.
- Do not pack too many features into one spec. Suggest splitting if User Stories exceed 5.
- When running `/afc:auto`, `[AUTO-SUGGESTED]` NFRs are included automatically. Review after completion is recommended.