specsmith

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.

For Zoo Code / Roo Code, use the canonical setup, repair, and governed-context guide.

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.
• Use especially for larger projects where explicit governance, traceability, and release evidence matter; benchmark outcomes vary by task and model, so review the published limitations before making efficiency assumptions.
• Use with local LLMs like LMStudio, vLLM, or llama.cpp for maximum cost control and privacy
• 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

The latest completed multi-condition benchmark was a historical 13-condition run across seven coding and safety tasks. GPT-4o-mini completed all 182 cells; the Qwen run was interrupted by provider credit and rate-limit errors and is excluded from model comparisons. The simulated DISPATCH condition is now excluded because it did not invoke the real dispatcher, and hidden safety oracles, isolated governance, bounded context, and global cost-of-pass aggregation have been corrected before the next run.

Key finding: governance effects were task-dependent. LIGHT and FULL improved T10 from 0% to 100%, while governed conditions underperformed on T1 and T13. With only two repetitions per slice, these results are directional rather than a general efficacy claim. The benchmark now fails closed on incomplete provider data so unavailable cells cannot appear as 0%-pass/$0-cost model results.

Current Stats

• 52+ model profiles in registry (including Qwen3.6-35B-A3B)
• 12 focused Specsmith skills; generic capabilities stay with the host agent
• Development mode with improvement tracking and session analysis

See the full benchmark report and comparison validity report.

Development Mode Features

When enabled in project configuration, development mode provides:

• Enhanced logging for all agent interactions and decision-making processes
• Session analysis that tracks what worked, what didn't, and improvement suggestions
• Cost-per-correct-solution metrics to measure efficiency
• Automated improvement tracking to identify patterns and areas for optimization
• Session reports that can be generated for review and analysis

To enable development mode, set enable_development_mode: true in your project's .specsmith/config.yml file.

See the full benchmark report and comparison validity report.

v0.23.0 — Guided context compression, resilient SpecSmith/Zoo-Code config repair, replicated ESDB evidence, cross-platform release closure, and fail-closed GovernanceBench comparisons with Qwen3.6/GPT-5.6 model coverage.

v0.22.0 - Epistemic chat handoffs preserve source provenance for Zoo-Code and other agents, while a mergeable JSONL session-event log keeps collaboration state reviewable. This release also adds CPU-safe local-model fallback (REQ-445) and stable-release validation before PyPI publishing.

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
specsmith endpoints add lmstudio            # add LMStudio endpoint for BYOE support

# 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 <skill-id>     # set active=false
specsmith skills delete <skill-id> --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.

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:

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.

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
# The license verifier is included in base specsmith; no cryptography injection is needed.

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

An intent limited to maintaining the local pipx CLI is returned as the non-blocking environment_only preflight decision. It exits successfully and creates no project work item, ledger entry, or ESDB record. All --help invocations are read-only.

Quick Start

pipx install specsmith
cd your-project
specsmith import --project-dir .   # or `specsmith init` for a new project
specsmith audit --project-dir .

Then choose one agent path:

# Recommended: keep your existing agent and add native governance/MCP
specsmith integrate claude-code    # or cursor, copilot, gemini, aider, warp, windsurf
specsmith mcp serve --project-dir .

# Optional local fallback: start Grace with Ollama
specsmith run --provider ollama

The essential AEE loop is intentionally small:

specsmith preflight "describe the change; scope REQ-123" --json
# Implement with your native agent or Grace; run the project's normal tests.
specsmith verify --project-dir .
specsmith checkpoint --project-dir .

Inside Grace, start with /help and /status; use /why to inspect the governance trace. Older epistemic context is compressed before it enters the model token path. If you already use an AI coding tool, the native integration is preferred: Specsmith supplies requirements, linked tests, uncertainty, and evidence while the host retains its own Git, test, browser, and framework tools.

See the five-minute quick start for provider setup, Zoo/Roo repair, first-run errors, and the integration matrix.

Standalone CLI (no AI agent)

All governance commands work without any AI agent or IDE integration:

specsmith audit                     # governance health check
specsmith preflight "<intent>" --json  # gate a change
specsmith verify                    # check equilibrium after changes
specsmith save                      # ESDB backup + commit + push
specsmith kill-session              # clean shutdown

