all-for-claudecode 2.8.1 → 2.9.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "afc",
-  "version": "2.8.1",
+  "version": "2.9.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",

package/commands/analyze.md

@@ -23,12 +23,10 @@ model: sonnet
 
 ## Config Load
 
-**Always** read `.claude/afc.config.md` first. This file contains free-form markdown sections:
-- `## Architecture` — architecture pattern, layers, import rules (primary reference for structural analysis)
-- `## Code Style` — language, naming conventions, lint rules
-- `## Project Context` — framework, state management, testing, etc.
+Architecture, Code Style, and Project Context are auto-loaded via `.claude/rules/afc-project.md`.
+Read `.claude/afc.config.md` if CI commands are needed.
 
-If config file is missing: read `CLAUDE.md` for architecture info. Proceed without config if neither exists.
+If neither rules file nor config exists: read `CLAUDE.md` for architecture info. Proceed without config if neither exists.
 
 ## Execution Steps
 

package/commands/architect.md

@@ -26,12 +26,10 @@ model: sonnet
 
 ## Config Load
 
-**Always** read `.claude/afc.config.md` first. This file contains free-form markdown sections:
-- `## Architecture` — architecture pattern, layers, import rules (primary reference for this command)
-- `## Code Style` — language, naming conventions, lint rules
-- `## Project Context` — framework, state management, testing, etc.
+Read `.claude/afc.config.md` if CI commands are needed.
+Architecture, Code Style, and Project Context are auto-loaded via `.claude/rules/afc-project.md`.
 
-If config file is missing: read `CLAUDE.md` for architecture info. Assume "Layered Architecture" if neither source has it.
+If neither rules file nor config exists: read `CLAUDE.md` for architecture info. Assume "Layered Architecture" if no source has it.
 
 ## Execution Steps
 

package/commands/consult.md

@@ -1,6 +1,6 @@
 ---
 name: afc:consult
-description: "Expert consultation — use when the user asks for expert advice, wants to consult a specialist, or needs domain-specific guidance on backend, infra, PM, design, marketing, legal, or tech decisions"
+description: "Expert consultation — use when the user asks for expert advice, wants to consult a specialist, needs domain-specific guidance on backend, infra, PM, design, marketing, legal, or tech decisions, or wants to think together, brainstorm, discuss ideas, or have a structured dialogue"
 argument-hint: "[domain?] \"[question]\" [brief|deep]"
 model: sonnet
 ---
@@ -14,7 +14,7 @@ model: sonnet
 ## Arguments
 
 - `$ARGUMENTS` — (optional) Format: `[domain] "[question]" [brief|deep]`
-  - `domain` — one of: `backend`, `infra`, `pm`, `design`, `marketing`, `legal`, `security`, `advisor` (optional, auto-detected if omitted)
+  - `domain` — one of: `backend`, `infra`, `pm`, `design`, `marketing`, `legal`, `security`, `advisor`, `peer` (optional, auto-detected if omitted)
   - `question` — the consultation question (optional, enters exploratory mode if omitted)
   - `brief|deep` — depth hint (optional, default: `auto`)
 
@@ -45,6 +45,7 @@ If `$ARGUMENTS` is empty → go to Step 2 (domain selection).
 | legal | GDPR, CCPA, privacy, cookie, consent, license, GPL, MIT, compliance, terms of service, data protection, PII, HIPAA, regulation, policy |
 | security | XSS, CSRF, injection, OWASP, vulnerability, attack, exploit, encryption, secret, credential, CORS, CSP, rate limit, brute force, penetration |
 | advisor | library, framework, stack, tool, package, which to use, alternative, compare, choose, select, recommend, what exists, ecosystem, best option, switch to |
+| peer | think together, brainstorm, discuss, explore idea, talk through, figure out, pros and cons, what if, should I, direction, approach, trade-off, opinion, weigh options |
 
 Match rules:
 - Case-insensitive keyword matching against the question
@@ -65,9 +66,79 @@ Options:
 6. Legal — GDPR, privacy, licenses, compliance, terms of service
 7. Security — application security, OWASP, threat modeling, secure coding
 8. Advisor — technology/library/framework selection, ecosystem navigation, stack decisions
+9. Peer — think together, brainstorm, discuss ideas, explore directions as equals
 ```
 
-### 3. Construct Expert Prompt
+### 3. Peer Mode (if domain is `peer`)
+
+If the detected domain is `peer`, **do not delegate to a subagent**. Run the dialogue directly in the main context.
+
+#### Behavior Principles
+
+You are a thinking partner, not an expert giving answers. Follow these rules:
+
+1. **Ask before answering.** Default to questions that deepen the user's thinking, not solutions. "What would happen if...?", "What are you optimizing for?"
+2. **Challenge, don't agree.** Apply the Anti-Sycophancy Rules from `expert-protocol.md`. When the user states a direction, probe its weaknesses before supporting it.
+3. **Present the strongest counter-argument.** Steel-man the opposing view: "The best case for NOT doing this is..."
+4. **Name what's been decided and what hasn't.** Periodically summarize: "So far we've landed on X. Still open: Y and Z."
+5. **Suggest convergence, don't force it.** When the discussion feels circular or key decisions are made, say so: "I think we have enough to move forward. Want to wrap up?"
+
+#### Coaching Techniques
+
+Use these as appropriate — not all at once, not in order:
+
+- **5 Whys** — repeat "why?" to reach the root motivation
+- **Pre-mortem** — "If this fails in 6 months, what went wrong?"
+- **Constraint flip** — "What if you had half the time?" / "What if cost didn't matter?"
+- **Steel-manning** — present the strongest version of the opposing view
+- **Bisection** — "Is the core question A or B?" to narrow scope
+
+#### Codebase Context
+
+If the discussion involves the current project:
+- Read relevant files (Read/Glob/Grep) to ground the conversation in reality
+- Reference actual code, not hypothetical structures
+- Note existing patterns that constrain or enable options
+
+#### Wrapping Up
+
+When the user signals completion (or agrees to your convergence suggestion):
+
+1. Write `.claude/afc/discuss.md` with:
+
+```markdown
+# Discussion: {topic}
+
+> Date: {YYYY-MM-DD}
+> Seed: {original question/topic}
+
+## Key Decisions
+- [DECIDED] {decision} — {rationale}
+
+## Open Questions
+- [OPEN] {unresolved item}
+
+## Summary
+{3-5 sentence synthesis of what was discussed and concluded}
+
+## Next Steps
+- {recommended action, e.g., → /afc:spec "...", → /afc:plan "...", → /afc:research "..."}
+```
+
+2. Output:
+```
+Discussion complete
+├─ .claude/afc/discuss.md
+├─ Decisions: {count}
+├─ Open questions: {count}
+└─ Suggested next: {command}
+```
+
+**Skip Steps 4-6 and end here.**
+
+---
+
+### 3b. Construct Expert Prompt (non-peer domains)
 
 Build the prompt for the expert agent:
 
@@ -146,6 +217,12 @@ Follow-up options:
 # With depth hint
 /afc:consult infra "How should I set up CI/CD?" deep
 
+# Peer mode — think together (explicit)
+/afc:consult peer "Should we split this into a monorepo or keep it separate?"
+
+# Peer mode — auto-detected from keywords
+/afc:consult "Let's think through the onboarding flow together"
+
 # No arguments (domain selection prompt)
 /afc:consult
 ```
@@ -158,3 +235,4 @@ Follow-up options:
 - **Domain adapters**: Industry-specific guardrails (fintech, ecommerce, healthcare) auto-loaded based on project profile.
 - **Pipeline-independent**: Works anytime, no active pipeline required. If a pipeline is active, experts consider the current phase context.
 - **Cross-referral**: Experts may suggest consulting another domain expert when a question crosses boundaries.
+- **Peer mode**: Unlike other domains, `peer` runs directly in the main context (no subagent). It produces `.claude/afc/discuss.md` on wrap-up. Overwritten on each new peer session — rename to preserve.

package/commands/doctor.md

@@ -1,6 +1,6 @@
 ---
 name: afc:doctor
