keystone-pi

Shared developer workflows packaged for Pi: named subagents, workflow skills, prompt templates, native commands, and tested shell helpers.

Releases

Releases follow the standard /merge flow: merging dev into main infers a semver bump from commits, requires a CHANGELOG.md entry, tags vX.Y.Z, pushes branch and tag, and publishes the provider release. install/manifest.json pins keystoneSource to the released main commit; the release merge bumps that pin so fresh installs get the tagged tree.

See PLAN.md for phase status and docs/reference.md for the complete command, agent, skill, and helper surface. Implementation records live in docs/implementations/.

Install

Install the subagent runtime once, then Keystone:

pi install npm:pi-subagents
pi install ./

Installer (#1927)

install/bootstrap.sh provisions a fresh macOS machine or re-syncs an existing one from install/manifest.json (the desired-version ledger for herdr, the pi CLI, every pi package, and keystone itself):

install/bootstrap.sh plan    # show what would change; writes nothing
install/bootstrap.sh apply   # reconcile to manifest state

Managed pi settings keys merge three-way against a last-applied ledger — user-edited values are preserved and reported as conflicts (override per run with --accept-desired-config). Secrets stop at templates: .env structure is seeded blank; auth stays with pi /login. Packaging is gated by npm run secrets-gate, which scans packed output under a config that carries no .env exemption.

Reload an active Pi session after changing package resources:

/reload

Commands

Agent-backed extension aliases validate arguments before dispatching one hidden workflow skill:

• /commit
• /push
• /ship
• /merge
• /pr
• /deploy

Direct extension handlers execute bounded helper operations:

• /worktrees [list|sweep]
• /rollback [--reason <text>] [--wp <id>] [--dry-run] [--force]
• /sc:config [plan|apply] [--example <path>] [--env <path>] [--dry-run] [--force]
• /openproject:info [<id>] [--all] [--parent <id>] [--type <name>]
• /openproject:start <id>
• /openproject:sync <id> [--file <task-doc.md>]
• /openproject:close <id>... [--recursive]

Orchestration

pi-subagents keeps its /run command. Keystone registers a distinct autonomous plan walker:

/run-plan --plan <path> [--parallel] [--workers <1-8>]
/run-plan --status
/run-plan --continue
/run-plan --abort

The hidden workflow validates the plan, asks for approval, persists recovery state in a Pi mission, launches isolated writers, authorizes captured patch paths before applying them, and commits one task at a time with a Keystone-Task: trailer. scripts/task-plan.sh scopes completion checks to the approved Git range.

/skill:squash now dispatches bounded Pi workers into persistent cluster worktrees. The lead validates RED/GREEN evidence, accepted OpenProject IDs, hook integrity, optimistic locks, merge order, closure outcomes, and publication.

Subagents

Keystone exposes nine package-qualified roles:

• Read-only: keystone-pi.deep-thinker, keystone-pi.code-auditor, keystone-pi.security-auditor, keystone-pi.code-reviewer, keystone-pi.commit-message-writer
• Writers: keystone-pi.task-executor, keystone-pi.test-generator, keystone-pi.code-simplifier, keystone-pi.docs-writer

Every role uses strict tools, fresh context, no ambient child extensions, and no nested delegation. Calling skills own sequencing and pass a full Pi model ID resolved from these optional keys:

Tier	Default
KEYSTONE_ORCHESTRATOR_MODEL	openai-codex/gpt-5.6-sol
KEYSTONE_EXECUTION_MODEL	openai-codex/gpt-5.6-sol
KEYSTONE_BULK_MODEL	openai-codex/gpt-5.6-terra
KEYSTONE_TRIVIAL_MODEL	openai-codex/gpt-5.6-luna

Project .env overrides ~/.env; values must use full provider/model form.

Safety model

• Every Phase 5 command requires TUI or RPC mode. JSON and print modes fail before execution.
• All explicit flags are validated before helper or Git execution; malformed quoting is rejected.
• Quoted and escaped values are parsed without shell evaluation.
• Helper paths resolve from the loaded package rather than the user’s home directory.
• Run-plan mission state stores recovery pointers; Git trailers and plan checkboxes remain completion authority.
• Shell-capable workers receive only exact operator-approved normalized contracts; raw plan and OpenProject prose stays with read-only analysis and the supervised parent.
• Squash hashes active Git hooks with SHA-256 and neutralizes hooks on lead-owned Git mutations.
• Dynamic values reach subprocesses as separate argv entries.
• --force skips a documented confirmation inside TUI or RPC mode only.
• Agent-backed aliases require trusted arguments. RPC callers must not forward bot, webhook, or other untrusted text into them because Pi appends validated arguments as model text.
• .env remains ignored and untracked; a test fails if it enters Git’s index. .env.example contains seedable defaults with blank secrets.

Layout

• agents/: package-qualified Pi subagent definitions
• extensions/: native command registration, command schemas, and direct handlers
• skills/: user-facing workflows, hidden Git procedures, and policy skills
• prompts/: lightweight text-guidance commands (explain, language)
• scripts/: deterministic Bash helpers
• tests/extensions/: TypeScript unit and Pi RPC integration tests
• tests/subagents/: discovery, preflight, capability, and caller-contract tests
• tests/*.bats: hermetic helper, OpenProject lock, hook-integrity, and worktree regressions
• docs/reference.md: complete surface map (commands, agents, skills, helpers)

Development checks

Requires Node.js, BATS 1.5 or newer, and Shellcheck.

npm install
npm run check

Individual gates:

npm run typecheck
npm run lint
npm run test:unit
npm run test:bats:quick
npm run test:bats