For Grace, headless use, and CI: 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/<domain>.yml file and run specsmith sync. Never hand-edit docs/REQUIREMENTS.md — it will be overwritten by the next sync.

Domain files:

Migration from Markdown-primary: scripts/migrate_governance_to_yaml.py once to convert an existing project. Idempotent — safe to re-run.

Least-Privilege Agent Permissions (REQ-012)

specsmith agent permissions                      # show active permission profile
specsmith agent permissions-check git_push       # check if git_push is allowed
specsmith agent permissions-check git_push --no-log  # dry-run (no ledger write)

Configure in docs/SPECSMITH.yml:

agent:
  permissions:
    preset: standard       # read_only | standard | extended | admin
    # Or custom:
    allow: [read_file, write_file, run_shell, git_status]
    deny:  [git_push, git_create_pr]

AI Compliance & Governance

DISCLAIMER — Best-effort only. specsmith is designed to help teams build auditable, explainable AI systems, but it does not guarantee compliance with any law or regulation. Regulations change frequently; final compliance determination is solely the responsibility of the end user. Layer1Labs makes no legal warranty. Found outdated coverage or a missing regulation? Open a ticket — we actively maintain the regulation database and welcome compliance PRs.

specsmith is designed from the ground up for auditable, explainable, and human-overseen AI. It implements concrete compliance mechanisms mapped to the two major regulatory frameworks that govern AI systems in production today.

Standards Coverage

EU AI Act (Regulation 2024/1689) — The world's first comprehensive legal framework for AI, enforced across the European Union. High-risk AI systems must provide transparency, auditability, human oversight, and robustness. specsmith implements:

NIST AI Risk Management Framework 1.0 (AI RMF) — The US standard for managing AI risk across the AI lifecycle. specsmith addresses all four core functions:

How Each Compliance Mechanism Works

1. Tamper-Evident Audit Log — TraceVault (REQ-206)

Every agent action, decision, milestone, and audit gate is recorded as a JSONL entry in .specsmith/trace.jsonl. Each entry contains a SHA-256 hash of its own content plus the hash of the previous entry, forming a cryptographic chain:

{"seq":1, "type":"DECISION", "description":"...", "hash":"a3f9...", "prev":"genesis"}
{"seq":2, "type":"MILESTONE", "description":"...", "hash":"7c2b...", "prev":"a3f9..."}

Any modification to a past entry breaks every subsequent hash. specsmith trace verify detects and reports the first corrupted entry. The file is append-only — overwrites are blocked by safe_write. This satisfies EU AI Act Art. 12 (logging and record-keeping) and NIST AI RMF GOVERN (accountability trail).

2. AI Disclosure — Every Response (REQ-207)

Every preflight response includes a mandatory ai_disclosure block:

{
  "ai_disclosure": {
    "governed_by": "specsmith",
    "governance_gated": true,
    "provider": "ollama",
    "model": "qwen2.5:14b",
    "spec_version": "0.20.0"
  }
}

This ensures every AI-generated output is traceable to its source model and version, meeting EU AI Act Art. 13 (transparency) and Art. 53 (GPAI transparency). It is impossible to suppress — the field is injected at the governance layer before any response is returned to the client.

3. Human Escalation — Configurable Threshold (REQ-209)

When an action's confidence is below the escalation threshold, specsmith sets escalation_required: true and includes an escalation_reason in the preflight payload. AI clients that support MCP will surface this via the governance_preflight tool response.

specsmith preflight "deploy to production" --escalate-threshold 0.85 --json
# → escalation_required: true, escalation_reason: "confidence 0.71 < threshold 0.85"

This implements EU AI Act Art. 14 (human oversight) and NIST AI RMF MANAGE.

4. Kill-Switch — Immediate Session Termination (REQ-210)

A kill-session CLI command immediately terminates all active agent sessions and records a timestamped kill event in LEDGER.md:

specsmith kill-session                   # terminate all sessions, log kill event
specsmith kill-session --session abc123  # terminate a specific session

