Specsmith

Specsmith is a lean governance layer for AI-assisted development. It keeps four things explicit while your existing coding agent and toolchain do the work:

1. the requirement being changed;
2. the test that proves it;
3. the evidence that was actually observed; and
4. a compact epistemic context that does not turn guesses into facts.

Specsmith is not an IDE, autonomous coding agent, CI replacement, generic skill catalog, or legal-compliance certificate. It integrates with those tools instead of duplicating them.

Install

The CLI is distributed through PyPI and should be isolated with pipx:

pipx install specsmith
specsmith --version

Python-library use remains available from an ordinary environment:

pip install specsmith

Five-minute start

Adopt an existing repository:

cd your-project
specsmith import --project-dir . --yes
specsmith req add --title "The API returns a stable error envelope"
specsmith test add --req REQ-001 --title "Verify the error envelope" --type integration
specsmith preflight "Implement the error envelope. Scope: REQ-001" --json

Let your normal agent edit the code and let your normal test runner execute the tests. Then close the evidence loop:

pytest -q                         # or your native test command
specsmith audit --project-dir .
specsmith checkpoint --project-dir .

For a new repository, use specsmith init. See the quick start for Windows, Linux, CI, and provider setup.

The core loop

requirement -> linked test -> accepted preflight -> host edits/tests
            -> verify/audit evidence -> compact trusted context

• req and test maintain requirement-to-test traceability.
• preflight classifies intent and stops ambiguous or destructive work.
• verify, audit, and checkpoint preserve observed evidence and uncertainty.
• compress and ESDB keep context bounded without promoting unsupported claims.
• integrate and MCP expose that contract to coding agents and editors.

Run specsmith --help for the small core surface and specsmith commands for the complete supported command list.

Grace local REPL

Grace is Specsmith's optional local fallback—not a replacement for a coding agent you already use.

specsmith run

The first run explains provider recovery and useful commands:

grace> /help
grace> /status
grace> /why
grace> /specsmith preflight "Fix config repair. Scope: REQ-001"

Grace reports its active provider, model, requirement/test context, token pressure, and evidence state. Older .specsmith/nexus.yml files and the l1-nexus served-model identifier are read only as compatibility inputs; the user-facing REPL is Grace.

Use /why to inspect the evidence behind the current decision.

For CPU-safe local fallback and VRAM-aware recommendations, see the local model guide.

Agent integrations

Prefer the host tool's native Git, browser, testing, and framework capabilities. Specsmith supplies only its distinct governance context.

specsmith integrate <tool> --project-dir .
specsmith mcp --help

• Agent integration guide
• Zoo Code / Roo Code setup and config repair
• Invocation strategy

Zoo Code integration repairs missing, older, and tampered managed configuration while preserving unrelated user settings. The same generated assets and tests run on Windows and Linux.

Policy

Policy stays intentionally small. Keep preflight and linked-test enforcement on; add approvals only where risk justifies them.

required_preflight: true
required_tests: true
required_human_approval:
  - release
risk_threshold: high

See the policy reference and the examples/policies directory.

Governance efficiency benchmark

The latest completed historical run is directional, not proof that governance always saves tokens. GPT-4o-mini completed the matrix; the Qwen run was interrupted by provider credit and rate-limit errors and is excluded from model comparisons.

Condition	Pass rate	Mean tokens	Cost of pass
Ungoverned	64%	49.5k	$0.01348
Cursor rules	71%	41.1k	$0.01015
Specsmith LIGHT	57%	52.0k	$0.01500
Specsmith FULL	57%	59.9k	$0.01665

The result drove the current simplification: deterministic governance work no longer consumes model turns, context is bounded and compressed, safety oracles are hidden, benchmark cells are isolated, and zero-pass conditions remain in cost-of-pass calculations. New provider runs must fail closed on missing cells.

• Benchmark report
• Comparison validity and limitations

ESDB and evidence

SQLite is the free default ESDB. ChronoMemory/ChronoStore is an optional commercial backend for cryptographic WAL integrity, richer provenance, and epistemic rollback.

specsmith esdb status

See the ESDB guide for migration, licensing, and the Python API. Commercial inquiries: licensing@layer1labs.ai.

Development and release quality

The supported baseline is Python 3.10–3.13 on Linux, macOS, and Windows. CI enforces formatting, Ruff, mypy, strict documentation builds, governance schema validation, dependency auditing, CodeQL, the full test matrix, and built-wheel smoke tests.

ruff format --check src/ tests/
ruff check src/ tests/
pytest tests/ -q
mypy src/specsmith/
mkdocs build --strict

Contributor guidance is in CONTRIBUTING.md. Security reports belong in SECURITY.md. Release history is in CHANGELOG.md.

Documentation

• Stable documentation
• CLI and first steps
• Requirements and test workflow
• Examples

Specsmith is MIT licensed. ChronoMemory is separately licensed; see COMMERCIAL-LICENSE.md.