claude-md-plugin

Use when the user wants to autonomously develop a feature end-to-end without manual steps. Runs requirements → CLAUDE.md → code generation as a pipeline. Autonomous execution from start to finish given only requirements, without step-by-step commands. Trigger keywords: auto develop, end-to-end, autonomous implementation

Converges an existing project to the current plugin schema. Uses fix-schema CLI's converge_schema to deterministically handle section rename/remove/add. No source version detection needed — target-state-driven migration.

Adds or updates the Conventions section (unified 6 subsections) in project/module CLAUDE.md. For existing projects, extracts conventions from source code; for new projects, collects them interactively. Use the --update option to modify an existing Conventions section (absorbs the former /convention-update).

Inter-session spec workflow step executor. Reads .claude/workflows/{dir-safe}/state.json and executes the next pending step. Use when a spec workflow was interrupted, or to run pipeline steps in separate sessions/CI jobs. Trigger keywords: resume spec, resume workflow, resume spec

Use this agent when performing 3-layer root cause analysis for a reported bug. Traces through CLAUDE.md (Layer 1), DEVELOPERS.md (Layer 2), and source code (Layer 3). Composes superpowers:systematic-debugging for evidence-based root cause tracing. For Layer 3 unambiguous cases: writes failing test → fixes code → verifies. Returns a structured result block for the SKILL to act on. <example> <user_request> Session file: .claude/tmp/bugfix-session-src-auth.md Target path: src/auth </user_request> <assistant_response> 1. Session read — E: "AuthError on expired token", A: "User returned" 2. Layer 1: REQ-2 found — "expired tokens rejected" — E matches S ✓ 3. Layer 2: CONST-2 found — "max 7 days" — constraint exists ✓ 4. Layer 3: source_changed=false, changed_requirements=[] — code diverged from spec 5. Judgment: unambiguous (E == S AND A != S) 6. [RED] wrote test_authenticate_rejects_expired_token — fails as expected 7. [GREEN] fixed authenticate() at auth.ts:42 — added expiry check 8. Tests: 1 passed, 0 failed ---bugfix-result--- status: fixed root_cause_layer: 3 judgment: unambiguous fix_type: code_fix fix_description: Added token expiry check in authenticate() at auth.ts:42 test_result: passed ---end-bugfix-result--- </assistant_response> </example> <example> <user_request> Session file: .claude/tmp/bugfix-session-src-payment.md Target path: src/payment </user_request> <assistant_response> 1. Session read — E: "refund within 30 days", A: "refund rejected after 14 days" 2. Layer 1: no Requirement found for refund window — S = null 3. Judgment: ambiguous (S == null) ---bugfix-result--- status: escalated root_cause_layer: unknown judgment: ambiguous fix_type: none fix_description: CLAUDE.md has no Requirement for refund window. Cannot determine if code or spec is wrong. test_result: skipped escalation: expected: "refund within 30 days" actual: "refund rejected after 14 days" spec: "none" reason: "S == null — missing requirement in CLAUDE.md" choices: [A, B, C] ---end-bugfix-result--- </assistant_response> </example>

Use this agent when analyzing source code to generate CLAUDE.md drafts for a single directory. Orchestrates CLI tools (resolve-boundary, analyze-code, format-analysis) and generates documents directly. Input is a pre-extracted session file with tree info and children context. <example> <context> The decompile skill calls decompiler agent with a session file for each directory in leaf-first order. </context> <user_request> Session file: ${TMP_DIR}decompile-session-src-auth.md Target: src/auth Save results to ${TMP_DIR} and return only the path </user_request> <assistant_response> ---decompiler-result--- status: success target_dir: src/auth validation: passed developers_md: generated ---end-decompiler-result--- </assistant_response> </example>

Use this agent when a large spec needs to be split into individual spec units. Analyzes natural language requirements and produces a module decomposition plan: target paths, requirement distribution, tree structure, and dependency order. Does NOT write CLAUDE.md — that is impl agent's responsibility. Returns result as a file to protect SKILL context window. <example> <context> The spec skill calls decompose agent before dispatching impl agents. </context> <user_request> Session file: ${TMP_DIR}decompose-session.md Save results to ${TMP_DIR} and return only the path </user_request> <assistant_response> 1. Scope Classification: multi (3 independent purpose groups identified) 2. Module Identification: src/auth, src/payment, src/notification 3. Requirement Distribution: 12 requirements assigned, 0 unassigned 4. Tree Validation: INV-1 passed (flat siblings, no circular deps) 5. Result written: ${TMP_DIR}decompose-result.json ---decompose-result--- result_file: ${TMP_DIR}decompose-result.json scope: multi module_count: 3 ambiguous_count: 0 ---end-decompose-result--- </assistant_response> </example>

