all-for-claudecode 2.5.0 → 2.7.0

package/commands/qa.md

@@ -0,0 +1,191 @@
+---
+name: afc:qa
+description: "Project quality audit — use when the user asks for a quality audit, QA check, test confidence assessment, or wants to detect gaps in error handling and code health"
+argument-hint: "[scope: all, tests, errors, coverage, or specific concern]"
+user-invocable: true
+context: fork
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+model: sonnet
+---
+
+# /afc:qa — Project Quality Audit
+
+> Detects quality gaps between structural correctness and actual runtime behavior.
+> **Read-only** — does not modify any files. Reports findings to console only.
+
+## Arguments
+
+- `$ARGUMENTS` — (optional) scope of audit. Defaults to `all`.
+  - `all` — run all 5 categories
+  - `tests` — category A only (Test Confidence)
+  - `errors` — category B only (Error Resilience)
+  - `coverage` — categories A + D (Test Confidence + API & Contract Safety)
+  - Or a free-form concern (e.g., "are error messages user-friendly", "check for dead exports")
+
+## 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
+
+If config file is missing: read `CLAUDE.md` for project info. Proceed without config if neither exists.
+
+## Audit Categories
+
+### A. Test Confidence
+
+Evaluate whether the test suite actually catches regressions.
+
+Checks:
+- **Assertion density**: ratio of assertions to test functions (low ratio = weak tests)
+- **Test-to-code ratio**: test LOC vs source LOC per layer (guided by `{config.architecture}`)
+- **Mock overuse**: tests that mock so much they only test the mock setup
+- **Runtime verification**: execute `{config.test}` and analyze output (pass/fail counts, skipped tests, timing)
+- **Missing coverage**: source files/modules with zero test coverage
+
+### B. Error Resilience
+
+Evaluate whether errors are handled consistently and helpfully.
+
+Checks:
+- **Catch consistency**: unhandled promise rejections, empty catch blocks, swallowed errors
+- **Error propagation**: errors that lose context through the call chain
+- **User-facing messages**: cryptic error strings, raw stack traces exposed to users
+- **Boundary validation**: missing input validation at API/CLI/form boundaries
+- Apply `{config.code_style}` error handling rules if available
+
+### C. Build & CI Integrity
+
+Evaluate whether CI pipeline is healthy and reproducible.
+
+Checks:
+- **CI execution**: run `{config.ci}` and `{config.gate}` commands, verify they pass
+- **Lock file integrity**: lock file present, consistent with manifest (package.json vs lock, etc.)
+- **Unused dependencies**: declared but never imported packages
+- **Build reproducibility**: environment-dependent paths, hardcoded secrets, missing env vars
+
+### D. API & Contract Safety
+
+Evaluate whether interfaces between modules are sound.
+
+Checks:
+- **Type mismatches**: function signatures vs actual usage at call sites
+- **Dead exports**: exported symbols never imported elsewhere
+- **Deprecated usage**: calls to deprecated APIs (internal or external)
+- **Layer boundary violations**: imports that cross architecture boundaries (guided by `{config.architecture}`)
+
+### E. Code Health Signals
+
+Evaluate general code quality indicators.
+
+Checks:
+- **Complexity hotspots**: deeply nested logic, functions exceeding ~50 LOC
+- **Duplication**: near-identical code blocks across files
+- **Magic numbers/strings**: unexplained literals in logic
+- **TODO/FIXME accumulation**: stale markers (count, age if git history available)
+- Compare against `{config.code_style}` rules if available
+
+## Execution Steps
+
+### 1. Load Config
+
+Read `.claude/afc.config.md` (or fallback to `CLAUDE.md`). Extract:
+- Test command (`{config.test}`)
+- CI/gate commands (`{config.ci}`, `{config.gate}`)
+- Architecture layers (`{config.architecture}`)
+- Code style rules (`{config.code_style}`)
+
+### 2. Parse Scope
+
+Interpret `$ARGUMENTS` to determine which categories to run:
+
+| Argument | Categories |
+|----------|-----------|
+| `all` or empty | A, B, C, D, E |
+| `tests` | A |
+| `errors` | B |
+| `coverage` | A, D |
+| free-form text | best-matching subset |
+
+### 3. Lightweight Runtime
+
+Run commands that produce real output:
+- `{config.test}` — capture pass/fail/skip counts and timing
+- `{config.gate}` or `{config.ci}` — capture exit code and output
+
+Only run commands that exist in config. Skip gracefully if not configured.
+
+### 4. Codebase Scan
+
+For each active category:
+1. Use Glob to discover relevant files
+2. Use Grep for pattern-based detection (empty catches, TODO markers, etc.)
+3. Use Read for targeted inspection of flagged files
+4. Cross-reference findings against `{config.architecture}` layer structure
+
+### 5. Critic Loop
+
+Apply `docs/critic-loop-rules.md` with **safety cap: 3 rounds**.
+
+Focus the critic on:
+- Are the findings actionable or just noise?
+- Did I miss obvious quality gaps?
+- Are severity ratings justified by evidence?
+
+### 6. Console Report
+
+Output the final report in this format:
+
+```markdown
+## QA Audit: {project name or directory}
+
+### Category A: Test Confidence
+{findings with file:line references}
+Verdict: PASS | WARN | FAIL
+
+### Category B: Error Resilience
+{findings with file:line references}
+Verdict: PASS | WARN | FAIL
+
+### Category C: Build & CI Integrity
+{findings with file:line references}
+Verdict: PASS | WARN | FAIL
+
+### Category D: API & Contract Safety
+{findings with file:line references}
+Verdict: PASS | WARN | FAIL
+
+### Category E: Code Health Signals
+{findings with file:line references}
+Verdict: PASS | WARN | FAIL
+
+### Summary
+├─ A: Test Confidence    — {PASS|WARN|FAIL} {(N issues) if any}
+├─ B: Error Resilience   — {PASS|WARN|FAIL} {(N issues) if any}
+├─ C: Build & CI         — {PASS|WARN|FAIL} {(N issues) if any}
+├─ D: API & Contract     — {PASS|WARN|FAIL} {(N issues) if any}
+└─ E: Code Health        — {PASS|WARN|FAIL} {(N issues) if any}
+
+Total: {N} PASS, {N} WARN, {N} FAIL
+Priority fixes: {top 3 most impactful issues}
+```
+
+## Verdict Criteria
+
+- **PASS** — no issues found, or only cosmetic observations
+- **WARN** — issues found but not blocking; quality could degrade over time
+- **FAIL** — critical gaps that likely cause bugs, outages, or security issues
+
+## Notes
+
+- **Read-only**: Do not modify any files. Report only.
+- **Evidence-based**: Every finding must include a `file:line` reference or command output.
+- **Config-aware**: Adapt checks to the project's declared architecture and conventions.
+- **Scope discipline**: Only run categories matching the requested scope.
+- **Not a linter**: Focus on semantic quality gaps that automated tools miss.