This satisfies EU AI Act Art. 14 §4 (ability to intervene and stop the AI system) and is required for certification of high-risk AI systems.

5. Append-Only Safe Write — safe_write (REQ-213)

All governance file writes go through safe_write, which:

• Appends to LEDGER.md and .specsmith/ledger.jsonl — never truncates
• Backs up any file before overwriting it (timestamped .bak copy)
• Prevents accidental destruction of audit history

This satisfies EU AI Act Art. 12 (records must be kept for the lifetime of the system) and provides recovery capability per NIST AI RMF MANAGE.

6. Least-Privilege Permissions (REQ-217, REQ-012)

Every agent tool call is gated through a permission profile. Tools outside the active profile are denied with exit code 3 and a ledger entry:

specsmith agent permissions-check git_push   # exit 0 = allowed, exit 3 = denied
specsmith agent permissions                  # show active profile

Four built-in presets (read_only, standard, extended, admin) plus full custom allow/deny lists in .specsmith/config.yml. This implements NIST AI RMF GOVERN (policy enforcement) and principle of least privilege per standard security practice.

7. Policy Guardrails — is_safe_command (REQ-220)

Before any shell command is executed, agent.safety.is_safe_command() classifies it against a deny list of destructive patterns (rm -rf, git push origin main, kubectl apply, cat .env, etc.). Denied commands are blocked and logged. This implements NIST AI RMF MANAGE (risk treatment at the action level).

8. Compliance Export Report (REQ-208, REQ-215)

specsmith export generates a full compliance report containing:

• AI System Inventory — all providers, models, and versions used
• Risk Classification — AEE phase, confidence scores, open work items
• Human Oversight Controls — active permission profile, escalation settings, kill-switch state
• Audit Trail Summary — TraceVault chain length, last verification, any tampering

specsmith export --format markdown > compliance-report.md
specsmith export --format json > compliance-report.json

This report is suitable as a starting point for audit evidence, but is not a legal certification. Always verify with qualified counsel before regulatory submission.

Compliance per Session and per Project

Compliance settings are layered:

1. Global defaults — ~/.specsmith/config.yml (user-level defaults)
2. Per-project policy — .specsmith/config.yml (committed to the repo)
3. Per-session overrides — CLI flags

Compliance controls include: escalation threshold, permission profile, kill-switch, and context window settings. Changes take effect immediately and can optionally be written back to the per-project .specsmith/config.yml.

Context Window Management

specsmith enforces safe, efficient use of LLM context windows — especially critical when running local models via Ollama where the context limit directly affects GPU VRAM.

GPU-Aware Context Sizing (REQ-244)

specsmith ollama gpu                    # detect GPU VRAM (NVIDIA + AMD supported)
specsmith ollama available              # show models within your VRAM budget

VRAM tiers and recommended context sizes:

Override via SPECSMITH_OLLAMA_CONTEXT_LENGTH or ollama.context_length in .specsmith/config.yml.

Live Context Fill Indicator (REQ-245)

The context fill tracker emits real-time JSONL events:

{"type": "context_fill", "used": 27500, "limit": 32768, "pct": 83.9}

When fill reaches the compression threshold (default 80%), specsmith signals that context summarization should run before the next turn.

Auto Context Compression (REQ-246)

When fill reaches the compression threshold, specsmith automatically triggers conversation summarization — the current context is condensed to a compact summary that preserves key decisions and facts while freeing window space. This happens transparently before the next agent turn.

Configure in .specsmith/config.yml:

context:
  compression_threshold_pct: 80   # trigger summarization at 80% fill
  auto_compress: true             # enable automatic compression

Hard Context Ceiling — Never 100% Full (REQ-247)

A hard reservation of 15% of the context window (minimum 2,048 tokens) is always held back for the governance layer. Attempts to fill beyond the effective ceiling raise ContextFullError — making it impossible to reach a state where even a compression request cannot be processed. This is a safety invariant, not a configuration option.

Governance REST API

# Start the governance REST API (for MCP clients and IDE integrations)
specsmith governance-serve --port 7700 --project-dir .

# Classify a natural-language utterance under Specsmith governance
specsmith preflight "fix the cleanup dry-run regression" --json

