@jaggerxtrm/substrate

Substrate is XTRM's durable work authority: a library-first Issue graph over SQLite/WAL with a terminal-native sb CLI plus first-party Pi and Claude integrations.

Current package version: 0.3.1. Published copies ship JavaScript and support Node ≥24 and Bun ≥1.3; a source checkout runs the TypeScript entrypoints directly.

60-second start

cd <git-repository>
sb init
sb issue list

sb init establishes the Git repository → Substrate Project relationship. One global ~/.xtrm/state.db can hold many Projects; global database cardinality is never project context.

Mental model

flowchart LR
  I[Issue revision + contract hash] --> R[readiness]
  R --> C[claim / workspace authority]
  C --> E[execution]
  E --> J[Journal result + WorkReceipt]
  J --> A[commit / PR / artifact]
  A --> V[validation]
  V --> X[Closure]

• Issue — authorized, revisioned work contract.
• Readiness — derived dispatchability over the current revision.
• Claim — who currently owns the work.
• Journal — append-only execution continuity: notes, findings, decisions, blockers, milestones, handoffs, results, checkpoints and compaction records. One entry's summary text is limited to 20,000 characters on the CLI and on the Pi tool, and a longer one is refused with its size rather than cut; --summary-file supplies long text from a file or stdin. The Claude MCP append path is not covered yet: it cuts at 2,000 characters.
• Resume Capsule — bounded reconstruction from durable state, not a second source of truth.
• Provenance — execution bindings, WorkReceipts, commits/PRs/artifacts, session/activation lineage and evidence queries.
• Closure — immutable terminal outcome, reason and evidence references.
• Git — code/integration truth; never the sole explanation of work state.

Normal workflow

sb init
  ↓
Issue / planning
  ↓
validate + attest readiness
  ↓
claim
  ↓
execute
  ↓
Journal finding / decision / milestone / result
  ↓
WorkReceipt + artifacts + validation
  ↓
Closure

If execution changes SCOPE, SUCCESS, NON_GOALS, CONSTRAINTS, VALIDATION or OUTPUT, stop and revise the Issue through planning. Progress belongs in the Journal, not in sb issue edit.

Human CLI

The sb binary runs through cli/sb-ux.ts for human output while the typed engine in cli/sb.ts remains the machine/JSON contract.

sb issue list                         # active board, hierarchical by default
sb issue list --status ready,blocked
sb issue list --all                   # include terminal history
sb issue list --flat --search provenance
sb issue show XTRM-252                # Markdown-aware rich terminal view
sb issue browse                       # interactive read-first navigator

in_progress, ready and blocked are derived operational states; they do not create new persisted lifecycle values. --json stays machine-oriented and fails closed when combined with human-only filters instead of silently ignoring them.

Mutations give explicit post-operation feedback: success, no-op, warning or error with remediation where the command can name one. Routine mutations do not ask for confirmation; destructive/batch flows may.

A claim, renewal or release takes its holder from --holder, else from SUBSTRATE_HOLDER, which the xt launcher exports for the session. Inside an xt session, sb issue claim <ref> is enough; --holder is only for claiming, renewing or releasing on someone else's behalf. With neither set the command fails closed, and the output names the holder and its source. resolveClaimHolder is the only place that pairing is decided — the holder is never taken from the unix user, a worktree path or a branch — and the Claude MCP and Pi claim tools apply the same rule. sb issue renew extends a live lease: the expiry moves and the generation does not.

Argument handling fails closed: an unknown flag, a value flag with no value, or surplus positional text is an error naming the offender, so a wrong invocation cannot succeed quietly. sb help contract, sb help kinds and sb help identity answer the three questions authors ask most.

Run sb --help or sb <group> <verb> --help. Help is part of the product contract and is side-effect-free.

Pi integration

Pi registers eight native Substrate tools over the same typed services:

substrate_issue_get
substrate_issue_search
substrate_issue_claim
substrate_issue_update
substrate_journal_append
substrate_journal_checkpoint
substrate_issue_resume
substrate_provenance_trace

The Pi integration also owns the claim-gated edit/write hook, resume command and mechanical-first compaction checkpoint. SUBSTRATE_ISSUE_REF is the canonical process-level rebind; SUBSTRATE_ISSUE is compatibility-only.

See docs/pi.md.

Claude integration

The substrate Claude plugin exposes a 15-tool MCP surface plus PreCompact/PostCompact/SessionStart hooks. It calls typed services in-process, never sb subprocesses or CLI-text parsing. The MCP surface includes first-class claim/release, contract update, Journal result/checkpoint/query, Closure, Issue/session/activation provenance and Resume Capsule operations.

Install from the repository marketplace with claude plugin marketplace add xtrm-dev/xtrm and claude plugin install substrate@substrate. Updates follow the version in plugin.json; see Distribution and updates.

See docs/claude.md.

Specialists integration

Specialists is the execution runtime; Substrate is the work authority. A native Specialist activation consumes a READY Issue through the WorkItemStore boundary, binds the exact revision/hash, and on meaningful settlement publishes bounded result/provenance under host control. Specialists does not get a second Issue or Journal implementation.

See docs/specialists.md.

Package layout

src/domain/          identities, contracts, Journal, Closure, provenance types
src/service/         Issue/Journal/Resume/Closure/Provenance/Repository services
src/store/           SQLite/WAL opener and append-only migrations
src/workitems/       backend-neutral Specialist work boundary
cli/                 machine engine + human terminal presentation
integrations/pi/     Pi-native tools, gates and compaction lifecycle
integrations/claude-code/  MCP + hook/runtime integration
plugin/substrate/    packaged Claude Code plugin
skills/              Pi-facing Substrate doctrine
docs/                current product/operator/reference documentation
tests/               acceptance, provider, docs and anti-drift gates

Documentation

Start with docs/README.md.

• docs/concepts.md — authority model.
• docs/workflow.md — end-to-end lifecycle.
• docs/issues-and-readiness.md — identity, contracts, readiness, claims.
• docs/journal-and-resume.md — all nine Journal kinds, checkpoints and Resume Capsule.
• docs/provenance-and-closure.md — bindings, receipts, artifacts and terminal outcomes.
• docs/repository-identity.md — sb init, Projects, worktrees and overrides.
• docs/cli.md — human/machine CLI surfaces.
• docs/pi.md / docs/claude.md — provider references.
• docs/troubleshooting.md — diagnostics and common recovery paths.

Deep ADRs, migration records and acceptance evidence remain under the repository root docs/substrate/.

Install and develop

Managed XTRM installs are enrolled through Core/xt; direct package use is also supported.

npm install -g @jaggerxtrm/substrate
sb --version
sb doctor

Development:

npm install
npm test
npm run typecheck
npm run test:bun

Release is fail-closed: npm run release:verify builds a staged JavaScript artifact and proves the packed layout under Node and Bun; npm run release publishes that verified artifact. A bare npm publish from the source tree is intentionally refused.