package/commands/release-notes.md

@@ -1,6 +1,6 @@
 ---
 name: afc:release-notes
-description: "Generate user-facing release notes from git history"
+description: "Generate user-facing release notes from git history — use when the user asks to write release notes, summarize changes between versions, or generate a changelog"
 argument-hint: "[v1.0.0..v2.0.0 | v2.0.0 | --post]"
 allowed-tools:
   - Read

package/commands/research.md

@@ -1,6 +1,6 @@
 ---
 name: afc:research
-description: "Technical research"
+description: "Technical research — use when the user asks to research a topic, investigate a technology, compare libraries, or explore options before deciding"
 argument-hint: "[research topic]"
 allowed-tools:
   - Read

package/commands/resume.md

@@ -1,6 +1,6 @@
 ---
 name: afc:resume
-description: "Restore session"
+description: "Restore session — use when the user asks to resume a previous session, restore saved state, or continue where they left off"
 argument-hint: "[no arguments]"
 model: haiku
 allowed-tools:
@@ -22,7 +22,7 @@ allowed-tools:
 ### 1. Load Checkpoint
 
 Read `.claude/afc/memory/checkpoint.md`:
-- If not found: check **auto-memory fallback** — read `~/.claude/projects/{ENCODED_PATH}/auto-memory/checkpoint.md` (where `ENCODED_PATH` = project path with `/` replaced by `-`):
+- If not found: check **auto-memory fallback** — read `~/.claude/projects/{ENCODED_PATH}/memory/checkpoint.md` (where `ENCODED_PATH` = project path with `/` replaced by `-`):
   - If fallback found: use it as the checkpoint source (auto-memory is written by `pre-compact-checkpoint.sh` during context compaction)
   - If fallback also not found: output "No saved checkpoint found. Use `/afc:checkpoint` to create one, or checkpoints are created automatically on context compaction." then **stop**
 - If found: parse the full contents (extract branch, commit hash, pipeline feature, task progress, modified files)