# Start the agentic REPL
specsmith run
> what does the cleanup module do?           # read-only ask -> answered
> fix the cleanup dry-run regression          # change -> Specsmith approves, runs
> delete the entire dist directory            # destructive -> needs clarification

Work Item (WI) Lifecycle

Every accepted specsmith preflight mints a Work Item — a unique ID such as WI-3A9F1C02 that tracks user intent through the full governance lifecycle. WIs are persisted to .specsmith/workitems.json and evolve through defined states:

# See all open work items
specsmith wi list --status open

# View full details of a WI
specsmith wi show WI-3A9F1C02

# Close a WI (change covered by an existing REQ)
specsmith wi close WI-3A9F1C02 --reason "covered by REQ-042"

# Promote a WI to a new requirement (new behaviour, no existing REQ)
specsmith wi promote WI-3A9F1C02 \
    --title "System must retry on transient HTTP 5xx failures" \
    --domain governance
specsmith sync   # regenerate REQUIREMENTS.md

# Set kind label
specsmith wi tag WI-3A9F1C02 --kind bug

# Import historical WIs from LEDGER.md
specsmith wi import --from-ledger

When to promote vs close: Promote (wi promote) when the change introduces new behaviour not covered by any existing REQ and the pattern is expected to recur. Close (wi close) for bug fixes, refactors, and chores that already have a matching REQ.

Full documentation: docs/site/wi-lifecycle.md

Grace local REPL

Grace is Specsmith's optional local fallback for terminal-only or private-model work. Existing agent integrations remain the recommended path. Grace keeps its interface small, compresses older epistemic context before model calls, and applies the same requirement, test, uncertainty, and evidence contract as MCP integrations.

# Interactive REPL with governance
specsmith run
grace> /help
grace> /status
grace> fix the cleanup bug
grace> /why
grace> /exit

/status reports the provider, model, history size, and whether context was compressed. /models, /model NAME, and /provider NAME handle routing. If no provider is available, Grace explains how to start Ollama or configure one cloud SDK.

AI Model Intelligence

specsmith ships a complete AI model intelligence layer for tracking, scoring, and routing to the best available LLM for each task type.

HF Open LLM Leaderboard Sync (REQ-263..REQ-269)

Syncs benchmark data from the HuggingFace Open LLM Leaderboard and computes three task-specific bucket scores — reasoning, conversational, and longform — for every model. A 40+ model static fallback ensures scores are always available even without network access.

specsmith model-intel sync                  # sync from HF leaderboard (static fallback if offline)
specsmith model-intel scores                # list all cached bucket scores
specsmith model-intel scores --model gpt-4o # show scores for a specific model
specsmith model-intel recommendations       # top-10 models for reasoning bucket
specsmith model-intel recommendations --bucket conversational  # or longform
specsmith model-intel connection            # test HF API connectivity + token status

Set SPECSMITH_HF_TOKEN for authenticated access (1000 req/5min instead of 500). Scores persist to ~/.specsmith/model_scores.json. Background sync runs 15s after startup then daily.

Bucket formulas (normalised 0-100):

• Reasoning = 0.35×MATH + 0.30×GPQA + 0.25×BBH + 0.10×IFEval
• Conversational = 0.40×IFEval + 0.35×MMLU-PRO + 0.25×BBH
• Longform = 0.35×MUSR + 0.35×IFEval + 0.30×MMLU-PRO

Model Capability Profiles (REQ-270..REQ-271)

40+ pre-built model profiles cover all major providers (OpenAI, Anthropic, Google, Mistral, Meta Llama, Qwen, DeepSeek, and local Ollama variants). Each profile specifies: max_tokens, prompt_style (sections/xml/markdown), supports_vision, supports_tool_calls, reasoning_mode, and context_window.

Context-aware history trimming preserves system messages while summarising older turns when the token budget is exceeded:

from specsmith.agent.model_profiles import get_profile, trim_history

profile = get_profile("qwen2.5:14b")   # exact or prefix match; returns default if unknown
messages = trim_history(messages, budget_chars=12000)

LLM Client with Provider Fallback (REQ-275..REQ-277)