Use this agent when implementing production code to pass approved tests (GREEN phase). Receives approved tests and must make them pass with minimal implementation. NEVER modifies test assertions. Called by dev SKILL after test review loop approval. <example> <context> The dev skill calls green-coder with approved tests. </context> <user_request> Session file: ${TMP_DIR}green-session-src-auth.md Target directory: src/auth Detected language: typescript Save results to ${TMP_DIR} and return only the path </user_request> <assistant_response> 1. Session read — target: src/auth, language: typescript 2. Mapping loaded — 10 tests across 2 files 3. [GREEN attempt 1] Implementation generated 4. [GREEN attempt 1] Tests: 8 passed, 2 failed 5. [GREEN attempt 2] Fixed 2 failures 6. [GREEN attempt 2] Tests: 10 passed, 0 failed ---green-result--- result_file: ${TMP_DIR}green-result-src-auth.json status: success implemented_files: [src/auth/index.ts, src/auth/types.ts] tests_passed: 10 tests_failed: 0 ---end-green-result--- </assistant_response> </example>

Use this agent when critically reviewing a spec execution plan (plan.md) before CLAUDE.md generation. Applies Socratic method to verify Requirements completeness, Constraints precision, and Rationale traceability. Called by spec SKILL in the Socratic Loop, after impl agent produces plan.md and before mode=execute generates CLAUDE.md + DEVELOPERS.md. Returns verdict: approved | rejected with specific Critical Questions. <example> <context> spec SKILL calls impl-reviewer after plan.md is produced. </context> <user_request> Session file: .claude/tmp/spec-reviewer-session-src-auth-v1.md Save results to .claude/tmp/ and return only the path </user_request> <assistant_response> 1. Session read — plan_file: .claude/tmp/spec-plan-src-auth.md, round: 1 2. Plan loaded — 4 Requirements, 3 Constraints 3. Critique: - REQ-3: "handle appropriately" → unmeasurable expression - CONST-2: error type not specified - No Constraint corresponding to REQ-4 4. Verdict: rejected (3 Critical Questions) 5. Result written: .claude/tmp/spec-reviewer-result-src-auth-v1.md ---spec-reviewer-result--- result_file: .claude/tmp/spec-reviewer-result-src-auth-v1.md verdict: rejected round: 1 ---end-spec-reviewer-result--- </assistant_response> </example>

Use this agent when analyzing user requirements and generating CLAUDE.md specifications. Combines requirement clarification and dual document generation (CLAUDE.md + DEVELOPERS.md) in a single workflow. Composes superpowers:brainstorming for requirement exploration. Called by spec SKILL in two modes: - Single mode (scope=single): full clarification workflow - Parallel mode (scope=multi, parallel=true): minimal clarification, target_path pre-determined <example> <context> The spec skill needs to create CLAUDE.md from user requirements. </context> <user_request> Session file: ${TMP_DIR}spec-session.md Project root: /Users/dev/my-app Read the session file and generate CLAUDE.md + DEVELOPERS.md. </user_request> <assistant_response> I'll analyze the requirements and generate CLAUDE.md specifications. 1. Session read — mode: single, completeness: medium 2. Dependency exploration: 2 internal deps found, 1 external 3. [AskUserQuestion: fields to return, token signing algorithm] 4. Target path determined: src/auth 5. CLAUDE.md + DEVELOPERS.md generated 6. Schema validation passed 7. [Plan Preview → User approved] ---spec-result--- claude_md_file: src/auth/CLAUDE.md developers_md_file: src/auth/DEVELOPERS.md status: success action: created ---end-spec-result--- </assistant_response> </example>

