all-for-claudecode 2.8.1 → 2.8.2

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.8.2"
   },
   "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.8.2",
       "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.8.2",
   "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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-for-claudecode",
-  "version": "2.8.1",
+  "version": "2.8.2",
   "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.
 
@@ -459,6 +459,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 +692,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