package/commands/review.md

@@ -1,6 +1,6 @@
 ---
 name: afc:review
-description: "Code review"
+description: "Code review — use when the user asks to review code, analyze a PR diff, do a code review, or evaluate code quality and correctness"
 argument-hint: "[scope: file path, PR number, or staged]"
 allowed-tools:
   - Read

package/commands/security.md

@@ -1,6 +1,6 @@
 ---
 name: afc:security
-description: "Security scan (read-only)"
+description: "Security scan (read-only) — use when the user asks for a security scan, security review, vulnerability check, or threat assessment"
 argument-hint: "[scan scope: file/directory path or full]"
 context: fork
 agent: afc-security

package/commands/spec.md

@@ -1,6 +1,6 @@
 ---
 name: afc:spec
-description: "Generate feature specification"
+description: "Generate feature specification — use when the user asks to write a spec, define requirements, create acceptance criteria, or specify a feature"
 argument-hint: "[feature description in natural language]"
 allowed-tools:
   - Read

package/commands/tasks.md

@@ -1,6 +1,6 @@
 ---
 name: afc:tasks
-description: "Task decomposition"
+description: "Task decomposition — auto-invoked during implement phase to break down plan into executable tasks with dependency tracking"
 argument-hint: "[constraints/priority directives]"
 user-invocable: false
 allowed-tools:

package/commands/test.md

@@ -1,6 +1,6 @@
 ---
 name: afc:test
-description: "Test strategy planning and test writing"
+description: "Test strategy planning and test writing — use when the user asks to write tests, add test coverage, improve coverage, create unit/integration/e2e tests, or plan a testing strategy"
 argument-hint: "[target: file path, feature name, or coverage]"
 allowed-tools:
   - Read

package/commands/triage.md

@@ -1,6 +1,6 @@
 ---
 name: afc:triage
-description: "Parallel triage of open PRs and issues"
+description: "Parallel triage of open PRs and issues — use when the user asks to triage PRs, review open issues, or prioritize the backlog of pull requests and issues"
 argument-hint: "[scope: --pr, --issue, --all (default), or specific numbers]"
 allowed-tools:
   - Read

package/commands/validate.md

@@ -1,6 +1,6 @@
 ---
 name: afc:validate
-description: "Artifact consistency validation (read-only)"
+description: "Artifact consistency validation (read-only) — auto-invoked to verify spec, plan, and task artifacts are consistent with each other"
 argument-hint: "[validation scope: spec-plan, tasks-only]"
 user-invocable: false
 context: fork

package/docs/phase-gate-protocol.md

@@ -34,7 +34,7 @@ Quantitatively inspect changed files within the Phase against `{config.code_styl
 After passing the Phase gate, automatically save session state:
 
 1. Create `.claude/afc/memory/` directory if it does not exist
-2. Write/update `.claude/afc/memory/checkpoint.md` **and** `~/.claude/projects/{ENCODED_PATH}/auto-memory/checkpoint.md` (dual-write for compaction resilience — `ENCODED_PATH` = project path with `/` replaced by `-`):
+2. Write/update `.claude/afc/memory/checkpoint.md` **and** `~/.claude/projects/{ENCODED_PATH}/memory/checkpoint.md` (dual-write for compaction resilience — `ENCODED_PATH` = project path with `/` replaced by `-`):
 
 ```markdown
 # Phase Gate Checkpoint

