specsmither 0.4.1

Open-source, local-first, NO-LLM Control System for Agentic AI Implementation

SpecSmither drives a software scope through Specification → Epic → Ticket → DAG and two lifecycles — planning (authoring a spec under a scoring gate) and work (building each ticket under a completion gate) — entirely over a single SQLite file. The engine is fully deterministic and synchronous; all AI reasoning lives in the MCP client, never in the engine.

It imports two independent, pure gates side-by-side:

• crucible (crucible-forge) — the planning gate (rubric scorer). A published dependency from day one.
• assay (assayforge → assay) — the work-session completion gate (0.2.0, upcoming).

Status

0.1.0 — the planning release. The deterministic substrate + the full planning lifecycle (authoring a spec draft → ready through the real crucible gate) + the agent surface (MCP server, TOON) + the human surface (the Textual TUI Observatory). The work lifecycle (building tickets under the assay gate) lands in 0.2.0.

Install

uv tool install specsmither      # or: pipx install specsmither  /  pip install specsmither

This installs two commands:

Quickstart

cd my-project
specsmither          # opens the Observatory; press `i` to init the workspace

init lazily creates the user-global DB, binds this workspace to a project (.specsmither/config.json), and scaffolds .claude/ (agent skills, subagents, opt-in read-only hooks + a statusline) so an agent can drive the same DB via specsmither-mcp in parallel. Then bootstrap a spec and drive planning:

The agent registers the server as specsmither (the init scaffold writes it into .claude/settings.local.json); every MCP response is TOON.

Architecture

src/specsmither/
  domain/      enums, status transitions, runtime records (SpecFull recompose)
  db/          SQLAlchemy 2.0 ORM: base, models, migrations, *StoreSqlite repos
  dag/         status calc, single-hop cascade, dependency tree, critical path
  rollups/     count derivation, planning aggregate, in-txn recompute worklist
  operations/  CRUD, queries, search, reports, workspace/init, project, errors
  lifecycle/   planning verbs (start/action/complete) + handover, gate, state machine
  dispatch/    the single MCP routing facade (envelopes, error guidance)
  adapters/    WritePlan executor, crucible validator, lifecycle ports, config
  toon/        the TOON wire encoder (the always-on MCP encoding)
  mcp/         the stdio MCP server  → `specsmither-mcp`
  tui/         the Textual Observatory → `specsmither`

Every mutation runs in one Session.begin() (BEGIN IMMEDIATE) → apply the WritePlan → recompute worklist (cascade → counts → tree, to fixpoint) → commit/rollback. Derived data (counts, cached dependency tree) is materialized in-transaction, recomputed from the authoritative child rows (no deltas, race-free).

Runtime & workspace

SpecSmither keeps everything in one user-global SQLite database — a single specsmither.db that holds every project. A workspace is any directory bound to one project via .specsmither/config.json; different workspaces serve different projects off the same DB file (WAL + BEGIN IMMEDIATE make concurrent workspaces/agents on one file safe).

~/.specsmither/specsmither.db          # the single DB — all projects live here
~/.specsmither/config.json             # global defaults
<workspace>/.specsmither/config.json   # { "projectId": "…", "specificationId"?, … }

Resolution precedence is env > project (.specsmither/config.json) > global (~/.specsmither/config.json) > default.

Development

uv sync --locked --dev
uv run ruff check src tests
uv run mypy
uv run pytest

Requires Python 3.11+. Determinism golden fixtures live in fixtures/golden/ and Textual snapshot SVGs in tests/__snapshots__/; both are committed (regenerated via tools/ and pytest --snapshot-update), so CI runs no Node.

License

Apache-2.0.