all-for-claudecode 2.1.0 → 2.2.0

package/scripts/afc-consistency-check.sh

@@ -0,0 +1,261 @@
+#!/bin/bash
+set -euo pipefail
+
+# afc-consistency-check.sh — Cross-reference validation for project consistency
+# Checks: config placeholders, agent names, hook scripts, test coverage
+# Run as part of: npm run lint
+
+# shellcheck disable=SC2329
+cleanup() {
+  :
+}
+trap cleanup EXIT
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="${1:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+ERRORS=0
+WARNINGS=0
+
+# --- Helpers ---
+
+fail() {
+  printf "[afc:consistency] FAIL: %s\n" "$1" >&2
+  ERRORS=$((ERRORS + 1))
+}
+
+warn() {
+  printf "[afc:consistency] WARN: %s\n" "$1" >&2
+  WARNINGS=$((WARNINGS + 1))
+}
+
+ok() {
+  printf "[afc:consistency] ✓ %s\n" "$1"
+}
+
+# --- Check 1: Config Placeholder Validation ---
+# Verify all {config.*} references in commands/ and docs/ map to known config keys
+
+check_config_placeholders() {
+  local template="$PROJECT_DIR/templates/afc.config.template.md"
+  if [ ! -f "$template" ]; then
+    warn "Config template not found: $template"
+    return
+  fi
+
+  # Extract valid config keys from template
+  # YAML keys: ci, gate, test
+  local yaml_keys
+  yaml_keys=$(grep -oE '^\s*[a-z_]+:' "$template" 2>/dev/null | sed 's/[[:space:]]*//;s/://' | sort -u || true)
+  # Section headers → lowercase with underscores: Architecture → architecture, Code Style → code_style, Project Context → project_context
+  local section_keys
+  section_keys=$(grep -oE '^## [A-Za-z ]+' "$template" 2>/dev/null \
+    | sed 's/^## //' \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed 's/ /_/g' \
+    | sort -u || true)
+
+  local valid_keys
+  valid_keys=$(printf '%s\n%s\n' "$yaml_keys" "$section_keys" | sort -u)
+
+  # Extract all {config.*} references from commands and docs
+  local refs
+  refs=$(grep -rohE '\{config\.[a-z_]+\}' "$PROJECT_DIR/commands/" "$PROJECT_DIR/docs/" 2>/dev/null \
+    | sed 's/{config\.//;s/}//' \
+    | sort -u || true)
+
+  local count=0
+  local invalid=0
+  for ref in $refs; do
+    count=$((count + 1))
+    if ! printf '%s\n' "$valid_keys" | grep -qxF "$ref"; then
+      fail "{config.$ref} referenced but not defined in config template"
+      invalid=$((invalid + 1))
+    fi
+  done
+
+  if [ "$invalid" -eq 0 ]; then
+    ok "Config placeholders: $count references, all valid"
+  fi
+}
+
+# --- Check 2: Agent Name Consistency ---
+# Verify subagent_type references in commands match agent definitions
+
+check_agent_names() {
+  local agents_dir="$PROJECT_DIR/agents"
+  if [ ! -d "$agents_dir" ]; then
+    warn "Agents directory not found"
+    return
+  fi
+
+  # Extract agent names from agent files (name: field in frontmatter)
+  local defined_agents
+  defined_agents=$(grep -h '^name:' "$agents_dir"/*.md 2>/dev/null \
+    | sed 's/^name:[[:space:]]*//' \
+    | tr -d '"' \
+    | sort -u || true)
+
+  # Extract subagent_type references from commands (afc:agent-name pattern)
+  local referenced_agents
+  referenced_agents=$(grep -rohE 'subagent_type:[[:space:]]*"afc:[^"]*"' "$PROJECT_DIR/commands/" 2>/dev/null \
+    | sed 's/.*"afc://;s/"//' \
+    | sort -u || true)
+
+  local count=0
+  local invalid=0
+  for ref in $referenced_agents; do
+    count=$((count + 1))
+    if ! printf '%s\n' "$defined_agents" | grep -qxF "$ref"; then
+      fail "subagent_type 'afc:$ref' referenced but no agents/$ref.md found"
+      invalid=$((invalid + 1))
+    fi
+  done
+
+  # Check for unprefixed subagent_type that should have afc: prefix
+  local unprefixed
+  unprefixed=$(grep -rohE 'subagent_type:[[:space:]]*"afc-[^"]*"' "$PROJECT_DIR/commands/" 2>/dev/null \
+    | sed 's/.*subagent_type:[[:space:]]*"//;s/".*//' \
+    | sort -u || true)
+  for ref in $unprefixed; do
+    if printf '%s\n' "$defined_agents" | grep -qxF "$ref"; then
+      fail "subagent_type '$ref' should use 'afc:$ref' prefix (found in agents/)"
+      invalid=$((invalid + 1))
+    fi
+  done
+
+  if [ "$invalid" -eq 0 ]; then
+    ok "Agent names: $count references, all consistent"
+  fi
+}
+
+# --- Check 3: Hook Script Existence ---
+# Verify all scripts referenced in hooks.json actually exist
+
+check_hook_scripts() {
+  local hooks_file="$PROJECT_DIR/hooks/hooks.json"
+  if [ ! -f "$hooks_file" ]; then
+    warn "hooks.json not found"
+    return
+  fi
+
+  local scripts
+  scripts=$(grep -oE 'scripts/[^"]+\.sh' "$hooks_file" 2>/dev/null | sort -u || true)
+
+  local count=0
+  local missing=0
+  for script in $scripts; do
+    count=$((count + 1))
+    if [ ! -f "$PROJECT_DIR/$script" ]; then
+      fail "hooks.json references '$script' but file not found"
+      missing=$((missing + 1))
+    fi
+  done
+
+  if [ "$missing" -eq 0 ]; then
+    ok "Hook scripts: $count references, all exist"
+  fi
+}
+
+# --- Check 4: Test Coverage ---
+# Verify each afc-*.sh script (except afc-state.sh library) has a spec file
+
+check_test_coverage() {
+  local count=0
+  local missing=0
+  for script in "$PROJECT_DIR"/scripts/afc-*.sh; do
+    local scriptname
+    scriptname=$(basename "$script" .sh)
+    # Skip shared library and self (validation script)
+    if [ "$scriptname" = "afc-state" ] || [ "$scriptname" = "afc-consistency-check" ]; then
+      continue
+    fi
+    count=$((count + 1))
+    if [ ! -f "$PROJECT_DIR/spec/${scriptname}_spec.sh" ]; then
+      fail "scripts/$scriptname.sh has no spec/${scriptname}_spec.sh"
+      missing=$((missing + 1))
+    fi
+  done
+
+  if [ "$missing" -eq 0 ]; then
+    ok "Test coverage: $count scripts, all have specs"
+  fi
+}
+
+# --- Check 5: Version Sync ---
+# Verify version numbers match across package.json, plugin.json, marketplace.json
+
+check_version_sync() {
+  local pkg="$PROJECT_DIR/package.json"
+  local plugin="$PROJECT_DIR/.claude-plugin/plugin.json"
+  local market="$PROJECT_DIR/.claude-plugin/marketplace.json"
+
+  if [ ! -f "$pkg" ] || [ ! -f "$plugin" ] || [ ! -f "$market" ]; then
+    warn "One or more version files missing"
+    return
+  fi
+
+  local pkg_ver plugin_ver market_meta market_plugin
+  if command -v jq >/dev/null 2>&1; then
+    pkg_ver=$(jq -r '.version' "$pkg")
+    plugin_ver=$(jq -r '.version' "$plugin")
+    market_meta=$(jq -r '.metadata.version' "$market")
+    market_plugin=$(jq -r '.plugins[0].version' "$market")
+  else
+    pkg_ver=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$pkg" | head -1 | sed 's/.*"version"[[:space:]]*:[[:space:]]*"//;s/"//')
+    plugin_ver=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$plugin" | head -1 | sed 's/.*"version"[[:space:]]*:[[:space:]]*"//;s/"//')
+    market_meta=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$market" | head -1 | sed 's/.*"version"[[:space:]]*:[[:space:]]*"//;s/"//')
+    market_plugin=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$market" | sed -n '2p' | sed 's/.*"version"[[:space:]]*:[[:space:]]*"//;s/"//')
+  fi
+
+  if [ "$pkg_ver" = "$plugin_ver" ] && [ "$plugin_ver" = "$market_meta" ] && [ "$market_meta" = "$market_plugin" ]; then
+    ok "Version sync: $pkg_ver (all 4 match)"
+  else
+    fail "Version mismatch: package.json=$pkg_ver plugin.json=$plugin_ver marketplace.meta=$market_meta marketplace.plugin=$market_plugin"
+  fi
+}
+
+# --- Check 6: SSOT Phase Constants ---
+# Verify SSOT phase list in afc-state.sh is not duplicated in other scripts
+
+check_phase_ssot() {
+  # shellcheck source=afc-state.sh
+  . "$SCRIPT_DIR/afc-state.sh"
+
+  local dupes=0
+  # Look for hardcoded phase lists (pipe-separated patterns with 3+ known phases)
+  for script in "$PROJECT_DIR"/scripts/afc-*.sh; do
+    local scriptname
+    scriptname=$(basename "$script")
+    # Skip the SSOT source itself and this validation script
+    if [ "$scriptname" = "afc-state.sh" ] || [ "$scriptname" = "afc-consistency-check.sh" ]; then
+      continue
+    fi
+    # Check for hardcoded phase case patterns (spec|plan|...|clean style)
+    if grep -qE 'spec\|plan\|.*\|clean' "$script" 2>/dev/null; then
+      fail "$scriptname contains hardcoded phase list — use SSOT helpers from afc-state.sh"
+      dupes=$((dupes + 1))
+    fi
+  done
+
+  if [ "$dupes" -eq 0 ]; then
+    ok "Phase SSOT: no hardcoded phase lists found in scripts"
+  fi
+}
+
+# --- Run All Checks ---
+
+printf "[afc:consistency] Running cross-reference validation...\n"
+
+check_config_placeholders
+check_agent_names
+check_hook_scripts
+check_test_coverage
+check_version_sync
+check_phase_ssot
+
+printf "\n[afc:consistency] Done: %d errors, %d warnings\n" "$ERRORS" "$WARNINGS"
+
+if [ "$ERRORS" -gt 0 ]; then
+  exit 1
+fi
+exit 0

package/scripts/afc-permission-request.sh

@@ -59,7 +59,7 @@ if [ -f "$CONFIG_FILE" ]; then
   # Extract ci, gate, test values from YAML code block
   # Handles both quoted and unquoted: ci: "npm run lint" or ci: npm run lint
   for key in ci gate test; do
-    val=$(grep -E "^${key}:" "$CONFIG_FILE" 2>/dev/null | head -1 | sed 's/^[^:]*:[[:space:]]*//;s/^"//;s/"[[:space:]]*$//' || true)
+    val=$(grep -E "^\s*${key}:\s*\"[^\"]*\"" "$CONFIG_FILE" 2>/dev/null | head -1 | sed 's/.*'"${key}"': *"\([^"]*\)".*/\1/' || true)
     if [ -n "$val" ] && [ "$val" != '""' ]; then
       DYNAMIC_WHITELIST="${DYNAMIC_WHITELIST:+${DYNAMIC_WHITELIST}|}${val}"
       # Generate PM-agnostic variants (npm → pnpm, yarn, bun)
@@ -97,6 +97,16 @@ if [ "$ALLOWED" = "false" ]; then
   esac
 fi
 
+# Plugin's own scripts (auto-allow during pipeline execution)
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [ "$ALLOWED" = "false" ] && [ -n "$PLUGIN_ROOT" ]; then
+  case "$COMMAND" in
+    "\"${PLUGIN_ROOT}/scripts/"*|"${PLUGIN_ROOT}/scripts/"*)
+      ALLOWED=true
+      ;;
+  esac
+fi
+
 # Prefix matching (allow paths after shellcheck, prettier, chmod +x)
 if [ "$ALLOWED" = "false" ]; then
   case "$COMMAND" in