LLMClient wraps multiple providers with automatic fallback on 429 / 401 errors, O-series parameter translation (max_completion_tokens, temperature=1, developer role), and vLLM guided-JSON payload injection:

from specsmith.agent.llm_client import LLMClient

client = LLMClient([
    {"provider_type": "cloud", "model": "gpt-4o", ...},
    {"provider_type": "ollama", "model": "qwen2.5:14b", ...},  # local fallback
])
result = client.chat([{"role": "user", "content": "hello"}])

Endpoint Presets + Suggest Profiles (REQ-278..REQ-280)

A registry of 10+ pre-configured endpoint presets for common cloud and local LLM providers:

specsmith agent endpoint-presets            # list all presets (vllm, lm_studio, openrouter, etc.)
specsmith agent endpoint-presets --json     # machine-readable output
specsmith agent suggest-profiles            # suggest optimal profiles based on env (API keys, hardware)
specsmith agent suggest-profiles --json     # structured suggestions with bucket/role annotations

Suggestions are read-only (never persisted) and inspect OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, and local Ollama availability.

Multi-Agent DAG Dispatcher (REQ-321..334)

The specsmith dispatch command group decomposes a task into a Directed Acyclic Graph of agent work items and executes them concurrently, with fail-forward BLOCKED propagation and ESDB context injection between nodes.

# Run a task through the DAG dispatcher (default: up to 4 concurrent workers)
specsmith dispatch run "add API endpoint with tests" --max-workers 4

# Stream JSONL events while the run is in progress
specsmith dispatch run "refactor auth module" --json

# Check status of a saved run
specsmith dispatch status --dag-id abc123def456

# List all saved runs
specsmith dispatch list

# Retry a single failed node from a checkpoint
specsmith dispatch retry --node impl --dag-id abc123def456

The dispatcher is also available programmatically:

from specsmith.agent.orchestrator import Orchestrator

orchestrator = Orchestrator()

# Use the DAG path (falls back to GroupChat on cycle detection)
result = orchestrator.run_task("add feature X", use_dag=True)

# Always use DAG — returns DispatchSummary with per-node outcomes
summary = orchestrator.run_dispatch(
    "add feature X",
    planner_output=[
        {"id": "arch", "title": "Design", "role": "architect", "depends_on": []},
        {"id": "impl", "title": "Implement", "role": "coder", "depends_on": ["arch"]},
        {"id": "test", "title": "Write tests", "role": "tester", "depends_on": ["arch"]},
    ],
    max_workers=3,
)
print(f"{len(summary.completed)} completed, {len(summary.failed)} failed")

Events are persisted to .specsmith/dispatch/<dag_id>/events.jsonl for resume and replay.

Compiler and Tool Support

All agent roles can invoke compiler, linter, and formatter tools. These are registered in AVAILABLE_TOOLS and wired into ROLE_TOOLS for the coder, reviewer, tester, architect, and embedded-coder roles.

All tools are usable directly in the agentic REPL and in specsmith dispatch worker nodes:

from specsmith.agent.tools import run_arm_gcc, run_clang_tidy, run_vsg

# Cross-compile for ARM bare-metal
result = run_arm_gcc("-Wall -O2 main.c -o firmware.elf", compiler="arm-none-eabi-gcc")

# Lint C/C++ with clang-tidy
result = run_clang_tidy("src/", checks="modernize-*,readability-*")

# Style-check VHDL files
result = run_vsg("rtl/top.vhd", rules="vsg_rules.yaml")

Supporting specsmith

specsmith is open source and built by a small team. Every bit of support helps:

• ⭐ Star specsmith on GitHub
• 📣 Tell your friends and colleagues — word of mouth is our best marketing
• 🐛 Report bugs via GitHub Issues — even small ones help
• 💡 Suggest features via GitHub Discussions — we read every suggestion
• 🔧 Fix bugs and contribute — see CONTRIBUTING.md; PRs welcome
• 📝 Write about specsmith — blog posts, tutorials, and talks help the community grow
• ❤️ Sponsor layer1labs — directly funds development

Ollama — Local LLMs (Zero API Cost)

specsmith has first-class Ollama support, including:

