CLAUDE.md

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

Repository Overview

Draft is a Claude Code plugin that implements Context-Driven Development methodology. It provides a two-tier command surface: 4 primary workflow commands (/draft:init, /draft:new-track, /draft:implement, /draft:review) plus 5 routers (/draft:plan, /draft:ops, /draft:docs, /draft:discover, /draft:jira) as the recommended public interface. 24 specialist commands are dispatched underneath the routers. The unified /draft:jira router supports preview, create, and the advanced review <JIRA-ID> qualification pipeline (deep-review + bughunt + coverage + test-gap analysis). Run /draft for the full intent map. Total surface: 33 skills.

Draft also ships a knowledge graph engine — codebase-memory-mcp, fetched on install to ~/.cache/draft/bin/ (not vendored; see bin/README.md) — driven by scripts/tools/ (53 deterministic shell helpers). Skills are markdown (source of truth, processed by a bash build script into platform-specific integration files for Copilot and Gemini); the graph engine and shell helpers handle mechanical work that markdown can't.

Build & Test Commands

make build              # Generate integration files from skills
make build-integrations # Same as above (explicit target)
make test               # Run all 83 test suites (skills, build, tools)
make lint               # Run shellcheck + markdownlint
make clean              # Remove generated integrations

# Run a single test
./tests/test-skill-frontmatter.sh
./tests/test-build-integrations.sh
./tests/test-tools-classify-files.sh
# etc. — any test in tests/ is independently executable

# Graph engine (codebase-memory-mcp — fetched on install, not vendored)
scripts/fetch-memory-engine.sh                          # install engine to ~/.cache/draft/bin/
scripts/tools/graph-snapshot.sh --repo .                # index repo + write draft/graph/schema.yaml gate
scripts/tools/hotspot-rank.sh --repo .                  # fan-in-ranked hotspots (live query)
scripts/tools/graph-impact.sh --repo . --symbol <name>  # blast radius for a symbol (live query)

# Prerequisites: Bash 4.0+, jq (graph tools), Node 18+ (draft CLI), python3 (OKF mode:
#                okf-fix-links.sh / okf-render-views.sh), shellcheck, markdownlint-cli (lint only)

Tests use a custom bash framework (tests/test-helpers.sh) with assert(), pass(), fail() helpers. No external test runner.

Architecture

Build Pipeline (the critical path)