Use this agent when applying coding conventions to implemented code (REFACTOR phase). Receives production code from green-coder and applies Conventions while ensuring regression tests pass. NEVER modifies test assertions. Rolls back on regression failure. <example> <context> The dev skill calls refactorer after green-coder completes. </context> <user_request> Session file: ${TMP_DIR}refactor-session-src-auth.md Target directory: src/auth Detected language: typescript Save results to ${TMP_DIR} and return only the path </user_request> <assistant_response> 1. Session read — target: src/auth, language: typescript 2. Conventions loaded — 6 subsections 3. Implementation files: 2 files 4. Refactoring: naming rules applied, coding rules applied 5. Regression test: 10 passed, 0 failed ---refactor-result--- result_file: ${TMP_DIR}refactor-result-src-auth.json status: success refactored_files: [src/auth/index.ts, src/auth/types.ts] tests_passed: 10 tests_failed: 0 ---end-refactor-result--- </assistant_response> </example>

Use this agent when concretizing vague requirements through project domain context exploration. Reads project code, CLAUDE.md files, DEVELOPERS.md, git history, and configuration to resolve ambiguities autonomously. Only used within the Self Socratic Loop before decompose. Returns concretized requirements as a file to protect SKILL context window. <example> <context> The spec skill calls requirement-explorer to concretize vague requirements before decompose/impl. </context> <user_request> Session file: ${TMP_DIR}explore-session-1.md Save results to ${TMP_DIR} and return only the path </user_request> <assistant_response> 1. Domain context collected — 5 key terms, 3 existing patterns 2. Ambiguity assessment — 4 items: 2 domain-clear, 1 explorable, 1 genuinely-ambiguous 3. Exploration — resolved 1 explorable item via src/auth/CLAUDE.md 4. Result written: ${TMP_DIR}explore-result-1.md ---explore-result--- result_file: ${TMP_DIR}explore-result-1.md total: 4 domain_clear: 2 resolved: 1 unresolved: 1 ---end-explore-result--- </assistant_response> </example>

Use this agent when critically reviewing concretized requirements before spec definition. Evaluates whether requirements are sufficiently concrete for complete CLAUDE.md/DEVELOPERS.md generation, judged against the project's domain context. Called by spec SKILL in the Self Socratic Loop, after requirement-explorer produces concretized requirements. Returns verdict: approved | rejected with specific Critical Questions. <example> <context> spec SKILL calls requirement-reviewer after explorer concretizes requirements. </context> <user_request> Session file: ${TMP_DIR}explore-reviewer-session-1.md Save results to ${TMP_DIR} and return only the path </user_request> <assistant_response> 1. Session read — round: 1, explore_result loaded 2. Original requirement loaded — faithfulness check ready 3. Evaluation: - Purpose identifiability: pass - Requirements derivability: fail — "notification behavior" not pass/fail determinable - Constraints derivability: pass - Domain Context sufficiency: pass - Resolution soundness: pass — spot-checked src/auth/CLAUDE.md:3 confirmed 4. Verdict: rejected (1 Critical Question) 5. Result written: ${TMP_DIR}explore-reviewer-result-1.md ---explore-reviewer-result--- result_file: ${TMP_DIR}explore-reviewer-result-1.md verdict: rejected round: 1 critical_questions: 1 ---end-explore-reviewer-result--- </assistant_response> </example>

Use this agent when reviewing tests generated by test-writer against the spec. Verifies Constraint/Requirement traceability, boundary coverage, interface consistency, and test independence. Called by dev SKILL in the test review loop. Returns verdict: approved | rejected. <example> <context> The dev skill calls test-reviewer after test-writer produces tests. </context> <user_request> Session file: ${TMP_DIR}test-reviewer-session-src-auth-v1.md Save results to ${TMP_DIR} and return only the path </user_request> <assistant_response> 1. Session read — round: 1, language: typescript 2. Mapping loaded — 3 Constraints, 2 Requirements 3. Test files read — 2 files, 10 tests 4. Critique: - CONST-2: boundary value test missing — no 7-day/8-day boundary for "maximum 7 days" 5. Verdict: rejected (1 Critical Question) 6. Result written: ${TMP_DIR}test-reviewer-result-src-auth-v1.md ---test-reviewer-result--- result_file: ${TMP_DIR}test-reviewer-result-src-auth-v1.md verdict: rejected round: 1 ---end-test-reviewer-result--- </assistant_response> </example>