-description: "Diagnose project health and plugin setup — use when the user asks for a health check, wants to diagnose project issues, or verify plugin installation"
+description: "Diagnose afc plugin setup and configuration — use when the user asks for a health check, wants to verify plugin installation, or check if afc is properly configured"
 argument-hint: "[--verbose]"
 allowed-tools:
   - Read
@@ -10,10 +10,13 @@ allowed-tools:
 model: haiku
 ---
 
-# /afc:doctor — Project Health Diagnosis
+# /afc:doctor — Plugin Setup Diagnosis
 
-> Runs a comprehensive health check on the all-for-claudecode setup for the current project.
+> Checks whether the all-for-claudecode plugin is correctly installed and configured in the current project.
+> Like `brew doctor` or `flutter doctor` — verifies the **tool's setup**, NOT the project's code quality.
 > Read-only — never modifies files. Reports issues with actionable fix commands.
+>
+> **IMPORTANT: Do NOT analyze project source code, architecture, or code quality. Only check afc plugin configuration, hooks, state, and environment as defined in the check tables below.**
 
 ## Arguments
 
@@ -32,136 +35,21 @@ Each failing check includes a **Fix:** line with the exact command to resolve it
 
 ---
 
-## Checks
-
-Run ALL checks regardless of earlier failures. Do not short-circuit.
-
-### Category 1: Environment
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| git installed | `which git` | git found in PATH | Fix: install git |
-| jq installed | `which jq` | jq found in PATH | ⚠ Warning: jq not found. Hook scripts will use grep/sed fallback (slower, less reliable). Fix: `brew install jq` or `apt install jq` |
-
-### Category 2: Project Config
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| Config file exists | Read `.claude/afc.config.md` | File exists | Fix: run `/afc:init` |
-| Required sections present | Grep for `## CI Commands`, `## Architecture`, `## Code Style` | All 3 sections found | Fix: add missing section to `.claude/afc.config.md` or re-run `/afc:init` |
-| Gate command defined | Grep for `gate:` inside `## CI Commands` section | `gate:` field found | Fix: add `gate:` field to `## CI Commands` section |
-| CI command runnable | Extract CI command from config, run it | Exits 0 | ⚠ Warning: CI command failed. Check `{config.ci}` in afc.config.md |
-| Gate command runnable | Extract gate command from config, run it | Exits 0 | ⚠ Warning: gate command failed. Check `{config.gate}` in afc.config.md |
-
-### Category 3: CLAUDE.md Integration
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| Global CLAUDE.md exists | Read `~/.claude/CLAUDE.md` | File exists | ⚠ Warning: no global CLAUDE.md. all-for-claudecode skills won't auto-trigger from intent. Fix: run `/afc:init` |
-| all-for-claudecode block present | Grep for `<!-- AFC:START -->` and `<!-- AFC:END -->` in `~/.claude/CLAUDE.md` | Both markers found | Fix: run `/afc:init` to inject all-for-claudecode block |
-| all-for-claudecode block version | Extract version from `<!-- AFC:VERSION:X.Y.Z -->` in CLAUDE.md. Read `${CLAUDE_PLUGIN_ROOT}/package.json` (`.version`) to get the actual plugin version. Compare the two. | Block version = plugin version | ⚠ Warning: all-for-claudecode block is outdated (found {block_version}, current {plugin_version}). Fix: run `/afc:init` to update |
-| No conflicting routing | Grep for conflicting agent patterns (`executor`, `deep-executor`, `debugger`, `code-reviewer`) outside all-for-claudecode block that could intercept afc intents | No conflicts or conflicts are inside other tool blocks | ⚠ Warning: found agent routing that may conflict with afc skills. Review `~/.claude/CLAUDE.md` |
-
-### Category 4: Legacy Migration (v1.x → v2.0)
-
-> Detects leftover artifacts from the old `selfish-pipeline` (v1.x) plugin. If none found, print `✓ No legacy artifacts` and skip this category.
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| No legacy CLAUDE.md block | Grep `~/.claude/CLAUDE.md` for `<!-- SELFISH:START -->` | Marker not found | ⚠ Warning: legacy `SELFISH:START` block found in `~/.claude/CLAUDE.md`. Fix: run `/afc:init` (will replace with all-for-claudecode block) |
-| No legacy config file | Check `.claude/selfish.config.md` | File does not exist | ⚠ Warning: legacy config `.claude/selfish.config.md` found. Fix: `mv .claude/selfish.config.md .claude/afc.config.md` |
-| No legacy state files | Glob `.claude/.selfish-*` | No files found | ⚠ Warning: legacy state files `.claude/.selfish-*` found. Fix: `cd .claude && for f in .selfish-*; do mv "$f" "${f/.selfish-/.afc-}"; done` |
-| No legacy artifact dir | Check `.claude/selfish/` directory | Directory does not exist | ⚠ Warning: legacy artifact directory `.claude/selfish/` found. Fix: `mv .claude/selfish .claude/afc` |
-| No legacy git tags | `git tag -l 'selfish/pre-*' 'selfish/phase-*'` | No tags found | ⚠ Warning: legacy git tags found. Fix: `git tag -l 'selfish/*' \| xargs git tag -d` |
-| No legacy plugin installed | Check if `selfish@selfish-pipeline` appears in installed plugins (grep settings.json for `selfish-pipeline`) | Not found | ⚠ Warning: old `selfish-pipeline` plugin still installed. Fix: `claude plugin uninstall selfish@selfish-pipeline && claude plugin marketplace remove jhlee0409/selfish-pipeline` |
-
-### Category 5: Pipeline State
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| No stale pipeline state | Check `.claude/.afc-state.json` via `afc-pipeline-manage.sh status` | File does not exist (no active pipeline) | ⚠ Warning: stale pipeline state found (feature: {name}, phase: {phase}). This may block normal operations. Fix: `"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" end --force` or run `/afc:resume` |
-| No orphaned artifacts | Glob `.claude/afc/specs/*/spec.md` | No specs directories, or all are from active pipeline | ⚠ Warning: orphaned `.claude/afc/specs/{name}/` found. Left over from a previous pipeline. Fix: `rm -rf .claude/afc/specs/{name}/` |
-| No lingering safety tags | `git tag -l 'afc/pre-*'` | No tags, or tags match active pipeline | ⚠ Warning: lingering safety tag `afc/pre-{x}` found. Fix: `git tag -d afc/pre-{x}` |
-| Checkpoint state | Read `.claude/afc/memory/checkpoint.md` if exists | No checkpoint (clean), or checkpoint is from current session | ⚠ Warning: stale checkpoint from {date}. Fix: run `/afc:resume` to continue or delete `.claude/afc/memory/checkpoint.md` |
-
-### Category 6: Memory Health
-
-> Checks `.claude/afc/memory/` subdirectory sizes and agent memory file sizes. If memory directory does not exist, print `✓ No memory directory` and skip this category.
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| quality-history count | Count files in `.claude/afc/memory/quality-history/` | ≤ 30 files | ⚠ Warning: {N} files in quality-history/ (threshold: 30). Oldest files should be pruned. Fix: run a pipeline with `/afc:auto` (Clean phase auto-prunes) or manually delete oldest files |
-| reviews count | Count files in `.claude/afc/memory/reviews/` | ≤ 40 files | ⚠ Warning: {N} files in reviews/ (threshold: 40). Fix: run a pipeline or manually delete oldest files |
-| retrospectives count | Count files in `.claude/afc/memory/retrospectives/` | ≤ 30 files | ⚠ Warning: {N} files in retrospectives/ (threshold: 30). Fix: run a pipeline or manually delete oldest files |
-| research count | Count files in `.claude/afc/memory/research/` | ≤ 50 files | ⚠ Warning: {N} files in research/ (threshold: 50). Fix: run a pipeline or manually delete oldest files |
-| decisions count | Count files in `.claude/afc/memory/decisions/` | ≤ 60 files | ⚠ Warning: {N} files in decisions/ (threshold: 60). Fix: run a pipeline or manually delete oldest files |
-| afc-architect MEMORY.md size | Count lines in `.claude/agent-memory/afc-architect/MEMORY.md` (if exists) | ≤ 100 lines | ⚠ Warning: afc-architect MEMORY.md is {N} lines (limit: 100). Fix: invoke `/afc:architect` to trigger self-pruning, or manually edit the file |
-| afc-security MEMORY.md size | Count lines in `.claude/agent-memory/afc-security/MEMORY.md` (if exists) | ≤ 100 lines | ⚠ Warning: afc-security MEMORY.md is {N} lines (limit: 100). Fix: invoke `/afc:security` to trigger self-pruning, or manually edit the file |
-
-### Category 7: Hook Health
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| hooks.json valid | Parse plugin's hooks.json with jq (or manual validation) | Valid JSON with `hooks` key | ✗ Fix: reinstall plugin — `claude plugin install afc@all-for-claudecode` |
-| All scripts exist | For each script referenced in hooks.json, check file exists | All scripts found | ✗ Fix: reinstall plugin |
-| Scripts executable | Check execute permission on each script in plugin's scripts/ | All have +x | Fix: `chmod +x` on the missing scripts, or reinstall plugin |
-
-### Category 8: Version Sync (development only)
-
-> Only run if current directory is the all-for-claudecode source repo (check for `package.json` with `"name": "all-for-claudecode"`).
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| Version triple match | Compare versions in `package.json` (`.version`), `.claude-plugin/plugin.json` (`.version`), `.claude-plugin/marketplace.json` (`.metadata.version` and `.plugins[0].version`) | All identical | ✗ Fix: update mismatched files to the same version |
-| Cache in sync | Compare `commands/auto.md` content between source and `~/.claude/plugins/cache/all-for-claudecode/afc/{version}/commands/auto.md` | Content matches | ⚠ Warning: plugin cache is stale. Fix: copy source files to cache directory |
-
-### Category 9: Command Definitions (development only)
-
-> Only run if current directory is the all-for-claudecode source repo (same condition as Category 8).
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| Frontmatter exists | Each `commands/*.md` file has opening and closing `---` block | All files have frontmatter | ✗ Fix: add YAML frontmatter block to `commands/{file}.md` |
-| Required fields | Each command frontmatter contains `name:` and `description:` | All files have both fields | ✗ Fix: add missing `name:` or `description:` to `commands/{file}.md` |
-| Name-filename match | `name:` value follows `afc:{filename}` pattern (e.g. `auto.md` → `name: afc:auto`) | All names match filenames | ✗ Fix: rename `name:` field in `commands/{file}.md` to `afc:{filename}` |
-| Fork-agent reference | Commands with `context: fork` and `agent:` field reference a file that exists in `agents/` (e.g. `agent: afc-architect` → `agents/afc-architect.md` exists) | All agent references resolve | ✗ Fix: create missing agent file `agents/{name}.md` or fix `agent:` field in `commands/{file}.md` |
-
-### Category 10: Agent Definitions (development only)
-
-> Only run if current directory is the all-for-claudecode source repo (same condition as Category 8).
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| Frontmatter exists | Each `agents/*.md` file has opening and closing `---` block | All files have frontmatter | ✗ Fix: add YAML frontmatter block to `agents/{file}.md` |
-| Required fields | Each agent frontmatter contains `name:`, `description:`, and `model:` | All files have all 3 fields | ✗ Fix: add missing field to `agents/{file}.md` |
-| Name-filename match | `name:` value equals the filename without extension (e.g. `afc-architect.md` → `name: afc-architect`) | All names match filenames | ✗ Fix: rename `name:` field in `agents/{file}.md` to match filename |
-| Expert memory | All 8 expert consultation agents (`afc-backend-expert`, `afc-infra-expert`, `afc-pm-expert`, `afc-design-expert`, `afc-marketing-expert`, `afc-legal-expert`, `afc-appsec-expert`, `afc-tech-advisor`) have `memory: project` | All experts have memory field | ✗ Fix: add `memory: project` to `agents/{name}.md` frontmatter |
-| Worker maxTurns | `afc-impl-worker` and `afc-pr-analyst` have `maxTurns:` field | Both workers have maxTurns | ✗ Fix: add `maxTurns:` to `agents/{name}.md` frontmatter |
-
-### Category 11: Doc References (development only)
-
-> Only run if current directory is the all-for-claudecode source repo (same condition as Category 8).
-
-| Check | How | Pass | Fail |
-|-------|-----|------|------|
-| Referenced docs exist | Scan commands and agents for file references to `docs/` (e.g. `docs/critic-loop-rules.md`, `docs/phase-gate-protocol.md`). Each referenced file must exist. | All referenced docs found | ✗ Fix: create missing `docs/{file}.md` or fix the reference |
-| Domain adapters exist | `docs/domain-adapters/` directory contains at least one `.md` file | ≥ 1 adapter file found | ✗ Fix: add domain adapter files to `docs/domain-adapters/` |
-
----
-
 ## Execution
 