specsmith ollama gpu                    # detect GPU and VRAM tier
specsmith ollama available              # show catalog filtered by VRAM budget
specsmith ollama available --task code  # filter by task type
specsmith ollama pull qwen2.5:14b      # download a model
specsmith ollama suggest requirements  # task-based recommendations
specsmith ollama list                  # show installed models

GPU-aware context sizing: 4K/8K/16K/32K tokens based on detected VRAM. Override via SPECSMITH_OLLAMA_CONTEXT_LENGTH env var or ollama.context_length in .specsmith/config.yml.

VRAM-aware model lineup (REQ-445): specsmith local-model recommend prints a per-role lineup — default / fast / harder pass / general — keyed to your detected VRAM, with a fit assessment (fits / tight / spills) so you can see which models run fully on the GPU before pulling. specsmith local-model detect and specsmith local-model setup pick and install a single hardware-appropriate Qwen2.5-Coder model.

FPGA / HDL Projects

specsmith supports FPGA-specific project types with full governance:

# scaffold.yml
type: fpga-rtl-amd          # or fpga-rtl-intel / fpga-rtl-lattice / fpga-rtl
fpga_tools:
  - vivado
  - gtkwave
  - vsg
  - ghdl
  - verilator

Supported tools: Synthesis: vivado, quartus, radiant, diamond, gowin. Simulation: ghdl, iverilog, verilator, modelsim, questasim, xsim. Waveform: gtkwave, surfer. Linting: vsg, verible, svlint. Formal: symbiyosys. OSS flow: yosys, nextpnr, openFPGALoader.

50+ CLI Commands

Governance: init import audit validate diff upgrade compress doctor export architect

AEE Epistemic: stress-test epistemic-audit belief-graph trace seal/verify/log

Workflow: phase show/set/next/list ledger add/list req list/add/gaps/trace

Work Items: wi list wi show wi close wi archive wi promote wi tag wi import

Agent: run agent run/plan/status/verify/improve/reports agent providers/tools/skills agent suggest-profiles agent endpoint-presets

Dispatch: dispatch run dispatch status dispatch list dispatch retry

Model Intel: model-intel sync model-intel scores model-intel recommendations model-intel connection

Ollama: ollama list/available/gpu/pull/suggest

Local Model: local-model detect/recommend/setup

Workspace: workspace init/audit/export

Integrations: integrate warp integrate codity integrate claude-code integrate cursor integrate copilot integrate aider integrate gemini integrate windsurf integrate agent-skill

VCS: commit push pull save load sync branch pr status checkpoint

Tools: tools scan [--fpga] tools install <tool> tools rules [--tool] [--list]

Session & Process: exec ps abort watch credits self-update kill-session session-end

Auth: auth set/list/remove/check

Patent: patent search/prior-art

64 Project Types

Python: cli-python, library-python, backend-frontend, backend-frontend-tray, embedded-python-hmi, research-python.

Systems languages: cli-rust, library-rust, cli-go, cli-c, library-c, dotnet-app.

Modern web: web-frontend, fullstack-js, nextjs-app, nuxt-app, sveltekit-app, remix-app, astro-site.

AI / Agents: llm-app, agent-orchestration, mcp-server, rag-pipeline, mlops-platform.

JVM: java-spring, java-library.

Mobile: mobile-app.

Infrastructure: serverless, kubernetes-operator, microservices, devops-iac, streaming-pipeline, data-warehouse, data-ml.

Game development: game-unity, game-godot.

Web3: smart-contract.

Desktop: desktop-electron, desktop-tauri.

Hardware / Embedded: fpga-rtl, fpga-rtl-amd, fpga-rtl-intel, fpga-rtl-lattice, mixed-fpga-embedded, mixed-fpga-firmware, yocto-bsp, embedded-hardware, pcb-hardware, safety-critical.

Documents & IP: spec-document, user-manual, research-paper, research-python, api-specification, brief-lang, requirements-mgmt, patent-application, patent-prosecution.

Business / Legal / AEE: business-plan, legal-compliance, monorepo, browser-extension, epistemic-pipeline, knowledge-engineering, aee-research.

