@bosun-sh/plot

@bosun-sh/plot

Spec-tree workflow scaffold — draft, validate, approve, and recover layered XML spec trees via CLI or MCP.

Requirements

Bun >= 1.3.9 is required.

This package ships raw TypeScript source (src/) and is designed for Bun-only environments. It does not compile to dist/. Bun resolves and executes the TypeScript files directly at runtime.

Installation

bun add @bosun-sh/plot

Quickstart

# Check workspace spec status
bunx plot status

# Draft a concept spec
bunx plot concept --workspace ./docs --prompt "AI-powered search feature"

# Draft an umbrella spec
bunx plot umbrella --workspace ./docs --prompt "Search umbrella"

# Draft a feature triplet
bunx plot feature --workspace ./docs --feature-slug search-indexing

# Validate all specs under docs/
bunx plot validate --workspace ./docs

# Approve a drafted spec
bunx plot approve --workspace ./docs --approval-phrase "approved"

# Recover / inspect gate state
bunx plot recover --workspace ./docs

# Manage config (provider + model)
bunx plot config get
bunx plot config set --provider openai --model gpt-4o

Add --human to any command for pretty-printed JSON output.

Features

Plot manages a layered spec tree following the concept → umbrella → feature hierarchy. Each layer has three sibling files: functional.spec, technical.spec, and test.spec.

CLI command	Tool ID	Description
status	plot.workspace.status	Inspect the Plot workspace and list canonical spec files
concept	plot.concept.draft	Draft docs/concept.spec and persist the approval gate
umbrella	plot.umbrella.draft	Draft the umbrella spec currently selected by the caller
feature	plot.feature.draft	Draft a feature triplet stage after umbrella approval
validate	plot.spec.validate	Enumerate spec files under docs/ and return scaffold validation output
approve	plot.spec.approve	Record an explicit approval phrase for a drafted target
recover	plot.spec.recover	Inspect or reset the current scaffold gate state
config get	plot.config.get	Return the scaffold Plot configuration view
config set	plot.config.upsert	Update the scaffold configuration (provider, model, base URL)

MCP usage

Plot exposes all tools as an MCP server via @bosun-sh/ohtools:

bunx ohtools --app ./src/ohtools.ts list    # list available MCP tools
bunx ohtools --app ./src/ohtools.ts graph   # display tool dependency graph

Development

bun install
bun run ci:premerge   # lint + typecheck + test + pack-dry-run — must be green

See CONTRIBUTING.md for full contribution guidelines.

License

Apache-2.0 — see LICENSE.