package/scripts/afc-pipeline-manage.sh

@@ -73,17 +73,14 @@ case "$COMMAND" in
 
   phase)
     PHASE="${2:?Phase name required}"
-    case "$PHASE" in
-      spec|plan|tasks|implement|review|clean|clarify|test-pre-gen|blast-radius|fast-path)
-        afc_state_write "phase" "$PHASE"
-        afc_state_invalidate_ci
-        echo "Phase: $PHASE"
-        ;;
-      *)
-        printf "[afc:pipeline] Invalid phase: %s\n  → Valid phases: spec|plan|tasks|implement|review|clean|clarify|test-pre-gen|blast-radius\n" "$PHASE" >&2
-        exit 1
-        ;;
-    esac
+    if afc_is_valid_phase "$PHASE"; then
+      afc_state_write "phase" "$PHASE"
+      afc_state_invalidate_ci
+      echo "Phase: $PHASE"
+    else
+      printf "[afc:pipeline] Invalid phase: %s\n  → Valid phases: %s\n" "$PHASE" "$AFC_VALID_PHASES" >&2
+      exit 1
+    fi
     ;;
 
   ci-pass)

package/scripts/afc-state.sh

@@ -8,6 +8,26 @@
 _AFC_STATE_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/.claude"
 _AFC_STATE_FILE="${_AFC_STATE_DIR}/.afc-state.json"
 
