Skip to content
Spec Engine Spec Engine Spec Engine

Agent Reference

Machine-oriented reference for coding agents. For narrative and rationale, see the other docs sections.

Mental model

Section titled “Mental model”
  • Canonical truth: spec-engine/<DOMAIN>/SPEC.json in git, one shared schema on every surface. Ids (KEY-NNN) are permanent; changes supersede, never overwrite.
  • Code binds with // @spec KEY-NNN. A test tag may add unit | integration | e2e.
  • Tag kind is path-derived: implementation code implements, a test path verifies.
  • The index at <platformDir>/.spec-engine/index.sqlite is derived and disposable.
  • Coverage, drift, and propagation are SQL projections over tags. Drift compares a member’s pin (spec-engine@N) against each referenced requirement’s changed_at_version; the platform version is the max domain version. Propagation rows come in dependency order, providers before consumers, from platform-map’s dependsOn.

The repo’s AGENTS.md is the canonical copy of this page, with every command’s flags and --json shape.

Invocation

Section titled “Invocation”
Terminal window
bunx @spec-engine/spec-engine <command> [...]   # published npm package (requires Bun)
spec <command> [...]                            # after: bun add -g @spec-engine/spec-engine
bun packages/engine/src/cli.ts <command> [...]  # from a checkout
./dist/spec <command> [...]                     # compiled binary
  • Almost every command takes an optional trailing platformDir positional (default: cwd)
  • All commands are non-interactive when stdin is not a TTY
  • --json output → stdout only; guidance, warnings, diagnostics → stderr

The agent loop

Section titled “The agent loop”

Route — before changing code

Section titled “Route — before changing code”
Terminal window
spec query "renewal charge" . --json
spec resolve src/billing/renew.ts . --json

Tag — while implementing

Section titled “Tag — while implementing”
export function renew() { /* … */ }     // @spec BILLING-009
it("charges current price", () => {})   // @spec BILLING-009 unit

Check — before finishing

Section titled “Check — before finishing”
Terminal window
echo | spec req bil                    # next unused BILLING id
spec index . --json
spec check . --ci --json               # exit 1 → fix before PR
spec guard . --json                    # exit 1 → this change deletes a live requirement

Path rules for spec resolve

Section titled “Path rules for spec resolve”
  • Multi-repo platform: pass <repo>/<path> — e.g., spec resolve api/src/renew.ts .
  • Single-repo (rung-1): both repo-relative (src/orders.ts) and basename-prefixed forms accepted
  • Absolute paths normalized against platformDir; paths outside it exit 2

Gotchas

Section titled “Gotchas”
  • fixtures/ is globally ignored by the tag scanner — planted fixture tags are test data, not coverage claims
  • The DB owns nothing — never edit .spec-engine/index.sqlite; edit the SPEC.json source and re-run spec index
  • Empty ≠ error — read commands exit 0 with [] on stdout and guidance on stderr
  • Determinism is contractual — JSON outputs are deterministically sorted, byte-stable across runs