all-for-claudecode 2.9.1 → 2.10.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Automated pipeline for Claude Code — spec → plan → implement → review → clean",
-    "version": "2.9.1"
+    "version": "2.10.0"
   },
   "plugins": [
     {
       "name": "afc",
       "source": "./",
       "description": "Automated pipeline for Claude Code. Automates the full development cycle: spec → plan → implement → review → clean.",
-      "version": "2.9.1",
+      "version": "2.10.0",
       "category": "automation",
       "tags": ["pipeline", "automation", "spec", "plan", "implement", "review", "critic-loop"]
     }

package/.claude-plugin/plugin.json

@@ -1,11 +1,11 @@
 {
   "name": "afc",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "Automated pipeline for Claude Code. Automates the full development cycle: spec → plan → implement → review → clean.",
   "author": { "name": "jhlee0409", "email": "relee6203@gmail.com" },
   "homepage": "https://github.com/jhlee0409/all-for-claudecode",
   "repository": "https://github.com/jhlee0409/all-for-claudecode",
   "license": "MIT",
   "keywords": ["pipeline", "automation", "spec", "plan", "implement", "review", "critic-loop"],
-  "commands": "./commands/"
+  "skills": "./skills/"
 }

package/MIGRATION.md

@@ -112,7 +112,7 @@ git tag -d selfish/pre-auto 2>/dev/null
 |------|--------|-------|
 | Installation | `git clone` + `./install.sh` | `/plugin install <url>` |
 | Command separator | `.` (`/afc-legacy.spec`) | `:` (`/afc:spec`) |
-| Command location | `~/.claude/commands/afc-legacy.*.md` | `commands/*.md` inside the plugin |
+| Command location | `~/.claude/commands/afc-legacy.*.md` | `skills/*/SKILL.md` inside the plugin |
 | Hook scripts | `<project>/.claude/hooks/*.sh` | `scripts/*.sh` inside the plugin |
 | Hook config | `<project>/.claude/settings.json` | `hooks/hooks.json` inside the plugin |
 | Config file | `.claude/afc.config.md` (unchanged) | `.claude/afc.config.md` (unchanged) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-for-claudecode",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "Claude Code plugin that automates the full dev cycle — spec, plan, implement, review, clean.",
   "bin": {
     "all-for-claudecode": "bin/cli.mjs"
@@ -9,7 +9,7 @@
   "files": [
     "agents/",
     "bin/",
-    "commands/",
+    "skills/",
     "docs/",
     "hooks/",
     "schemas/",

package/schemas/plugin.schema.json

@@ -41,9 +41,9 @@
       "type": "array",
       "items": { "type": "string" }
     },
-    "commands": {
+    "skills": {
       "type": "string",
-      "description": "Path to commands directory"
+      "description": "Path to skills directory"
     },
     "agents": {
       "type": "string",

package/scripts/afc-consistency-check.sh

@@ -42,7 +42,7 @@ get_cmd_field() {
 }
 
 # --- Check 1: Config Placeholder Validation ---
-# Verify all {config.*} references in commands/ and docs/ map to known config keys
+# Verify all {config.*} references in skills/ and docs/ map to known config keys
 
 check_config_placeholders() {
   local template="$PROJECT_DIR/templates/afc.config.template.md"
@@ -66,9 +66,9 @@ check_config_placeholders() {
   local valid_keys
   valid_keys=$(printf '%s\n%s\n' "$yaml_keys" "$section_keys" | sort -u)
 
-  # Extract all {config.*} references from commands and docs
+  # Extract all {config.*} references from skills and docs
   local refs
-  refs=$(grep -rohE '\{config\.[a-z_]+\}' "$PROJECT_DIR/commands/" "$PROJECT_DIR/docs/" 2>/dev/null \
+  refs=$(grep -rohE '\{config\.[a-z_]+\}' "$PROJECT_DIR/skills/" "$PROJECT_DIR/docs/" 2>/dev/null \
     | sed 's/{config\.//;s/}//' \
     | sort -u || true)
 
@@ -104,9 +104,9 @@ check_agent_names() {
     | tr -d '"' \
     | sort -u || true)
 
-  # Extract subagent_type references from commands (afc:agent-name pattern)
+  # Extract subagent_type references from skills (afc:agent-name pattern)
   local referenced_agents
-  referenced_agents=$(grep -rohE 'subagent_type:[[:space:]]*"afc:[^"]*"' "$PROJECT_DIR/commands/" 2>/dev/null \
+  referenced_agents=$(grep -rohE 'subagent_type:[[:space:]]*"afc:[^"]*"' "$PROJECT_DIR/skills/" 2>/dev/null \
     | sed 's/.*"afc://;s/"//' \
     | sort -u || true)
 
@@ -122,7 +122,7 @@ check_agent_names() {
 
   # Check for unprefixed subagent_type that should have afc: prefix
   local unprefixed
-  unprefixed=$(grep -rohE 'subagent_type:[[:space:]]*"afc-[^"]*"' "$PROJECT_DIR/commands/" 2>/dev/null \
+  unprefixed=$(grep -rohE 'subagent_type:[[:space:]]*"afc-[^"]*"' "$PROJECT_DIR/skills/" 2>/dev/null \
     | sed 's/.*subagent_type:[[:space:]]*"//;s/".*//' \
     | sort -u || true)
   for ref in $unprefixed; do
@@ -254,22 +254,22 @@ check_phase_ssot() {
   fi
 }
 
-# --- Check 7: Command Documentation Cross-Reference ---
-# Verify commands are documented in README.md, init.md, and CLAUDE.md
+# --- Check 7: Skill Documentation Cross-Reference ---
+# Verify skills are documented in README.md, init/SKILL.md, and CLAUDE.md
 
 check_command_docs() {
-  local commands_dir="$PROJECT_DIR/commands"
-  [ -d "$commands_dir" ] || return
+  local skills_dir="$PROJECT_DIR/skills"
+  [ -d "$skills_dir" ] || return
 
   local readme="$PROJECT_DIR/README.md"
-  local init_cmd="$commands_dir/init.md"
+  local init_skill="$skills_dir/init/SKILL.md"
   local claude_md="$PROJECT_DIR/CLAUDE.md"
   local issues=0
 
-  for cmd_file in "$commands_dir"/*.md; do
-    [ -f "$cmd_file" ] || continue
+  for skill_file in "$skills_dir"/*/SKILL.md; do
+    [ -f "$skill_file" ] || continue
     local cmd_name
-    cmd_name=$(basename "$cmd_file" .md)
+    cmd_name=$(basename "$(dirname "$skill_file")")
 
     # Sub-check A: README.md should mention /afc:{name}
     if [ -f "$readme" ]; then
@@ -279,29 +279,29 @@ check_command_docs() {
       fi
     fi
 
-    # Sub-check B: init.md should mention afc:{name} for user-invocable commands
+    # Sub-check B: init/SKILL.md should mention afc:{name} for user-invocable skills
     local invocable
-    invocable=$(get_cmd_field "$cmd_file" "user-invocable")
-    if [ "$invocable" != "false" ] && [ -f "$init_cmd" ]; then
-      if ! grep -qE "afc:${cmd_name}([^a-z0-9-]|$)" "$init_cmd" 2>/dev/null; then
-        warn "Command '$cmd_name' missing from init.md skill routing"
+    invocable=$(get_cmd_field "$skill_file" "user-invocable")
+    if [ "$invocable" != "false" ] && [ -f "$init_skill" ]; then
+      if ! grep -qE "afc:${cmd_name}([^a-z0-9-]|$)" "$init_skill" 2>/dev/null; then
+        warn "Skill '$cmd_name' missing from init/SKILL.md skill routing"
         issues=$((issues + 1))
       fi
     fi
 
-    # Sub-check C: CLAUDE.md fork list for context:fork commands
+    # Sub-check C: CLAUDE.md fork list for context:fork skills
     local ctx
-    ctx=$(get_cmd_field "$cmd_file" "context")
+    ctx=$(get_cmd_field "$skill_file" "context")
     if [ "$ctx" = "fork" ] && [ -f "$claude_md" ]; then
       if ! grep "context: fork" "$claude_md" 2>/dev/null | grep -qE "([(, ])${cmd_name}([,) ]|$)"; then
-        warn "Command '$cmd_name' (context:fork) missing from CLAUDE.md fork list"
+        warn "Skill '$cmd_name' (context:fork) missing from CLAUDE.md fork list"
         issues=$((issues + 1))
       fi
     fi
   done
 
   if [ "$issues" -eq 0 ]; then
-    ok "Command docs: all commands referenced in README.md, init.md, CLAUDE.md"
+    ok "Skill docs: all skills referenced in README.md, init/SKILL.md, CLAUDE.md"
   fi
 }
 

package/scripts/afc-doctor.sh

@@ -457,8 +457,8 @@ if [ "$IS_DEV" = true ]; then
   # Cache sync check
   CACHE_DIR="$HOME/.claude/plugins/cache/all-for-claudecode/afc/$V_PKG"
   if [ -d "$CACHE_DIR" ]; then
-    CACHE_AUTO="$CACHE_DIR/commands/auto.md"
-    SOURCE_AUTO="$PROJECT_DIR/commands/auto.md"
+    CACHE_AUTO="$CACHE_DIR/skills/auto/SKILL.md"
+    SOURCE_AUTO="$PROJECT_DIR/skills/auto/SKILL.md"
     if [ -f "$CACHE_AUTO" ] && [ -f "$SOURCE_AUTO" ]; then
       if diff -q "$SOURCE_AUTO" "$CACHE_AUTO" >/dev/null 2>&1; then
         pass "Cache in sync"
@@ -472,21 +472,21 @@ if [ "$IS_DEV" = true ]; then
     warn "Plugin cache directory not found" "install plugin first, then npm run sync:cache"
   fi
 
-  # --- Category 10: Command Definitions (dev only) ---
-  section "Command Definitions (dev)"
+  # --- Category 10: Skill Definitions (dev only) ---
+  section "Skill Definitions (dev)"
 
-  CMD_DIR="$PROJECT_DIR/commands"
-  if [ -d "$CMD_DIR" ]; then
+  SKILL_DIR="$PROJECT_DIR/skills"
+  if [ -d "$SKILL_DIR" ]; then
     CMD_COUNT=0
     CMD_FM_MISSING=""
     CMD_FIELD_MISSING=""
     CMD_NAME_MISMATCH=""
     CMD_AGENT_MISSING=""
 
-    for cmd_file in "$CMD_DIR"/*.md; do
+    for cmd_file in "$SKILL_DIR"/*/SKILL.md; do
       [ -f "$cmd_file" ] || continue
       CMD_COUNT=$((CMD_COUNT + 1))
-      BASENAME=$(basename "$cmd_file" .md)
+      BASENAME=$(basename "$(dirname "$cmd_file")")
 
       # Check frontmatter exists (--- ... ---)
       if ! head -1 "$cmd_file" | grep -q '^---' 2>/dev/null; then
@@ -658,9 +658,9 @@ if [ "$IS_DEV" = true ]; then
   # --- Category 12: Doc References (dev only) ---
   section "Doc References (dev)"
 
-  # Scan commands and agents for docs/ references
+  # Scan skills and agents for docs/ references
   DOC_REFS_MISSING=""
-  for src_file in "$CMD_DIR"/*.md "$AGENT_DIR"/*.md; do
+  for src_file in "$SKILL_DIR"/*/SKILL.md "$AGENT_DIR"/*.md; do
     [ -f "$src_file" ] || continue
     while IFS= read -r ref; do
       [ -z "$ref" ] && continue

package/scripts/afc-qa-audit.sh

@@ -452,7 +452,7 @@ check_d1_cache_divergence() {
   local diverged=0
   local checked=0
 
-  for subdir in commands scripts hooks; do
+  for subdir in skills scripts hooks; do
     local src_dir="$PROJECT_DIR/$subdir"
     local cache_subdir="$cache_version_dir/$subdir"
     [ -d "$src_dir" ] && [ -d "$cache_subdir" ] || continue

package/scripts/afc-sync-cache.sh

@@ -31,7 +31,7 @@ if [ ! -d "$CACHE_DIR" ]; then
 fi
 
 # Sync directories and files
-DIRS_TO_SYNC="commands agents scripts hooks docs schemas templates"
+DIRS_TO_SYNC="skills agents scripts hooks docs schemas templates"
 FILES_TO_SYNC="package.json"
 
 for dir in $DIRS_TO_SYNC; do

package/{commands/plan.md → skills/plan/SKILL.md}

@@ -101,128 +101,7 @@ Future pipelines can reference prior research to avoid redundant investigation.
 
 ### 4. Phase 1 — Write Design
 
-Create `.claude/afc/specs/{feature}/plan.md`. **Must** follow the structure below:
-
-```markdown
-# Implementation Plan: {feature name}
-
-## Summary
-{summary of core requirements from spec + technical approach, 3-5 sentences}
-
-## Technical Context
-{Summarize key project settings from .claude/rules/afc-project.md (auto-loaded) and afc.config.md}
-- **Constraints**: {constraints extracted from spec}
-
-## Principles Check
-{if .claude/afc/memory/principles.md exists: validation results against MUST principles}
-{if violations possible: state explicitly + justification}
-
-## Architecture Decision
-### Approach
-{core idea of the chosen design}
-
-### Architecture Placement
-| Layer | Path | Role |
-|-------|------|------|
-| {entities/features/widgets/shared} | {path} | {description} |
-
-### State Management Strategy (omit if not applicable)
-{what combination of Zustand store / React Query / Context is used where}
-
-### API Design (omit if not applicable)
-{plan for new API endpoints or use of existing APIs}
-
-## Test Strategy
-
-> Written alongside the File Change Map. Classify each implementation file and decide test coverage level.
-> Determines which files need test coverage and at what level.
-
-### Code Classification
-
-| File | Code Type | Test Need | Reason |
-|------|-----------|:---------:|--------|
-| {path} | {business-logic / pure-function / side-effect / framework / config / UI} | {required / optional / unnecessary} | {brief justification} |
-
-> Classification guide:
-> - **business-logic / pure-function**: Required — unit tests (AAA pattern)
-> - **side-effect code** (external API, DB, file I/O): Required — integration tests with mocks
-> - **framework / config / getter-setter / boilerplate**: Unnecessary — no test
-> - **UI rendering** (no state logic): Optional — minimal snapshot or skip
-
-### Test Pyramid
-
-- **Unit tests**: {count} files ({which files})
-- **Integration tests**: {count} files ({which files}, if applicable)
-- **E2E tests**: {count} (if applicable, only for critical user flows)
-
-### Required Test Cases (derived from spec EARS requirements)
-
-{For each spec EARS requirement with `→ TC:` mapping, list the test case here}
-- `should_{behavior}_when_{trigger}` → covers FR-{NNN}
-- `should_{behavior}_while_{state}` → covers FR-{NNN}
-
-## File Change Map
-
-| File | Action | Description | Depends On | Phase |
-|------|--------|-------------|------------|-------|
-| {path} | create/modify/delete | {summary} | {file(s) or "—"} | {1-N} |
-
-> - **Depends On**: list file(s) that must be created/modified first (enables dependency-aware task generation in /afc:implement).
-> - **Phase**: implementation phase number. Same-phase + no dependency + different file = parallelizable.
-> - **Test files**: For each implementation file classified as "required" in Code Classification, include a corresponding test file in the same Phase. Test files are first-class citizens in the File Change Map.
-
-## Implementation Context
-
-> Auto-generated section for implementation agents. Compress to under 500 words.
-> This section travels with every sub-agent prompt during /afc:implement.
-
-- **Objective**: {1-sentence feature purpose from spec Overview}
-- **Key Constraints**: {NFR summaries + spec Constraints section, compressed}
-- **Critical Edge Cases**: {top 3 edge cases from spec, 1 line each}
-- **Risk Watchpoints**: {top risks from Risk & Mitigation table}
-- **Must NOT**: {explicit prohibitions — from spec constraints, principles.md, or CLAUDE.md}
-- **Acceptance Anchors**: {key acceptance criteria from spec that implementation must satisfy}
-
-## Risk & Mitigation
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| {risk} | {H/M/L} | {approach} |
-
-## Alternative Design
-### Approach 0: No Change (status quo)
-{Why might the current state be sufficient? What is the cost of doing nothing?}
-{If no change is clearly inferior: state specific reason — "Status quo lacks X, which is required by FR-001"}
-{If no change is viable: recommend it — avoid implementing for the sake of implementing}
-
-### Approach A: {chosen approach name}
-{Brief description — this is the approach detailed above}
-
-### Approach B: {alternative approach name}
-{Brief description of a meaningfully different approach}
-
-| Criterion | No Change | Approach A | Approach B |
-|-----------|-----------|-----------|-----------|
-| Complexity | None | {evaluation} | {evaluation} |
-| Risk | None | {evaluation} | {evaluation} |
-| Maintainability | Current | {evaluation} | {evaluation} |
-| Justification | {why not enough} | {why this} | {why this} |
-
-**Decision**: Approach {0/A/B} — {1-sentence rationale}
-{If Approach 0 chosen: abort plan, report: "No implementation needed — current state satisfies requirements."}
-
-## Phase Breakdown
-### Phase 1: Setup
-{project structure, type definitions, configuration}
-
-### Phase 2: Core Implementation
-{core business logic, state management}
-
-### Phase 3: UI & Integration
-{UI components, API integration}
-
-### Phase 4: Polish
-{error handling, performance optimization, tests}
-```
+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
 

package/skills/plan/plan-template.md

@@ -0,0 +1,118 @@
+# Implementation Plan: {feature name}
+
+## Summary
+{summary of core requirements from spec + technical approach, 3-5 sentences}
+
+## Technical Context
+{Summarize key project settings from .claude/rules/afc-project.md (auto-loaded) and afc.config.md}
+- **Constraints**: {constraints extracted from spec}
+
+## Principles Check
+{if .claude/afc/memory/principles.md exists: validation results against MUST principles}
+{if violations possible: state explicitly + justification}
+
+## Architecture Decision
+### Approach
+{core idea of the chosen design}
+
+### Architecture Placement
+| Layer | Path | Role |
+|-------|------|------|
+| {entities/features/widgets/shared} | {path} | {description} |
+
+### State Management Strategy (omit if not applicable)
+{what combination of Zustand store / React Query / Context is used where}
+
+### API Design (omit if not applicable)
+{plan for new API endpoints or use of existing APIs}
+
+## Test Strategy
+
+> Written alongside the File Change Map. Classify each implementation file and decide test coverage level.
+> Determines which files need test coverage and at what level.
+
+### Code Classification
+
+| File | Code Type | Test Need | Reason |
+|------|-----------|:---------:|--------|
+| {path} | {business-logic / pure-function / side-effect / framework / config / UI} | {required / optional / unnecessary} | {brief justification} |
+
+> Classification guide:
+> - **business-logic / pure-function**: Required — unit tests (AAA pattern)
+> - **side-effect code** (external API, DB, file I/O): Required — integration tests with mocks
+> - **framework / config / getter-setter / boilerplate**: Unnecessary — no test
+> - **UI rendering** (no state logic): Optional — minimal snapshot or skip
+
+### Test Pyramid
+
+- **Unit tests**: {count} files ({which files})
+- **Integration tests**: {count} files ({which files}, if applicable)
+- **E2E tests**: {count} (if applicable, only for critical user flows)
+
+### Required Test Cases (derived from spec EARS requirements)
+
+{For each spec EARS requirement with `→ TC:` mapping, list the test case here}
+- `should_{behavior}_when_{trigger}` → covers FR-{NNN}
+- `should_{behavior}_while_{state}` → covers FR-{NNN}
+
+## File Change Map
+
+| File | Action | Description | Depends On | Phase |
+|------|--------|-------------|------------|-------|
+| {path} | create/modify/delete | {summary} | {file(s) or "—"} | {1-N} |
+
+> - **Depends On**: list file(s) that must be created/modified first (enables dependency-aware task generation in /afc:implement).
+> - **Phase**: implementation phase number. Same-phase + no dependency + different file = parallelizable.
+> - **Test files**: For each implementation file classified as "required" in Code Classification, include a corresponding test file in the same Phase. Test files are first-class citizens in the File Change Map.
+
+## Implementation Context
+
+> Auto-generated section for implementation agents. Compress to under 500 words.
+> This section travels with every sub-agent prompt during /afc:implement.
+
+- **Objective**: {1-sentence feature purpose from spec Overview}
+- **Key Constraints**: {NFR summaries + spec Constraints section, compressed}
+- **Critical Edge Cases**: {top 3 edge cases from spec, 1 line each}
+- **Risk Watchpoints**: {top risks from Risk & Mitigation table}
+- **Must NOT**: {explicit prohibitions — from spec constraints, principles.md, or CLAUDE.md}
+- **Acceptance Anchors**: {key acceptance criteria from spec that implementation must satisfy}
+
+## Risk & Mitigation
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {risk} | {H/M/L} | {approach} |
+
+## Alternative Design
+### Approach 0: No Change (status quo)
+{Why might the current state be sufficient? What is the cost of doing nothing?}
+{If no change is clearly inferior: state specific reason — "Status quo lacks X, which is required by FR-001"}
+{If no change is viable: recommend it — avoid implementing for the sake of implementing}
+
+### Approach A: {chosen approach name}
+{Brief description — this is the approach detailed above}
+
+### Approach B: {alternative approach name}
+{Brief description of a meaningfully different approach}
+
+| Criterion | No Change | Approach A | Approach B |
+|-----------|-----------|-----------|-----------|
+| Complexity | None | {evaluation} | {evaluation} |
+| Risk | None | {evaluation} | {evaluation} |
+| Maintainability | Current | {evaluation} | {evaluation} |
+| Justification | {why not enough} | {why this} | {why this} |
+
+**Decision**: Approach {0/A/B} — {1-sentence rationale}
+{If Approach 0 chosen: abort plan, report: "No implementation needed — current state satisfies requirements."}
+
+## Phase Breakdown
+### Phase 1: Setup
+{project structure, type definitions, configuration}
+
+### Phase 2: Core Implementation
+{core business logic, state management}
+
+### Phase 3: UI & Integration
+{UI components, API integration}
+
+### Phase 4: Polish
+{error handling, performance optimization, tests}

package/{commands/spec.md → skills/spec/SKILL.md}

@@ -75,82 +75,7 @@ Detect whether `$ARGUMENTS` references external libraries, APIs, or technologies
 
 ### 3. Write Spec
 
-Create `.claude/afc/specs/{feature-name}/spec.md`:
-
-```markdown
-# Feature Spec: {feature name}
-
-> Created: {YYYY-MM-DD}
-> Branch: {BRANCH_NAME}
-> Status: Draft
-
-## Overview
-{2-3 sentences on the purpose and background of the feature}
-
-## User Stories
-
-### US1: {story title} [P1]
-**Description**: {feature description from user perspective}
-**Priority rationale**: {why this order}
-**Independent testability**: {whether this story can be tested on its own}
-
-#### Acceptance Scenarios (GWT for user scenarios)
-- [ ] Given {precondition}, When {action}, Then {result}
-- [ ] Given {precondition}, When {action}, Then {result}
-
-#### System Requirements (EARS notation)
-
-> Use one of the 5 EARS patterns for each requirement. Each requirement must map to at least one expected test case (TC).
-
-| Pattern | Template | Use When |
-|---------|----------|----------|
-| Ubiquitous | `THE System SHALL {behavior}` | Always-on property (no trigger needed) |
-| Event-driven | `WHEN {trigger}, THE System SHALL {response}` | Specific event triggers a response |
-| State-driven | `WHILE {state}, THE System SHALL {behavior}` | Behavior depends on system state |
-| Unwanted | `IF {condition}, THE System SHALL {handling}` | Error/failure handling |
-| Optional | `WHERE {feature/config active}, THE System SHALL {behavior}` | Feature flag or conditional capability |
-
-- [ ] WHEN {trigger}, THE System SHALL {behavior} → TC: `should_{behavior}_when_{trigger}`
-- [ ] WHILE {state}, THE System SHALL {behavior} → TC: `should_{behavior}_while_{state}`
-
-### US2: {story title} [P2]
-{same format}
-
-## Requirements
-
-### Functional Requirements
-- **FR-001**: {requirement}
-- **FR-002**: {requirement}
-
-### Non-Functional Requirements
-- **NFR-001**: {performance/security/accessibility etc.}
-
-### Auto-Suggested NFRs
-{Load `${CLAUDE_PLUGIN_ROOT}/docs/nfr-templates.md` and select 3-5 relevant NFRs based on the project type detected from afc.config.md}
-- **NFR-A01** [AUTO-SUGGESTED]: {suggestion from matching project type template}
-- **NFR-A02** [AUTO-SUGGESTED]: {suggestion}
-- **NFR-A03** [AUTO-SUGGESTED]: {suggestion}
-{Tag each with [AUTO-SUGGESTED]. Users may accept, modify, or remove.}
-
-### Key Entities
-| Entity | Description | Related Existing Code |
-|--------|-------------|-----------------------|
-| {name} | {description} | {path or "new"} |
-
-## Success Criteria
-- **SC-001**: {measurable success indicator}
-- **SC-002**: {measurable success indicator}
-
-## Edge Cases
-- {edge case 1}
-- {edge case 2}
-
-## Constraints
-- {technical/business constraints}
-
-## [NEEDS CLARIFICATION]
-- {uncertain items — record if any, remove section if none}
-```
+Create `.claude/afc/specs/{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)
 

package/skills/spec/spec-template.md

@@ -0,0 +1,72 @@
+# Feature Spec: {feature name}
+
+> Created: {YYYY-MM-DD}
+> Branch: {BRANCH_NAME}
+> Status: Draft
+
+## Overview
+{2-3 sentences on the purpose and background of the feature}
+
+## User Stories
+
+### US1: {story title} [P1]
+**Description**: {feature description from user perspective}
+**Priority rationale**: {why this order}
+**Independent testability**: {whether this story can be tested on its own}
+
+#### Acceptance Scenarios (GWT for user scenarios)
+- [ ] Given {precondition}, When {action}, Then {result}
+- [ ] Given {precondition}, When {action}, Then {result}
+
+#### System Requirements (EARS notation)
+
+> Use one of the 5 EARS patterns for each requirement. Each requirement must map to at least one expected test case (TC).
+
+| Pattern | Template | Use When |
+|---------|----------|----------|
+| Ubiquitous | `THE System SHALL {behavior}` | Always-on property (no trigger needed) |
+| Event-driven | `WHEN {trigger}, THE System SHALL {response}` | Specific event triggers a response |
+| State-driven | `WHILE {state}, THE System SHALL {behavior}` | Behavior depends on system state |
+| Unwanted | `IF {condition}, THE System SHALL {handling}` | Error/failure handling |
+| Optional | `WHERE {feature/config active}, THE System SHALL {behavior}` | Feature flag or conditional capability |
+
+- [ ] WHEN {trigger}, THE System SHALL {behavior} → TC: `should_{behavior}_when_{trigger}`
+- [ ] WHILE {state}, THE System SHALL {behavior} → TC: `should_{behavior}_while_{state}`
+
+### US2: {story title} [P2]
+{same format}
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: {requirement}
+- **FR-002**: {requirement}
+
+### Non-Functional Requirements
+- **NFR-001**: {performance/security/accessibility etc.}
+
+### Auto-Suggested NFRs
+{Load `${CLAUDE_SKILL_DIR}/nfr-templates.md` and select 3-5 relevant NFRs based on the project type detected from afc.config.md}
+- **NFR-A01** [AUTO-SUGGESTED]: {suggestion from matching project type template}
+- **NFR-A02** [AUTO-SUGGESTED]: {suggestion}
+- **NFR-A03** [AUTO-SUGGESTED]: {suggestion}
+{Tag each with [AUTO-SUGGESTED]. Users may accept, modify, or remove.}
+
+### Key Entities
+| Entity | Description | Related Existing Code |
+|--------|-------------|-----------------------|
+| {name} | {description} | {path or "new"} |
+
+## Success Criteria
+- **SC-001**: {measurable success indicator}
+- **SC-002**: {measurable success indicator}
+
+## Edge Cases
+- {edge case 1}
+- {edge case 2}
+
+## Constraints
+- {technical/business constraints}
+
+## [NEEDS CLARIFICATION]
+- {uncertain items — record if any, remove section if none}