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:
- the requirement being changed;
- the test that proves it;
- the evidence that was actually observed; and
- 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
reqandtestmaintain requirement-to-test traceability.preflightclassifies intent and stops ambiguous or destructive work.verify,audit, andcheckpointpreserve observed evidence and uncertainty.compressand ESDB keep context bounded without promoting unsupported claims.integrateand 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
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.
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
Specsmith is MIT licensed. ChronoMemory is separately licensed; see COMMERCIAL-LICENSE.md.
1 maintainer
Metadata
1 maintainer
Release files for specsmith 0.25.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| specsmith-0.25.0.tar.gz | 973.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| specsmith-0.25.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.9 MB
Release files / specsmith-0.25.0.tar.gz
| Download URL | specsmith-0.25.0.tar.gz |
|---|---|
| Size | 973.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5575b667af12e89cfe7c93a05b3e1f7490ec59751e9711ad00bee35f290a19e6
|
|
BLAKE2b-256 checksum How to use checksums |
599adc676e65b5c85b2274d1035522ff6a89549e82cb469507b3d6eecdf30082
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 20, 2026.
Transparency logRelease files / specsmith-0.25.0-py3-none-any.whl
| Download URL | specsmith-0.25.0-py3-none-any.whl |
|---|---|
| Size | 895.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b998d1bc0f41d5ee3aaa7e96a884e1130a71401322afc92424771120ab4807d
|
|
BLAKE2b-256 checksum How to use checksums |
33bf5ce132bdf74cc5cd307f7eed421e61940a6c8253e59b63aea8c28da0258e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 20, 2026.
Transparency log