+# --- Phase Constants (SSOT) ---
+# All valid pipeline phases. Update HERE when adding a new phase.
+AFC_VALID_PHASES="spec|plan|tasks|implement|review|clean|clarify|test-pre-gen|blast-radius|fast-path"
+# Phases that do NOT require CI gate to pass (preparatory phases)
+AFC_CI_EXEMPT_PHASES="spec|plan|tasks|clarify|test-pre-gen|blast-radius"
+
+# Check if a phase name is valid
+# Usage: afc_is_valid_phase <phase>
+# Returns: 0 if valid, 1 if not
+afc_is_valid_phase() {
+  printf '%s\n' "$AFC_VALID_PHASES" | tr '|' '\n' | grep -qxF "$1"
+}
+
+# Check if a phase is exempt from CI gate
+# Usage: afc_is_ci_exempt <phase>
+# Returns: 0 if exempt, 1 if CI required
+afc_is_ci_exempt() {
+  printf '%s\n' "$AFC_CI_EXEMPT_PHASES" | tr '|' '\n' | grep -qxF "$1"
+}
+
 # --- Public API ---
 
 # Check if pipeline is active (state file exists and has feature)

package/scripts/afc-stop-gate.sh

@@ -45,12 +45,10 @@ FEATURE="$(afc_state_read feature || echo '')"
 # Check current Phase
 CURRENT_PHASE="$(afc_state_read phase || echo '')"
 
