Afc:spec

/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)

1. Create directory: .claude/afc/specs/{YYYY-MM-DD}-{feature-name}/ (create parent .claude/afc/specs/ directory if it does not exist)
2. 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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jhlee0409
• Source: jhlee0409/all-for-claudecode
• License: MIT
• Homepage: https://www.npmjs.com/package/all-for-claudecode

Install and usage instructions live in the source repository linked above.