skills/<name>/SKILL.md  ──┐
core/methodology.md       ├──→  scripts/build-integrations.sh  ──→  integrations/copilot/.github/copilot-instructions.md
core/shared/*.md          │                                          (~25,300 lines, auto-generated)
core/templates/*.md       ├──→  (Gemini uses bootstrap .gemini.md — no longer generated)
core/agents/*.md          ──┘

The build script (scripts/build-integrations.sh) reads SKILL_ORDER, CORE_FILES, and TOOLS from scripts/lib.sh (sourced) and:

1. Iterates SKILL_ORDER (33 skills in current two-tier model, order matters)
2. Validates YAML frontmatter (name: and description: required)
3. Validates body format: blank, # Title, blank, then content
4. Extracts body via extract_body(), skipping frontmatter
5. Applies syntax transforms (/draft:command → draft command; @architect, @debugger, etc. → @workspace for Copilot)
6. Inlines 66 core reference files (methodology, shared procedures, templates, agents, guardrails)
7. Writes atomically to a temp file then renames into place
8. Runs verify_output() — line count, completeness, syntax

Source of Truth Hierarchy

1. core/methodology.md — Master methodology (update first)
2. skills/<name>/SKILL.md — Skill implementations (derive from methodology)
3. integrations/copilot/.github/copilot-instructions.md — GENERATED, never edit directly

Key Directories

• core/shared/ — Shared procedures loaded by skills (context loading, git metadata, pattern learning, cross-skill dispatch, Jira sync, graph queries, parallel analysis, VCS commands)
• core/agents/ — Behavioral protocols for specialized agents (architect, debugger, planner, rca, reviewer, ops, writer)
• core/templates/ — 28 templates for files that /draft:init generates in user projects (24 top-level + 4 okf/ bundle templates for DRAFT_INIT_MODE=okf)
• bin/ — Holds only README.md. The graph engine (codebase-memory-mcp) is not vendored — it is fetched on install (scripts/fetch-memory-engine.sh) to ~/.cache/draft/bin/ and resolved by scripts/tools/_lib.sh:find_memory_bin() (DRAFT_MEMORY_BIN → $PATH → cache). Output gate marker under draft/graph/schema.yaml; all structural data is queried live. CLI and schema documented in bin/README.md.
• scripts/tools/ — 53 deterministic shell helpers (git-metadata, classify-files, hotspot-rank, cycle-detect, graph-* capability wrappers, resolve-tools.sh, etc.). Skills call these for mechanical work. All knowledge-graph Cypher lives in the sourced _graph_queries.sh module (single source of query truth); the graph-*.sh wrappers are thin arg-parse → builder → fail-loud JSON.
• scripts/lib.sh — Shared definitions sourced by build script: SKILL_ORDER, SKILL_META, CORE_FILES, TOOLS.
• scripts/benchmark/ — Efficacy-benchmark harness (bench-checkout.sh, bench-grade.sh, bench-report.sh). Protocol in docs/benchmark/README.md — public by design: a pre-registered protocol is what makes the published numbers credible. Not part of the shipped plugin. Note docs/internal/ is gitignored; nothing under it ships.
• web/ — Static website deployed to GitHub Pages (getdraft.dev), deployed via .github/workflows/pages.yml. Includes the Draft Book (22 chapters + 2 appendices) under web/book/.
• docs/tracker/ — Sharded work tracker: INDEX.md rollup + one file per major work. Read the index, open only the tracker you act on.
• draft/ — Dogfooding: Draft's own context files, generated by running /draft:init on this repo

CI

.github/workflows/ holds three workflows:

The repo-size gate exists because plugin marketplace add git-clones this repo — anything in HEAD is downloaded before install can proceed. Never commit large assets; attach them to a Release.

Skill File Format (strict)

---
name: skill-name
description: Brief description
---

# Skill Title

Execution instructions below...

After the closing ---, the body must be: (1) blank line, (2) # Title heading, (3) blank line, (4) content. The build script skips the first 3 body lines (tail -n +4) when inlining into integrations. Violating this format produces silent corruption in the generated output.

Progressive Disclosure: skills/<skill>/references/*.md

A skill may ship supplementary content under skills/<skill>/references/*.md (top-level .md files only). The build script inlines these into the Copilot integration immediately after the SKILL body, sorted alphabetically, with the same syntax transforms applied. Use this for detail that bloats SKILL.md beyond the 1,500–2,000-word target (advanced patterns, schemas, exhaustive examples).

Coverage in tests: tests/test-skill-references.sh.

Syntax Transformation Rules

The build script transforms skill content for platform compatibility:

• /draft:command → draft command (Copilot uses bare syntax, no slash prefix)
• @architect, @debugger, etc. → @workspace (Copilot agent references)

Maintaining the Plugin

Updating Methodology

1. Update core/methodology.md first
2. Apply changes to relevant skills/ SKILL.md files
3. Run ./scripts/build-integrations.sh to regenerate integrations
4. Update this CLAUDE.md only if core concepts change

Adding a New Skill

1. Create skills/<skill-name>/SKILL.md with frontmatter (kebab-case name, no path traversal chars)
2. Add skill name to SKILL_ORDER in scripts/lib.sh
3. Add a <name>|<header>|<trigger> row to SKILL_META in scripts/lib.sh (coverage-checked by tests/test-trigger-functions.sh)
4. Run make build && make test (plugin.json auto-discovers skills via directory convention)
5. Document in README.md and CHANGELOG.md

Adding a New Tool

1. Create scripts/tools/<tool-name>.sh (kebab-case, lowercase)
2. Add to TOOLS array in scripts/lib.sh (tests/test-tools-registered.sh reads this array dynamically and validates the new entry — no separate allowlist to update)
3. Create a test at tests/test-tools-<tool-name>.sh and add it to TEST_SCRIPTS in Makefile
4. Run make test

Plugin Manifest

.claude-plugin/plugin.json — registers skills with Claude Code. The skills field uses a directory path ("./skills/") for auto-discovery; SKILL_ORDER in the build script controls integration generation order (these are independent).

Releasing / Bumping the Version

package.json is the single source of truth for the version. Never hand-edit the version anywhere else. Bump with:

npm version <patch|minor|major|x.y.z>   # writes package.json, runs the `version` hook
git push --follow-tags origin main      # the tag push publishes the GitHub Release and npm

Do not run npm publish by hand: release.yml publishes from a clean checkout of the tag, so the tarball matches the tag and carries no untracked build leftovers.

The npm version lifecycle hook runs scripts/sync-version.sh --stage, which propagates the new version into .claude-plugin/plugin.json, .claude-plugin/marketplace.json, .cursor-plugin/plugin.json, and the website's version labels (the nav version pill on every page, the landing hero's REV, the book landing's REV), then git adds exactly those files — so they all land in the bump commit atomically. Release copy (headlines, dates, changelog prose, the site changelog's Latest entry) stays hand-written. tests/test-version-sync.sh (in make test) fails CI if any consumer drifts from package.json; run bash scripts/sync-version.sh to fix.

End-User Context

When users run /draft:init, it creates a draft/ directory in their project. Output mode is tier-gated (DRAFT_INIT_MODE unset → tier 1–2 monolith, tier 3–5 okf; explicit DRAFT_INIT_MODE=monolith|okf overrides). Mode changes only the architecture.md / .ai-context.md packaging; all other files below are produced in both modes.

Always produced (mode-independent):

• index.md — Plain docs index listing the prose context files and tracks.md; notes the graph is engine-only.
• product.md, tech-stack.md, workflow.md, guardrails.md — Project config files
• .ai-profile.md — Ultra-compact 20-50 line always-injected profile (derived from .ai-context.md)
• tracks/ + tracks.md — Individual feature/fix tracks with spec.md, plan.md, metadata.json (includes impact block: files_touched, modules_touched, downstream_files, by_category)
• .state/ — Freshness hashes, signal classification, run memory for incremental refresh
• graph/ — Holds only schema.yaml (gate marker: engine metadata, point-of-index counts; access: engine-live). All structural graph data is queried live from the codebase-memory-mcp engine via the scripts/tools/graph-*.sh wrappers.

Packaging differs by mode:

• monolith (tier 1–2 default) — architecture.md is the source of truth (10-section graph-primary reference with Mermaid); .ai-context.md is the token-optimized AI context derived from it, sized by repo tier (100–900 lines).
• okf (tier 3+ default) — wiki/ is the source of truth (OKF concept taxonomy, one concept per file); .ai-context.md is the index root (Synopsis + Concept Map); architecture.md is a generated rendered view of the bundle; wiki/web/index.html is an optional offline viewer. See skills/init/references/okf-emitter.md.

Status markers in tracks: [ ] Pending, [~] In Progress, [x] Completed, [!] Blocked

Quality Disciplines

• Verification Before Completion: No completion claims without fresh verification evidence
• Systematic Debugging: Investigate → Analyze → Hypothesize → Implement (see core/agents/debugger.md)
• Root Cause Analysis: Reproduce → Trace → Hypothesize → Fix with blast radius scoping (see core/agents/rca.md)
• Three-Stage Review: (1) Automated Validation, (2) Spec Compliance, (3) Code Quality (see core/agents/reviewer.md)

Communication Style

Lead with conclusions. Be concise. Direct, professional tone. Code over explanation.

Code wiki (graphwiki)

Graph-grounded wiki at /tmp/draft-wiki-cmp/. Start at /tmp/draft-wiki-cmp/.ai-context.md for the concept index, or /tmp/draft-wiki-cmp/architecture.md for the system map. Refresh with graphwiki update.