SpecTree

SpecTree (stc) compiles portable Markdown/YAML sources into a validated semantic graph, calculates change impact, creates approval-bound build manifests, and rejects unauthorized implementation drift.

Quick start

Install the package in a project (the stc executable and compiled library are included):

npm install @mysetsuna/spectree
stc init C:\your-project
stc next --root C:\your-project
stc validate --root C:\your-project
stc ui --root C:\your-project
stc obsidian export --root C:\your-project --vault C:\your-vault --note-directory SpecTree

The export is a view, not an authority; see docs/obsidian.md for the vault layout and boundary rules. Full operating procedure: docs/SOP.md.

To review multiple projects at once, start one UI process per project:

stc ui --root C:\projects\one
stc ui --root C:\projects\two

Each process owns one project root and watcher. Without --port, the operating system assigns a separate port; use distinct explicit ports when supplying --port. A server closing or failing cannot expose another project's state.

For a local checkout, the equivalent build-backed commands are:

npm install
npm run init -- C:\your-project
npm start -- --root C:\your-project

The package exposes dist/src/index.js as its ESM library entry, with declarations at dist/src/index.d.ts. Runtime JSON schemas are shipped under schemas/; the CLI resolves them from that package-relative location.

npm start starts the MCP server. OAuth values come from environment variables; npm run oauth-login -- --root C:\your-project performs command-line login. Use node dist/src/cli.js oauth refresh --root C:\your-project after the stored refresh token is needed.

Run checks with npm test.

Adopt an existing project

SpecTree can retrofit an existing codebase without treating inferred behavior as approved intent:

npm run init -- C:\your-project
node dist/src/cli.js migrate observe --root C:\your-project
node dist/src/cli.js migrate adopt --root C:\your-project
node dist/src/cli.js migrate review --root C:\your-project

observe writes a deterministic, non-authoritative inventory to .spectree/migration/observed.json. adopt adds candidates under specs/migration/ as DRAFT nodes marked migration_state: INFERRED; it never overwrites existing specs. Edit the generated nodes and the scaffold project node, set each reviewed node to migration_state: CONFIRMED, then establish the first enforced baseline:

node dist/src/cli.js migrate baseline --confirm --root C:\your-project
node dist/src/cli.js status --root C:\your-project
node dist/src/cli.js verify --run-tests --root C:\your-project

The baseline creates BASELINE-001, an approval-bound lock, and an enforced file-hash boundary. Later behavior changes use the normal change → review → approve → lock → build → verify flow. If source files change between observation and adoption, rerun migrate observe rather than accepting a stale inventory.

The same migration operations are available through the OAuth-protected MCP tools stc_migration_status, stc_migrate_observe, stc_migrate_adopt, stc_migrate_review, and stc_migrate_baseline.

Core workflow:

stc parse
stc graph
stc validate
stc design "Project intent" --backend codex
stc design "Project intent" --backend ark
stc impact CHG-001
stc stale CHG-001
stc reason CHG-001
stc critique CHG-001
stc reason CHG-001 --backend codex
stc critique CHG-001 --backend codex
stc reason CHG-001 --backend ark
stc critique CHG-001 --backend ark
stc review CHG-001
stc tree
stc audit
stc coverage
stc interface
stc lang
stc lang zh-CN
stc lang init
stc benchmark impact --root C:\code\stc
stc benchmark quality --root C:\code\stc
stc apply CHG-001
stc apply CHG-001 --confirm
stc approve CHG-001
stc lock CHG-001
stc verify CHG-001
stc verify CHG-001 --run-tests
stc complete CHG-001
# Explicitly starts external Codex backend after lock preparation:
stc build CHG-001 --backend codex

reason/critique --backend codex invoke external Codex in read-only mode; --backend ark invokes the OpenAI-compatible Ark Coding endpoint. Configure ARK_API_KEY; optional ARK_BASE_URL and ARK_MODEL default to https://ark.cn-beijing.volces.com/api/coding/v3 and ark-code-latest. Both outputs pass the same JSON Schema gate; omit the flag for deterministic local output.

design --backend codex|ark produces validated L2-L4 proposals under .spectree/proposals; it does not modify authoritative specs or create approval/lock state.

stc apply turns a stored proposal into authoritative nodes only with --confirm; new nodes arrive as lifecycle: PLANNED and removals become RETIRING. stc complete absorbs verified, authorized work into the lock baseline, marks the change COMPLETED, activates planned nodes, and archives retiring ones. Skipping it blocks the next lock with POLICY_E_UNAUTHORIZED_DIFF. stc next reports the single next step for the current state; stc ui opens an on-demand loopback review page.

The deterministic core has no mandatory LLM, Codex, Obsidian, or OpenAI API dependency. ChatGPT can call semantic operations through the OAuth 2.1 MCP boundary:

STC_PUBLIC_URL=https://stc.example.com \
STC_OAUTH_ISSUER=https://auth.example.com \
node dist/src/cli.js start --root C:\your-project

Configure the authorization server and scopes as described in docs/oauth.md.

Mainstream coding-agent installation and MCP configuration examples are in docs/agent-mcp.md. Local agents use the stdio transport:

npx --no-install @mysetsuna/spectree mcp-stdio --root C:\your-project

HTTP agents use the same semantic tools through the OAuth-protected /mcp endpoint; the HTTP transport remains bearer-token and session guarded. Stdio does not bypass approval, lock, trace, stale, or verification gates.

When an agent or user needs to clarify a boundary, semantics, behavior, UI, architecture, structure, tests, or conflicting records, it may enter the optional cross-cutting discussion loop. The four MCP tools stc_discussion_start, stc_discussion_status, stc_discussion_decide, and stc_discussion_finish persist one-item-at-a-time decisions under .spectree/discussions/. The loop is soft: it adds status and risk metadata without introducing a hard NextStep or changing the approval, lock, build, and verification gates.

Command-line OAuth login uses authorization-code + PKCE and stores the token under .spectree:

$env:STC_OAUTH_ISSUER="https://auth.example.com"
$env:STC_OAUTH_CLIENT_ID="stc-cli"
$env:STC_PUBLIC_URL="https://stc.example.com"
npm run oauth-login -- --root C:\your-project

To make verification execute project tests, add a tokenized command to .spectree/config.json before locking:

{
  "version": 1,
  "testCommand": ["npm", "test"]
}

For an observable JavaScript or TypeScript API, declare normalized export ... signatures in the node frontmatter with public_interface. Verification rejects a post-lock signature change as DRIFT_E_UNDECLARED_INTERFACE until the semantic contract is updated and re-locked. Contracts for other languages, mixed targets, or semantic names remain authoritative declarations and are not compared by the built-in JS/TS extractor.