-1. Run the automated health check script:
+1. Run the health check script (covers ALL categories — no manual checks needed):
    ```
    "${CLAUDE_PLUGIN_ROOT}/scripts/afc-doctor.sh" $ARGUMENTS
    ```
-   This covers Categories 1-8 automatically.
 
-2. Print the script's stdout output as-is (already formatted with pass/warn/fail markers).
+2. Print the script's stdout output as-is. Do not reformat, summarize, or interpret.
 
-3. If in the source repo (package.json `name` = `"all-for-claudecode"`), continue with Categories 9-11 manually using the check tables above.
+3. **Stop.** Output nothing after the script output. No analysis, no suggestions, no follow-up actions.
 
-4. Print combined summary (script summary + any additional findings from Categories 9-11).
+**Rules:**
+- The ONLY Bash command you may run is the `afc-doctor.sh` script above. No other Bash calls.
+- Do NOT execute Fix commands. They are for the user to run manually.
+- Do NOT analyze project source code, git history, branches, or architecture.
 
 ## Example Output
 
@@ -226,7 +114,8 @@ Results: 28 passed, 2 warnings, 0 failures
 
 ## Notes
 
-- **Read-only**: this command never modifies any files. It only reads and reports.
+- **Read-only**: this command NEVER modifies any files, deletes tags, changes permissions, or executes fix commands. It only reads and reports. The `Fix:` lines are instructions for the USER to run manually — do NOT execute them.
+- **No project analysis**: after printing the summary, STOP. Do not analyze project source code, git history, branches, or suggest next steps about the project. Doctor's scope ends at the summary line.
 - **Always run all checks**: do not stop on first failure. The full picture is the value.
 - **Actionable fixes**: every non-pass result must include a Fix line. Never report a problem without a solution.
 - **Fast execution**: skip CI/gate command checks if `--fast` is in arguments (these are the slowest checks).

package/commands/implement.md

@@ -313,9 +313,14 @@ This enables granular rollback: `git reset --hard afc/phase-{N}` restores state
 For each task:
 
 1. **Read files**: always read files before modifying them
