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

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

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

specsmith-0.25.0.tar.gz (973.3 kB view details)

Uploaded Jul 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

specsmith-0.25.0-py3-none-any.whl (895.9 kB view details)

Uploaded Jul 20, 2026 Python 3

File details

Details for the file specsmith-0.25.0.tar.gz.

File metadata

Download URL: specsmith-0.25.0.tar.gz
Upload date: Jul 20, 2026
Size: 973.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for specsmith-0.25.0.tar.gz
Algorithm	Hash digest
SHA256	`5575b667af12e89cfe7c93a05b3e1f7490ec59751e9711ad00bee35f290a19e6`
MD5	`b13017ed76caf7e0b11da7d94995f933`
BLAKE2b-256	`599adc676e65b5c85b2274d1035522ff6a89549e82cb469507b3d6eecdf30082`

See more details on using hashes here.

Provenance

The following attestation bundles were made for specsmith-0.25.0.tar.gz:

Publisher: release.yml on layer1labs/specsmith

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: specsmith-0.25.0.tar.gz
- Subject digest: 5575b667af12e89cfe7c93a05b3e1f7490ec59751e9711ad00bee35f290a19e6
- Sigstore transparency entry: 2207144194
- Sigstore integration time: Jul 20, 2026
Source repository:
- Permalink: layer1labs/specsmith@e22c0ea5e5810d5f06836b05e2d003b08254d559
- Branch / Tag: refs/tags/v0.25.0
- Owner: https://github.com/layer1labs
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@e22c0ea5e5810d5f06836b05e2d003b08254d559
- Trigger Event: push