SpecAnvil
SpecAnvil sets up spec-driven development in an existing repository with one command. It builds a local code index, detects the stack and conventions, and writes the configuration an AI coding tool needs to work from specifications: a code-index MCP server that returns symbols instead of whole files, project-specific skills, role agents, lifecycle workflows from ticket grooming to end-to-end tests, and connectors for the ticket system and databases in use.
It supports Claude Code, GitHub Copilot, Cursor, Augment Code, Windsurf, OpenAI Codex, Kiro, Gemini CLI and Replit. Indexing, detection and analysis run locally and make no network calls.
cd your-repo
specanvil init # about 1 second on a 250-file repo; no AI calls
claude # then: /sa:learn, /sa:flow PROJ-123
Documentation: architecture and decision records · benchmarks and evals · tool reference · AI coding tool support · roadmap · changelog
Formerly SpecForge. Repositories set up under the old name are upgraded by the next specanvil init, and the specforge and specforge-mcp commands remain as aliases. Workflows are /sa:<name>; before 0.10 they were /sf:<name>.
Measured results
Every figure below is reproducible from this repository. Methods, commits and caveats are in docs/BENCHMARKS.md; the rows marked CI gate fail the build if they regress.
| Measurement | Result |
|---|
| Tokens returned for 13 typical lookups, against reading the files involved (full-stack-fastapi-template) | 84% fewer (about 22k against 142k) |
| Retrieval: is the symbol an engineer needs in a 4k-token context? 150 questions, 9 repositories, 9 languages (Python, JavaScript, Go, Java, C#, Rust, PHP, Ruby, Kotlin) | found 97%, MRR 0.76 (CI gate: 90%, 0.60) |
| Retrieval on the original 12-task set (Python and TypeScript) | recall 1.00, MRR 0.86 (CI gate: 0.95, 0.75) |
| Static call graph against execution: 779 caller/callee pairs observed while running the unit tests | 92% present in the graph (CI gate: 85%) |
| Calls through injected dependencies (Spring, NestJS, ASP.NET Core): 66 hand-checked call sites in 5 repositories | 66 resolved to the right method, 0 to a wrong one (CI gate: 95%); 14 of 15 on the held-out repository at first run |
| Cold index including call and import graphs (express / fastapi / gin) | 0.3 s / 3.4 s / 0.4 s |
| Scale: Kubernetes (25,126 files, 397,268 symbols) on 2 cores | cold index 67 s, peak memory 393 MB, refresh with no changes 0.3 s, search about 70 ms |
| Refresh after one edit, Django (5.6k files) | 0.14 s |
| Tool schema sent on every turn | about 790 tokens by default (6 tools); about 8,100 with all 96 tools loaded |
Paraphrased tasks that share no words with the code, get_context | 8 of 12 with local embeddings, 3 of 12 without |
| Network calls during indexing | none (a test blocks sockets) |
Install
Requires Python 3.10 or later. Node 18+ (npx) and uv (uvx) are needed only by the connectors that use them.
pipx install git+https://github.com/Abdulwahab26/SpecAnvil # or: uv tool install git+https://github.com/Abdulwahab26/SpecAnvil
specanvil doctor
specanvil-mcp must be on the PATH so the AI coding tool can start it from its MCP configuration.
Supported AI coding tools
specanvil init detects the tools a repository already uses from their configuration folders and writes the same setup in each tool's own format: always-on rules, the lifecycle workflows, role agents, skills and the MCP connection. Select tools explicitly with --agents cursor,copilot or --agents all.
| Tool | Run a workflow | Files SpecAnvil writes |
|---|
| Claude Code | /sa:groom | CLAUDE.md, .claude/commands, .claude/agents, .claude/skills, .mcp.json |
| GitHub Copilot | /sa-groom | AGENTS.md, .github/prompts, .github/agents, .github/skills, .vscode/mcp.json |
| Cursor | /sa-groom | AGENTS.md, .cursor/commands, .cursor/rules/*.mdc, .cursor/mcp.json |
| Augment Code | /sa:groom | AGENTS.md, .augment/commands, .augment/skills, MCP import file |
| Windsurf / Devin Local | sa-groom skill | AGENTS.md, .agents/skills, .devin/mcp_config.json |
| OpenAI Codex | sa-groom skill | AGENTS.md, .agents/skills, .codex/agents, .codex/config.toml |
| Kiro | #sa-groom | AGENTS.md, .kiro/steering, feature specs in .kiro/specs/, .kiro/settings/mcp.json |
| Gemini CLI | /sa:groom | GEMINI.md, .gemini/commands/*.toml, .gemini/settings.json |
| Replit Agent | groom playbook | replit.md, .specanvil/playbooks; tools via specanvil tool <name> '<json>' (no local MCP) |
Per-tool limits and the documentation each format was checked against are in docs/PROVIDERS.md.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
