capstone

Capstone Toolkit

Lightweight spec-driven development plugin for Claude Code. Keeps capstone projects aligned with structured specs, prevents regressions with gated merges, and maintains shared decisions across the team.

What's included

Skills

Skill	Description
/spec	Interactive spec builder: natural language description to full feature spec with acceptance criteria and machine-readable FeatureSpec JSON
/merge	Spec-gated merge: validates branch strategy (feature → dev → main), runs build/test/lint gates, walks acceptance criteria from the spec, reviews the diff, and catches regressions with post-merge tests
/scout --bootstrap	One-time repo onboarding: scans an unfamiliar codebase and generates CLAUDE.md (conventions) + decisions.sql (architectural decisions) so every teammate's Claude understands the project the same way
/audit	Code audit with scored report and per-finding acceptance criteria. Use --claude-only for zero external dependencies, or dual-engine mode (Gemini + Claude) for deeper analysis

Decision Memory MCP Server

Persists project decisions ("we use tRPC, not REST — because X") to SQLite with a portable SQL dump (decisions.sql) committed to git. Prevents the same architectural debate from happening four times.

Tools exposed:

• record_project_decision -- record a decision with file scope patterns
• query_project_decisions -- search by text query and/or file patterns
• get_decision -- look up a single decision by ID
• query_decisions_by_domain -- filter active decisions by domain
• sync_decision_store -- force rebuild from SQL dump

Installation

Local (development)

claude --plugin-dir ./capstone-toolkit

From GitHub

/plugin install kelsi-andrewss/capstone-toolkit

Dependencies

• Python 3.10+ -- required for decision memory and scout generators
• mcp (pip install mcp) -- required for the decisions MCP server
• fastembed (pip install fastembed) -- optional, enables semantic search in decision memory. Without it, keyword search (FTS5) still works.

Workflow

/scout --bootstrap /path/to/repo     (one-time: onboard the codebase)
         |
         v
/spec <product> <description>         (write the contract)
         |
         v
   implement on feature branch
         |
         v
/merge                                (feature → dev, spec-gated)
         |
         v
/merge --to-main                      (dev → main, promotion gate)

Use /audit at any point to review code quality.

• scout --bootstrap generates CLAUDE.md and decisions.sql from the codebase so Claude knows the project conventions
• spec builds a feature spec with acceptance criteria — this becomes the source of truth for merge gates
• merge enforces branch strategy and validates the code against the spec before allowing merge
• audit runs a structured code review with severity scoring and acceptance criteria per finding

Branch Strategy

The merge skill enforces:

feature/xyz  ──→  dev  ──→  main
     │              │          │
  /merge        /merge      never
 (spec-gated)  --to-main    direct

• Feature branches merge to dev with full gates: build, test, lint, spec acceptance criteria, diff review
• dev merges to main as a promotion gate (build + test + regression check)
• Direct pushes to main are blocked — all work flows through dev
• Post-merge regression tests catch integration issues immediately

Decision Memory

Decisions are stored in two forms:

1. decisions.sql -- SQL dump committed to git. Text-based, diffable, mergeable. Source of truth.
2. decisions.db -- Local SQLite rebuilt from the dump on demand. Gitignored.

After git pull, the local DB auto-rebuilds if the dump changed. No manual sync needed.

License

MIT