epistemic Library

The standalone epistemic Python library works in any Python 3.10+ project — no specsmith coupling:

from epistemic import AEESession, BeliefArtifact, StressTester

session = AEESession("my-project", threshold=0.70)
session.add_belief(
    artifact_id="HYP-001",
    propositions=["The API always returns valid JSON"],
    epistemic_boundary=["Valid auth token required"],
)
session.accept("HYP-001")
result = session.run()
print(result.summary())
# certainty=0.55, failures=2, equilibrium=False

Use cases: linguistics research, compliance pipelines, AI alignment, patent prosecution.

Governance Rules

22 hard rules enforced by specsmith validate and specsmith audit. Rules 1–14 cover core engineering and traceability (ledger required, proposals required, platform-awareness, documentation currency, etc.). Rules 15–22 address anti-hallucination and epistemic stability, derived from the OEA (Ontological Epistemic Anchoring) research framework (Layer1Labs, 2026).

Full rule reference: docs/governance/RULES.md

Codity.ai AI Code Review Integration

specsmith can scaffold Codity.ai AI code review into any project:

specsmith integrate codity --project-dir ./my-project

This generates:

• .github/workflows/codity-review.yml (GitHub Actions) or .gitlab-ci-codity.yml / .azure-pipelines/codity-review.yml depending on your VCS
• docs/codity-setup.md — one-time setup checklist
• Appends a TODO checklist to LEDGER.md

Windows note: Codity's install.sh is Linux/macOS only. For native PowerShell use, install codity.exe from the official codity-ai/codity-cli GitHub release zip and place it on PATH (for example ~/.local/bin).

AGENTS.md rule (REQ-355): Projects with Codity configured SHOULD run codity review --staged before any commit touching production code. HIGH-severity findings are blocking; MEDIUM findings require inline acknowledgement.

See the codity-ai-review governance skill (specsmith skill install codity-ai-review) for the full CLI workflow reference.

Skills

Specsmith has a deliberately small default catalog: 12 skills covering only its differentiated AEE capabilities—preflight, requirements, linked tests, traceability, epistemic context, token budgets, verification, release evidence, and compact Specsmith references.

specsmith skill list
specsmith skill search context
specsmith skill install specsmith

Skills install to .agents/skills/<slug>/SKILL.md, but they are optional. Prefer specsmith integrate <host> or the MCP server so Claude Code, Codex, Cursor, Copilot, Gemini, Aider, Warp, Windsurf, and Zoo/Roo keep their native tools. Specsmith supplies only the AEE governance contract; it does not duplicate generic Git, testing, framework, or document skills.

See the focused skills index for the complete list and integration boundary.

Agent Integrations

Run specsmith integrate <tool> once in your project root — specsmith writes the governance file your AI client reads automatically.

All generated files embed the same core content: governance rules, the mandatory session protocol, preflight requirements, and AGENTS.md as the primary governance source.

Mandatory session protocol (all tools)

# Session start
specsmith kill-session 2>/dev/null || true
specsmith audit --project-dir .
specsmith sync  --project-dir .
specsmith checkpoint --project-dir .   # output GOVERNANCE ANCHOR verbatim

# Before every code change
specsmith preflight "<describe the change>" --json
# decision == "accepted"           → proceed with work_item_id in scope
# decision == "needs_clarification" → surface instruction to user first

# Every 8–10 turns
specsmith checkpoint --project-dir .

# Session end
specsmith save && specsmith kill-session

Claude Code

specsmith integrate claude-code   # writes CLAUDE.md

To enable native MCP tool calls, add to .mcp.json (project root) or ~/.claude/mcp.json:

{
  "mcpServers": {
    "specsmith-governance": {
      "command": "specsmith",
      "args": ["mcp", "serve", "--project-dir", "."]
    }
  }
}

Or run specsmith mcp install-claude-code to print the snippet. With MCP configured, Claude calls governance tools natively — no shell roundtrip.

Cursor

specsmith integrate cursor   # writes .cursor/rules/governance.mdc

Add to .cursor/mcp.json to enable MCP:

