all-for-claudecode: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build / Lint / Test

npm run lint          # shellcheck + schema validation + consistency check
npm run qa            # QA audit (hook I/O safety, test strength, UX, build integrity)
npm test              # ShellSpec BDD suite (vendor/shellspec/shellspec)
npm run test:all      # lint + qa + test combined
npm run setup:test    # install ShellSpec to vendor/shellspec/ (first-time setup)
npm run sync:cache    # sync source files to plugin cache (development only)

Single script lint: shellcheck scripts/afc-bash-guard.sh Single spec run: vendor/shellspec/shellspec spec/afc-bash-guard_spec.sh

Architecture

all-for-claudecode is a Claude Code plugin that automates the full development cycle (spec → plan → implement → review → clean) through markdown skill prompts and bash hook scripts. Project config (afc.config.md) holds CI Commands in fixed YAML format (parsed by scripts); Architecture, Code Style, and Project Context are also stored there as detailed references but are primarily delivered via .claude/rules/afc-project.md (auto-loaded by Claude Code for all conversations and sub-agents). Init auto-analyzes the project structure and generates project-local files; Setup manages the global ~/.claude/CLAUDE.md AFC routing block separately. Tasks are generated automatically at implement start from plan.md's File Change Map (no separate tasks phase). Implementation uses dependency-aware orchestration: sequential for simple tasks, parallel batch (≤5 tasks), or orchestrator-managed swarm (6+ tasks) with native TaskCreate/TaskUpdate primitives. Skill Advisor system dynamically invokes auxiliary skills (ideate, consult, architect, security, analyze, test, qa, learner) at 5 phase-boundary checkpoints (A–E) based on signal detection, with budget control (max 5 per pipeline run).

Core Layers

• skills/ — Skill prompts with YAML frontmatter (name, description, argument-hint, allowed-tools, model, user-invocable, context). Each skill lives in skills/<name>/SKILL.md with optional reference files (progressive disclosure). Pipeline phases (spec, plan, implement, review, clean) each have standalone skills. Additional standalone utilities include consult, debug, doctor, learner, qa, research, test, analyze, architect, security, triage, issue, resolve, checkpoint, resume, principles, etc. Setup manages global CLAUDE.md configuration separately from init (project-local). Deployment tools include ideate, launch, pr-comment, release-notes.
• agents/ — Subagents: afc-architect, afc-security (persistent memory with memory: project, security uses isolation: worktree), afc-impl-worker (ephemeral parallel worker, orchestrator-managed worktree isolation), afc-pr-analyst (PR deep analysis worker, orchestrator-managed worktree isolation for triage), 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 — persistent memory, routed via consult skill)
• hooks/hooks.json — Hook event declarations with handler types: command (shell scripts), prompt (LLM single-turn). Some hooks use async: true. Includes ConfigChange (settings audit), TeammateIdle (Agent Teams gate), and WorktreeCreate/WorktreeRemove (worktree lifecycle)
• schemas/ — JSON Schema definitions (hooks.schema.json, plugin.schema.json, marketplace.schema.json) validated during npm run lint
• scripts/ — Bash hook/utility scripts (afc-*.sh + non-afc utilities) + Node.js ESM validators (.mjs) + shared state library (afc-state.sh). Includes afc-consistency-check.sh for cross-reference validation and skill-documentation gap detection. Bash scripts follow: set -euo pipefail + trap cleanup EXIT + jq-first with grep/sed fallback
• docs/ — Shared reference documents (critic-loop-rules.md, phase-gate-protocol.md, expert-protocol.md, learner-signals.md, skill-authoring-guide.md, agent-authoring-guide.md, context-management-harness.md, orchestration-modes.md) referenced by skills and agents. Includes domain-adapters/ subdirectory with industry-specific guardrails (fintech, ecommerce, healthcare). Single-consumer docs live inside their skill directory (e.g., skills/spec/nfr-templates.md)
• templates/ — config template (afc.config.template.md) for CI Commands YAML + free-form sections, and project rules template (afc-project.template.md) for .claude/rules/afc-project.md (auto-loaded by Claude Code)
• bin/cli.mjs — ESM CLI entry point (install helper)
• .claude-plugin/ — Plugin manifest (plugin.json) and marketplace registration (marketplace.json)