# Specsmith > AEE governance CLI for AI-assisted dev — WI lifecycle (specsmith wi), preflight gates, multi-agent dispatch, requirements<->test traceability, ESDB, MCP server, compliance, 64 project types, 136 skills, and 1607 tests. - **Type:** MCP server - **Install:** `agentstack add mcp-layer1labs-specsmith` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [layer1labs](https://agentstack.voostack.com/s/layer1labs) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [layer1labs](https://github.com/layer1labs) - **Source:** https://github.com/layer1labs/specsmith - **Website:** https://specsmith.readthedocs.io ## Install ```sh agentstack add mcp-layer1labs-specsmith ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # specsmith [](https://github.com/layer1labs/specsmith/actions/workflows/ci.yml) [](https://github.com/sponsors/layer1labs) [](https://specsmith.readthedocs.io/en/stable/) [](https://pypi.org/project/specsmith/) [](https://www.python.org/downloads/) [](https://github.com/layer1labs/specsmith/blob/main/LICENSE) SpecSmith is the governance layer for AI-assisted development: it sits between agents and your repo, enforces preflight decisions, and records requirement/test traceability with auditable evidence. It is **not** an IDE, autonomous coding agent, CI runner, or legal-compliance certifier. Use SpecSmith when changes need repeatable controls, work-item lineage, and review-ready artifacts; do not use it for throwaway prototyping where governance overhead is unnecessary. Compared with GitHub Spec Kit, OpenSpec, and BMAD, SpecSmith adds execution-time policy gates and trace chains. Compared with Aider, Claude Code, and Cursor, SpecSmith governs those clients instead of replacing them. Compared with LangGraph and AutoGen, SpecSmith prioritizes software-governance outcomes and evidence quality over general-purpose multi-agent orchestration. ## Architecture at a glance ``` AI Agents / IDE Clients | v SpecSmith Governance Layer ├── Repository Files ├── Requirements and Tests ──> CI and MCP Integrations └── ESDB / Audit Ledger ──> CI and MCP Integrations ``` ## When to use / when not to use - Use when you need governed AI development, auditable decision trails, and requirement-to-test linkage. - Avoid when rapid local prototyping is the only goal and formal governance is unnecessary. ## Comparison summary - **GitHub Spec Kit / OpenSpec / BMAD:** strong specification practices; SpecSmith adds execution-time governance, work-item lifecycle control, and trace-chain evidence. - **Aider / Claude Code / Cursor:** agentic coding interfaces; SpecSmith is the policy and evidence layer around these clients. - **LangGraph / AutoGen:** orchestration frameworks; SpecSmith is a governance-first development layer with compliance-oriented traceability. ### Governance efficiency benchmark We ran a [multi-condition benchmark](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) comparing specsmith governance against 11 alternatives (ungoverned, BMAD, Cursor rules, Copilot, Aider, Cline, Codex CLI, OpenSpec, Agile BDD/TDD, and context injection) across real coding tasks with gpt-4o-mini and gpt-5.5. | Condition | Pass Rate | Mean Tokens | Cost/run | Cost-of-Pass | |---|---|---|---|---| | Ungoverned (raw agent) | 0% on T1 | 44.6k | $0.0079 | ∞ | | Context injection (CLAUDE.md) | 100% | 43.7k | $0.0084 | $0.0084 | | BMAD-style structured prompting | 50% | 139.1k | $0.0262 | $0.0523 | | **specsmith LIGHT (preflight)** | **100%** | **21.1k** | **$0.0032** | **$0.0032** | | **specsmith FULL (governed)** | **100%** | **17.1k** | **$0.0026** | **$0.0026** | **Key findings:** specsmith FULL is the only condition to achieve 100% pass rate on the feature-addition task (T1). It uses 2.6× fewer tokens than ungoverned and produces a cost-of-pass 3.2× lower than the next-best alternative. With gpt-5.5, governance reduces cost-of-pass by **6.3×** ($0.028 vs $0.179). See the [full benchmark report](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) and [model comparison (gpt-4o-mini vs gpt-5.5)](https://specsmith.readthedocs.io/en/stable/model-comparison/). **v0.20.0** — Native Warp integration: `specsmith integrate warp` scaffolds `.warp/` MCP + launch configs and a Warp-aware `specsmith run` banner (REQ-444). Plus VRAM-aware local model recommendations: `specsmith local-model recommend` prints a per-role lineup (default / fast / harder pass / general) with a `fits`/`tight`/`spills` fit assessment (REQ-445). **v0.19.x** — `specsmith wi link-test`, the governance-YAML content auditor and sync markdown-reconcile warnings, and a HuggingFace provider + 15-model multi-provider benchmark matrix for GovernanceBench. **v0.18.0** — ESDB-first dual-write architecture (every governance event is written to ESDB alongside the append-only `LEDGER.md`), the `specsmith inspect` session-start governance block, and a token-pricing / cost-of-pass module. **v0.17.x** — Canonical `docs/SPECSMITH.yml` scaffold path adopted across every CLI command, with CodeQL alerts driven to zero. specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689) and the NIST AI Risk Management Framework 1.0. Every agent action is cryptographically sealed, every AI-generated output is disclosed, context windows are GPU-aware, and compliance settings are configurable per-session and per-project. ### Selected CLI highlights ```bash specsmith governance-serve --port 7700 # governance REST API specsmith sync # YAML → JSON → MD (YAML-first mode) specsmith generate docs # regenerate REQUIREMENTS.md + TESTS.md specsmith validate --strict # dup IDs, orphans, coverage gaps specsmith agent permissions-check git_push # tool permission gate (REQ-012) specsmith ollama gpu # detect GPU VRAM, recommend context size specsmith local-model recommend # VRAM-aware model lineup (fits/tight/spills) specsmith integrate warp # scaffold Warp-native governance (MCP + launch config) specsmith export # generate full compliance report # Update channels specsmith channel set stable # pin to stable releases specsmith channel set dev # opt in to pre-release builds # ESDB lifecycle specsmith esdb export --json # dump records to JSON snapshot specsmith esdb backup # create timestamped snapshot specsmith esdb compact # WAL compaction # Skills specsmith skills deactivate # set active=false specsmith skills delete --yes # permanently remove # MCP + agent dispatch specsmith mcp generate "Search USPTO patents" --json specsmith agent ask "show esdb status" --json-output ``` It also co-installs the standalone `epistemic` Python library for direct use in any project: ```python from epistemic import AEESession # works in any Python 3.10+ project from epistemic import BeliefArtifact, StressTester, CertaintyEngine ``` > **Library vs CLI:** The `specsmith` CLI requires pipx for isolation. The `epistemic` library > (and `specsmith.esdb`) work in any venv — `pip install specsmith` is all you need for > library-only use. The pipx guard only fires on CLI invocations. --- ## What is Applied Epistemic Engineering? AEE treats requirements, decisions, and assumptions — the beliefs your project depends on — as engineering artifacts subject to the same discipline as code: version control, testing, and refactoring. **The 4-step core method: Frame → Disassemble → Stress-Test → Reconstruct** **The 5 foundational axioms:** 1. **Observability** — every belief must be inspectable 2. **Falsifiability** — every belief must be challengeable 3. **Irreducibility** — beliefs decompose to atomic primitives 4. **Reconstructability** — every failed belief can be rebuilt 5. **Convergence** — stress-test + recovery always reaches Equilibrium --- ## The AEE Workflow — 7 Phases specsmith tracks your project through the full AEE development cycle: ``` 🌱 Inception → 🏗 Architecture → 📋 Requirements → ✅ Test Spec → ⚙ Implementation → 🔬 Verification → 🚀 Release ``` ```bash specsmith phase # show current phase + readiness checklist specsmith phase next # advance to the next phase (runs checks first) specsmith phase set requirements # jump to a specific phase specsmith phase list # list all phases ``` The current phase is persisted in `scaffold.yml` as `aee_phase`. Each phase has a checklist of file/command criteria, recommended commands, and a readiness percentage. ## 1.0 release criteria status | Criterion | Status | Source | |---|---|---| | Stable CLI core contract documented | In progress | `docs/stability.md` | | Stable generated file schemas documented | In progress | `docs/stability.md` | | Stable MCP tool schemas documented | In progress | `docs/stability.md` | | Migration tests linked (#218) | In progress | `docs/roadmap/1.0-criteria.md` | | Security threat model documented | In progress | `docs/security-threat-model.md` | | Docs/tutorial/glossary baseline complete | In progress | `docs/roadmap/1.0-criteria.md` | | Upgrade path and changelog criteria defined | In progress | `docs/roadmap/1.0-criteria.md` | --- ## Install **Recommended — via pipx (CLI + CI):** ```bash pipx install specsmith ``` That's it. `specsmith audit`, `preflight`, `sync`, `checkpoint`, `esdb`, `mcp serve`, and all governance commands work immediately with no additional packages. > **Want `specsmith run` with a cloud LLM?** Inject the provider SDK only if you use > the built-in agentic REPL with a cloud API key: > > ```bash > pipx inject specsmith anthropic # if you set ANTHROPIC_API_KEY > pipx inject specsmith openai # if you set OPENAI_API_KEY > pipx inject specsmith google-genai # if you set GOOGLE_API_KEY > ``` > > Ollama works out of the box with no injection — specsmith uses stdlib HTTP. > For Warp, Claude Code, Cursor, and Copilot, the AI client provides the LLM; > no injection needed. **Library-only use (venv / conda / any Python environment):** ```bash pip install specsmith # epistemic library + SQLite ESDB — no pipx needed ``` This makes `from epistemic import AEESession` and `from specsmith.esdb import SqliteStore` immediately importable. The pipx isolation guard only applies to the `specsmith` CLI command — not to library imports. Use this when you want the AEE belief-state machinery in your own application without managing a pipx environment. **ESDB — Epistemic State Database** Terminology used in this repo is strict: - **ESDB** = the specification/data model category. - **SQLite backend** = the free/default ESDB implementation bundled in `specsmith`. - **ChronoMemory** = the commercial package. - **ChronoStore** = the backend engine/class provided by the ChronoMemory package. | Tier | Package | License | What you get | |------|---------|---------|-------------| | **Default** | `specsmith` (built-in) | MIT, free | SQLite backend — requirements, test cases, confidence filtering | | **Commercial** | `chronomemory` via `specsmith[esdb]` | Proprietary — license required (see [COMMERCIAL-LICENSE.md](https://github.com/layer1labs/specsmith/blob/develop/COMMERCIAL-LICENSE.md)) | ChronoMemory package (ChronoStore backend): tamper-evident SHA-256 WAL, OEA anti-hallucination fields, Rust acceleration, epistemic rollback | See `docs/editions.md` for the full OSS vs commercial feature matrix. `pip install specsmith` always installs the **free SQLite backend** automatically. No additional packages, no license key, no configuration — it works out of the box. ```bash specsmith esdb status # shows: SQLite (free, MIT) — active by default ``` **ESDB version-control policy (this repository):** - Commit canonical SQLite state file: `.specsmith/esdb.sqlite3`. - Commit canonical ChronoMemory state files: `.chronomemory/events.wal` and `.chronomemory/snapshot.json`. - Do not commit ChronoMemory timestamped backup copies under `.chronomemory/backup/` (regenerated by `specsmith save` / `specsmith esdb backup`). **Upgrading to ChronoMemory (ChronoStore backend, commercial):** If you hold a chronomemory ESDB license, activate the commercial backend: ```bash # Step 1 — install the chronomemory package pip install "specsmith[esdb]" # installs chronomemory from PyPI # or if using pipx: pipx inject specsmith "chronomemory>=0.2.0" # inject into the specsmith pipx venv # Step 2 — activate your license key specsmith esdb enable --key-file /path/to/your.esdb.key # The key is copied to ~/.specsmith/esdb.key and used automatically from now on. # Step 3 — verify ChronoStore is active specsmith esdb status # ● ESDB — ChronoStore WAL (chronomemory commercial) # ✔ License: your-org (expires YYYY-MM-DD) ``` To obtain a chronomemory ESDB license: [licensing@layer1labs.ai](mailto:licensing@layer1labs.ai) · [ESDB licensing docs](https://specsmith.readthedocs.io/en/stable/esdb/#licensing) · [ChronoMemory commercial terms](https://github.com/layer1labs/specsmith/blob/develop/COMMERCIAL-LICENSE.md) See the [full ESDB docs](https://specsmith.readthedocs.io/en/stable/esdb/) for a feature comparison and Python API reference. **Upgrading specsmith:** ```bash pipx upgrade specsmith # preferred — upgrades the pipx-isolated CLI specsmith self-update # alternative: self-update from within specsmith ``` --- ## Quick Start ```bash # 1. Install pipx install specsmith # 2. Start a new project (or import an existing one) specsmith init # interactive scaffold wizard specsmith import --project-dir ./my-project # adopt an existing repo # 3. Bootstrap every session (run once at the start of each work session) specsmith migrate run # apply any pending schema migrations specsmith audit # verify governance health specsmith sync # YAML → JSON → MD sync specsmith checkpoint # emit GOVERNANCE ANCHOR # 4. Before every code change: preflight specsmith preflight "add paginated GET /todos endpoint" # gate the intent # → decision: accepted | needs_clarification + work_item_id: WI-XXXXXXXX # 5. After making changes: verify + save specsmith verify # check equilibrium specsmith save # commit governance state + push # 6. Check AEE workflow phase and health specsmith phase # current phase + readiness % specsmith audit # full governance health check ``` > **Agentic REPL:** run `specsmith run` to start the Nexus governance-gated LLM REPL. > Every utterance is preflighted automatically. Use `/why` to see the governance trace. > For the multi-agent DAG dispatcher, see `specsmith dispatch run ""`. ### Standalone CLI (no AI agent) All governance commands work without any AI agent or IDE integration: ```bash specsmith audit # governance health check specsmith preflight "" --json # gate a change specsmith verify # check equilibrium after changes specsmith save # ESDB backup + commit + push specsmith kill-session # clean shutdown ``` For the full standalone session workflow, Nexus REPL usage, multi-agent dispatcher, and CI integration: **[Standalone CLI docs →](https://specsmith.readthedocs.io/en/stable/standalone-cli/)** --- ## Machine State Sync + YAML Governance As of v0.11, specsmith uses **YAML-first governance**: `docs/requirements/*.yml` and `docs/tests/*.yml` are the canonical sources. `REQUIREMENTS.md` and `TESTS.md` are **generated artifacts** — do not hand-edit them. ```bash # YAML-first pipeline (v0.11+) specsmith sync # YAML → .specsmith/*.json → docs/*.md (all in one) specsmith generate docs # regenerate only the Markdown artifacts from YAML specsmith generate docs --check # dry-run: report what would change specsmith validate --strict # enforce schema: dup IDs, orphans, missing fields specsmith validate --strict --json # machine-readable validation result # CI guard (already in .github/workflows/ci.yml) specsmith sync --check # exits 1 if JSON cache is out of sync with YAML ``` **To add a new requirement**, edit the appropriate `docs/requirements/.yml` file and run `specsmith sync`. **Never** hand-edit `docs/REQUIREMENTS.md` — it will be overwritten by the next sync. **Domain files:** | File | REQ range | Domain | |---|---|---| | `docs/requirements/governance.yml` | REQ-001..064 | Core AEE governance | | `docs … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [layer1labs](https://github.com/layer1labs) - **Source:** [layer1labs/specsmith](https://github.com/layer1labs/specsmith) - **License:** MIT - **Homepage:** https://specsmith.readthedocs.io Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-layer1labs-specsmith - Seller: https://agentstack.voostack.com/s/layer1labs - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.