{
  "specsmith-governance": {
    "command": "specsmith",
    "args": ["mcp", "serve", "--project-dir", "${workspaceFolder}"]
  }
}

Windsurf

specsmith integrate windsurf   # writes .windsurfrules

MCP: Settings → MCP Servers → { "specsmith-governance": { "command": "specsmith", "args": ["mcp", "serve"] } }

Gemini CLI

specsmith integrate gemini   # writes GEMINI.md (read automatically by the gemini CLI)

Aider

specsmith integrate aider   # writes .aider.conf.yml

For full governance, use --no-auto-commits and commit via specsmith save:

aider --no-auto-commits --read AGENTS.md --read .agents/skills/specsmith-session-governance/SKILL.md

Run specsmith preflight in a separate terminal before each change; run specsmith save after aider finishes.

GitHub Copilot

specsmith integrate copilot   # writes .github/copilot-instructions.md

Copilot reads .github/copilot-instructions.md for all workspace interactions. MCP not yet natively supported; governance is enforced through the instructions file and AGENTS.md.

Full per-tool setup: Agent Integrations docs →

Warp Terminal Integration

specsmith ships first-class integration with Warp terminal: a one-command specsmith integrate warp setup, a governance MCP server, a Warp-aware agentic REPL, and repository workflows.

One-command setup — specsmith integrate warp

specsmith integrate warp        # scaffold Warp-native governance into the repo

The warp adapter (first-class as of v0.20.0 — no longer a legacy alias to agent-skill) writes:

• .warp/specsmith-mcp.json — the governance MCP server config (identical to specsmith mcp install-warp)
• .warp/launch_configs/specsmith-governed.yaml — a Warp launch configuration that opens a governed specsmith run session
• .agents/skills/SKILL.md — the auto-discovered governance skill

Warp-aware REPL

When you start specsmith run inside Warp, specsmith detects the host terminal (via TERM_PROGRAM / WARP_* env vars) and shows a terminal: Warp … — native integration active banner; the JSON ready frame carries a matching terminal field. Behavior is unchanged outside Warp.

Native MCP Governance Server

specsmith mcp serve starts a zero-dependency stdio MCP server (JSON-RPC 2.0, MCP 2024-11-05). Warp/Oz, Cursor, Claude Code, or any other MCP client can call governance commands as structured tool calls — no shell roundtrip, fully typed inputs and outputs.

Setup (one time):

# Get the Warp config snippet
specsmith mcp install-warp

Copy the output JSON into Warp Settings → Agents → MCP servers. Or pass it inline:

oz agent run --mcp '{"specsmith-governance": {"command": "specsmith", "args": ["mcp", "serve"]}}' \
  --prompt "check governance health and preflight my next change"

Six MCP tools exposed:

Third-party CLI agent toolbar

For specsmith and aider (not yet natively supported by Warp), add this regex once in Warp → Settings → Agents → Third party CLI agents → Commands that enable the toolbar:

specsmith\s+run|aider

claude, codex, gemini, and cursor are already natively supported — no regex needed.

Once set, the toolbelt (Rich Input, attach code, File Explorer, Tab Configs, Remote Control) appears whenever specsmith run or aider is running. specsmith run also emits an OSC 9 desktop notification on session start — intercepted automatically by Warp, iTerm2, and Windows Terminal.

Run specsmith integrate warp to regenerate .warp/SETUP.md with the full per-REPL setup guide.

Repository Workflows (Ctrl+Shift+R)

Clone this repo and open it in Warp — seven governance workflows appear automatically in Ctrl+Shift+R search:

The specsmith Bootstrap

specsmith governs itself — the specsmith repo is a specsmith-managed project. Run specsmith audit in this repo to check its governance health. This means every feature we add to specsmith is immediately dogfooded on specsmith itself.

Documentation

specsmith.readthedocs.io — Full manual: AEE primer, command reference, project types, tool registry, governance model, ESDB, skills integrations, Ollama guide.

Links

• PyPI
• Documentation
• Stability Contract
• Editions Matrix
• Changelog
• Contributing
• Roadmap
• Compatibility Matrix
• Product Principles
• Security

License

MIT — Copyright (c) 2026 Layer1Labs Silicon, Inc.