CLI Commands¶

specsmith has 50+ commands. Every command that operates on a project accepts --project-dir PATH (default: current directory).

`specsmith preflight`¶

Classify a natural-language utterance under Specsmith governance and emit a deterministic JSON payload (REQ-085, REQ-088, REQ-092, REQ-093, REQ-099, REQ-100).

specsmith preflight "fix the cleanup dry-run regression" --json
specsmith preflight "delete the dist directory" --json
specsmith preflight "refactor the broker" --stress --verbose --json

Options:

--project-dir PATH \u2014 project root (default: .).
--json \u2014 emit the decision as JSON on stdout.
--verbose \u2014 include a plain-language narration block alongside the JSON payload.
--stress \u2014 run an AEE stress-test pass over matched requirements; surfaces critical failures as stress_warnings.

JSON payload keys: decision (one of accepted, needs_clarification, blocked, rejected), work_item_id, requirement_ids, test_case_ids, confidence_target, instruction, intent. Optional: stress_warnings, narration.

Exit codes (REQ-092): 0 for accepted, 2 for needs_clarification, 3 for blocked/rejected. The JSON payload still prints to stdout for non-zero exits so CI scripts can branch on intent without re-parsing the entire output.

Ledger side-effects: when the decision is accepted and LEDGER.md exists, the CLI appends a preflight entry tagged with REQ-085 plus the resolved requirement_ids. Brand-new work_item_id values also get a distinct work_proposal entry tagged with REQ-044,REQ-085 (REQ-099).

`specsmith verify`¶

Verify a Specsmith-governed change set per the verification input contract (REQ-027, REQ-097).

echo '{"diff":"...","files_changed":["src/foo.py"],"test_results":{"passed":5,"failed":0}}' | \
  specsmith verify --stdin

specsmith verify --diff change.patch --tests test-results.json --logs run.log

Options:

--project-dir PATH \u2014 project root (default: .).
--stdin \u2014 read the verification input as a single JSON object from stdin.
--diff PATH / --tests PATH / --logs PATH \u2014 file-based alternatives to --stdin.
--changed a,b,c \u2014 comma-separated list of changed file paths.
--work-item-id ID \u2014 optional work item id to bind the verification to.

JSON payload keys: equilibrium, confidence, summary, files_changed, test_results, retry_strategy (one of narrow_scope, expand_scope, fix_tests, rollback, stop, or empty when equilibrium is reached), work_item_id, retry_budget, confidence_threshold.

Exit codes (REQ-097): 0 when equilibrium is reached and confidence \u2265 the configured threshold; 2 when retry is recommended; 3 when stop-and-align is required.

Agentic REPL (`specsmith run`)¶

specsmith run                            # AEE-integrated REPL (auto-detects provider)
specsmith run --provider ollama          # force local Ollama
specsmith run --task "fix lint errors"  # non-interactive single task

The broker classifies intent, infers scope from docs/REQUIREMENTS.md, calls specsmith preflight, and gates execution: only accepted decisions proceed. Toggle /why in the REPL to reveal the underlying work_item_id, requirement_ids, and test_case_ids Specsmith assigned.

`specsmith chat`¶

Run a single chat turn that emits the JSONL block protocol on stdout (REQ-112, REQ-113, REQ-114, REQ-115, REQ-116). This is the wire format consumed by IDE clients (e.g. Kairos and compatible IDE clients).

specsmith chat "add a hello world greeter" --project-dir .
specsmith chat "refactor the broker" --profile safe --interactive --decision-timeout 120

Options:

--project-dir PATH \u2014 project root (default: .).
--session-id ID \u2014 reuse an existing session id; persisted turns under .specsmith/sessions/<id>/turns.jsonl are replayed as prior context (REQ-120).
--parent-session ID \u2014 mark this run as a sub-session of the given parent (REQ-125).
--profile {safe,standard,yolo} \u2014 permission tier (REQ-115). safe emits a tool_request event and waits before executing.
--comment TEXT \u2014 reviewer comment fed into the next retry (REQ-116).
--json-events \u2014 emit JSONL block events (on by default).
--interactive \u2014 read decision events from stdin (tool_decision and diff_decision). Used by IDE consumers to drive safe-mode approval and inline diff review.
--decision-timeout SECONDS \u2014 maximum wait for a stdin decision (default 120.0).

Event protocol (selected types): block_start / block_complete (kinds: plan, message, tool_call, tool_result, diff), token, tool_call, tool_request, tool_result, plan_step, task_complete. Each event is a single JSON object on its own line.

Stdin decision protocol (only with --interactive):

{"type":"tool_decision","decision":"approve"}
{"type":"tool_decision","decision":"deny","reason":"unsafe path"}
{"type":"diff_decision","decision":"accept"}
{"type":"diff_decision","decision":"reject","comment":"use uppercase greeting"}

A non-accept diff_decision with a comment field is folded into the persisted turn's reviewer_comment so the next harness retry can consume it (REQ-116).