Use this agent when generating tests from a dev session file during the RED phase. Reads Requirements and Constraints from session file, produces test files + mapping JSON. Called by dev SKILL in two modes: write (initial) and revise (after reviewer feedback). <example> <context> The dev skill calls test-writer to generate tests from spec. </context> <user_request> Session file: ${TMP_DIR}test-writer-session-src-auth.md Save results to ${TMP_DIR} and return only the path </user_request> <assistant_response> 1. Session read — mode: write, target: src/auth, language: typescript 2. Requirements extracted: 2, Constraints extracted: 3 3. Test files generated: 2 files (8 unit tests, 2 acceptance tests) 4. Mapping table: 3/3 Constraints mapped, 2/2 Requirements mapped 5. Unmapped: 0 constraints, 0 requirements ---test-writer-result--- result_file: ${TMP_DIR}test-writer-result-src-auth.json status: success test_dir: ${TMP_DIR}tests/src-auth/ mapping_file: ${TMP_DIR}test-mapping-src-auth.json tests_generated: 10 unmapped_constraints: 0 unmapped_requirements: 0 ---end-test-writer-result--- </assistant_response> </example>

Use this agent when validating consistency between CLAUDE.md and actual code. Detects semantic drift in Requirements, Convention CODE_VIOLATION, and DEVELOPERS.md content. Composes superpowers:verification-before-completion for evidence-based verification discipline. <example> <user_request> Session file: ${TMP_DIR}validate-session-src-auth.md Validation target: src/auth strict: false </user_request> <assistant_response> ---validate-result--- status: success result_file: ${TMP_DIR}validate-src-auth.md directory: src/auth issues_count: 3 strict: false ---end-validate-result--- </assistant_response> </example> <example> <user_request> Session file: ${TMP_DIR}validate-session-src-legacy.md Validation target: src/legacy strict: true </user_request> <assistant_response> ---validate-result--- status: success result_file: ${TMP_DIR}validate-src-legacy.md directory: src/legacy issues_count: 7 strict: true ---end-validate-result--- </assistant_response> </example>

This skill should be used when the user reports a bug, unexpected behavior, or asks to "fix this bug", "debug this", "something is broken", "not working as expected", or uses "/bugfix". Traces root cause through 3 layers: CLAUDE.md (requirements) → DEVELOPERS.md (constraints) → source code. Fixes at the highest affected layer following Fix-Highest-Layer-First principle. Never patches code while leaving CLAUDE.md inconsistent. Trigger keywords: fix bug, debug, unexpected behavior, broken, not working

This skill should be used when the user asks to "decompile code to CLAUDE.md", "extract CLAUDE.md from code", "document existing codebase", "reverse engineer spec", "extract documentation from source", or uses "/decompile" or "/decom". Analyzes existing source code and creates CLAUDE.md + DEVELOPERS.md documentation for each directory. Uses parse-tree CLI for directory discovery, then runs decompiler agent per directory in leaf-first order. Trigger keywords: decompile, extract docs from code, document existing code

This skill should be used when the user asks to "develop from CLAUDE.md", "generate code from CLAUDE.md", "implement CLAUDE.md", "create source files", or uses "/dev". Processes changed CLAUDE.md files in the target path (or all with --all flag). Performs 4-agent TDD pipeline: test-writer → test-reviewer loop → green-coder → refactorer. Trigger keywords: code generation, develop, code from CLAUDE.md

This skill should be used when the user asks to "define requirements", "write spec", "create CLAUDE.md from requirements", "define behavior before coding", or uses "/spec". Analyzes natural language requirements and generates CLAUDE.md without implementing code. Follows ATDD principle: specification first, then code generation via /dev. Trigger keywords: define requirements, write spec, spec first

This skill should be used when the user asks to "validate CLAUDE.md", "check documentation-code consistency", "verify specification matches implementation", "check for drift", "lint documentation", "resolve drift", "fix documentation mismatch", "sync docs with code", or uses "/validate". Runs deterministic CLI validation (schema, convention structure, boundary, DEVELOPERS.md existence) and semantic validator agent for comprehensive drift detection, with interactive auto-fix. Trigger keywords: validate CLAUDE.md, document verification, drift check, resolve drift

1 hook across 1 event