{"id":50553434,"url":"https://github.com/layer1labs/specsmith","last_synced_at":"2026-06-04T05:01:11.576Z","repository":{"id":348395239,"uuid":"1197753061","full_name":"layer1labs/specsmith","owner":"layer1labs","description":"Applied Epistemic Engineering toolkit for governed AI-assisted development: requirements, tests, CI, agents, ESDB, compliance, docs, and integrations.","archived":false,"fork":false,"pushed_at":"2026-05-30T02:56:02.000Z","size":63756,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-30T03:17:15.318Z","etag":null,"topics":["aee","agentic-ai","ai-governance","applied-epistemic-engineering","ci-cd","cli","code-review","codity","compliance","epistemic-engineering","esdb","fpga","kairos","llm","mkdocs","ollama","python","readthedocs","requirements-management","traceability"],"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":null,"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-05-30T02:52:00.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":39,"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":33890052,"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-04T02:00:06.755Z","response_time":64,"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","ci-cd","cli","code-review","codity","compliance","epistemic-engineering","esdb","fpga","kairos","llm","mkdocs","ollama","python","readthedocs","requirements-management","traceability"],"created_at":"2026-06-04T05:01:10.789Z","updated_at":"2026-06-04T05:01:11.566Z","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)](LICENSE)\n\n**Applied Epistemic Engineering toolkit for AI-assisted development.**\n\n\u003e Intelligence proposes. Constraints decide. The ledger remembers.\n\nspecsmith treats belief systems like code: codable, testable, and deployable. It scaffolds\nepistemically-governed projects, stress-tests requirements as BeliefArtifacts, runs\ncryptographically-sealed trace vaults, and orchestrates AI agents under formal AEE governance.\n\n**v0.13.0 — 16 new project types (LLM apps, MCP servers, Kubernetes operators, game dev, Web3, desktop, JVM and more), 131 built-in skills across 16 domains, EU AI Act / NIST AI RMF compliance, native Warp/Oz MCP governance server, multi-agent DAG dispatch, and context window management.**\nSpecsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689)\nand the NIST AI Risk Management Framework 1.0. Every agent action is cryptographically sealed,\nevery AI-generated output is disclosed, context windows are GPU-aware and protected against\noverflow, and a dedicated governance tools panel in Kairos surfaces compliance settings\nper-session and per-project.\n\n```bash\nspecsmith governance-serve --port 7700     # Kairos governance REST API\nspecsmith sync                              # sync YAML → JSON → MD (YAML-first mode)\nspecsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md from YAML\nspecsmith validate --strict                 # YAML schema checks: dup IDs, orphans, coverage\nspecsmith agent permissions-check git_push # check tool permission (REQ-012)\nspecsmith ollama gpu                        # detect GPU VRAM, recommend context size\nspecsmith export                            # generate full compliance report\n\n# Update channel management (REQ-248)\nspecsmith channel set stable               # pin to stable releases\nspecsmith channel set dev                  # opt in to dev/pre-release builds\nspecsmith channel get --json               # show current channel + source\n\n# ESDB extended lifecycle (REQ-249..253)\nspecsmith esdb export --json               # dump all records to JSON snapshot\nspecsmith esdb import backup.json          # validate + stage an import\nspecsmith esdb backup                      # create timestamped snapshot\nspecsmith esdb rollback --steps 2          # report WAL rollback (stub)\nspecsmith esdb compact                     # request WAL compaction\n\n# Skills lifecycle (REQ-254..255)\nspecsmith skills deactivate \u003cskill-id\u003e     # set active=false in skill.json\nspecsmith skills delete \u003cskill-id\u003e --yes   # permanently remove skill\n\n# MCP config generation (REQ-256)\nspecsmith mcp generate \"Search USPTO patents\" --json  # JSON config stub\n\n# Agent ask dispatcher — no LLM required (REQ-257)\nspecsmith agent ask \"show esdb status\" --json-output\nspecsmith agent ask \"build skill for summarizing\"\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---\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` and displayed in the\nKairos Governance page. Each phase has a checklist of file/command criteria, recommended\ncommands, and a readiness percentage.\n\n---\n\n## Install\n\n**Recommended — via pipx (works with Kairos, any terminal, and CI):**\n\n```bash\npipx install specsmith                    # core CLI + epistemic library\npipx inject specsmith anthropic           # + Claude support\npipx inject specsmith openai              # + GPT / O-series support\npipx inject specsmith google-generativeai # + Gemini support\n```\n\n**Or with pip:**\n\n```bash\npip install specsmith                     # core\npip install \"specsmith[anthropic]\"       # + Claude\npip install \"specsmith[openai]\"          # + GPT/O-series\npip install \"specsmith[gemini]\"          # + Gemini\n```\n\n**Update:**\n\n```bash\npipx upgrade specsmith\nspecsmith self-update\n```\n\n---\n\n## Quick Start\n\n```bash\n# New project (interactive)\nspecsmith init\n\n# Adopt an existing project\nspecsmith import --project-dir ./my-project\n\n# Check governance health\nspecsmith audit --project-dir ./my-project\n\n# Run AEE stress-test on requirements\nspecsmith stress-test --project-dir ./my-project\n\n# Full epistemic audit (certainty + logic knots + recovery proposals)\nspecsmith epistemic-audit --project-dir ./my-project\n\n# Start the agentic REPL\nspecsmith run --project-dir ./my-project\n\n# AG2 agent shell — Planner/Builder/Verifier over Ollama\nspecsmith agent status                    # check agent config + Ollama\nspecsmith agent plan \"add logging\"        # plan only (no execution)\nspecsmith agent run \"fix lint errors\"     # full Plan → Build → Verify\nspecsmith agent improve \"add tests\"       # self-improvement with reports\nspecsmith agent verify                    # run Verifier on current state\nspecsmith agent reports                   # list improvement reports\n\n# Check current AEE workflow phase\nspecsmith phase --project-dir ./my-project\n```\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/overflow.yml` | REQ-335..356 | VCS ops, skills catalog, ESDB namespace, session governance, modern web types, Codity.ai integration |\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 (REG-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\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 (H1–H22), 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.11.4\"\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.\nKairos surfaces this as a confirmation dialog before execution proceeds.\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 and keyboard shortcut (surfaced in Kairos) immediately\nterminates all active agent sessions and records a 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 for submission to regulators, internal audit teams, or\nSOC-2 / ISO-42001 reviewers.\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** — Kairos Governance panel or CLI flags\n\nThe Kairos **Governance Tools Panel** (Settings → Governance) exposes all compliance\ncontrols in a live UI: escalation threshold, permission profile, kill-switch, audit log\nviewer, and context window settings. Changes take effect immediately for the active\nsession and can optionally be written back to 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 consumed by Kairos:\n\n```jsonl\n{\"type\": \"context_fill\", \"used\": 27500, \"limit\": 32768, \"pct\": 83.9}\n```\n\nKairos displays a compact fill bar in the agent footer. When fill reaches the\ncompression threshold (default 80%), specsmith signals that context summarization\nshould 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## Kairos + Governance REST API\n\n**Kairos** is the companion Rust terminal runtime (`BitConcepts/kairos`). specsmith\nacts as the governance backend: Kairos spawns `specsmith governance-serve` at startup\nand routes all preflight and verify calls through it.\n\n```bash\n# Start the governance REST API (Kairos calls this automatically)\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## 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### Kairos AI Providers — Bucket Score Columns (REQ-281)\n\nThe Kairos **Agents \u003e AI Providers** table gained three new columns — **R** (reasoning),\n**C** (conversational), **L** (longform) — showing each provider's HF bucket scores inline.\nA **Sync Scores** button triggers a background sync from the HF leaderboard without\ninterrupting the active session.\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.\nKairos renders the live dispatch view — see `app/` for build instructions.\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## Kairos — Flagship Terminal Client\n\n**[Kairos](https://github.com/layer1labs/kairos)** is the recommended terminal client for specsmith.\nKairos spawns specsmith as a managed governance child process at startup and routes all\npreflight, verify, and BYOE proxy calls through it. The Governance settings page shows live\nspecsmith status, version, and one-click update.\n\n```bash\n# Kairos starts specsmith automatically; or run manually:\nspecsmith governance-serve --port 7700 --project-dir .\n```\n\nThe Kairos **Dispatch Panel** (`app/` — Rust, egui/eframe) renders the multi-agent DAG live:\n- SVG DAG graph with nodes coloured by status (grey/blue/green/red/amber)\n- Gantt timeline strip showing parallelism\n- Per-node Retry (FAILED/BLOCKED) and Abort (RUNNING) buttons\n- Subscribes to `GET /api/dispatch/events?dag_id=` SSE from `specsmith serve`\n\nBuild Kairos dispatch panel: `cd app \u0026\u0026 cargo build --release`\n\nUse `pipx install specsmith` for standalone CLI usage from any terminal.\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) and [kairos](https://github.com/layer1labs/kairos) 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](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---\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**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**Workspace:** `workspace init/audit/export`\n\n**Integrations:** `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## 53 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`, `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 (H1–H22)\n\n22 hard rules enforced by `specsmith validate` and `specsmith audit`.\nFull rule text: [`docs/governance/RULES.md`](docs/governance/RULES.md)\n\n**H1–H14 — Core engineering and traceability rules:**\n- **H1** — No ledger entry = work not done.\n- **H2** — No proposal = no execution.\n- **H3** — All work must consider every target platform.\n- **H4** — No system-dependent assumptions; virtual environments required.\n- **H5** — No hidden service logic.\n- **H6** — If the task grows beyond the proposal, stop and re-propose.\n- **H7** — Every state change must be traceable and recorded.\n- **H8** — Architecture changes MUST update docs in the same work cycle.\n- **H9** — Every agent command must have a timeout.\n- **H10** — No hardcoded version strings outside `pyproject.toml`.\n- **H11** — Every loop must have a deadline; no unbounded blocking I/O.\n- **H12** — Platform-aware automation: sh/bash on Unix, `.cmd`/`.ps1` on Windows.\n- **H13** — Every proposal must declare its epistemic boundaries and assumptions.\n- **H14** — Documentation must be updated in the same work cycle as code changes.\n\n**H15–H22 — Anti-hallucination and epistemic stability (OEA framework):**\n\nRules H15–H22 are derived from the *\"Ontology-Epistemic-Agentic (OEA) Recursive\nGenerative Stability\"* study (BitConcepts Research, 2026), which empirically validated\nthe primary control mechanisms for preventing hallucination and semantic drift in\nproduction LLM systems:\n\n- **H15** — Epistemic scope bounding: no claims outside verified knowledge; say \"unknown\" rather than fabricate.\n- **H16** — Anti-drift recursion guard: max 5 autonomous generation steps before a human checkpoint.\n- **H17** — Calibration direction: express uncertainty, not false confidence.\n- **H18** — RAG retrieval filtering: validate context relevance (similarity ≥ 0.6) before injection.\n- **H19** — Synthetic contamination prevention: never mix synthetic and real data silently.\n- **H20** — Falsifiability required: cite sources or flag claims as `[HYPOTHESIS]`.\n- **H21** — Disclose all model-specific assumptions (context window, format, temperature).\n- **H22** — Cross-platform CI: green on one OS ≠ cross-platform coverage.\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**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 **131 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` | 14 | AEE workflows, verification, release, CI polling, patent prosecution |\n| `ai-agents` | 14 | LLM apps, MCP servers, agent orchestration, RAG, prompt engineering, fine-tuning, MLOps |\n| `software-engineering` | 12 | Code review, TDD, debugging, security hardening, API design, ADRs |\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` | 10 | Zephyr, Yocto, FreeRTOS, 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## Warp Terminal Integration (v0.13.0)\n\nspecsmith ships native integration with [Warp](https://www.warp.dev) terminal — both as\nan MCP server and as repository workflows.\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### 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. [Kairos](https://github.com/layer1labs/kairos)\nis the companion terminal and flagship client.\n\n## Documentation\n\n**[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full manual: AEE primer,\ncommand reference, project types, tool registry, governance model, Ollama guide, Kairos integration.\n\n## Links\n\n- [PyPI](https://pypi.org/project/specsmith/)\n- [Documentation](https://specsmith.readthedocs.io)\n- [Changelog](CHANGELOG.md)\n- [Kairos terminal client](https://github.com/layer1labs/kairos)\n- [Contributing](CONTRIBUTING.md)\n- [Security](SECURITY.md)\n\n## License\n\nMIT — Copyright (c) 2026 BitConcepts, LLC.\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"}