-2. **Implement**: write code following the design in plan.md
-3. **Type/Lint check**: verify new code passes `{config.gate}`
-4. **Update tasks.md**: mark completed tasks as `[x]`
+2. **TDD cycle** (when plan.md Test Strategy classifies the task's target file as "required"):
+   - **Red**: write the test file first (failing test that defines expected behavior)
+   - **Green**: implement the minimum code to pass the test
+   - **Refactor**: clean up while keeping tests green
+   - If `{config.tdd}` is `strict` or `guide`: always follow this order. If `off` or unset: recommended but not enforced.
+3. **Implement**: write code following the design in plan.md
+4. **Type/Lint check**: verify new code passes `{config.gate}`
+5. **Update tasks.md**: mark completed tasks as `[x]`
    ```markdown
    - [x] T001 {description}  ← complete
    - [ ] T002 {description}  ← incomplete

package/commands/init.md

@@ -125,7 +125,25 @@ Write sections as natural descriptions — **no YAML code blocks** except for CI
 For items that cannot be inferred: note `TODO: Adjust for your project` inline.
 Save to `.claude/afc.config.md`.
 
-### 4.5. Generate Project Profile
+### 4.5. Generate Project Rules File
+
+Generate `.claude/rules/afc-project.md` — a concise summary of project rules that Claude Code auto-loads for all conversations and sub-agents.
+
+1. Create `.claude/rules/` directory if it does not exist
+2. If `.claude/rules/afc-project.md` already exists:
+   - If it contains `<!-- afc:auto-generated` marker: overwrite silently (auto-generated file, safe to regenerate)
+   - If it does NOT contain the marker: ask user "Project rules file exists (user-managed). Overwrite with auto-generated version?" — skip if declined
+3. Reference `${CLAUDE_PLUGIN_ROOT}/templates/afc-project.template.md` for section structure
+4. Fill in from the analysis performed in Step 3:
+   - **Architecture**: pattern, key layers, import rules, path alias — concise bullet points
+   - **Code Style**: language, naming conventions, lint rules — concise bullet points
+   - **Project Context**: framework, state management, styling, testing, DB/ORM — concise bullet points
+5. Include `<!-- afc:auto-generated — do not edit manually; regenerate with /afc:init -->` as the first line
+6. Keep total length **under 30 lines** (excluding the marker comment) — rules only, no explanations
+7. Save to `.claude/rules/afc-project.md`
+8. Print: `Project rules: .claude/rules/afc-project.md (auto-loaded by Claude Code)`
+
+### 4.6. Generate Project Profile
 
 Generate `.claude/afc/project-profile.md` for expert consultation agents:
 
@@ -302,6 +320,7 @@ The following rules were auto-generated to resolve conflicts:
 ```
 all-for-claudecode initialization complete
 ├─ Config: .claude/afc.config.md
+├─ Rules: .claude/rules/afc-project.md (auto-loaded)
 ├─ Framework: {detected framework}
 ├─ Architecture: {detected style}
 ├─ Package Manager: {detected manager}

package/commands/plan.md

@@ -26,7 +26,8 @@ model: sonnet
 
 ## Config Load
 
-**Always** read `.claude/afc.config.md` first (read manually if not auto-loaded above).
+**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?"
@@ -40,7 +41,7 @@ If config file is missing:
 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. Run `/afc:spec` first." then **abort**
+   - 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
@@ -109,7 +110,7 @@ Create `.claude/afc/specs/{feature}/plan.md`. **Must** follow the structure belo
 {summary of core requirements from spec + technical approach, 3-5 sentences}
 
 ## Technical Context
-{Summarize key project settings from afc.config.md — Architecture, Code Style, and Project Context sections}
+{Summarize key project settings from .claude/rules/afc-project.md (auto-loaded) and afc.config.md}
 - **Constraints**: {constraints extracted from spec}
 
 ## Principles Check
@@ -131,6 +132,35 @@ Create `.claude/afc/specs/{feature}/plan.md`. **Must** follow the structure belo
 ### 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 |
@@ -139,6 +169,7 @@ Create `.claude/afc/specs/{feature}/plan.md`. **Must** follow the structure belo
 
 > - **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
 
@@ -215,7 +246,7 @@ Run the critic loop until convergence. Safety cap: 5 passes.
 
 | Criterion | Validation |
 |-----------|------------|
-| **COMPLETENESS** | Are all requirements (FR-*) from spec.md reflected in the plan? |
+| **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) |

package/commands/qa.md

@@ -28,11 +28,8 @@ model: sonnet
 
 ## Config Load
 
-**Always** read `.claude/afc.config.md` first. This file contains free-form markdown sections:
-- `## Architecture` — architecture pattern, layers, import rules
-- `## Code Style` — language, naming conventions, lint rules
-- `## CI Commands` — test, lint, gate commands (YAML)
-- `## Project Context` — framework, state management, testing strategy
+**Always** read `.claude/afc.config.md` first — needed for CI Commands (YAML: ci, gate, test).
+Architecture, Code Style, and Project Context are auto-loaded via `.claude/rules/afc-project.md`.
 
 If config file is missing: read `CLAUDE.md` for project info. Proceed without config if neither exists.
 

package/commands/review.md

@@ -9,6 +9,7 @@ allowed-tools:
   - Glob
   - Bash
   - Task
+  - LSP
 model: sonnet
 ---
 
@@ -28,7 +29,8 @@ model: sonnet
 
 ## Config Load
 
-**Always** read `.claude/afc.config.md` first (read manually if not auto-loaded above).
+**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?"
@@ -48,6 +50,33 @@ If config file is missing:
 3. Read **full content** of each changed file (not just the diff — full context)
 4. **Load spec context** (if available): Check for `.claude/afc/specs/{feature}/context.md` and `.claude/afc/specs/{feature}/spec.md`. If found, load them for SPEC_ALIGNMENT validation in the Critic Loop. If neither exists, SPEC_ALIGNMENT criterion is skipped with note "no spec artifacts available"
 
+### 1.5. Reverse Impact Analysis
+
+Before reviewing, identify **files affected by the changes** (not just the changed files themselves):
+
+1. **For each changed file**, find files that depend on it:
+   - **LSP (preferred)**: `LSP(findReferences)` on exported symbols — tracks type references, function calls, re-exports
+   - **Grep (fallback)**: `Grep` for `import.*{filename}`, `require.*{filename}`, `source.*{filename}` patterns across the codebase
+   - LSP and Grep are complementary — use both when LSP is available (LSP catches type-level references Grep misses; Grep catches dynamic patterns LSP misses)
+
+2. **Build impact map**:
+   ```
+   Impact Map:
+   ├─ src/auth/login.ts (changed)
+   │  └─ affected: src/pages/LoginPage.tsx, src/middleware/auth.ts
+   ├─ scripts/afc-state.sh (changed)
+   │  └─ affected: scripts/afc-stop-gate.sh, scripts/afc-drift.sh (grep: source.*afc-state)
+   └─ Total: {N} changed files → {M} affected files
+   ```
+
+3. **Scope decision**:
+   - Affected files are NOT full review targets (that would explode scope)
+   - Instead, include them as **cross-reference context** in Step 2 and Step 3.5
+   - If an affected file has >3 references to a changed symbol → flag for closer inspection
+
+4. **Limitations** (include in review output):
+   > ⚠ Dynamic dependencies not covered: runtime dispatch (`obj[method]()`), reflection, cross-language calls, config/env-driven branching. Manual verification recommended for these patterns.
+
 ### 2. Parallel Review (scaled by file count)
 
 Choose review orchestration based on the number of changed files:
@@ -58,7 +87,8 @@ Before distributing files to review agents, collect cross-boundary context:
 
 1. For each changed file, identify **outbound calls** to other changed files (imports + function calls)
 2. For each outbound call target, extract: function signature + 1-line side-effect summary (e.g., "mutates playlist state", "triggers async cascade")
-3. Include this context in each review agent's prompt:
+3. Include the **Impact Map** from Step 1.5 — each agent receives the list of affected (non-changed) files that depend on its assigned files
+4. Include this context in each review agent's prompt:
    ```
    ## Cross-File Context
    This file calls:
@@ -176,6 +206,8 @@ After individual/parallel reviews complete, the **orchestrator** MUST perform a
 
 **For 11+ file reviews**: This is especially critical because individual review agents cannot see cross-file interactions. The orchestrator MUST read callee implementations directly.
 
+0. **Impact Map integration**: Use the Impact Map from Step 1.5 to prioritize verification. Affected files with >3 references to changed symbols should be read and checked for breakage — even if no finding was raised against them.
+
 1. **Filter**: From all collected findings, select those involving:
    - Call order changes (function A now calls B before C)
    - Error handling modifications (try/catch scope changes, error propagation changes)
@@ -212,6 +244,13 @@ This step runs in the orchestrator context (not delegated), as it requires readi
 | Warning | {N} | {summary} |
 | Info | {N} | {summary} |
 
+### Impact Analysis
+| Changed File | Affected Files | Method |
+|---|---|---|
+| {path} | {affected file list} | LSP / Grep |
+
+> ⚠ Dynamic dependencies (runtime dispatch, reflection, cross-language calls) require manual verification.
+
 ### Detailed Findings
 
 #### C-{N}: {title}

package/commands/security.md

@@ -26,12 +26,10 @@ model: sonnet
 
 ## Config Load
 
-**Always** read `.claude/afc.config.md` first. This file contains free-form markdown sections:
-- `## Project Context` — framework, state management, testing, etc. (primary source for framework info)
-- `## Architecture` — architecture pattern, layers, import rules
-- `## Code Style` — language, naming conventions, lint rules
+Architecture, Code Style, and Project Context are auto-loaded via `.claude/rules/afc-project.md`.
+Read `.claude/afc.config.md` if CI commands are needed.
 
