A CLI tool that reverse-engineers structured OpenSpec specifications from existing codebases, continuously detects spec-to-code drift, and provides semantic navigation for AI agents.
spec-gen is a TypeScript-based CLI tool (npm package spec-gen-cli, version 1.3.3) focused on reverse-engineering structured OpenSpec specifications from existing codebases. Its core workflow spans three layers:
Static Analysis Layer: Leverages tree-sitter for AST parsing across 9 languages (TypeScript, JavaScript, Python, Go, Rust, Ruby, Java, C++, Swift), building cross-language dependency graphs, auto-clustering business domains, and extracting DB schemas (Prisma, TypeORM, Drizzle, SQLAlchemy), HTTP routes (Express, NestJS, Next.js, FastAPI, Flask), UI components (React, Vue, Svelte, Angular), middleware chains, and environment variables. Notably, it performs cross-language HTTP edge detection, matching JS/TS fetch/axios calls to Python FastAPI/Flask route definitions.
Spec Generation & Governance Layer: A six-stage LLM-driven pipeline (project investigation → entity extraction → service analysis → API extraction → architecture synthesis → ADR enrichment) outputs OpenSpec-formatted specifications (GIVEN/WHEN/THEN scenario structure). The companion drift detection (spec-gen drift) runs purely statically in milliseconds, covering five drift types: Gap, Stale, Uncovered, Orphaned, and ADR Gap/Orphaned, with --use-llm to reduce false positives and --suggest-tests to link affected domain test files. Architecture decision tracking (spec-gen decisions) enforces pre-commit review via gate hooks, supporting interactive TUI, structured JSON (ACP-compatible IDE), and Agent JSON modes.
Test & Integration Layer: Test generation (spec-gen test) parses scenario blocks into executable test skeletons, with a THEN-clause pattern engine generating assertions without LLM, supporting Vitest, Playwright, pytest, Google Test, and Catch2, with --min-coverage <n> CI gating and // spec-gen: {} annotation tags for location-agnostic coverage tracking. An MCP server (spec-gen mcp) exposes semantic search and call graph expansion for AI agents. It also auto-generates AI tool config files like CLAUDE.md, .cursorrules, .clinerules/, .vibe/skills/. Dependency graph visualization (spec-gen view) is powered by an embedded React 19 + Vite 7 viewer.
Installation & Usage: Requires Node.js >= 20.0.0. After npm install -g spec-gen-cli, use spec-gen init to initialize, spec-gen analyze --ai-configs for static analysis, spec-gen generate for spec generation (requires API key), and spec-gen drift for drift detection. Nix/NixOS source installation is supported. Analysis artifacts are stored in .spec-gen/analysis/ (structured JSON), spec outputs in openspec/specs/ and openspec/decisions/. Internally uses LanceDB + Apache Arrow for vector semantic search, Commander.js for CLI, and chokidar for file watching.
Unconfirmed Information: npm publish page URL inferred from package.json but not directly verified; @fission-ai/openspec specification standard details not elaborated in README; full MCP server tool schema not listed; specific LLM provider list not explicitly stated.