{"id":50553434,"url":"https://github.com/layer1labs/specsmith","last_synced_at":"2026-06-30T04:00:36.341Z","repository":{"id":348395239,"uuid":"1197753061","full_name":"layer1labs/specsmith","owner":"layer1labs","description":"AEE governance CLI for AI-assisted dev — WI lifecycle (specsmith wi), preflight gates, multi-agent dispatch, requirements\u003c-\u003etest traceability, ESDB, MCP server, compliance, 64 project types, 136 skills, and 1607 tests.","archived":false,"fork":false,"pushed_at":"2026-06-26T13:13:15.000Z","size":65109,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-26T13:23:01.034Z","etag":null,"topics":["aee","agentic-ai","ai-governance","applied-epistemic-engineering","cli","compliance","epistemic-engineering","esdb","fpga","llm","mcp","mcp-configs","ollama","python","rag","requirements-management","skills","traceability","wi-lifecycle","work-items"],"latest_commit_sha":null,"homepage":"https://specsmith.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/layer1labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":"docs/governance/CONTEXT-BUDGET.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":null,"custom":null}},"created_at":"2026-03-31T21:19:09.000Z","updated_at":"2026-06-25T20:10:52.000Z","dependencies_parsed_at":"2026-04-07T03:00:33.765Z","dependency_job_id":null,"html_url":"https://github.com/layer1labs/specsmith","commit_stats":null,"previous_names":["bitconcepts/specsmith","layer1labs/specsmith"],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/layer1labs/specsmith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layer1labs%2Fspecsmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layer1labs%2Fspecsmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layer1labs%2Fspecsmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layer1labs%2Fspecsmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/layer1labs","download_url":"https://codeload.github.com/layer1labs/specsmith/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layer1labs%2Fspecsmith/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34951598,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aee","agentic-ai","ai-governance","applied-epistemic-engineering","cli","compliance","epistemic-engineering","esdb","fpga","llm","mcp","mcp-configs","ollama","python","rag","requirements-management","skills","traceability","wi-lifecycle","work-items"],"created_at":"2026-06-04T05:01:10.789Z","updated_at":"2026-06-30T04:00:36.331Z","avatar_url":"https://github.com/layer1labs.png","language":"Python","funding_links":["https://github.com/sponsors/layer1labs"],"categories":[],"sub_categories":[],"readme":"# specsmith\n\n[![CI](https://github.com/layer1labs/specsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/layer1labs/specsmith/actions/workflows/ci.yml)\n[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=github)](https://github.com/sponsors/layer1labs)\n[![Docs](https://readthedocs.org/projects/specsmith/badge/?version=stable)](https://specsmith.readthedocs.io/en/stable/)\n[![PyPI](https://img.shields.io/pypi/v/specsmith?label=stable\u0026style=flat\u0026color=blue\u0026cacheSeconds=60)](https://pypi.org/project/specsmith/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/layer1labs/specsmith/blob/main/LICENSE)\n\nSpecSmith 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.\n\n## Architecture at a glance\n\n```\nAI Agents / IDE Clients\n        |\n        v\n  SpecSmith Governance Layer\n  ├── Repository Files\n  ├── Requirements and Tests ──\u003e CI and MCP Integrations\n  └── ESDB / Audit Ledger  ──\u003e CI and MCP Integrations\n```\n\n## When to use / when not to use\n\n- Use when you need governed AI development, auditable decision trails, and requirement-to-test linkage.\n- Avoid when rapid local prototyping is the only goal and formal governance is unnecessary.\n\n## Comparison summary\n\n- **GitHub Spec Kit / OpenSpec / BMAD:** strong specification practices; SpecSmith adds execution-time governance, work-item lifecycle control, and trace-chain evidence.\n- **Aider / Claude Code / Cursor:** agentic coding interfaces; SpecSmith is the policy and evidence layer around these clients.\n- **LangGraph / AutoGen:** orchestration frameworks; SpecSmith is a governance-first development layer with compliance-oriented traceability.\n\n### Governance efficiency benchmark\n\nWe 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.\n\n| Condition | Pass Rate | Mean Tokens | Cost/run | Cost-of-Pass |\n|---|---|---|---|---|\n| Ungoverned (raw agent) | 0% on T1 | 44.6k | $0.0079 | ∞ |\n| Context injection (CLAUDE.md) | 100% | 43.7k | $0.0084 | $0.0084 |\n| BMAD-style structured prompting | 50% | 139.1k | $0.0262 | $0.0523 |\n| **specsmith LIGHT (preflight)** | **100%** | **21.1k** | **$0.0032** | **$0.0032** |\n| **specsmith FULL (governed)** | **100%** | **17.1k** | **$0.0026** | **$0.0026** |\n\n**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).\n\nSee 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/).\n\n**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).\n\n**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.\n\n**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.\n\n**v0.17.x** — Canonical `docs/SPECSMITH.yml` scaffold path adopted across every CLI command, with CodeQL alerts driven to zero.\n\nspecsmith 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.\n\n### Selected CLI highlights\n\n```bash\nspecsmith governance-serve --port 7700     # governance REST API\nspecsmith sync                              # YAML → JSON → MD (YAML-first mode)\nspecsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md\nspecsmith validate --strict                 # dup IDs, orphans, coverage gaps\nspecsmith agent permissions-check git_push  # tool permission gate (REQ-012)\nspecsmith ollama gpu                        # detect GPU VRAM, recommend context size\nspecsmith local-model recommend            # VRAM-aware model lineup (fits/tight/spills)\nspecsmith integrate warp                    # scaffold Warp-native governance (MCP + launch config)\nspecsmith export                            # generate full compliance report\n\n# Update channels\nspecsmith channel set stable               # pin to stable releases\nspecsmith channel set dev                  # opt in to pre-release builds\n\n# ESDB lifecycle\nspecsmith esdb export --json               # dump records to JSON snapshot\nspecsmith esdb backup                      # create timestamped snapshot\nspecsmith esdb compact                     # WAL compaction\n\n# Skills\nspecsmith skills deactivate \u003cskill-id\u003e     # set active=false\nspecsmith skills delete \u003cskill-id\u003e --yes   # permanently remove\n\n# MCP + agent dispatch\nspecsmith mcp generate \"Search USPTO patents\" --json\nspecsmith agent ask \"show esdb status\" --json-output\n```\n\nIt also co-installs the standalone `epistemic` Python library for direct use in any project:\n\n```python\nfrom epistemic import AEESession         # works in any Python 3.10+ project\nfrom epistemic import BeliefArtifact, StressTester, CertaintyEngine\n```\n\n\u003e **Library vs CLI:** The `specsmith` CLI requires pipx for isolation. The `epistemic` library\n\u003e (and `specsmith.esdb`) work in any venv — `pip install specsmith` is all you need for\n\u003e library-only use. The pipx guard only fires on CLI invocations.\n\n---\n\n## What is Applied Epistemic Engineering?\n\nAEE treats requirements, decisions, and assumptions — the beliefs your project depends on — as\nengineering artifacts subject to the same discipline as code: version control, testing, and refactoring.\n\n**The 4-step core method: Frame → Disassemble → Stress-Test → Reconstruct**\n\n**The 5 foundational axioms:**\n1. **Observability** — every belief must be inspectable\n2. **Falsifiability** — every belief must be challengeable\n3. **Irreducibility** — beliefs decompose to atomic primitives\n4. **Reconstructability** — every failed belief can be rebuilt\n5. **Convergence** — stress-test + recovery always reaches Equilibrium\n\n---\n\n## The AEE Workflow — 7 Phases\n\nspecsmith tracks your project through the full AEE development cycle:\n\n```\n🌱 Inception → 🏗 Architecture → 📋 Requirements → ✅ Test Spec\n    → ⚙ Implementation → 🔬 Verification → 🚀 Release\n```\n\n```bash\nspecsmith phase          # show current phase + readiness checklist\nspecsmith phase next     # advance to the next phase (runs checks first)\nspecsmith phase set requirements  # jump to a specific phase\nspecsmith phase list     # list all phases\n```\n\nThe current phase is persisted in `scaffold.yml` as `aee_phase`. Each phase has a checklist\nof file/command criteria, recommended commands, and a readiness percentage.\n\n## 1.0 release criteria status\n\n| Criterion | Status | Source |\n|---|---|---|\n| Stable CLI core contract documented | In progress | `docs/stability.md` |\n| Stable generated file schemas documented | In progress | `docs/stability.md` |\n| Stable MCP tool schemas documented | In progress | `docs/stability.md` |\n| Migration tests linked (#218) | In progress | `docs/roadmap/1.0-criteria.md` |\n| Security threat model documented | In progress | `docs/security-threat-model.md` |\n| Docs/tutorial/glossary baseline complete | In progress | `docs/roadmap/1.0-criteria.md` |\n| Upgrade path and changelog criteria defined | In progress | `docs/roadmap/1.0-criteria.md` |\n\n---\n\n## Install\n\n**Recommended — via pipx (CLI + CI):**\n\n```bash\npipx install specsmith\n```\n\nThat's it. `specsmith audit`, `preflight`, `sync`, `checkpoint`, `esdb`, `mcp serve`,\nand all governance commands work immediately with no additional packages.\n\n\u003e **Want `specsmith run` with a cloud LLM?** Inject the provider SDK only if you use\n\u003e the built-in agentic REPL with a cloud API key:\n\u003e\n\u003e ```bash\n\u003e pipx inject specsmith anthropic    # if you set ANTHROPIC_API_KEY\n\u003e pipx inject specsmith openai       # if you set OPENAI_API_KEY\n\u003e pipx inject specsmith google-genai # if you set GOOGLE_API_KEY\n\u003e ```\n\u003e\n\u003e Ollama works out of the box with no injection — specsmith uses stdlib HTTP.\n\u003e For Warp, Claude Code, Cursor, and Copilot, the AI client provides the LLM;\n\u003e no injection needed.\n\n**Library-only use (venv / conda / any Python environment):**\n\n```bash\npip install specsmith          # epistemic library + SQLite ESDB — no pipx needed\n```\n\nThis makes `from epistemic import AEESession` and `from specsmith.esdb import SqliteStore`\nimmediately importable.  The pipx isolation guard only applies to the `specsmith` CLI\ncommand — not to library imports.  Use this when you want the AEE belief-state machinery\nin your own application without managing a pipx environment.\n\n**ESDB — Epistemic State Database**\nTerminology used in this repo is strict:\n- **ESDB** = the specification/data model category.\n- **SQLite backend** = the free/default ESDB implementation bundled in `specsmith`.\n- **ChronoMemory** = the commercial package.\n- **ChronoStore** = the backend engine/class provided by the ChronoMemory package.\n\n| Tier | Package | License | What you get |\n|------|---------|---------|-------------|\n| **Default** | `specsmith` (built-in) | MIT, free | SQLite backend — requirements, test cases, confidence filtering |\n| **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 |\n\nSee `docs/editions.md` for the full OSS vs commercial feature matrix.\n\n`pip install specsmith` always installs the **free SQLite backend** automatically.\nNo additional packages, no license key, no configuration — it works out of the box.\n\n```bash\nspecsmith esdb status   # shows: SQLite (free, MIT) — active by default\n```\n\n**ESDB version-control policy (this repository):**\n- Commit canonical SQLite state file: `.specsmith/esdb.sqlite3`.\n- Commit canonical ChronoMemory state files: `.chronomemory/events.wal` and `.chronomemory/snapshot.json`.\n- Do not commit ChronoMemory timestamped backup copies under `.chronomemory/backup/` (regenerated by `specsmith save` / `specsmith esdb backup`).\n\n**Upgrading to ChronoMemory (ChronoStore backend, commercial):**\n\nIf you hold a chronomemory ESDB license, activate the commercial backend:\n\n```bash\n# Step 1 — install the chronomemory package\npip install \"specsmith[esdb]\"                 # installs chronomemory from PyPI\n# or if using pipx:\npipx inject specsmith \"chronomemory\u003e=0.2.0\"  # inject into the specsmith pipx venv\n\n# Step 2 — activate your license key\nspecsmith esdb enable --key-file /path/to/your.esdb.key\n# The key is copied to ~/.specsmith/esdb.key and used automatically from now on.\n\n# Step 3 — verify ChronoStore is active\nspecsmith esdb status\n# ● ESDB — ChronoStore WAL (chronomemory commercial)\n#   ✔ License: your-org (expires YYYY-MM-DD)\n```\n\nTo obtain a chronomemory ESDB license:\n[licensing@layer1labs.ai](mailto:licensing@layer1labs.ai) · [ESDB licensing docs](https://specsmith.readthedocs.io/en/stable/esdb/#licensing)\n· [ChronoMemory commercial terms](https://github.com/layer1labs/specsmith/blob/develop/COMMERCIAL-LICENSE.md)\nSee the [full ESDB docs](https://specsmith.readthedocs.io/en/stable/esdb/) for a feature comparison and Python API reference.\n\n**Upgrading specsmith:**\n\n```bash\npipx upgrade specsmith   # preferred — upgrades the pipx-isolated CLI\nspecsmith self-update    # alternative: self-update from within specsmith\n```\n\n---\n\n## Quick Start\n\n```bash\n# 1. Install\npipx install specsmith\n\n# 2. Start a new project (or import an existing one)\nspecsmith init                           # interactive scaffold wizard\nspecsmith import --project-dir ./my-project  # adopt an existing repo\n\n# 3. Bootstrap every session (run once at the start of each work session)\nspecsmith migrate run                    # apply any pending schema migrations\nspecsmith audit                          # verify governance health\nspecsmith sync                           # YAML → JSON → MD sync\nspecsmith checkpoint                     # emit GOVERNANCE ANCHOR\n\n# 4. Before every code change: preflight\nspecsmith preflight \"add paginated GET /todos endpoint\"  # gate the intent\n# → decision: accepted | needs_clarification  +  work_item_id: WI-XXXXXXXX\n\n# 5. After making changes: verify + save\nspecsmith verify                         # check equilibrium\nspecsmith save                           # commit governance state + push\n\n# 6. Check AEE workflow phase and health\nspecsmith phase                          # current phase + readiness %\nspecsmith audit                          # full governance health check\n```\n\n\u003e **Agentic REPL:** run `specsmith run` to start the Nexus governance-gated LLM REPL.\n\u003e Every utterance is preflighted automatically. Use `/why` to see the governance trace.\n\u003e For the multi-agent DAG dispatcher, see `specsmith dispatch run \"\u003ctask\u003e\"`.\n\n### Standalone CLI (no AI agent)\n\nAll governance commands work without any AI agent or IDE integration:\n\n```bash\nspecsmith audit                     # governance health check\nspecsmith preflight \"\u003cintent\u003e\" --json  # gate a change\nspecsmith verify                    # check equilibrium after changes\nspecsmith save                      # ESDB backup + commit + push\nspecsmith kill-session              # clean shutdown\n```\n\nFor 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/)**\n\n---\n\n## Machine State Sync + YAML Governance\n\nAs of v0.11, specsmith uses **YAML-first governance**: `docs/requirements/*.yml`\nand `docs/tests/*.yml` are the canonical sources. `REQUIREMENTS.md` and `TESTS.md`\nare **generated artifacts** — do not hand-edit them.\n\n```bash\n# YAML-first pipeline (v0.11+)\nspecsmith sync                     # YAML → .specsmith/*.json → docs/*.md (all in one)\nspecsmith generate docs            # regenerate only the Markdown artifacts from YAML\nspecsmith generate docs --check    # dry-run: report what would change\nspecsmith validate --strict        # enforce schema: dup IDs, orphans, missing fields\nspecsmith validate --strict --json # machine-readable validation result\n\n# CI guard (already in .github/workflows/ci.yml)\nspecsmith sync --check             # exits 1 if JSON cache is out of sync with YAML\n```\n\n**To add a new requirement**, edit the appropriate `docs/requirements/\u003cdomain\u003e.yml`\nfile and run `specsmith sync`. **Never** hand-edit `docs/REQUIREMENTS.md` — it will\nbe overwritten by the next sync.\n\n**Domain files:**\n\n| File | REQ range | Domain |\n|---|---|---|\n| `docs/requirements/governance.yml` | REQ-001..064 | Core AEE governance |\n| `docs/requirements/agent.yml` | REQ-065..129 | Nexus + CI |\n| `docs/requirements/harness.yml` | REQ-130..160 | Slash commands + subagents |\n| `docs/requirements/intelligence.yml` | REQ-161..220 | Instinct, eval, memory |\n| `docs/requirements/context.yml` | REQ-244..247 | Context window |\n| `docs/requirements/esdb.yml` | REQ-248..262 | ESDB + skills + MCP |\n| `docs/requirements/ai_intelligence.yml` | REQ-263..299 | AI model intelligence |\n| `docs/requirements/yaml_governance.yml` | REQ-300..312 | YAML governance layer |\n| `docs/requirements/multiagent_compliance.yml` | REQ-313..320 | Multi-agent governance traceability |\n| `docs/requirements/dispatch.yml` | REQ-321..334 | Multi-agent DAG dispatcher |\n| `docs/requirements/esdb_full_coverage.yml` | REQ-395..402 | ESDB coverage gap-fill |\n| `docs/requirements/esdb_first.yml` | REQ-403..422 | ESDB-first dual-write architecture |\n| `docs/requirements/overflow.yml` | REQ-050, REQ-335..445 | VCS ops, skills catalog, session governance, Codity.ai, native Warp integration (REQ-444), VRAM-aware local-model recommendations (REQ-445) |\n\n**Migration from Markdown-primary:**\n`scripts/migrate_governance_to_yaml.py` once to convert an existing project.\nIdempotent — safe to re-run.\n\n## Least-Privilege Agent Permissions (REQ-012)\n\n```bash\nspecsmith agent permissions                      # show active permission profile\nspecsmith agent permissions-check git_push       # check if git_push is allowed\nspecsmith agent permissions-check git_push --no-log  # dry-run (no ledger write)\n```\n\nConfigure in `docs/SPECSMITH.yml`:\n```yaml\nagent:\n  permissions:\n    preset: standard       # read_only | standard | extended | admin\n    # Or custom:\n    allow: [read_file, write_file, run_shell, git_status]\n    deny:  [git_push, git_create_pr]\n```\n\n---\n\n## AI Compliance \u0026 Governance\n\n\u003e **DISCLAIMER — Best-effort only.** specsmith is designed to *help* teams build\n\u003e auditable, explainable AI systems, but **it does not guarantee compliance** with\n\u003e any law or regulation. Regulations change frequently; final compliance determination\n\u003e is solely the responsibility of the end user. Layer1Labs makes no legal warranty.\n\u003e Found outdated coverage or a missing regulation?\n\u003e [Open a ticket](https://github.com/layer1labs/specsmith/issues) — we actively\n\u003e maintain the regulation database and welcome compliance PRs.\n\nspecsmith is designed from the ground up for **auditable, explainable, and human-overseen AI**.\nIt implements concrete compliance mechanisms mapped to the two major regulatory frameworks\nthat govern AI systems in production today.\n\n### Standards Coverage\n\n**EU AI Act (Regulation 2024/1689)** — The world's first comprehensive legal framework for AI,\nenforced across the European Union. High-risk AI systems must provide transparency, auditability,\nhuman oversight, and robustness. specsmith implements:\n\n| EU AI Act Requirement | specsmith Mechanism |\n|---|---|\n| Art. 9 — Risk Management System | AEE verification loop with confidence scoring and equilibrium checks |\n| Art. 12 — Logging \u0026 Record-Keeping | `TraceVault` SHA-256 chained ledger (tamper-evident, append-only) |\n| Art. 13 — Transparency \u0026 Explainability | `ai_disclosure` block in every preflight response; `/why` in Nexus REPL |\n| Art. 14 — Human Oversight | Human escalation threshold (`--escalate-threshold`); kill-switch CLI |\n| Art. 15 — Accuracy \u0026 Robustness | Bounded retry (max 3×), confidence gates, hard context ceiling (REQ-247) |\n| Art. 53 — GPAI Model Transparency | Provider + model name emitted in every `ai_disclosure` block |\n\n**NIST AI Risk Management Framework 1.0 (AI RMF)** — The US standard for managing AI risk\nacross the AI lifecycle. specsmith addresses all four core functions:\n\n| NIST AI RMF Function | specsmith Mechanism |\n|---|---|\n|| **GOVERN** — Policies \u0026 accountability | Governance rules, permissions profile, `scaffold.yml` policy |\n| **MAP** — Risk identification | AEE stress-test, belief graph, contradictions and uncertainty metrics |\n| **MEASURE** — Risk analysis | Confidence scoring, epistemic equilibrium, `specsmith epistemic-audit` |\n| **MANAGE** — Risk treatment | Kill-switch, escalation, bounded retry, safe-write backup, permissions deny-list |\n\n### How Each Compliance Mechanism Works\n\n#### 1. Tamper-Evident Audit Log — `TraceVault` (REQ-206)\n\nEvery agent action, decision, milestone, and audit gate is recorded as a JSONL entry in\n`.specsmith/trace.jsonl`. Each entry contains a SHA-256 hash of its own content plus the\nhash of the previous entry, forming a cryptographic chain:\n\n```jsonl\n{\"seq\":1, \"type\":\"DECISION\", \"description\":\"...\", \"hash\":\"a3f9...\", \"prev\":\"genesis\"}\n{\"seq\":2, \"type\":\"MILESTONE\", \"description\":\"...\", \"hash\":\"7c2b...\", \"prev\":\"a3f9...\"}\n```\n\nAny modification to a past entry breaks every subsequent hash. `specsmith trace verify`\ndetects and reports the first corrupted entry. The file is append-only — overwrites are\nblocked by `safe_write`. This satisfies **EU AI Act Art. 12** (logging and record-keeping)\nand **NIST AI RMF GOVERN** (accountability trail).\n\n#### 2. AI Disclosure — Every Response (REQ-207)\n\nEvery preflight response includes a mandatory `ai_disclosure` block:\n\n```json\n{\n  \"ai_disclosure\": {\n    \"governed_by\": \"specsmith\",\n    \"governance_gated\": true,\n    \"provider\": \"ollama\",\n    \"model\": \"qwen2.5:14b\",\n    \"spec_version\": \"0.20.0\"\n  }\n}\n```\n\nThis ensures every AI-generated output is traceable to its source model and version,\nmeeting **EU AI Act Art. 13** (transparency) and **Art. 53** (GPAI transparency).\nIt is impossible to suppress — the field is injected at the governance layer before\nany response is returned to the client.\n\n#### 3. Human Escalation — Configurable Threshold (REQ-209)\n\nWhen an action's confidence is below the escalation threshold, specsmith sets\n`escalation_required: true` and includes an `escalation_reason` in the preflight payload.\nAI clients that support MCP will surface this via the `governance_preflight` tool response.\n\n```bash\nspecsmith preflight \"deploy to production\" --escalate-threshold 0.85 --json\n# → escalation_required: true, escalation_reason: \"confidence 0.71 \u003c threshold 0.85\"\n```\n\nThis implements **EU AI Act Art. 14** (human oversight) and **NIST AI RMF MANAGE**.\n\n#### 4. Kill-Switch — Immediate Session Termination (REQ-210)\n\nA `kill-session` CLI command immediately terminates all active agent sessions and records\na timestamped kill event in `LEDGER.md`:\n\n```bash\nspecsmith kill-session                   # terminate all sessions, log kill event\nspecsmith kill-session --session abc123  # terminate a specific session\n```\n\nThis satisfies **EU AI Act Art. 14 §4** (ability to intervene and stop the AI system)\nand is required for certification of high-risk AI systems.\n\n#### 5. Append-Only Safe Write — `safe_write` (REQ-213)\n\nAll governance file writes go through `safe_write`, which:\n- **Appends** to `LEDGER.md` and `.specsmith/ledger.jsonl` — never truncates\n- **Backs up** any file before overwriting it (timestamped `.bak` copy)\n- **Prevents** accidental destruction of audit history\n\nThis satisfies **EU AI Act Art. 12** (records must be kept for the lifetime of the system)\nand provides recovery capability per **NIST AI RMF MANAGE**.\n\n#### 6. Least-Privilege Permissions (REQ-217, REQ-012)\n\nEvery agent tool call is gated through a permission profile. Tools outside the active\nprofile are denied with exit code 3 and a ledger entry:\n\n```bash\nspecsmith agent permissions-check git_push   # exit 0 = allowed, exit 3 = denied\nspecsmith agent permissions                  # show active profile\n```\n\nFour built-in presets (`read_only`, `standard`, `extended`, `admin`) plus full\ncustom allow/deny lists in `.specsmith/config.yml`. This implements **NIST AI RMF GOVERN**\n(policy enforcement) and principle of least privilege per standard security practice.\n\n#### 7. Policy Guardrails — `is_safe_command` (REQ-220)\n\nBefore any shell command is executed, `agent.safety.is_safe_command()` classifies it\nagainst a deny list of destructive patterns (`rm -rf`, `git push origin main`,\n`kubectl apply`, `cat .env`, etc.). Denied commands are blocked and logged.\nThis implements **NIST AI RMF MANAGE** (risk treatment at the action level).\n\n#### 8. Compliance Export Report (REQ-208, REQ-215)\n\n`specsmith export` generates a full compliance report containing:\n- **AI System Inventory** — all providers, models, and versions used\n- **Risk Classification** — AEE phase, confidence scores, open work items\n- **Human Oversight Controls** — active permission profile, escalation settings, kill-switch state\n- **Audit Trail Summary** — TraceVault chain length, last verification, any tampering\n\n```bash\nspecsmith export --format markdown \u003e compliance-report.md\nspecsmith export --format json \u003e compliance-report.json\n```\n\nThis report is suitable as a starting point for audit evidence, but is **not a legal\ncertification**. Always verify with qualified counsel before regulatory submission.\n\n### Compliance per Session and per Project\n\nCompliance settings are layered:\n\n1. **Global defaults** — `~/.specsmith/config.yml` (user-level defaults)\n2. **Per-project policy** — `.specsmith/config.yml` (committed to the repo)\n3. **Per-session overrides** — CLI flags\n\nCompliance controls include: escalation threshold, permission profile, kill-switch, and\ncontext window settings. Changes take effect immediately and can optionally be written back\nto the per-project `.specsmith/config.yml`.\n\n---\n\n## Context Window Management\n\nspecsmith enforces safe, efficient use of LLM context windows — especially critical\nwhen running local models via Ollama where the context limit directly affects GPU VRAM.\n\n### GPU-Aware Context Sizing (REQ-244)\n\n```bash\nspecsmith ollama gpu                    # detect GPU VRAM (NVIDIA + AMD supported)\nspecsmith ollama available              # show models within your VRAM budget\n```\n\nVRAM tiers and recommended context sizes:\n\n| VRAM | Recommended Context |\n|---|---|\n| \u003c 6 GB (CPU or low-end GPU) | 4,096 tokens |\n| 6–11 GB | 8,192 tokens |\n| 12–19 GB | 16,384 tokens |\n| 20 GB+ | 32,768 tokens |\n\nOverride via `SPECSMITH_OLLAMA_CONTEXT_LENGTH` or `ollama.context_length` in `.specsmith/config.yml`.\n\n### Live Context Fill Indicator (REQ-245)\n\nThe context fill tracker emits real-time JSONL events:\n\n```jsonl\n{\"type\": \"context_fill\", \"used\": 27500, \"limit\": 32768, \"pct\": 83.9}\n```\n\nWhen fill reaches the compression threshold (default 80%), specsmith signals that context\nsummarization should run before the next turn.\n\n### Auto Context Compression (REQ-246)\n\nWhen fill reaches the compression threshold, specsmith automatically triggers\nconversation summarization — the current context is condensed to a compact summary\nthat preserves key decisions and facts while freeing window space. This happens\ntransparently before the next agent turn.\n\nConfigure in `.specsmith/config.yml`:\n\n```yaml\ncontext:\n  compression_threshold_pct: 80   # trigger summarization at 80% fill\n  auto_compress: true             # enable automatic compression\n```\n\n### Hard Context Ceiling — Never 100% Full (REQ-247)\n\nA hard reservation of **15% of the context window** (minimum 2,048 tokens) is always\nheld back for the governance layer. Attempts to fill beyond the effective ceiling raise\n`ContextFullError` — making it impossible to reach a state where even a compression\nrequest cannot be processed. This is a safety invariant, not a configuration option.\n\n---\n\n## Governance REST API\n\n```bash\n# Start the governance REST API (for MCP clients and IDE integrations)\nspecsmith governance-serve --port 7700 --project-dir .\n\n# Classify a natural-language utterance under Specsmith governance\nspecsmith preflight \"fix the cleanup dry-run regression\" --json\n\n# Start the agentic REPL\nspecsmith run\n\u003e what does the cleanup module do?           # read-only ask -\u003e answered\n\u003e fix the cleanup dry-run regression          # change -\u003e Specsmith approves, runs\n\u003e delete the entire dist directory            # destructive -\u003e needs clarification\n```\n\n---\n\n## Work Item (WI) Lifecycle\n\nEvery accepted `specsmith preflight` mints a **Work Item** — a unique ID such as\n`WI-3A9F1C02` that tracks user intent through the full governance lifecycle.\nWIs are persisted to `.specsmith/workitems.json` and evolve through defined states:\n\n| State | Meaning |\n|---|---|\n| `open` | Minted by preflight; work in progress |\n| `implemented` | `specsmith verify` reached equilibrium (auto-set) |\n| `promoted` | Elevated to a formal REQ-NNN via `specsmith wi promote` |\n| `closed` | Done; maps to an existing requirement |\n| `archived` | Deferred; may be re-opened |\n| `rejected` | Explicitly rejected |\n\n```bash\n# See all open work items\nspecsmith wi list --status open\n\n# View full details of a WI\nspecsmith wi show WI-3A9F1C02\n\n# Close a WI (change covered by an existing REQ)\nspecsmith wi close WI-3A9F1C02 --reason \"covered by REQ-042\"\n\n# Promote a WI to a new requirement (new behaviour, no existing REQ)\nspecsmith wi promote WI-3A9F1C02 \\\n    --title \"System must retry on transient HTTP 5xx failures\" \\\n    --domain governance\nspecsmith sync   # regenerate REQUIREMENTS.md\n\n# Set kind label\nspecsmith wi tag WI-3A9F1C02 --kind bug\n\n# Import historical WIs from LEDGER.md\nspecsmith wi import --from-ledger\n```\n\n**When to promote vs close:** Promote (`wi promote`) when the change introduces new\nbehaviour not covered by any existing REQ and the pattern is expected to recur.\nClose (`wi close`) for bug fixes, refactors, and chores that already have a matching REQ.\n\nFull documentation: [`docs/site/wi-lifecycle.md`](https://specsmith.readthedocs.io/en/stable/wi-lifecycle/)\n\n---\n\n## Nexus\n\nThe Nexus runtime is specsmith's local-first agentic REPL — a\ngovernance-gated broker that sits between you and the LLM.\n\nEvery utterance passes through `specsmith preflight` before execution.\nThe broker classifies intent, matches requirements, and gates the action.\nAfter execution, `specsmith verify` checks equilibrium. The `/why` command\nshows the full governance trace.\n\n```bash\n# Interactive REPL with governance\nspecsmith run\nnexus\u003e fix the cleanup bug         # broker classifies → accepts → executes → verifies\nnexus\u003e /why                         # show governance trace for last action\nnexus\u003e /exit\n```\n\nThe Nexus broker:\n- **Preflight gate**: every change goes through `specsmith preflight`\n- **Bounded retry**: failed actions retry up to 3× with strategy classification\n- **Execution trace**: every action is sealed in the cryptographic trace vault\n- **`/why` toggle**: shows governance rationale in human-readable form\n\n**How it works.** A natural-language **broker** classifies intent, infers scope from\nyour requirements, and asks Specsmith to **preflight** the request. Only when the\npreflight decision is `accepted` does Nexus drive the AG2 orchestrator — and it does so\nthrough a **bounded-retry harness** so you can never accidentally run away. By default,\nNexus speaks plain English; toggle `/why` in the REPL to surface the underlying\nrequirement, test, and work-item identifiers Specsmith assigned.\n\n**Pieces in this repo.**\n- `specsmith preflight` — CLI subcommand emitting a deterministic governance JSON payload\n  (`decision`, `requirement_ids`, `test_case_ids`, `confidence_target`, `instruction`).\n- `src/specsmith/agent/broker.py` — natural-language broker (intent + scope + narration).\n- `src/specsmith/agent/repl.py` — Nexus REPL with the `/why` toggle and execution gate.\n- `docker-compose.yml` — pinned vLLM `l1-nexus` model server with the Hermes tool-call parser.\n- `scripts/nexus_smoke.py` — opt-in live smoke test (`NEXUS_LIVE=1` to run against\n  a running container).\n\n---\n\n## AI Model Intelligence\n\nspecsmith ships a complete AI model intelligence layer for tracking, scoring, and routing\nto the best available LLM for each task type.\n\n### HF Open LLM Leaderboard Sync (REQ-263..REQ-269)\n\nSyncs benchmark data from the HuggingFace Open LLM Leaderboard and computes three\ntask-specific bucket scores — **reasoning**, **conversational**, and **longform** — for\nevery model. A 40+ model static fallback ensures scores are always available even without\nnetwork access.\n\n```bash\nspecsmith model-intel sync                  # sync from HF leaderboard (static fallback if offline)\nspecsmith model-intel scores                # list all cached bucket scores\nspecsmith model-intel scores --model gpt-4o # show scores for a specific model\nspecsmith model-intel recommendations       # top-10 models for reasoning bucket\nspecsmith model-intel recommendations --bucket conversational  # or longform\nspecsmith model-intel connection            # test HF API connectivity + token status\n```\n\nSet `SPECSMITH_HF_TOKEN` for authenticated access (1000 req/5min instead of 500).\nScores persist to `~/.specsmith/model_scores.json`. Background sync runs 15s after startup\nthen daily.\n\n**Bucket formulas (normalised 0-100):**\n- Reasoning = 0.35×MATH + 0.30×GPQA + 0.25×BBH + 0.10×IFEval\n- Conversational = 0.40×IFEval + 0.35×MMLU-PRO + 0.25×BBH\n- Longform = 0.35×MUSR + 0.35×IFEval + 0.30×MMLU-PRO\n\n### Model Capability Profiles (REQ-270..REQ-271)\n\n40+ pre-built model profiles cover all major providers (OpenAI, Anthropic, Google, Mistral,\nMeta Llama, Qwen, DeepSeek, and local Ollama variants). Each profile specifies:\n`max_tokens`, `prompt_style` (sections/xml/markdown), `supports_vision`,\n`supports_tool_calls`, `reasoning_mode`, and `context_window`.\n\nContext-aware history trimming preserves system messages while summarising older turns when\nthe token budget is exceeded:\n\n```python\nfrom specsmith.agent.model_profiles import get_profile, trim_history\n\nprofile = get_profile(\"qwen2.5:14b\")   # exact or prefix match; returns default if unknown\nmessages = trim_history(messages, budget_chars=12000)\n```\n\n### LLM Client with Provider Fallback (REQ-275..REQ-277)\n\n`LLMClient` wraps multiple providers with automatic fallback on 429 / 401 errors,\nO-series parameter translation (`max_completion_tokens`, temperature=1, developer role),\nand vLLM guided-JSON payload injection:\n\n```python\nfrom specsmith.agent.llm_client import LLMClient\n\nclient = LLMClient([\n    {\"provider_type\": \"cloud\", \"model\": \"gpt-4o\", ...},\n    {\"provider_type\": \"ollama\", \"model\": \"qwen2.5:14b\", ...},  # local fallback\n])\nresult = client.chat([{\"role\": \"user\", \"content\": \"hello\"}])\n```\n\n### Endpoint Presets + Suggest Profiles (REQ-278..REQ-280)\n\nA registry of 10+ pre-configured endpoint presets for common cloud and local LLM providers:\n\n```bash\nspecsmith agent endpoint-presets            # list all presets (vllm, lm_studio, openrouter, etc.)\nspecsmith agent endpoint-presets --json     # machine-readable output\nspecsmith agent suggest-profiles            # suggest optimal profiles based on env (API keys, hardware)\nspecsmith agent suggest-profiles --json     # structured suggestions with bucket/role annotations\n```\n\nSuggestions are read-only (never persisted) and inspect `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,\n`GOOGLE_API_KEY`, and local Ollama availability.\n\n---\n\n## Multi-Agent DAG Dispatcher (REQ-321..334)\n\nThe `specsmith dispatch` command group decomposes a task into a **Directed Acyclic Graph** of\nagent work items and executes them concurrently, with fail-forward BLOCKED propagation and\nESDB context injection between nodes.\n\n```bash\n# Run a task through the DAG dispatcher (default: up to 4 concurrent workers)\nspecsmith dispatch run \"add API endpoint with tests\" --max-workers 4\n\n# Stream JSONL events while the run is in progress\nspecsmith dispatch run \"refactor auth module\" --json\n\n# Check status of a saved run\nspecsmith dispatch status --dag-id abc123def456\n\n# List all saved runs\nspecsmith dispatch list\n\n# Retry a single failed node from a checkpoint\nspecsmith dispatch retry --node impl --dag-id abc123def456\n```\n\nThe dispatcher is also available programmatically:\n\n```python\nfrom specsmith.agent.orchestrator import Orchestrator\n\norchestrator = Orchestrator()\n\n# Use the DAG path (falls back to GroupChat on cycle detection)\nresult = orchestrator.run_task(\"add feature X\", use_dag=True)\n\n# Always use DAG — returns DispatchSummary with per-node outcomes\nsummary = orchestrator.run_dispatch(\n    \"add feature X\",\n    planner_output=[\n        {\"id\": \"arch\", \"title\": \"Design\", \"role\": \"architect\", \"depends_on\": []},\n        {\"id\": \"impl\", \"title\": \"Implement\", \"role\": \"coder\", \"depends_on\": [\"arch\"]},\n        {\"id\": \"test\", \"title\": \"Write tests\", \"role\": \"tester\", \"depends_on\": [\"arch\"]},\n    ],\n    max_workers=3,\n)\nprint(f\"{len(summary.completed)} completed, {len(summary.failed)} failed\")\n```\n\nEvents are persisted to `.specsmith/dispatch/\u003cdag_id\u003e/events.jsonl` for resume and replay.\n\n---\n\n## Compiler and Tool Support\n\nAll agent roles can invoke compiler, linter, and formatter tools. These are registered in\n`AVAILABLE_TOOLS` and wired into `ROLE_TOOLS` for the `coder`, `reviewer`, `tester`, `architect`,\nand `embedded-coder` roles.\n\n| Tool | Function | Default binary |\n|------|----------|-|\n| GCC / G++ | `run_gcc(args, compiler='gcc')` | `gcc` / `g++` |\n| ARM bare-metal | `run_arm_gcc(args, compiler='arm-none-eabi-gcc')` | `arm-none-eabi-gcc` |\n| AArch64 Linux | `run_aarch64_gcc(args, compiler='aarch64-linux-gnu-gcc')` | `aarch64-linux-gnu-gcc` |\n| IAR Embedded | `run_iar_compiler(project_file, executable='IarBuild')` | `IarBuild` |\n| Intel oneAPI | `run_intel_compiler(args, compiler='icx')` | `icx` / `icpx` / `icc` |\n| clang-format | `run_clang_format(files, style='file', in_place=False)` | `clang-format` |\n| clang-tidy | `run_clang_tidy(files, checks='', fix=False)` | `clang-tidy` |\n| VSG (VHDL) | `run_vsg(files, rules=None, fix=False)` | `vsg` |\n\nAll tools are usable directly in the agentic REPL and in `specsmith dispatch` worker nodes:\n\n```python\nfrom specsmith.agent.tools import run_arm_gcc, run_clang_tidy, run_vsg\n\n# Cross-compile for ARM bare-metal\nresult = run_arm_gcc(\"-Wall -O2 main.c -o firmware.elf\", compiler=\"arm-none-eabi-gcc\")\n\n# Lint C/C++ with clang-tidy\nresult = run_clang_tidy(\"src/\", checks=\"modernize-*,readability-*\")\n\n# Style-check VHDL files\nresult = run_vsg(\"rtl/top.vhd\", rules=\"vsg_rules.yaml\")\n```\n\n---\n\n## Supporting specsmith\n\nspecsmith is open source and built by a small team. Every bit of support helps:\n\n- ⭐ **Star** [specsmith](https://github.com/layer1labs/specsmith) on GitHub\n- 📣 **Tell your friends and colleagues** — word of mouth is our best marketing\n- 🐛 **Report bugs** via [GitHub Issues](https://github.com/layer1labs/specsmith/issues) — even small ones help\n- 💡 **Suggest features** via [GitHub Discussions](https://github.com/layer1labs/specsmith/discussions) — we read every suggestion\n- 🔧 **Fix bugs and contribute** — see [CONTRIBUTING.md](https://github.com/layer1labs/specsmith/blob/main/CONTRIBUTING.md); PRs welcome\n- 📝 **Write about specsmith** — blog posts, tutorials, and talks help the community grow\n- ❤️ **[Sponsor layer1labs](https://github.com/sponsors/layer1labs)** — directly funds development\n\n---\n\n## Ollama — Local LLMs (Zero API Cost)\n\nspecsmith has first-class Ollama support, including:\n\n```bash\nspecsmith ollama gpu                    # detect GPU and VRAM tier\nspecsmith ollama available              # show catalog filtered by VRAM budget\nspecsmith ollama available --task code  # filter by task type\nspecsmith ollama pull qwen2.5:14b      # download a model\nspecsmith ollama suggest requirements  # task-based recommendations\nspecsmith ollama list                  # show installed models\n```\n\nGPU-aware context sizing: 4K/8K/16K/32K tokens based on detected VRAM.\nOverride via `SPECSMITH_OLLAMA_CONTEXT_LENGTH` env var or `ollama.context_length` in `.specsmith/config.yml`.\n\n**VRAM-aware model lineup (REQ-445):** `specsmith local-model recommend` prints a per-role\nlineup — default / fast / harder pass / general — keyed to your detected VRAM, with a fit\nassessment (`fits` / `tight` / `spills`) so you can see which models run fully on the GPU\nbefore pulling. `specsmith local-model detect` and `specsmith local-model setup` pick and\ninstall a single hardware-appropriate Qwen2.5-Coder model.\n\n---\n\n## FPGA / HDL Projects\n\nspecsmith supports FPGA-specific project types with full governance:\n\n```yaml\n# scaffold.yml\ntype: fpga-rtl-amd          # or fpga-rtl-intel / fpga-rtl-lattice / fpga-rtl\nfpga_tools:\n  - vivado\n  - gtkwave\n  - vsg\n  - ghdl\n  - verilator\n```\n\nSupported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.\n**Simulation:** ghdl, iverilog, verilator, modelsim, questasim, xsim.\n**Waveform:** gtkwave, surfer. **Linting:** vsg, verible, svlint.\n**Formal:** symbiyosys. **OSS flow:** yosys, nextpnr, openFPGALoader.\n\n---\n\n## 50+ CLI Commands\n\n**Governance:** `init` `import` `audit` `validate` `diff` `upgrade` `compress` `doctor` `export` `architect`\n\n**AEE Epistemic:** `stress-test` `epistemic-audit` `belief-graph` `trace seal/verify/log`\n\n**Workflow:** `phase show/set/next/list` `ledger add/list` `req list/add/gaps/trace`\n\n**Work Items:** `wi list` `wi show` `wi close` `wi archive` `wi promote` `wi tag` `wi import`\n\n**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills` `agent suggest-profiles` `agent endpoint-presets`\n\n**Dispatch:** `dispatch run` `dispatch status` `dispatch list` `dispatch retry`\n\n**Model Intel:** `model-intel sync` `model-intel scores` `model-intel recommendations` `model-intel connection`\n\n**Ollama:** `ollama list/available/gpu/pull/suggest`\n\n**Local Model:** `local-model detect/recommend/setup`\n\n**Workspace:** `workspace init/audit/export`\n\n**Integrations:** `integrate warp` `integrate codity` `integrate claude-code` `integrate cursor` `integrate copilot` `integrate aider` `integrate gemini` `integrate windsurf` `integrate agent-skill`\n\n**VCS:** `commit` `push` `pull` `save` `load` `sync` `branch` `pr` `status` `checkpoint`\n\n**Tools:** `tools scan [--fpga]` `tools install \u003ctool\u003e` `tools rules [--tool] [--list]`\n\n**Session \u0026 Process:** `exec` `ps` `abort` `watch` `credits` `self-update` `kill-session` `session-end`\n\n**Auth:** `auth set/list/remove/check`\n\n**Patent:** `patent search/prior-art`\n\n---\n\n## 64 Project Types\n\n**Python:** `cli-python`, `library-python`, `backend-frontend`, `backend-frontend-tray`, `embedded-python-hmi`, `research-python`.\n\n**Systems languages:** `cli-rust`, `library-rust`, `cli-go`, `cli-c`, `library-c`, `dotnet-app`.\n\n**Modern web:** `web-frontend`, `fullstack-js`, `nextjs-app`, `nuxt-app`, `sveltekit-app`, `remix-app`, `astro-site`.\n\n**AI / Agents:** `llm-app`, `agent-orchestration`, `mcp-server`, `rag-pipeline`, `mlops-platform`.\n\n**JVM:** `java-spring`, `java-library`.\n\n**Mobile:** `mobile-app`.\n\n**Infrastructure:** `serverless`, `kubernetes-operator`, `microservices`, `devops-iac`, `streaming-pipeline`, `data-warehouse`, `data-ml`.\n\n**Game development:** `game-unity`, `game-godot`.\n\n**Web3:** `smart-contract`.\n\n**Desktop:** `desktop-electron`, `desktop-tauri`.\n\n**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`.\n\n**Documents \u0026 IP:** `spec-document`, `user-manual`, `research-paper`, `research-python`, `api-specification`, `brief-lang`, `requirements-mgmt`, `patent-application`, `patent-prosecution`.\n\n**Business / Legal / AEE:** `business-plan`, `legal-compliance`, `monorepo`, `browser-extension`, `epistemic-pipeline`, `knowledge-engineering`, `aee-research`.\n\n---\n\n## epistemic Library\n\nThe standalone `epistemic` Python library works in any Python 3.10+ project — no specsmith coupling:\n\n```python\nfrom epistemic import AEESession, BeliefArtifact, StressTester\n\nsession = AEESession(\"my-project\", threshold=0.70)\nsession.add_belief(\n    artifact_id=\"HYP-001\",\n    propositions=[\"The API always returns valid JSON\"],\n    epistemic_boundary=[\"Valid auth token required\"],\n)\nsession.accept(\"HYP-001\")\nresult = session.run()\nprint(result.summary())\n# certainty=0.55, failures=2, equilibrium=False\n```\n\nUse cases: linguistics research, compliance pipelines, AI alignment, patent prosecution.\n\n---\n\n## Governance Rules\n\n22 hard rules enforced by `specsmith validate` and `specsmith audit`. Rules 1–14 cover\ncore engineering and traceability (ledger required, proposals required, platform-awareness,\ndocumentation currency, etc.). Rules 15–22 address anti-hallucination and epistemic\nstability, derived from the OEA (Ontological Epistemic Anchoring) research framework\n(Layer1Labs, 2026).\n\nFull rule reference: [`docs/governance/RULES.md`](https://github.com/layer1labs/specsmith/blob/develop/docs/governance/RULES.md)\n\n---\n\n## Codity.ai AI Code Review Integration\n\nspecsmith can scaffold [Codity.ai](https://codity.ai) AI code review into any project:\n\n```bash\nspecsmith integrate codity --project-dir ./my-project\n```\n\nThis generates:\n- `.github/workflows/codity-review.yml` (GitHub Actions) or `.gitlab-ci-codity.yml` / `.azure-pipelines/codity-review.yml` depending on your VCS\n- `docs/codity-setup.md` — one-time setup checklist\n- Appends a TODO checklist to `LEDGER.md`\n\n**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`).\n\n**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.\n\nSee the `codity-ai-review` governance skill (`specsmith skill install codity-ai-review`) for the full CLI workflow reference.\n\n---\n\n## Skills\n\nspecsmith ships **138 built-in skills** across 16 domains that AI agents (Warp, Claude Code, Codex, Cursor) can install and use.\n\n```bash\n# List all available skills\nspecsmith skill list\n\n# Search by keyword\nspecsmith skill search zephyr\n\n# Install a skill into .agents/skills/\nspecsmith skill install specsmith\nspecsmith skill install specsmith-save\nspecsmith skill install specsmith-audit\n```\n\nSkills are installed as `.agents/skills/\u003cslug\u003e/SKILL.md` and are auto-discovered by any AI tool that scans `.agents/skills/`.\n\n### Skill domains\n\n| Domain | Count | Coverage |\n|--------|-------|----------|\n| `governance` | 21 | AEE workflows, verification, release, CI polling, patent prosecution, client integrations |\n| `ai-agents` | 14 | LLM apps, MCP servers, agent orchestration, RAG, prompt engineering, fine-tuning, MLOps |\n| `software-engineering` | 14 | Code review, TDD, debugging, security hardening, API design, ADRs, Brief lang |\n| `web-backend` | 11 | Frontend UI, Next.js, REST/GraphQL, PostgreSQL, Redis, WebSockets |\n| `platform-engineering` | 10 | Helm, observability, GitOps, secrets, OAuth2, chaos engineering |\n| `embedded` | 11 | Zephyr, Yocto, FreeRTOS, bare-metal C, NuttX, Buildroot, Azure RTOS |\n| `docs` | 10 | MkDocs, Sphinx, Doxygen, JSDoc, OpenAPI, mdBook |\n| `data-engineering` | 8 | ETL/ELT, dbt, Spark, data quality, feature stores, Delta Lake |\n| `hardware` | 9 | KiCad, Altium, Vivado, Quartus, GTKWave, JTAG |\n| `corporate` | 7 | Budgets, fundraising, marketing, HR, legal |\n| `devops` | 6 | Docker, Kubernetes, Terraform, GitHub Actions |\n| `cloud` | 4 | AWS, Azure, GCP, GitHub CLI |\n| `mobile` | 4 | iOS, Android, Flutter, React Native |\n| `ssh` | 3 | SSH, WSL2, remote dev |\n| `cross-platform` | 3 | CMake, package managers, terminal awareness |\n| `productivity` | 3 | Email, presentations, MS Office |\n\n### Self-referential governance skills\n\nThree skills document specsmith itself:\n\n| Slug | Purpose |\n|------|--------|\n| `specsmith` | Master CLI reference — session workflow, commands, audit codes |\n| `specsmith-save` | When and how to run `specsmith save` |\n| `specsmith-audit` | Running audits and interpreting results |\n\n### Remote reference (Warp Oz cloud agents)\n\n```bash\noz agent run-cloud --skill \"layer1labs/specsmith:specsmith-save\" --prompt \"save my work\"\n```\n\n---\n\n## Agent Integrations\n\nRun `specsmith integrate \u003ctool\u003e` once in your project root — specsmith writes the governance file your AI client reads automatically.\n\n| Tool | Command | Generated file | MCP support |\n|---|---|---|---|\n| **Warp** | `specsmith integrate warp` | `.warp/specsmith-mcp.json` + `.warp/launch_configs/` | ✓ Native |\n| **Claude Code** | `specsmith integrate claude-code` | `CLAUDE.md` | ✓ via `.mcp.json` |\n| **Cursor** | `specsmith integrate cursor` | `.cursor/rules/governance.mdc` | ✓ via `.cursor/mcp.json` |\n| **Windsurf** | `specsmith integrate windsurf` | `.windsurfrules` | ✓ via Settings → MCP |\n| **Gemini CLI** | `specsmith integrate gemini` | `GEMINI.md` | — |\n| **Aider** | `specsmith integrate aider` | `.aider.conf.yml` | — |\n| **Copilot** | `specsmith integrate copilot` | `.github/copilot-instructions.md` | — |\n\nAll generated files embed the same core content: governance rules, the mandatory session protocol, preflight requirements, and AGENTS.md as the primary governance source.\n\n### Mandatory session protocol (all tools)\n\n```bash\n# Session start\nspecsmith kill-session 2\u003e/dev/null || true\nspecsmith audit --project-dir .\nspecsmith sync  --project-dir .\nspecsmith checkpoint --project-dir .   # output GOVERNANCE ANCHOR verbatim\n\n# Before every code change\nspecsmith preflight \"\u003cdescribe the change\u003e\" --json\n# decision == \"accepted\"           → proceed with work_item_id in scope\n# decision == \"needs_clarification\" → surface instruction to user first\n\n# Every 8–10 turns\nspecsmith checkpoint --project-dir .\n\n# Session end\nspecsmith save \u0026\u0026 specsmith kill-session\n```\n\n### Claude Code\n\n```bash\nspecsmith integrate claude-code   # writes CLAUDE.md\n```\n\nTo enable native MCP tool calls, add to `.mcp.json` (project root) or `~/.claude/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"specsmith-governance\": {\n      \"command\": \"specsmith\",\n      \"args\": [\"mcp\", \"serve\", \"--project-dir\", \".\"]\n    }\n  }\n}\n```\n\nOr run `specsmith mcp install-claude-code` to print the snippet. With MCP configured, Claude calls governance tools natively — no shell roundtrip.\n\n### Cursor\n\n```bash\nspecsmith integrate cursor   # writes .cursor/rules/governance.mdc\n```\n\nAdd to `.cursor/mcp.json` to enable MCP:\n\n```json\n{\n  \"specsmith-governance\": {\n    \"command\": \"specsmith\",\n    \"args\": [\"mcp\", \"serve\", \"--project-dir\", \"${workspaceFolder}\"]\n  }\n}\n```\n\n### Windsurf\n\n```bash\nspecsmith integrate windsurf   # writes .windsurfrules\n```\n\nMCP: **Settings → MCP Servers** → `{ \"specsmith-governance\": { \"command\": \"specsmith\", \"args\": [\"mcp\", \"serve\"] } }`\n\n### Gemini CLI\n\n```bash\nspecsmith integrate gemini   # writes GEMINI.md (read automatically by the gemini CLI)\n```\n\n### Aider\n\n```bash\nspecsmith integrate aider   # writes .aider.conf.yml\n```\n\nFor full governance, use `--no-auto-commits` and commit via `specsmith save`:\n\n```bash\naider --no-auto-commits --read AGENTS.md --read .agents/skills/specsmith-session-governance/SKILL.md\n```\n\nRun `specsmith preflight` in a separate terminal before each change; run `specsmith save` after aider finishes.\n\n### GitHub Copilot\n\n```bash\nspecsmith integrate copilot   # writes .github/copilot-instructions.md\n```\n\nCopilot reads `.github/copilot-instructions.md` for all workspace interactions. MCP not yet natively supported; governance is enforced through the instructions file and `AGENTS.md`.\n\nFull per-tool setup: **[Agent Integrations docs →](https://specsmith.readthedocs.io/en/stable/agent-integrations/)**\n\n---\n\n## Warp Terminal Integration\n\nspecsmith ships first-class integration with [Warp](https://www.warp.dev) terminal: a\none-command `specsmith integrate warp` setup, a governance MCP server, a Warp-aware\nagentic REPL, and repository workflows.\n\n### One-command setup — `specsmith integrate warp`\n\n```bash\nspecsmith integrate warp        # scaffold Warp-native governance into the repo\n```\n\nThe `warp` adapter (first-class as of v0.20.0 — no longer a legacy alias to `agent-skill`)\nwrites:\n\n- `.warp/specsmith-mcp.json` — the governance MCP server config (identical to `specsmith mcp install-warp`)\n- `.warp/launch_configs/specsmith-governed.yaml` — a Warp launch configuration that opens a governed `specsmith run` session\n- `.agents/skills/SKILL.md` — the auto-discovered governance skill\n\n### Warp-aware REPL\n\nWhen you start `specsmith run` inside Warp, specsmith detects the host terminal (via\n`TERM_PROGRAM` / `WARP_*` env vars) and shows a `terminal: Warp … — native integration\nactive` banner; the JSON `ready` frame carries a matching `terminal` field. Behavior is\nunchanged outside Warp.\n\n### Native MCP Governance Server\n\n`specsmith mcp serve` starts a zero-dependency stdio MCP server (JSON-RPC 2.0, MCP 2024-11-05).\nWarp/Oz, Cursor, Claude Code, or any other MCP client can call governance commands as structured\ntool calls — no shell roundtrip, fully typed inputs and outputs.\n\n**Setup (one time):**\n\n```bash\n# Get the Warp config snippet\nspecsmith mcp install-warp\n```\n\nCopy the output JSON into **Warp Settings → Agents → MCP servers**. Or pass it inline:\n\n```bash\noz agent run --mcp '{\"specsmith-governance\": {\"command\": \"specsmith\", \"args\": [\"mcp\", \"serve\"]}}' \\\n  --prompt \"check governance health and preflight my next change\"\n```\n\n**Six MCP tools exposed:**\n\n| Tool | What it returns |\n|---|---|\n| `governance_audit` | Full audit health JSON — passed/failed checks, fixable count |\n| `governance_checkpoint` | GOVERNANCE ANCHOR snapshot — phase, health, REQ/TEST counts, ESDB chain |\n| `governance_preflight` | Preflight decision — `accepted`/`needs_clarification` + `work_item_id` |\n| `governance_phase` | Current AEE phase, readiness %, failing checks |\n| `governance_req_list` | All requirements with status + test coverage, filterable |\n| `governance_trace_seal` | Create a cryptographic trace vault seal |\n\n### Third-party CLI agent toolbar\n\nFor **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**:\n\n```\nspecsmith\\s+run|aider\n```\n\n`claude`, `codex`, `gemini`, and `cursor` are already natively supported — no regex needed.\n\nOnce 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.\n\nRun `specsmith integrate warp` to regenerate `.warp/SETUP.md` with the full per-REPL setup guide.\n\n### Repository Workflows (Ctrl+Shift+R)\n\nClone this repo and open it in Warp — seven governance workflows appear automatically in\n`Ctrl+Shift+R` search:\n\n| Workflow | Command |\n|---|---|\n| specsmith — Session Start | Full bootstrap: kill → migrate → audit → sync → checkpoint |\n| specsmith — Audit | `specsmith audit` |\n| specsmith — Checkpoint | `specsmith checkpoint` (emits GOVERNANCE ANCHOR) |\n| specsmith — Preflight | `specsmith preflight \"{{intent}}\" --json` |\n| specsmith — Save | `specsmith save` |\n| specsmith — Phase Status | `specsmith phase show` |\n| specsmith — Session End | `specsmith save \u0026\u0026 specsmith kill-session` |\n\n---\n\n## The specsmith Bootstrap\n\nspecsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`\nin this repo to check its governance health. This means every feature we add to specsmith is\nimmediately dogfooded on specsmith itself.\n\n## Documentation\n\n**[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full manual: AEE primer,\ncommand reference, project types, tool registry, governance model, ESDB, skills integrations, Ollama guide.\n\n## Links\n\n- [PyPI](https://pypi.org/project/specsmith/)\n- [Documentation](https://specsmith.readthedocs.io)\n- [Stability Contract](https://github.com/layer1labs/specsmith/blob/develop/docs/stability.md)\n- [1.0 Release Criteria](https://github.com/layer1labs/specsmith/blob/develop/docs/roadmap/1.0-criteria.md)\n- [Editions Matrix](https://github.com/layer1labs/specsmith/blob/develop/docs/editions.md)\n- [Changelog](https://github.com/layer1labs/specsmith/blob/develop/CHANGELOG.md)\n- [Contributing](https://github.com/layer1labs/specsmith/blob/develop/CONTRIBUTING.md)\n- [Roadmap](https://github.com/layer1labs/specsmith/blob/develop/ROADMAP.md)\n- [Compatibility Matrix](https://github.com/layer1labs/specsmith/blob/develop/docs/site/compatibility.md)\n- [Product Principles](https://github.com/layer1labs/specsmith/blob/develop/docs/product-principles.md)\n- [Security](https://github.com/layer1labs/specsmith/blob/develop/SECURITY.md)\n\n## License\n\nMIT — Copyright (c) 2026 Layer1Labs Silicon, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flayer1labs%2Fspecsmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flayer1labs%2Fspecsmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flayer1labs%2Fspecsmith/lists"}