-If config file is missing: read `CLAUDE.md` for framework info. Assume "unknown" if neither source has it.
+If neither rules file nor config exists: read `CLAUDE.md` for framework info. Assume "unknown" if no source has it.
 
 For dependency audit command: infer from `packageManager` field in `package.json` or the lockfile (e.g., `npm audit`, `yarn audit`, `pnpm audit`).
 

package/commands/spec.md

@@ -99,8 +99,19 @@ Create `.claude/afc/specs/{feature-name}/spec.md`:
 - [ ] Given {precondition}, When {action}, Then {result}
 
 #### System Requirements (EARS notation)
-- [ ] WHEN {trigger}, THE System SHALL {behavior}
-- [ ] WHILE {state}, THE System SHALL {behavior}
+
+> 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}
@@ -172,6 +183,7 @@ Run the critic loop until convergence. Safety cap: 5 passes.
 | **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. |
 
 **On FAIL**: auto-fix and continue to next pass.
 **On ESCALATE**: pause, present options to user, apply choice, resume.

package/hooks/hooks.json

@@ -45,6 +45,16 @@
             "statusMessage": "Checking spec immutability..."
           }
         ]
+      },
+      {
+        "matcher": "Edit|MultiEdit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/afc-tdd-guard.sh\"",
+            "statusMessage": "Checking TDD compliance..."
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-for-claudecode",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "Claude Code plugin that automates the full dev cycle — spec, plan, implement, review, clean.",
   "bin": {
     "all-for-claudecode": "bin/cli.mjs"

package/scripts/afc-doctor.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 # afc-doctor.sh — Automated health check for all-for-claudecode plugin
-# Runs categories 1-9 deterministically. Categories 10-12 require LLM analysis.
+# Runs ALL categories deterministically. No LLM judgment required.
 # Output: human-readable text (no JSON), directly printable.
 # Read-only: never modifies files.
 
@@ -122,6 +122,18 @@ else
   fail ".claude/afc.config.md not found" "run /afc:init"
 fi
 
+# Project rules file
+RULES_FILE="$PROJECT_DIR/.claude/rules/afc-project.md"
+if [ -f "$RULES_FILE" ]; then
+  if grep -q '<!-- afc:auto-generated' "$RULES_FILE" 2>/dev/null; then
+    pass "Project rules file exists (auto-generated)"
+  else
+    pass "Project rules file exists (user-managed)"
+  fi
+else
+  warn "No .claude/rules/afc-project.md — project rules not auto-loaded" "run /afc:init to generate"
+fi
+
 # --- Category 3: CLAUDE.md Integration ---
 section "CLAUDE.md Integration"
 
@@ -459,6 +471,224 @@ if [ "$IS_DEV" = true ]; then
   else
     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)"
+
+  CMD_DIR="$PROJECT_DIR/commands"
+  if [ -d "$CMD_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
+      [ -f "$cmd_file" ] || continue
+      CMD_COUNT=$((CMD_COUNT + 1))
+      BASENAME=$(basename "$cmd_file" .md)
+
+      # Check frontmatter exists (--- ... ---)
+      if ! head -1 "$cmd_file" | grep -q '^---' 2>/dev/null; then
+        CMD_FM_MISSING="${CMD_FM_MISSING:+$CMD_FM_MISSING, }$BASENAME"
+        continue
+      fi
+
+      # Extract frontmatter (between first and second ---)
+      FM=$(sed -n '2,/^---$/p' "$cmd_file" 2>/dev/null | sed '$d')
+
+      # Check required fields: name and description
+      if ! printf '%s\n' "$FM" | grep -q '^name:' 2>/dev/null || ! printf '%s\n' "$FM" | grep -q '^description:' 2>/dev/null; then
+        CMD_FIELD_MISSING="${CMD_FIELD_MISSING:+$CMD_FIELD_MISSING, }$BASENAME"
+      fi
+
+      # Check name-filename match (afc:{basename})
+      FM_NAME=$(printf '%s\n' "$FM" | grep '^name:' | head -1 | sed 's/name:[[:space:]]*//' | tr -d '"' | tr -d "'" | tr -d ' ')
+      EXPECTED_NAME="afc:$BASENAME"
+      if [ -n "$FM_NAME" ] && [ "$FM_NAME" != "$EXPECTED_NAME" ]; then
+        CMD_NAME_MISMATCH="${CMD_NAME_MISMATCH:+$CMD_NAME_MISMATCH, }$BASENAME (got $FM_NAME)"
+      fi
+
+      # Check fork-agent reference
+      if printf '%s\n' "$FM" | grep -q 'context:.*fork' 2>/dev/null; then
+        AGENT_NAME=$(printf '%s\n' "$FM" | grep '^agent:' | head -1 | sed 's/agent:[[:space:]]*//' | tr -d '"' | tr -d "'" | tr -d ' ' || true)
+        if [ -n "$AGENT_NAME" ] && [ ! -f "$PROJECT_DIR/agents/$AGENT_NAME.md" ]; then
+          CMD_AGENT_MISSING="${CMD_AGENT_MISSING:+$CMD_AGENT_MISSING, }$BASENAME → $AGENT_NAME"
+        fi
+      fi
+    done
+
+    if [ -z "$CMD_FM_MISSING" ]; then
+      pass "Frontmatter exists ($CMD_COUNT files)"
+    else
+      fail "Missing frontmatter: $CMD_FM_MISSING" "add YAML frontmatter block"
+    fi
+
+    if [ -z "$CMD_FIELD_MISSING" ]; then
+      pass "Required fields present"
+    else
+      fail "Missing name/description: $CMD_FIELD_MISSING" "add missing fields"
+    fi
+
+    if [ -z "$CMD_NAME_MISMATCH" ]; then
+      pass "Name-filename match"
+    else
+      fail "Name mismatch: $CMD_NAME_MISMATCH" "rename name: field to afc:{filename}"
+    fi
+
+    if [ -z "$CMD_AGENT_MISSING" ]; then
+      pass "Fork-agent references valid"
+    else
+      fail "Missing agent: $CMD_AGENT_MISSING" "create missing agent file or fix agent: field"
+    fi
+  fi
+
+  # --- Category 11: Agent Definitions (dev only) ---
+  section "Agent Definitions (dev)"
+
+  AGENT_DIR="$PROJECT_DIR/agents"
+  if [ -d "$AGENT_DIR" ]; then
+    AGENT_COUNT=0
+    AGENT_FM_MISSING=""
+    AGENT_FIELD_MISSING=""
+    AGENT_NAME_MISMATCH=""
+    EXPERT_MEMORY_MISSING=""
+    WORKER_TURNS_MISSING=""
+
+    EXPERT_AGENTS="afc-backend-expert afc-infra-expert afc-pm-expert afc-design-expert afc-marketing-expert afc-legal-expert afc-appsec-expert afc-tech-advisor"
+    WORKER_AGENTS="afc-impl-worker afc-pr-analyst"
+
+    for agent_file in "$AGENT_DIR"/*.md; do
+      [ -f "$agent_file" ] || continue
+      AGENT_COUNT=$((AGENT_COUNT + 1))
+      BASENAME=$(basename "$agent_file" .md)
+
+      # Check frontmatter exists
+      if ! head -1 "$agent_file" | grep -q '^---' 2>/dev/null; then
+        AGENT_FM_MISSING="${AGENT_FM_MISSING:+$AGENT_FM_MISSING, }$BASENAME"
+        continue
+      fi
+
+      FM=$(sed -n '2,/^---$/p' "$agent_file" 2>/dev/null | sed '$d')
+
+      # Check required fields: name, description, model
+      if ! printf '%s\n' "$FM" | grep -q '^name:' 2>/dev/null || ! printf '%s\n' "$FM" | grep -q '^description:' 2>/dev/null || ! printf '%s\n' "$FM" | grep -q '^model:' 2>/dev/null; then
+        AGENT_FIELD_MISSING="${AGENT_FIELD_MISSING:+$AGENT_FIELD_MISSING, }$BASENAME"
+      fi
+
+      # Check name-filename match
+      FM_NAME=$(printf '%s\n' "$FM" | grep '^name:' | head -1 | sed 's/name:[[:space:]]*//' | tr -d '"' | tr -d "'" | tr -d ' ')
+      if [ -n "$FM_NAME" ] && [ "$FM_NAME" != "$BASENAME" ]; then
+        AGENT_NAME_MISMATCH="${AGENT_NAME_MISMATCH:+$AGENT_NAME_MISMATCH, }$BASENAME (got $FM_NAME)"
+      fi
+
+      # Expert memory check
+      for expert in $EXPERT_AGENTS; do
+        if [ "$BASENAME" = "$expert" ]; then
+          if ! printf '%s\n' "$FM" | grep -q '^memory:' 2>/dev/null; then
+            EXPERT_MEMORY_MISSING="${EXPERT_MEMORY_MISSING:+$EXPERT_MEMORY_MISSING, }$BASENAME"
+          fi
+        fi
+      done
+
+      # Worker maxTurns check
+      for worker in $WORKER_AGENTS; do
+        if [ "$BASENAME" = "$worker" ]; then
+          if ! printf '%s\n' "$FM" | grep -q '^maxTurns:' 2>/dev/null; then
+            WORKER_TURNS_MISSING="${WORKER_TURNS_MISSING:+$WORKER_TURNS_MISSING, }$BASENAME"
+          fi
+        fi
+      done
+    done
+
+    if [ -z "$AGENT_FM_MISSING" ]; then
+      pass "Frontmatter exists ($AGENT_COUNT files)"
+    else
+      fail "Missing frontmatter: $AGENT_FM_MISSING" "add YAML frontmatter block"
+    fi
+
+    if [ -z "$AGENT_FIELD_MISSING" ]; then
+      pass "Required fields present"
+    else
+      fail "Missing name/description/model: $AGENT_FIELD_MISSING" "add missing fields"
+    fi
+
+    if [ -z "$AGENT_NAME_MISMATCH" ]; then
+      pass "Name-filename match"
+    else
+      fail "Name mismatch: $AGENT_NAME_MISMATCH" "rename name: field to match filename"
+    fi
+
+    # Count experts found
+    EXPERT_TOTAL=0
+    EXPERT_WITH_MEM=0
+    for expert in $EXPERT_AGENTS; do
+      if [ -f "$AGENT_DIR/$expert.md" ]; then
+        EXPERT_TOTAL=$((EXPERT_TOTAL + 1))
+        FM=$(sed -n '2,/^---$/p' "$AGENT_DIR/$expert.md" 2>/dev/null | sed '$d')
+        if printf '%s\n' "$FM" | grep -q '^memory:' 2>/dev/null; then
+          EXPERT_WITH_MEM=$((EXPERT_WITH_MEM + 1))
+        fi
+      fi
+    done
+    if [ -z "$EXPERT_MEMORY_MISSING" ]; then
+      pass "Expert memory configured ($EXPERT_WITH_MEM/$EXPERT_TOTAL)"
+    else
+      fail "Missing memory: field: $EXPERT_MEMORY_MISSING" "add memory: project to agent frontmatter"
+    fi
+
+    WORKER_TOTAL=0
+    WORKER_WITH_TURNS=0
+    for worker in $WORKER_AGENTS; do
+      if [ -f "$AGENT_DIR/$worker.md" ]; then
+        WORKER_TOTAL=$((WORKER_TOTAL + 1))
+        FM=$(sed -n '2,/^---$/p' "$AGENT_DIR/$worker.md" 2>/dev/null | sed '$d')
+        if printf '%s\n' "$FM" | grep -q '^maxTurns:' 2>/dev/null; then
+          WORKER_WITH_TURNS=$((WORKER_WITH_TURNS + 1))
+        fi
+      fi
+    done
+    if [ -z "$WORKER_TURNS_MISSING" ]; then
+      pass "Worker maxTurns configured ($WORKER_WITH_TURNS/$WORKER_TOTAL)"
+    else
+      fail "Missing maxTurns: $WORKER_TURNS_MISSING" "add maxTurns: to agent frontmatter"
+    fi
+  fi
+
+  # --- Category 12: Doc References (dev only) ---
+  section "Doc References (dev)"
+
+  # Scan commands and agents for docs/ references
+  DOC_REFS_MISSING=""
+  for src_file in "$CMD_DIR"/*.md "$AGENT_DIR"/*.md; do
+    [ -f "$src_file" ] || continue
+    while IFS= read -r ref; do
+      [ -z "$ref" ] && continue
+      DOC_PATH="$PROJECT_DIR/$ref"
+      if [ ! -f "$DOC_PATH" ]; then
+        DOC_REFS_MISSING="${DOC_REFS_MISSING:+$DOC_REFS_MISSING, }$ref (in $(basename "$src_file"))"
+      fi
+    done < <(grep -oE 'docs/[a-zA-Z0-9_/-]+\.md' "$src_file" 2>/dev/null | sort -u)
+  done
+
+  if [ -z "$DOC_REFS_MISSING" ]; then
+    pass "Referenced docs exist"
+  else
+    fail "Missing docs: $DOC_REFS_MISSING" "create missing doc files or fix references"
+  fi
+
+  # Domain adapters
+  ADAPTER_DIR="$PROJECT_DIR/docs/domain-adapters"
+  if [ -d "$ADAPTER_DIR" ]; then
+    ADAPTER_COUNT=$(find "$ADAPTER_DIR" -maxdepth 1 -name '*.md' -type f 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$ADAPTER_COUNT" -ge 1 ]; then
+      pass "Domain adapters exist ($ADAPTER_COUNT files)"
+    else
+      fail "No domain adapter files" "add .md files to docs/domain-adapters/"
+    fi
+  else
+    fail "docs/domain-adapters/ directory missing" "create docs/domain-adapters/ with at least one .md file"
+  fi
 fi
 
 # --- Summary ---
@@ -474,9 +704,5 @@ else
   printf '%d issues need attention. Run the Fix commands above.\n' "$FAIL"
 fi
 
-# Signal dev-only categories to caller
-if [ "$IS_DEV" = true ]; then
-  printf '\nNote: Categories 10-12 (Command/Agent/Doc validation) require LLM analysis.\n'
-fi
 
 exit 0

package/scripts/afc-subagent-context.sh

@@ -15,8 +15,6 @@ cleanup() {
 }
 trap cleanup EXIT
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
-
 # Consume stdin (required -- pipe breaks if not consumed)
 cat > /dev/null
 
@@ -34,31 +32,8 @@ PHASE=$(afc_state_read phase || echo "unknown")
 # 3. Build context string
 CONTEXT="[AFC PIPELINE] Feature: $FEATURE | Phase: $PHASE | [AFC] When this task matches an AFC skill (analyze, implement, review, debug, test, plan, spec, research, ideate), use the Skill tool to invoke it. Do not substitute with raw Task agents. When analyzing external systems, verify against official documentation."
 
-# 4. Extract config sections from afc.config.md
-CONFIG_FILE="$PROJECT_DIR/.claude/afc.config.md"
-
-if [ -f "$CONFIG_FILE" ]; then
-  # Extract Architecture section (## Architecture to next ##)
-  # shellcheck disable=SC2001
-  ARCH=$(sed -n '/^## Architecture/,/^## /p' "$CONFIG_FILE" 2>/dev/null | sed '1d;/^## /d;/^$/d' | head -15 | tr '\n' ' ' | sed 's/  */ /g;s/^ *//;s/ *$//')
-  if [ -n "$ARCH" ]; then
-    CONTEXT="$CONTEXT | Architecture: $ARCH"
-  fi
-
-  # Extract Code Style section (## Code Style to next ##)
-  # shellcheck disable=SC2001
-  STYLE=$(sed -n '/^## Code Style/,/^## /p' "$CONFIG_FILE" 2>/dev/null | sed '1d;/^## /d;/^$/d' | head -15 | tr '\n' ' ' | sed 's/  */ /g;s/^ *//;s/ *$//')
-  if [ -n "$STYLE" ]; then
-    CONTEXT="$CONTEXT | Code Style: $STYLE"
-  fi
-
-  # Extract Project Context section (## Project Context to next ## or EOF)
-  # shellcheck disable=SC2001
-  PROJ_CTX=$(sed -n '/^## Project Context/,/^## /p' "$CONFIG_FILE" 2>/dev/null | sed '1d;/^## /d;/^$/d' | head -15 | tr '\n' ' ' | sed 's/  */ /g;s/^ *//;s/ *$//')
-  if [ -n "$PROJ_CTX" ]; then
-    CONTEXT="$CONTEXT | Project Context: $PROJ_CTX"
-  fi
-fi
+# 4. Architecture/Code Style/Project Context are auto-loaded via .claude/rules/afc-project.md
+# No need to extract from afc.config.md — Claude Code loads rules files automatically
 
 # 5. Output as hookSpecificOutput JSON (required for SubagentStart context injection)
 if command -v jq &>/dev/null; then

package/scripts/afc-tdd-guard.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+set -euo pipefail
+# PreToolUse Hook: TDD Guard — blocks non-test file writes during implement phase
+# Only active when: pipeline active + phase=implement + tdd=strict (or warns on guide)
+# tdd setting read from afc.config.md CI Commands YAML
+
+# shellcheck source=afc-state.sh
+. "$(dirname "$0")/afc-state.sh"
+
+# shellcheck disable=SC2329
+cleanup() {
+  :
+}
+trap cleanup EXIT
+
+ALLOW='{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+
+# Consume stdin immediately (prevents SIGPIPE if exiting early)
+INPUT=$(cat)
+
+# If pipeline is inactive -> allow
+if ! afc_state_is_active; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+
+# Read current phase — only guard during implement
+PHASE="$(afc_state_read phase || echo '')"
+if [ "$PHASE" != "implement" ]; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+
+# Read tdd setting from afc.config.md (YAML in markdown — grep/sed parse)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+CONFIG_FILE="$PROJECT_DIR/.claude/afc.config.md"
+TDD_MODE="off"
+
+if [ -f "$CONFIG_FILE" ]; then
+  TDD_MODE=$(grep -E '^tdd:' "$CONFIG_FILE" | head -1 | sed 's/^tdd:[[:space:]]*"//;s/".*$//' 2>/dev/null || echo "off")
+fi
+
+# Normalize: empty or missing -> off
+TDD_MODE="${TDD_MODE:-off}"
+
+# If tdd is off -> allow immediately (0ms overhead goal)
+if [ "$TDD_MODE" = "off" ]; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+
+if [ -z "$INPUT" ]; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+
+# Extract file_path from tool_input
+FILE_PATH=""
+if command -v jq &> /dev/null; then
+  FILE_PATH=$(printf '%s\n' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+else
+  FILE_PATH=$(printf '%s\n' "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//;s/"$//' 2>/dev/null || true)
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+
+# Check if the file is a test file — always allow test file edits
+# Patterns: *.test.*, *.spec.*, *_test.*, *_spec.*, *_test.go, spec/*, __tests__/*, test/*, tests/*
+BASENAME=$(basename "$FILE_PATH")
+if printf '%s' "$BASENAME" | grep -qE '\.(test|spec)\.[^.]+$'; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+if printf '%s' "$BASENAME" | grep -qE '_(test|spec)\.[^.]+$'; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+if printf '%s' "$FILE_PATH" | grep -qE '(^|/)(spec|__tests__|tests?)/'; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+
+# Non-code files (markdown, json, yaml, config) — always allow
+if printf '%s' "$BASENAME" | grep -qE '\.(md|json|ya?ml|toml|txt|csv|lock|gitignore)$'; then
+  printf '%s\n' "$ALLOW"
+  exit 0
+fi
+
+# At this point: implement phase + tdd is strict or guide + file is not a test file + file is code
+# Sanitize BASENAME for JSON safety (remove double quotes and backslashes)
+SAFE_BASENAME=$(printf '%s' "$BASENAME" | tr -d '"\\')
+
+if [ "$TDD_MODE" = "strict" ]; then
+  printf '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"[afc:tdd-guard] TDD strict mode: write test file first before implementing. Target: %s"}}\n' "$SAFE_BASENAME"
+  exit 0
+fi
+
+if [ "$TDD_MODE" = "guide" ]; then
+  printf '{"hookSpecificOutput":{"permissionDecision":"allow","additionalContext":"[afc:tdd-guard] TDD guide: consider writing tests first for %s"}}\n' "$SAFE_BASENAME"
+  exit 0
+fi
+
+# Fallback: unknown tdd value -> allow
+printf '%s\n' "$ALLOW"
+exit 0

package/scripts/afc-user-prompt-submit.sh

@@ -41,13 +41,17 @@ if ! afc_state_is_active; then
   # Normalize: lowercase + truncate for matching
   LOWER=$(printf '%s' "$USER_TEXT" | tr '[:upper:]' '[:lower:]' | cut -c1-500)
 
+  # Compact skill catalog: injected when regex misses, so the model classifies semantically
+  FALLBACK_HINT="[afc] Route via Skill tool if applicable — debug(bug/에러/수정/fix) | review(코드검토/리뷰/PR) | test(테스트/coverage) | spec(요구사항/스펙) | plan(설계/계획) | implement(구현/리팩터) | auto(새기능/feature) | consult(조언/상의/discuss) | analyze(분석/trace) | research(조사/리서치) | security(보안/취약점) | architect(아키텍처/설계) | qa(품질감사) | launch(릴리스/배포) | triage(PR정리/이슈분류) | clean(정리/cleanup) | ideate(아이디어/brainstorm) | doctor(진단/health) | release-notes(변경이력)"
+
   # Early exit for empty prompts (context-only messages, malformed JSON)
   if [ -z "$LOWER" ]; then
     if command -v jq >/dev/null 2>&1; then
-      jq -n --arg c "[afc] If this request matches an afc skill, invoke it via Skill tool. See CLAUDE.md routing table." \
-        '{"hookSpecificOutput":{"additionalContext":$c}}'
+      jq -n --arg c "$FALLBACK_HINT" '{"hookSpecificOutput":{"additionalContext":$c}}'
     else
-      printf '{"hookSpecificOutput":{"additionalContext":"[afc] If this request matches an afc skill, invoke it via Skill tool. See CLAUDE.md routing table."}}\n'
+      SAFE_FALLBACK="${FALLBACK_HINT//\\/\\\\}"
+      SAFE_FALLBACK="${SAFE_FALLBACK//\"/\\\"}"
+      printf '{"hookSpecificOutput":{"additionalContext":"%s"}}\n' "$SAFE_FALLBACK"
     fi
     exit 0
   fi
@@ -55,43 +59,55 @@ if ! afc_state_is_active; then
   # Intent detection: priority-ordered if/elif chain.
   # Each pattern targets strong-signal phrases to minimize false positives.
   # The model retains final authority — this is a hint, not enforcement.
+  # Patterns include Korean (한국어) variants for natural language coverage.
   SKILL=""
   # High confidence: distinctive multi-word or rare keywords
-  if printf '%s' "$LOWER" | grep -qE '(bug|broken|debug|not working|crash|exception)' 2>/dev/null; then
+  if printf '%s' "$LOWER" | grep -qE '(bug|broken|debug|not working|crash|exception|에러|버그|오류|안.?됨|안.?돼|안.?되|고장)' 2>/dev/null; then
     SKILL="afc:debug"
-  elif printf '%s' "$LOWER" | grep -qE '(code review|pr review)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(code review|pr review|코드.?리뷰|pr.?리뷰|코드.?검토)' 2>/dev/null; then
     SKILL="afc:review"
-  elif printf '%s' "$LOWER" | grep -qE '(write test|add test|test coverage|improve coverage)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(write test|add test|test coverage|improve coverage|unit test|integration test|e2e test|테스트.?작성|테스트.?추가|커버리지)' 2>/dev/null; then
     SKILL="afc:test"
-  elif printf '%s' "$LOWER" | grep -qE '(security scan|security review|security audit|vulnerabilit)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(security scan|security review|security audit|vulnerabilit|보안.?검사|보안.?스캔|보안.?리뷰|취약점)' 2>/dev/null; then
     SKILL="afc:security"
-  elif printf '%s' "$LOWER" | grep -qE '(architecture|architect|system design)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(architecture|architect|system design|아키텍처|시스템.?설계|구조.?설계)' 2>/dev/null; then
     SKILL="afc:architect"
-  elif printf '%s' "$LOWER" | grep -qE '(doctor|health check|diagnose.*project)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(doctor|health check|diagnose.*project|진단|상태.?확인|헬스.?체크)' 2>/dev/null; then
     SKILL="afc:doctor"
-  elif printf '%s' "$LOWER" | grep -qE '(quality audit|qa audit|project quality)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(quality audit|qa audit|project quality|품질.?감사|품질.?점검|qa.?점검)' 2>/dev/null; then
     SKILL="afc:qa"
-  elif printf '%s' "$LOWER" | grep -qE '(new release|version bump|changelog|publish.*package)' 2>/dev/null; then
+  # NOTE: release-notes MUST come before launch — 릴리스.?노트 vs 릴리스 순서 의존
+  elif printf '%s' "$LOWER" | grep -qE '(release note|릴리스.?노트|변경.?이력|release.?note)' 2>/dev/null; then
+    SKILL="afc:release-notes"
+  elif printf '%s' "$LOWER" | grep -qE '(new release|version bump|changelog|publish.*package|릴리스|버전.?업|배포.?준비)' 2>/dev/null; then
     SKILL="afc:launch"
+  elif printf '%s' "$LOWER" | grep -qE '(triage|pr.?정리|이슈.?정리|백로그.?정리|pr.?분류|이슈.?분류)' 2>/dev/null; then
+    SKILL="afc:triage"
   # Medium confidence: still distinctive but broader
-  elif printf '%s' "$LOWER" | grep -qE '(specification|requirements|acceptance criteria)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(specification|requirements|acceptance criteria|요구.?사항|기능.?정의|인수.?조건)' 2>/dev/null; then
     SKILL="afc:spec"
-  elif printf '%s' "$LOWER" | grep -qE '(brainstorm|ideate|what to build|product brief)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(brainstorm|ideate|what to build|product brief|아이디어|브레인스토밍|뭘.*만들)' 2>/dev/null; then
     SKILL="afc:ideate"
-  elif printf '%s' "$LOWER" | grep -qE '(expert advice)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(expert advice|discuss|advice|think together|같이.*생각|함께.*생각|상의|조언|의견.*구|자문|상담)' 2>/dev/null; then
     SKILL="afc:consult"
-  elif printf '%s' "$LOWER" | grep -qE '(analyz|trace.*flow|how does.*work)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(analyz|trace.*flow|how does.*work|분석|추적|어떻게.*동작|흐름.*파악)' 2>/dev/null; then
     SKILL="afc:analyze"
-  elif printf '%s' "$LOWER" | grep -qE '(research|investigat|compare.*lib)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(research|investigat|compare.*lib|조사|리서치|비교.*라이브러리|탐색)' 2>/dev/null; then
     SKILL="afc:research"
-  # Lower confidence: common verbs
-  elif printf '%s' "$LOWER" | grep -qE '(implement|add feature|refactor|modify.*code)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(clean.*up|cleanup|아티팩트.?정리|파이프라인.?정리|산출물.?정리)' 2>/dev/null; then
+    SKILL="afc:clean"
+  # Lower confidence: common verbs — auto for non-trivial feature scopes
+  elif printf '%s' "$LOWER" | grep -qE '(새.*기능|신규.*기능|기능.*개발|기능.*만들|feature.*develop|build.*feature|develop.*feature|create.*feature)' 2>/dev/null; then
+    SKILL="afc:auto"
+  elif printf '%s' "$LOWER" | grep -qE '(implement|add feature|refactor|modify.*code|리팩터|리팩토링|코드.?수정)' 2>/dev/null; then
     SKILL="afc:implement"
-  elif printf '%s' "$LOWER" | grep -qE '(review)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(fix|error|issue|problem|failing|수정|고쳐|문제)' 2>/dev/null; then
+    SKILL="afc:debug"
+  elif printf '%s' "$LOWER" | grep -qE '(review|검토|리뷰)' 2>/dev/null; then
     SKILL="afc:review"
-  elif printf '%s' "$LOWER" | grep -qE '(spec[^a-z]|spec$)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(spec[^a-z]|spec$|스펙)' 2>/dev/null; then
     SKILL="afc:spec"
-  elif printf '%s' "$LOWER" | grep -qE '(plan[^a-z]|plan$)' 2>/dev/null; then
+  elif printf '%s' "$LOWER" | grep -qE '(plan[^a-z]|plan$|계획|설계)' 2>/dev/null; then
     SKILL="afc:plan"
   fi
 
@@ -99,13 +115,15 @@ if ! afc_state_is_active; then
   if [ -n "$SKILL" ]; then
     HINT="[afc:route -> ${SKILL}] Detected intent from user prompt. Invoke /${SKILL} via Skill tool."
   else
-    HINT="[afc] If this request matches an afc skill, invoke it via Skill tool. See CLAUDE.md routing table."
+    HINT="$FALLBACK_HINT"
   fi
 
   if command -v jq >/dev/null 2>&1; then
     jq -n --arg c "$HINT" '{"hookSpecificOutput":{"additionalContext":$c}}'
   else
-    printf '{"hookSpecificOutput":{"additionalContext":"%s"}}\n' "$HINT"
+    SAFE_HINT="${HINT//\\/\\\\}"
+    SAFE_HINT="${SAFE_HINT//\"/\\\"}"
+    printf '{"hookSpecificOutput":{"additionalContext":"%s"}}\n' "$SAFE_HINT"
   fi
   exit 0
 fi

package/templates/afc-project.template.md

@@ -0,0 +1,27 @@
+<!-- afc:auto-generated — do not edit manually; regenerate with /afc:init -->
+# Project Rules
+
+> Auto-generated by /afc:init. Claude Code loads this file automatically for all conversations.
+> For CI/gate/test commands, see .claude/afc.config.md.
+
+## Architecture
+
+- **Pattern**: (e.g., FSD, Clean Architecture, Layered, Modular, Flat)
+- **Key layers**: (e.g., app, pages, widgets, features, entities, shared)
+- **Import rule**: (e.g., upper layers may import lower only, no cross-feature imports)
+- **Path alias**: (e.g., @/ → src/)
+
+## Code Style
+
+- **Language**: (e.g., TypeScript strict, JavaScript ESM, Python 3.12)
+- **Naming**: (e.g., PascalCase components, camelCase functions, UPPER_SNAKE constants)
+- **Lint**: (e.g., ESLint flat config + Prettier, Biome)
+- **Key rules**: (e.g., import type separated, no any, prefer const)
+
+## Project Context
+
+- **Framework**: (e.g., Next.js 14 App Router, FastAPI, Express)
+- **State**: (e.g., Zustand + TanStack Query, Redux Toolkit, Pinia)
+- **Styling**: (e.g., Tailwind CSS, styled-components, CSS Modules)
+- **Testing**: (e.g., Vitest + Playwright, Jest + Cypress)
+- **DB/ORM**: (e.g., PostgreSQL + Prisma, MongoDB + Mongoose)

package/templates/afc.config.template.md

@@ -1,8 +1,8 @@
 # Project Configuration
 
-> afc commands reference this file to determine project-specific behavior.
-> CI Commands are parsed by scripts — keep the YAML format intact.
-> All other sections are free-form markdown — write whatever best describes your project.
+> CI Commands are parsed by hook scripts — keep the YAML format intact.
+> Architecture, Code Style, and Project Context sections below are detailed references.
+> A concise summary is also generated in `.claude/rules/afc-project.md` (auto-loaded by Claude Code).
 
 ## CI Commands
 
@@ -11,6 +11,7 @@
 ci: "npm run ci"
 gate: "npm run typecheck && npm run lint"
 test: "npm test"
+tdd: "off"                                # TDD mode: "strict" (block impl without tests), "guide" (warn only), "off" (disabled)
 ```
 
 ## Architecture