Real LLM backend. When chat runs, the command first attempts a real model turn through specsmith.agent.chat_runner, which selects the first available provider in this order: a local Ollama daemon (default http://127.0.0.1:11434, model qwen2.5:7b), then the anthropic, openai, and google-genai SDKs (each gated on the matching ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY env var and the SDK being installed). If no provider is reachable the runner returns None and the command falls back to a deterministic stub so tests and offline workflows stay green. Set SPECSMITH_DISABLE_REAL_CHAT=1 to force the deterministic path.

`specsmith skill`¶

Discover and install built-in agent skills.

specsmith skill list
specsmith skill search verifier
specsmith skill install diff-reviewer --project-dir ./my-project

Subcommands:

list \u2014 print the built-in catalog (verifier, planner, diff-reviewer, onboarding-coach, release-pilot).
search QUERY \u2014 fuzzy-match the catalog by slug, name, or description.
install SLUG \u2014 write the skill's SKILL.md to .agents/skills/<slug>/SKILL.md so the local Nexus runtime picks it up at session start. Existing files are preserved unless --force is passed.

`specsmith init`¶

Scaffold a new governed project.

specsmith init                                    # Interactive prompts
specsmith init --config scaffold.yml              # From config file
specsmith init --config scaffold.yml --guided     # + architecture definition
specsmith init --config scaffold.yml --no-git     # Skip git init
specsmith init --output-dir /path/to/parent       # Custom output location

Options:

--config PATH — Path to scaffold.yml. If omitted, runs interactive prompts for project name, type, platforms, VCS, branching, and integrations.
--output-dir PATH — Parent directory for the new project (default: .). The project is created as a subdirectory named after name in the config.
--no-git — Skip running git init in the new project.
--guided — After scaffolding, prompts for component names and generates REQUIREMENTS.md with REQ-{COMPONENT}-001/002 stubs, TESTS.md with linked tests, and architecture.md with component descriptions.

What it generates: AGENTS.md, LEDGER.md, modular governance, project docs, type-specific directories, CI config, dependency management, agent integration files, scripts, and scaffold.yml.

Exit codes: 0 on success, 1 if the output directory already exists and is not empty.

`specsmith import`¶

Adopt an existing project by detecting its structure and generating governance overlay.

specsmith import --project-dir ./my-project
specsmith import --project-dir ./my-project --force
specsmith import --project-dir ./my-project --guided

Options:

--project-dir PATH — Project root to analyze (default: .).
--force — Overwrite existing governance files. Without this flag, existing files (AGENTS.md, LEDGER.md, etc.) are preserved.
--guided — After generating overlay, prompts for component names and generates richer REQ/TEST stubs.

Merge behavior: Import only generates files that don't already exist. This means you can safely run import on a project that already has a hand-crafted AGENTS.md — it will add the missing pieces (scaffold.yml, docs/governance/, REQUIREMENTS.md) without touching what's already there.

Detection: Language (by file extension counts), build system (pyproject.toml, Cargo.toml, etc.), test framework, CI platform, VCS remote, modules, entry points, test files, existing governance. See Importing Projects for full details.

`specsmith checkpoint`¶

Emit a compact GOVERNANCE ANCHOR to prevent session drift (REQ-351). Run this every 8–10 turns and always include the output verbatim in any context summary so governance state survives context window compression in any chat application.

specsmith checkpoint                      # human-readable GOVERNANCE ANCHOR block
specsmith checkpoint --json               # machine-readable JSON payload
specsmith checkpoint --project-dir ./my-project

Output fields (--json): ts, project, phase, phase_label, phase_pct, health, audit_failed, req_count, test_count, esdb_records, esdb_chain_valid, recent_wis, last_preflight, anchor.

Typical agent usage:

# At session start (output verbatim as first response)
specsmith audit && specsmith sync && specsmith checkpoint

# Every 8-10 turns — tag the output clearly
# ⎠ GOVERNANCE ANCHOR:
# <paste checkpoint output here>

# When producing any context summary — checkpoint goes at top
specsmith checkpoint --json   # machine-readable for programmatic injection

All data gathering is best-effort: the command never fails even on projects with no ESDB WAL, no LEDGER.md, or no .specsmith/ directory.

`specsmith sync`¶

Sync .specsmith/ machine-state JSON from docs/ Markdown (REQ-003).

specsmith sync                            # regenerate requirements.json + testcases.json
specsmith sync --check                    # CI: exit 1 if out of sync, no writes
specsmith sync --json                     # emit result as JSON

Markdown files in docs/ are always the source of truth; the JSON files are a derived cache that tools like preflight and verify read for fast machine-state lookup. Run sync after any edit to docs/REQUIREMENTS.md or docs/TESTS.md.

`specsmith governance-serve`¶

Start the governance REST API server for Kairos (REQ-001 Kairos side).

specsmith governance-serve --port 7700   # default port for Kairos integration
specsmith governance-serve --port 7700 --project-dir ./my-project

Endpoints: - GET /health — liveness probe; returns {"status": "ok", "version": "..."} - POST /preflight — governance gate; returns a PreflightDecision JSON - POST /verify — post-change verification; returns a VerifyResult JSON

This is separate from specsmith serve (port 8421, chat/SSE for IDE clients). Architecture invariant I2 enforced: host must be localhost (127.0.0.1 / ::1). External hosts are rejected.

`specsmith agent permissions`¶

Show the active least-privilege permission profile for this project (REG-012).

specsmith agent permissions                  # human-readable profile
specsmith agent permissions --json           # JSON summary
specsmith agent permissions-check git_push   # check specific tool (exit 0=ok, 3=denied)
specsmith agent permissions-check git_push --no-log  # dry-run, no ledger write

Configure in docs/SPECSMITH.yml:

agent:
  permissions:
    preset: standard       # read_only | standard | extended | admin
    allow: [read_file, write_file, run_shell, git_status, git_diff]
    deny:  [git_commit, git_push, git_create_pr, open_url]

Denied tool attempts are logged to docs/LEDGER.md as permission-denied entries (REG-012 audit trail).

`specsmith audit`¶

Run drift detection and health checks.

specsmith audit --project-dir ./my-project
specsmith audit --fix --project-dir ./my-project

Checks performed:

Required files — AGENTS.md and LEDGER.md must exist
Modular governance — If AGENTS.md exceeds 200 lines, docs/governance/*.md must exist
REQ↔TEST coverage — Every requirement ID in REQUIREMENTS.md must have a Covers: reference in TESTS.md
Ledger health — LEDGER.md must be under 500 lines; open TODOs must be under 20
Governance size — Individual governance files must not exceed their line thresholds
Tool configuration — CI config must reference the expected verification tools for the project type (reads scaffold.yml to determine type)

--fix auto-repairs:

Creates stub AGENTS.md and LEDGER.md if missing
Creates stub modular governance files if missing
Compresses oversized ledger via specsmith compress
Generates CI config from the tool registry if missing or incomplete

Exit codes: 0 if healthy, 1 if issues found.

`specsmith validate`¶

Check governance file consistency.

specsmith validate --project-dir ./my-project

Checks: scaffold.yml structure and required fields, AGENTS.md local file references resolve, requirement ID uniqueness across REQUIREMENTS.md, architecture.md references at least one requirement.

Exit codes: 0 if valid, 1 if issues found.

`specsmith compress`¶

Archive old ledger entries when LEDGER.md grows too large.

specsmith compress --project-dir ./my-project
specsmith compress --threshold 300 --keep-recent 20 --project-dir ./my-project

Options:

--threshold INT — Only compress if LEDGER.md exceeds this many lines (default: 500).
--keep-recent INT — Keep the N most recent entries in LEDGER.md (default: 10).

Archived entries are moved to docs/ledger-archive.md. This is non-destructive — the full history is preserved, just split across files.

`specsmith upgrade`¶

Update governance files to a newer spec version.

specsmith upgrade --spec-version 0.3.0 --project-dir ./my-project

Re-renders all governance templates (docs/governance/*.md) using the current scaffold.yml config and the new version. Updates scaffold.yml with the new spec_version. Does not touch AGENTS.md, LEDGER.md, or project source code.

`specsmith status`¶

Show CI, alerts, and PR status from the VCS platform CLI.

specsmith status --project-dir ./my-project

Requires: gh (GitHub), glab (GitLab), or bb (Bitbucket) CLI installed and authenticated. Reads scaffold.yml to determine which platform to use.

Shows: Latest CI run status, Dependabot/security alert count, open PR/MR count.

`specsmith diff`¶

Compare current governance files against what specsmith templates would generate.

specsmith diff --project-dir ./my-project

For each governance file, reports: ✓ (matches template), ~ (differs from template), or ✗ (missing). Useful after manual edits to see what's drifted from the spec.

`specsmith export`¶

Generate a compliance and coverage report.

specsmith export --project-dir ./my-project                    # Print to terminal
specsmith export --project-dir ./my-project --output report.md # Save to file

Report sections: Project summary, verification tools, REQ↔TEST coverage matrix (with percentage), audit summary (pass/fail/fixable), recent git activity (last 10 commits, contributors), governance file inventory.

See Export & Compliance for a detailed breakdown.

`specsmith doctor`¶

Check if the verification tools for your project type are installed locally.

specsmith doctor --project-dir ./my-project

Reads scaffold.yml, looks up the ToolSet for the project type, and checks if each tool is available on PATH. Reports installed (with version) or missing for each tool across all 7 categories (lint, typecheck, test, security, build, format, compliance).

See Doctor for details.

`specsmith architect`¶

Generate or enrich architecture documentation by scanning the project and interviewing you.

specsmith architect --project-dir ./my-project
specsmith architect --project-dir ./my-project --non-interactive

What it does: Scans for modules, languages, dependencies, git history, and existing architecture docs. In interactive mode, prompts for component names, purposes, interfaces, data flow, and deployment notes. Generates a rich docs/ARCHITECTURE.md.

Options:

--non-interactive — Skip prompts, auto-generate from scan data only.

`specsmith self-update`¶

Update specsmith itself.

specsmith self-update                       # Auto-detect channel
specsmith self-update --channel dev          # Force dev channel
specsmith self-update --version 0.1.3        # Pin specific version

Auto-detects whether you're on stable or dev and upgrades accordingly.

`specsmith credits`¶

AI credit/token spend tracking and analysis.

specsmith credits summary                                # Spend overview
specsmith credits summary --month 2026-04                # Monthly view
specsmith credits record --model claude-sonnet \          # Record usage
  --provider anthropic --tokens-in 5000 --tokens-out 2000 --task "import"
specsmith credits report --output credits-report.md      # Markdown report
specsmith credits analyze                                # Optimization insights
specsmith credits budget --cap 50 --alert-pct 80         # Set budget

Subcommands:

summary — Aggregate spend by model, provider, task. Shows budget alerts.
record — Log a credit usage entry (model, provider, tokens, task, cost).
report — Generate markdown credit report.
analyze — Detect model inefficiency, token waste, cost trends. Recommendations.
budget — View/set monthly cap, alert threshold, watermark levels.

Credit data stored locally at .specsmith/credits.json (gitignored).

`specsmith exec`¶

Execute a command with PID tracking and timeout enforcement.

specsmith exec "pytest tests/" --timeout 300
specsmith exec "make build" --timeout 120 --project-dir ./my-project

Options:

--timeout INT — Maximum seconds to wait (default: 120). Process is killed when deadline fires.
--project-dir PATH — Project root (default: .). PID and log files go under .specsmith/.

Tracks the process in .specsmith/pids/<pid>.json and logs stdout/stderr to .specsmith/logs/. Works on Windows (taskkill), Linux, and macOS (SIGTERM → SIGKILL).

Exit codes: Mirrors the child process exit code. Returns 124 on timeout.

`specsmith ps`¶

List tracked running processes.

specsmith ps --project-dir ./my-project

Shows PID, time remaining to timeout, and command for every tracked process. Prunes stale PID files for processes that already exited.

`specsmith abort`¶

Kill tracked process(es).

specsmith abort --pid 12345
specsmith abort --all

Options:

--pid INT — Kill a specific tracked PID.
--all — Kill every tracked process.

Without --pid or --all, prints the current process list and instructions.

`specsmith commit`¶

Governance-aware commit: checks ledger, optionally audits, then commits.

specsmith commit -m "feat: add export command"
specsmith commit --no-audit --auto-push

Options:

-m / --message TEXT — Override the commit message (default: last ledger entry heading).
--no-audit — Skip the pre-commit audit check.
--auto-push — Push after a successful commit.

Warns if LEDGER.md was not updated since the last commit.

`specsmith push`¶

Push the current branch with safety checks.

specsmith push
specsmith push --force

Options:

--force — Skip branch-protection checks.

`specsmith pull`¶

Pull latest, or discard local changes and hard-reset to remote.

specsmith pull --project-dir ./my-project            # standard git pull
specsmith pull --discard --project-dir ./my-project  # git fetch + reset --hard
specsmith pull --clean --project-dir ./my-project    # reset + git clean -fd

Options:

--discard — Hard-reset to origin/<branch>, discarding all local uncommitted changes. Runs git fetch first.
--clean — Same as --discard plus git clean -fd to remove untracked files. Useful for a full workspace reset.

Standard pull warns about conflicts in governance files (AGENTS.md, LEDGER.md, docs/governance/*).

`specsmith branch`¶

Strategy-aware branch management.

specsmith branch create feature/my-feature
specsmith branch list

Subcommands:

create NAME — Create a branch following the configured branching strategy (gitflow / trunk-based / GitHub Flow). Reads strategy from scaffold.yml.
list — List branches with their role annotation (main, develop, feature, hotfix, etc.).

`specsmith pr`¶

Create a PR with governance context in the body.

specsmith pr --title "Add export command"
specsmith pr --draft

Options:

--title TEXT — PR title.
--draft — Create as a draft PR.

Appends the first 2000 characters of specsmith export output to the PR body. Requires gh (GitHub), glab (GitLab), or bb (Bitbucket) CLI.

`specsmith session-end`¶

Run the end-of-session checklist.

specsmith session-end --project-dir ./my-project

Checks: uncommitted changes, ledger updated, open TODOs count, audit health. Reports items that need action before ending the session.

`specsmith update`¶

Check for updates and optionally install the latest version + migrate the project.

specsmith update
specsmith update --check            # Check only, don't install
specsmith update --yes              # Skip confirmation prompt

Options:

--check — Print available version and exit without installing.
--yes — Auto-confirm update and migration prompts.

Auto-detects channel (stable vs dev) from the installed version. Runs migrate-project if the project scaffold needs migration after the update.

`specsmith apply`¶

Regenerate CI and agent integration files from the current scaffold.yml.

specsmith apply --project-dir ./my-project

Re-renders GitHub Actions / GitLab CI / Bitbucket Pipelines config and agent integration files (CLAUDE.md, GEMINI.md, .agents/skills/SKILL.md, etc.). Safe: never overwrites AGENTS.md, LEDGER.md, or user-authored docs.

`specsmith integrate`¶

Scaffold third-party tool integrations into a project.

specsmith integrate codity --project-dir ./my-project   # Codity.ai AI code review
specsmith integrate agent-skill                         # Agent skill SKILL.md
specsmith integrate claude-code                         # CLAUDE.md for Claude Code
specsmith integrate cursor                              # .cursor/rules/ for Cursor
specsmith integrate aider                               # .aider.conf.yml
specsmith integrate copilot                             # .github/copilot-instructions.md
specsmith integrate gemini                              # GEMINI.md
specsmith integrate windsurf                            # .windsurfrules

codity integration (REQ-354):

Generates the Codity.ai AI code review CI workflow for the detected VCS host:

GitHub (default): .github/workflows/codity-review.yml (GitHub Actions, uses CODITY_ACCESS_TOKEN secret)
GitLab (detected from scaffold.yml or .gitlab-ci.yml): .gitlab-ci-codity.yml
Azure DevOps (detected from scaffold.yml or azure-pipelines.yml): .azure-pipelines/codity-review.yml

Also writes docs/codity-setup.md (setup checklist) and appends a TODO entry to LEDGER.md.

See the generated docs/codity-setup.md file in your project and the codity-ai-review skill for the pre-commit workflow.

`specsmith migrate-project`¶

Migrate project scaffold to the current specsmith version.

specsmith migrate-project --project-dir ./my-project
specsmith migrate-project --dry-run

Options:

--dry-run — Show what would change without writing.

`specsmith release`¶

Bump the version string everywhere and scan for stale references.

specsmith release 0.3.0
specsmith release 0.3.0 --project-dir ./my-project

Updates version in pyproject.toml, Cargo.toml, package.json, src/**/__init__.py, README badges, and CHANGELOG. Scans for references to the old version that may need updating. Prints the next manual steps (CHANGELOG, git tag, push).

`specsmith verify-release`¶

Post-release smoke check: verify PyPI, RTD, and GitHub release are live.

specsmith verify-release

Checks that the installed version is published on PyPI, that the RTD site is reachable, and that the GitHub Release tag exists. Requires gh CLI for the GitHub check.

`specsmith ledger`¶

Structured ledger management.

specsmith ledger add "Implemented export command" --type feature --reqs REQ-CLI-005
specsmith ledger list --since 2026-03-01
specsmith ledger stats

Subcommands:

add DESCRIPTION — Append a structured entry. Options: --type (task/feature/fix/migration), --author, --reqs (comma-separated REQ IDs).
list — List ledger entries. Option: --since YYYY-MM-DD.
stats — Show entry count and per-author breakdown.

`specsmith req`¶

Requirements management.

specsmith req list
specsmith req add REQ-CLI-010 --component cli --priority high --description "Add export"
specsmith req trace
specsmith req gaps
specsmith req orphans

Subcommands:

list — List all requirements with status, priority, and description.
add REQ_ID — Add a new requirement stub to docs/REQUIREMENTS.md.
trace — Show REQ → TEST traceability matrix (which tests cover each requirement).
gaps — List requirements that have no test coverage.
orphans — List tests that reference non-existent requirement IDs.

`specsmith plugin`¶

List installed specsmith plugins.

specsmith plugin

Plugins extend project types and tool registries. They register via pyproject.toml entry points under specsmith.types. Shows each plugin's load status and any import errors.

`specsmith serve`¶

Start the local API server for the web dashboard (placeholder).

specsmith serve --port 8910

Not yet fully implemented. See project roadmap for the planned REST API.

`specsmith credits limits`¶

Manage persisted per-model RPM/TPM rate-limit profiles.

specsmith credits limits list
specsmith credits limits set --provider openai --model gpt-4o --rpm 500 --tpm 30000000
specsmith credits limits status --provider openai --model gpt-4o
specsmith credits limits defaults
specsmith credits limits defaults --install

Subcommands:

list — Print all locally saved profiles (provider, model, RPM, TPM, utilization target, concurrency).
set — Create or replace a local profile. Options: --provider, --model, --rpm, --tpm, --target FLOAT (default 0.70), --concurrency INT (default 1).
status — Show the rolling-window snapshot for a model: requests and tokens used in the current 60-second window, concurrency, moving averages.
defaults — List built-in profiles for common OpenAI, Anthropic, and Google models. Use --install to merge them into the local project config (existing overrides are preserved).

Profiles are stored at .specsmith/model-rate-limits.json (gitignored). The scheduler uses these to pace requests before dispatch and to apply exponential backoff after a 429.

`specsmith phase`¶

Track and advance the AEE workflow phase. Phase is persisted as aee_phase in scaffold.yml.

specsmith phase                     # show current phase and checklist (alias: phase show)
specsmith phase show                # show current phase, readiness %, and recommended commands
specsmith phase next                # advance to next phase (checks prerequisites)
specsmith phase next --force        # advance without checks
specsmith phase set requirements    # explicitly set phase
specsmith phase set implementation --force  # set without checks
specsmith phase list                # list all 7 phases in order
specsmith phase status              # one-line status for CI/IDE: 'requirements 📋 Requirements 60%'

Phases:

inception 🌱 — Governance scaffold, AGENTS.md, project type established
architecture 🏗 — ARCHITECTURE.md, components, key decisions sealed
requirements 📋 — REQUIREMENTS.md populated, stress-tested, equilibrium reached
test_spec ✅ — TESTS.md covers all P1 requirements (≥80%)
implementation ⚙ — Development cycle: code, commit, audit, ledger
verification 🔬 — Epistemic audit passes, trace vault sealed
release 🚀 — CHANGELOG updated, tag created, compliance report filed

Each phase has a checklist of file/command prerequisites. phase next runs the checklist before advancing.

`specsmith ollama`¶

Manage Ollama local LLM models. Requires Ollama running at localhost:11434.

specsmith ollama list                       # list installed models
specsmith ollama available                  # catalog with VRAM filter and install status
specsmith ollama available --task code      # filter by task type
specsmith ollama gpu                        # detect GPU and VRAM tier
specsmith ollama pull qwen2.5:14b          # download a model (streams progress)
specsmith ollama suggest requirements      # suggest best installed models for a task

Task types for available and suggest: code, requirements, architecture, chat, analysis, reasoning

Curated catalog (9 models):

Model	VRAM	Best for
llama3.2:latest	2 GB	chat, quick tasks
mistral:latest	4.5 GB	chat, writing
qwen2.5:7b	5 GB	coding, analysis
qwen2.5-coder:7b	4.8 GB	code generation
gemma3:12b	8 GB	general, analysis
phi4:latest	9 GB	reasoning, requirements
qwen2.5:14b	9 GB	AEE workflows (recommended)
deepseek-coder-v2	11 GB	code generation, review
qwen2.5:32b	20 GB	complex reasoning

`specsmith workspace`¶

Manage multi-project workspaces.

specsmith workspace init my-org ./backend ./frontend ./shared-lib
specsmith workspace audit --dir ./my-org
specsmith workspace export --dir ./my-org --output compliance.md

Subcommands:

init NAME [PROJECTS...] — Create workspace.yml. PROJECTS are relative paths.
audit — Run specsmith audit across all projects and report aggregate health.
export — Generate combined compliance report for all projects.

`specsmith --version`¶

specsmith --version
# specsmith, version 0.13.0

`specsmith channel` (REQ-248)¶

Manage the specsmith update channel. The channel controls whether specsmith self-update targets stable releases or dev/pre-release builds. Persisted to ~/.specsmith/channel.

specsmith channel get              # show effective channel + source
specsmith channel get --json       # JSON: {"channel": "stable", "source": "version"}
specsmith channel set stable       # pin to stable releases
specsmith channel set dev          # opt in to dev/pre-release builds
specsmith channel clear            # remove persisted preference (revert to auto-detect)

Source values: user when a preference file exists; version when inferred from the installed version string (.devN suffix ? dev, otherwise stable).

`specsmith esdb` � Extended ESDB Lifecycle (REQ-249..253)¶

Full lifecycle management for the ChronoMemory Epistemic State Database. All new commands accept --json for machine-readable output.

# Existing commands
specsmith esdb status [--json]           # status and record counts
specsmith esdb migrate                   # validate flat JSON ? ESDB migration
specsmith esdb replay                    # verify WAL chain integrity

# New commands (REQ-249..253)
specsmith esdb export [--output PATH] [--json]
  # Dump all records to <project>/.specsmith/esdb_export.json (or --output).
  # Payload: {esdb_version, backend, record_count, requirements[], testcases[]}

specsmith esdb import <source> [--json]
  # Validate a JSON export and stage it at .specsmith/esdb_import.json.
  # Exits non-zero for missing or invalid files.

specsmith esdb backup [--dir DIR] [--json]
  # Create a timestamped snapshot at .specsmith/backups/esdb_backup_<UTC>.json.
  # Payload includes: esdb_version, timestamp, backend, record_count, requirements[], testcases[]

specsmith esdb rollback [--steps N] [--json]
  # Report WAL events that would be undone (stub mode � does not modify state).
  # JSON: {ok, steps_requested, records_before, note}

specsmith esdb compact [--json]
  # Request WAL compaction (stub mode). JSON: {ok, backend, records, note}

`specsmith skills` � Full Lifecycle (REQ-254..255)¶

# Existing commands
specsmith skills build <description>     # generate skill from natural-language description
specsmith skills list [--json]           # list skills with active/inactive badge
specsmith skills test <skill-id>         # dry-run validation
specsmith skills activate <skill-id>     # set active=true

# New commands (REQ-254..255)
specsmith skills deactivate <skill-id>   # set active=false in skill.json
specsmith skills delete <skill-id> [--yes]  # permanently remove skill directory

Notes: - deactivate exits non-zero if the skill is not found. - delete prompts for confirmation unless --yes is passed. - Sibling skills are unaffected by delete.

`specsmith mcp generate` (REQ-256)¶

Generate a deterministic MCP server configuration stub from a natural-language description.

specsmith mcp generate "Search USPTO patents by keyword"
specsmith mcp generate "Calculate BMI" --json

JSON output schema:

{
  "server": {
    "id": "mcp-calculate-bmi-<hex>",
    "name": "calculate-bmi",
    "command": "node",
    "args": ["/usr/local/lib/mcp-calculate-bmi-<hex>/index.js"],
    "description": "Calculate BMI",
    "env": {}
  },
  "note": "Generated stub � review and adjust before use."
}

The generated stub can be appended to ~/.specsmith/mcp.json for use with the Kairos AI Builder card.

`specsmith agent ask` (REQ-257)¶

Keyword-based routing dispatcher that answers settings and status queries without requiring an LLM. Useful for IDE integrations and the Kairos settings agent widget.

specsmith agent ask "show esdb status" --json-output
specsmith agent ask "build skill for summarizing" --project-dir .
specsmith agent ask "check compliance gaps" --json-output

Routing table:

Keywords	Action	Subsystem called
compliance / coverage / gaps / trace	`compliance_summary`	`get_compliance_summary()`
audit / health / governance / drift	`audit`	`run_audit()`
skill / build skill / create skill	`skills_hint`	hint to `skills build`
esdb / database / backup / export / records	`esdb_status`	`EsdbBridge.status()`
mcp / server / tool server	`mcp_hint`	hint to `mcp generate`
session / phase / status / project	`session_info`	`init_session()`
(no match)	`unknown`	help text

JSON output: {"reply": "...", "action": "...", "prompt": "..."}

Exit code: always 0 (the dispatcher is best-effort).

model-intel¶

AI model intelligence — HuggingFace Open LLM Leaderboard sync, bucket scoring, and recommendations.

model-intel sync¶

specsmith model-intel sync [--json] [--project-dir DIR]

Fetch benchmark data from the HF Datasets Server and compute bucket scores for all models. Falls back to 40+ built-in static scores when HF is unreachable. Exits 0 even without network access.

JSON output: {"synced": N, "errors": 0, "message": "..."}

model-intel scores¶

specsmith model-intel scores [--model MODEL] [--bucket BUCKET] [--json] [--project-dir DIR]

List all cached bucket scores or show scores for a specific model.

Without --model: {"scores": [{"model_name": ..., "reasoning_score": ..., "conversational_score": ..., "longform_score": ...}]}

With --model: {"score": {"model_name": ..., "reasoning_score": ..., "conversational_score": ..., "longform_score": ...}}

model-intel recommendations¶

specsmith model-intel recommendations [--bucket BUCKET] [--top-k N] [--json] [--project-dir DIR]

Return the top-k models for a given bucket (reasoning/conversational/longform), sorted descending by score. Default bucket: reasoning. Default top-k: 10.

JSON output: {"recommendations": [{"model": ..., "score": ..., "reasoning": ..., "conversational": ..., "longform": ...}], "bucket": "..."}

model-intel connection¶

specsmith model-intel connection [--json] [--project-dir DIR]

Probe HuggingFace API connectivity and validate SPECSMITH_HF_TOKEN.

JSON output: {"valid": bool, "token_set": bool, "token_valid": bool, "rate_limit_tier": "...", "dataset_server_ok": bool, "message": "..."}

agent suggest-profiles¶

specsmith agent suggest-profiles [--json] [--project-dir DIR]

Suggest optimal model profiles based on available API keys and hardware (Ollama, BYOE endpoints). Suggestions are read-only — never persisted to providers.json.

Each suggestion includes: provider_type, model, bucket, role, notes.

agent endpoint-presets¶

specsmith agent endpoint-presets [--json] [--project-dir DIR]

List all built-in endpoint presets for common OpenAI-compatible LLM providers.

Includes: vllm, lm_studio, llama_cpp, openrouter, together, groq, fireworks, deepinfra, perplexity, azure_openai (10+ presets).

Each preset: {"id": ..., "label": ..., "base_url": ..., "endpoint_kind": ..., "needs_key": bool}

specsmith dispatch (REQ-321..334)¶

Multi-agent DAG dispatcher. Decomposes a task into a Directed Acyclic Graph of worker nodes and executes them concurrently with fail-forward BLOCKED propagation and ESDB context injection.

specsmith dispatch run¶

ash specsmith dispatch run TASK [--max-workers N] [--json] [--no-dag] [--project-dir DIR] [--endpoint URL] [--model MODEL]

Decompose TASK into a TaskDAG and execute with up to --max-workers concurrent workers (default 4).

--json — stream JSONL DispatchEvents to stdout while the run progresses.
--no-dag — skip DAG decomposition; fall back to flat GroupChat (equivalent to specsmith run).

Events are persisted to .specsmith/dispatch//events.jsonl for status queries and resume.

specsmith dispatch status¶

ash specsmith dispatch status [--dag-id ID] [--project-dir DIR]

Print per-node status for a saved DAG run. If --dag-id is omitted, shows the most recent run.

Output columns: status (pending/running/completed/failed/blocked) and ode_id.

specsmith dispatch list¶

ash specsmith dispatch list [--project-dir DIR]

List all saved DAG runs under .specsmith/dispatch/, showing completed and failed node counts.

specsmith dispatch retry¶

ash specsmith dispatch retry --node NODE_ID --dag-id ID [--project-dir DIR] [--endpoint URL] [--model MODEL]

Re-run a single FAILED or BLOCKED node from a saved DAG run checkpoint (REQ-330). COMPLETED nodes are not re-executed — only the specified node is retried.

Agent Compiler and Linter Tools¶

The following tools are available to agent roles (coder, eviewer, ester, mbedded-coder) and can be invoked from any dispatch node or directly in the agentic REPL.

¶

un_gcc

python run_gcc(args: str, cwd: str | None = None, compiler: str = "gcc", timeout: int = 120) -> str

Compile with GCC. Use compiler="g++" for C++, "gcc-12" to pin a version.

¶

un_arm_gcc

python run_arm_gcc(args: str, cwd: str | None = None, compiler: str = "arm-none-eabi-gcc", timeout: int = 120) -> str

Cross-compile for ARM bare-metal. Switch compiler to rm-none-eabi-g++ for C++, or rm-linux-gnueabihf-gcc for Linux userspace.

¶

un_aarch64_gcc

python run_aarch64_gcc(args: str, cwd: str | None = None, compiler: str = "aarch64-linux-gnu-gcc", timeout: int = 120) -> str

Cross-compile for AArch64 Linux (64-bit ARM). Use arch64-linux-gnu-g++ for C++.

¶

un_iar_compiler

python run_iar_compiler(project_file: str, args: str = "", executable: str = "IarBuild", timeout: int = 300) -> str

Build an IAR Embedded Workbench project. Pass -build Debug in rgs for a specific configuration. Set xecutable to the full path to IarBuild.exe if it is not on PATH.

¶

un_intel_compiler

python run_intel_compiler(args: str, cwd: str | None = None, compiler: str = "icx", timeout: int = 120) -> str

Compile with Intel oneAPI (icx/icpx) or classic (icc/icpc) compilers.

¶

un_clang_format

python run_clang_format(files: str, style: str = "file", in_place: bool = False, cwd: str | None = None) -> str

Run clang-format. Set in_place=True to apply changes; omit to print the diff. The style parameter maps to --style (e.g. "LLVM", "Google", "Mozilla", "file" for .clang-format).

¶

un_clang_tidy

python run_clang_tidy(files: str, checks: str = "", fix: bool = False, compile_commands: str | None = None, cwd: str | None = None) -> str

Run clang-tidy static analysis. Use checks="modernize-,readability-" to filter rules. Pass compile_commands to point at a compile_commands.json when not in cwd.

¶

un_vsg

python run_vsg(files: str = ".", rules: str | None = None, fix: bool = False, junit: str | None = None, cwd: str | None = None) -> str

Run VSG (VHDL Style Guide) on .vhd/.vhdl files or directories. Pass ules to supply a custom VSG YAML config; junit to write a JUnit XML report.

CLI Commands¶

specsmith preflight¶

specsmith verify¶

Agentic REPL (specsmith run)¶

specsmith chat¶

specsmith skill¶

specsmith init¶

specsmith import¶

specsmith checkpoint¶

specsmith sync¶

specsmith governance-serve¶

specsmith agent permissions¶

specsmith audit¶

specsmith validate¶

specsmith compress¶

specsmith upgrade¶

specsmith status¶

specsmith diff¶

specsmith export¶

specsmith doctor¶

specsmith architect¶

specsmith self-update¶

specsmith credits¶

specsmith exec¶

specsmith ps¶

specsmith abort¶

specsmith commit¶

specsmith push¶

specsmith pull¶

specsmith branch¶

specsmith pr¶

specsmith session-end¶

specsmith update¶

specsmith apply¶

specsmith integrate¶

specsmith migrate-project¶

specsmith release¶

specsmith verify-release¶

specsmith ledger¶

specsmith req¶

specsmith plugin¶

specsmith serve¶

specsmith credits limits¶

specsmith phase¶

specsmith ollama¶

specsmith workspace¶

specsmith --version¶

specsmith channel (REQ-248)¶

specsmith esdb � Extended ESDB Lifecycle (REQ-249..253)¶

specsmith skills � Full Lifecycle (REQ-254..255)¶

specsmith mcp generate (REQ-256)¶

specsmith agent ask (REQ-257)¶

model-intel¶

model-intel sync¶

model-intel scores¶

model-intel recommendations¶

model-intel connection¶

agent suggest-profiles¶

agent endpoint-presets¶

specsmith dispatch (REQ-321..334)¶

specsmith dispatch run¶

specsmith dispatch status¶

specsmith dispatch list¶

specsmith dispatch retry¶

Agent Compiler and Linter Tools¶

`specsmith preflight`¶

`specsmith verify`¶

Agentic REPL (`specsmith run`)¶

`specsmith chat`¶

`specsmith skill`¶

`specsmith init`¶

`specsmith import`¶

`specsmith checkpoint`¶

`specsmith sync`¶

`specsmith governance-serve`¶

`specsmith agent permissions`¶

`specsmith audit`¶

`specsmith validate`¶

`specsmith compress`¶

`specsmith upgrade`¶

`specsmith status`¶

`specsmith diff`¶

`specsmith export`¶

`specsmith doctor`¶

`specsmith architect`¶

`specsmith self-update`¶

`specsmith credits`¶

`specsmith exec`¶

`specsmith ps`¶

`specsmith abort`¶

`specsmith commit`¶

`specsmith push`¶

`specsmith pull`¶

`specsmith branch`¶

`specsmith pr`¶

`specsmith session-end`¶

`specsmith update`¶

`specsmith apply`¶

`specsmith integrate`¶

`specsmith migrate-project`¶

`specsmith release`¶

`specsmith verify-release`¶

`specsmith ledger`¶

`specsmith req`¶

`specsmith plugin`¶

`specsmith serve`¶

`specsmith credits limits`¶

`specsmith phase`¶

`specsmith ollama`¶

`specsmith workspace`¶

`specsmith --version`¶

`specsmith channel` (REQ-248)¶

`specsmith esdb` � Extended ESDB Lifecycle (REQ-249..253)¶

`specsmith skills` � Full Lifecycle (REQ-254..255)¶

`specsmith mcp generate` (REQ-256)¶

`specsmith agent ask` (REQ-257)¶