Specsmith

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 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 and model comparison (gpt-4o-mini vs gpt-5.5).

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

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:

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

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):

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):

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) | 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.

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:

# 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 · ChronoMemory commercial terms See the full ESDB docs for a feature comparison and Python API reference.

Upgrading specsmith:

pipx upgrade specsmith   # preferred — upgrades the pipx-isolated CLI
specsmith self-update    # alternative: self-update from within specsmith

---

Quick Start

# 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:

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 →

---

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.

# 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
• Source: layer1labs/specsmith
• License: MIT
• Homepage: https://specsmith.readthedocs.io

Install and usage instructions live in the source repository linked above.