package/hooks/hooks.json

@@ -1,4 +1,5 @@
 {
+  "description": "Event hooks for the all-for-claudecode pipeline — CI gates, safety guards, context injection, and workflow automation",
   "hooks": {
     "SessionStart": [
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-for-claudecode",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Claude Code plugin that automates the full dev cycle — spec, plan, implement, review, clean.",
   "bin": {
     "all-for-claudecode": "bin/cli.mjs"
@@ -35,9 +35,11 @@
   },
   "scripts": {
     "lint": "shellcheck -x --source-path=scripts --severity=warning scripts/*.sh && bash scripts/afc-schema-validate.sh --all && bash scripts/afc-consistency-check.sh",
+    "qa": "bash scripts/afc-qa-audit.sh",
     "test": "vendor/shellspec/shellspec",
-    "test:all": "npm run lint && npm run test",
-    "setup:test": "bash scripts/install-shellspec.sh"
+    "test:all": "npm run lint && npm run qa && npm run test",
+    "setup:test": "bash scripts/install-shellspec.sh",
+    "sync:cache": "bash scripts/afc-sync-cache.sh"
   },
   "engines": {
     "node": ">=18"

package/schemas/hooks.schema.json

@@ -6,6 +6,10 @@
   "required": ["hooks"],
   "additionalProperties": false,
   "properties": {
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the hook configuration"
+    },
     "hooks": {
       "type": "object",
       "patternProperties": {

package/schemas/plugin.schema.json

@@ -45,9 +45,13 @@
       "type": "string",
       "description": "Path to commands directory"
     },
+    "agents": {
+      "type": "string",
+      "description": "Path to agents directory"
+    },
     "hooks": {
       "type": "string",
-      "description": "Path to hooks directory"
+      "description": "Path to hooks configuration file"
     }
   }
 }

package/scripts/afc-bash-guard.sh

@@ -14,15 +14,15 @@ cleanup() {
 }
 trap cleanup EXIT
 
+# Consume stdin immediately (prevents SIGPIPE if exiting early)
+INPUT=$(cat)
+
 # If pipeline is inactive -> allow
 if ! afc_state_is_active; then
   printf '{"hookSpecificOutput":{"permissionDecision":"allow"}}\n'
   exit 0
 fi
 
-# Parse tool input from stdin
-INPUT=$(cat)
-
 # If stdin is empty -> allow
 if [ -z "$INPUT" ]; then
   printf '{"hookSpecificOutput":{"permissionDecision":"allow"}}\n'

package/scripts/afc-config-change.sh

@@ -48,6 +48,14 @@ FILE_PATH=$(printf '%s' "$FILE_PATH" | head -1 | tr -d '\n\r' | cut -c1-500)
 
 TIMESTAMP="$(date '+%Y-%m-%d %H:%M:%S')"
 
+# Auto-rotate if audit log exceeds 1 MB
+if [ -f "$AUDIT_LOG" ]; then
+  LOG_SIZE=$(wc -c < "$AUDIT_LOG" | tr -d ' ')
+  if [ "$LOG_SIZE" -ge 1048576 ]; then
+    mv "$AUDIT_LOG" "${AUDIT_LOG}.1"
+  fi
+fi
+
 # policy_settings changes are logged only (not blocked)
 if [ "$SOURCE" = "policy_settings" ]; then
   printf '[%s] source=%s path=%s\n' "$TIMESTAMP" "$SOURCE" "$FILE_PATH" >> "$AUDIT_LOG"

package/scripts/afc-consistency-check.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 # afc-consistency-check.sh — Cross-reference validation for project consistency
-# Checks: config placeholders, agent names, hook scripts, test coverage
+# Checks: config placeholders, agent names, hook scripts, test coverage, command docs
 # Run as part of: npm run lint
 
 # shellcheck disable=SC2329
@@ -32,6 +32,15 @@ ok() {
   printf "[afc:consistency] ✓ %s\n" "$1"
 }
 
+# Extract a field value from command file YAML frontmatter
+get_cmd_field() {
+  local file="$1" field="$2"
+  awk '/^---$/{n++; next} n==1{print} n>=2{exit}' "$file" \
+    | grep "^${field}:" \
+    | sed "s/^${field}:[[:space:]]*//" \
+    | tr -d '"' | head -1 || true
+}
+
 # --- Check 1: Config Placeholder Validation ---
 # Verify all {config.*} references in commands/ and docs/ map to known config keys
 
@@ -240,30 +249,59 @@ check_phase_ssot() {
     fi
   done
 
-  # Sub-check B: Every command name should map to a valid phase or be a known non-phase command
-  # Non-phase commands that are not pipeline phases
-  # NOTE: Update this list when adding non-phase commands to commands/
-  local non_phase_cmds="auto|init|doctor|principles|checkpoint|resume|launch|ideate|research|architect|security|debug|analyze|validate|test|consult|triage|pr-comment|release-notes"
+  if [ "$issues" -eq 0 ]; then
+    ok "Phase SSOT: no hardcoded phase lists in scripts"
+  fi
+}
+
+# --- Check 7: Command Documentation Cross-Reference ---
+# Verify commands are documented in README.md, init.md, and CLAUDE.md
+
+check_command_docs() {
   local commands_dir="$PROJECT_DIR/commands"
-  if [ -d "$commands_dir" ]; then
-    for cmd_file in "$commands_dir"/*.md; do
-      [ -f "$cmd_file" ] || continue
-      local cmd_name
-      cmd_name=$(basename "$cmd_file" .md)
-      # Skip known non-phase commands
-      if printf '%s\n' "$non_phase_cmds" | tr '|' '\n' | grep -qxF "$cmd_name"; then
-        continue
+  [ -d "$commands_dir" ] || return
+
+  local readme="$PROJECT_DIR/README.md"
+  local init_cmd="$commands_dir/init.md"
+  local claude_md="$PROJECT_DIR/CLAUDE.md"
+  local issues=0
+
+  for cmd_file in "$commands_dir"/*.md; do
+    [ -f "$cmd_file" ] || continue
+    local cmd_name
+    cmd_name=$(basename "$cmd_file" .md)
+
+    # Sub-check A: README.md should mention /afc:{name}
+    if [ -f "$readme" ]; then
+      if ! grep -qE "/afc:${cmd_name}([^a-z0-9-]|$)" "$readme" 2>/dev/null; then
+        warn "Command '$cmd_name' missing from README.md command table"
+        issues=$((issues + 1))
       fi
-      # Remaining commands should correspond to a valid phase
-      if ! afc_is_valid_phase "$cmd_name"; then
-        warn "Command '$cmd_name' is not a recognized phase in AFC_VALID_PHASES and not in non-phase list"
+    fi
+
+    # Sub-check B: init.md should mention afc:{name} for user-invocable commands
+    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"
         issues=$((issues + 1))
       fi
-    done
-  fi
+    fi
+
+    # Sub-check C: CLAUDE.md fork list for context:fork commands
+    local ctx
+    ctx=$(get_cmd_field "$cmd_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"
+        issues=$((issues + 1))
+      fi
+    fi
+  done
 
   if [ "$issues" -eq 0 ]; then
-    ok "Phase SSOT: no hardcoded lists, all commands map to valid phases"
+    ok "Command docs: all commands referenced in README.md, init.md, CLAUDE.md"
   fi
 }
 
@@ -277,6 +315,7 @@ check_hook_scripts
 check_test_coverage
 check_version_sync
 check_phase_ssot
+check_command_docs
 
 printf "\n[afc:consistency] Done: %d errors, %d warnings\n" "$ERRORS" "$WARNINGS"
 

package/scripts/afc-dag-validate.sh

@@ -100,7 +100,7 @@ dfs_check() {
     if [ "$color" = "0" ]; then
       printf '1' > "$color_file"
 
-      neighbors="$(grep -E "^${current}\t" "$EDGES_FILE" | cut -f2 || true)"
+      neighbors="$(grep -E "^${current}	" "$EDGES_FILE" | cut -f2 || true)"
       if [ -n "$neighbors" ]; then
         while IFS= read -r neighbor; do
           [ -z "$neighbor" ] && continue