-# Spec/Plan/Tasks Phase (1-3) do not require CI -> pass through
-case "${CURRENT_PHASE:-}" in
-  spec|plan|tasks|clarify|test-pre-gen|blast-radius)
-    exit 0
-    ;;
-esac
+# Preparatory phases do not require CI -> pass through
+if afc_is_ci_exempt "${CURRENT_PHASE:-}"; then
+  exit 0
+fi
 
 # Implement/Review/Clean Phase (4-6) require CI to pass
 CI_TIME="$(afc_state_read ciPassedAt 2>/dev/null || echo '')"

package/scripts/afc-subagent-context.sh

@@ -51,6 +51,13 @@ if [ -f "$CONFIG_FILE" ]; then
   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
 
 # 5. Output as hookSpecificOutput JSON (required for SubagentStart context injection)

package/scripts/afc-task-completed-gate.sh

@@ -32,12 +32,10 @@ FEATURE="$(afc_state_read feature || echo '')"
 # Check current Phase
 CURRENT_PHASE="$(afc_state_read phase || echo '')"
 
-# Spec/Plan/Tasks Phase (1-3) do not require CI -> pass through
-case "${CURRENT_PHASE:-}" in
-  spec|plan|tasks)
-    exit 0
-    ;;
-esac
+# Preparatory phases do not require CI -> pass through
+if afc_is_ci_exempt "${CURRENT_PHASE:-}"; then
+  exit 0
+fi
 
 # Implement/Review/Clean Phase (4-6) require CI to pass
 CI_TIME="$(afc_state_read ciPassedAt 2>/dev/null || echo '')"

package/templates/afc.config.template.md

@@ -1,90 +1,26 @@
-# all-for-claudecode Configuration
+# Project Configuration
 
-> This file defines project-specific settings for the afc command system.
-> All afc commands reference this file to determine project-specific behavior.
-> Modify each section to match your project.
+> 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
 
+<!-- DO NOT change the format below. Scripts parse these keys. -->
 ```yaml
-ci: "npm run ci"                        # Full CI (lint + typecheck + build)
-typecheck: "npm run typecheck"          # Typecheck only
-lint: "npm run lint"                    # Lint only
-lint_fix: "npm run lint:fix"            # Auto-fix lint
-gate: "npm run typecheck && npm run lint"  # Phase gate (run repeatedly during implement)
-test: "npm test"                        # Tests
+ci: "npm run ci"
+gate: "npm run typecheck && npm run lint"
+test: "npm test"
 ```
 
 ## Architecture
 
-```yaml
-style: "Layered"                        # e.g.: FSD, Clean Architecture, Modular Monolith, Layered
-layers: []                              # List from top to bottom layer
-import_rule: ""                         # Import direction rule (e.g.: "upper → lower only")
-segments: []                            # Sub-segments for each layer
-path_alias: ""                          # e.g.: "@/* → ./src/*"
-```
-
-## Framework
-
-```yaml
-name: ""                                # e.g.: Next.js 14, Vite, CRA
-runtime: ""                             # e.g.: App Router, Pages Router
-client_directive: ""                    # e.g.: 'use client' (leave empty if not applicable)
-client_directive_rule: ""               # Rule for applying client directives
-server_client_boundary: false           # Whether a server/client boundary exists
-```
+(init analyzes your project and writes this section in free-form)
 
 ## Code Style
 
-```yaml
-language: "TypeScript"
-strict_mode: true
-type_keyword: "type"                    # type vs interface
-import_type: true                       # Whether to use import type
-component_style: "PascalCase"
-props_position: "above component"
-handler_naming: "handle[Event]"
-boolean_naming: "is/has/can[State]"
-constant_naming: "UPPER_SNAKE_CASE"
-any_policy: "minimize"
-```
-
-## State Management
-
-```yaml
-global_state: ""                        # e.g.: Zustand, Redux, Pinia
-server_state: ""                        # e.g.: React Query, SWR, Apollo
-local_state: ""                         # e.g.: Context API, useState
-store_location: ""                      # Store file location pattern
-query_location: ""                      # Query file location pattern
-```
-
-## Styling
-
-```yaml
-framework: ""                           # e.g.: Tailwind CSS, styled-components, CSS Modules
-```
-
-## Testing
-
-```yaml
-framework: ""                           # e.g.: Jest, Vitest, Playwright
-```
-
-## Project-Specific Risks
-
-> Project-specific risk patterns that must be checked in the Plan's RISK Critic
-> Modify to match your project.
-
-1. (example) Import order violation
-2. (example) Circular reference
-3. (example) Type safety bypass (as any)
-
-## Mini-Review Checklist
+(init analyzes your project and writes this section in free-form)
 
-> Items to inspect for each file in the Mini-Review of the Implement Phase gate
+## Project Context
 
-1. Architecture rule violations
-2. Code style pattern compliance
-3. Dead code (unused imports, empty exports, dead code)
+(init analyzes your project and writes this section in free-form — framework, state management, styling, testing, risks, etc.)

package/templates/afc.config.express-api.md

@@ -1,99 +0,0 @@
-# all-for-claudecode Configuration
-
-> This file defines project-specific settings for the afc command system.
-> All afc commands reference this file to determine project-specific behavior.
-
-## CI Commands
-
-```yaml
-ci: "npm run build && npm run lint && npm run test"  # Full CI (build + lint + test)
-typecheck: "npx tsc --noEmit"                        # Typecheck only
-lint: "npx eslint src/"                              # Lint only
-lint_fix: "npx eslint src/ --fix"                    # Auto-fix lint
-gate: "npx tsc --noEmit && npx eslint src/"          # Phase gate (run repeatedly during implement)
-test: "npx jest --runInBand"                         # Tests
-```
-
-## Architecture
-
-```yaml
-style: "Layered"                        # Layered architecture
-layers:                                 # Top → bottom order
-  - src/routes
-  - src/controllers
-  - src/services
-  - src/repositories
-  - src/models
-  - src/middleware
-  - src/lib
-  - src/types
-  - src/config
-import_rule: "Upper layers (routes) depend only in order: controllers → services → repositories"
-segments: []
-path_alias: "@/* → ./src/*"
-```
-
-## Framework
-
-```yaml
-name: "Express.js"
-runtime: "Node.js (CommonJS or ESM)"
-client_directive: ""                    # Server-only — not applicable
-server_client_boundary: false           # Server-only application
-```
-
-## Code Style
-
-```yaml
-language: "TypeScript"
-strict_mode: true
-type_keyword: "type"                    # Use type instead of interface
-import_type: true                       # Use import type { ... }
-component_style: ""                     # No UI components
-props_position: ""                      # No UI components
-handler_naming: "camelCase"
-boolean_naming: "is/has/can[State]"
-constant_naming: "UPPER_SNAKE_CASE"
-any_policy: "banned (use unknown with strict mode)"
-```
-
-## State Management
-
-```yaml
-global_state: ""                        # Server — stateless
-server_state: ""
-local_state: ""
-store_location: ""
-query_location: ""
-```
-
-## Styling
-
-```yaml
-framework: ""                           # Not applicable
-```
-
-## Testing
-
-```yaml
-framework: "Jest + Supertest"
-```
-
-## Project-Specific Risks
-
-> Project-specific risk patterns that must be checked in the Plan's RISK Critic
-
-1. Prisma migration and schema mismatch
-2. Express middleware ordering errors (auth → validation → handler)
-3. Missing async/await error handling (try-catch or wrapper)
-4. Runtime errors when environment variables (.env) are not set
-5. SQL injection (caution with raw queries when using Prisma)
-
-## Mini-Review Checklist
-
-> Items to inspect for each file in the Mini-Review of the Implement Phase gate
-
-1. TypeScript strict mode violations
-2. Error handling (try-catch or asyncHandler on async routes)
-3. Input validation (type checking of req.body/params/query)
-4. Unused imports / dead code