--- slug: "static-var-keystone" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/static-var/Keystone@main/README.md" repo: "https://github.com/static-var/Keystone" source_file: "README.md" branch: "main" --- # Keystone

Keystone

npm CI License: MIT

> Proactive workflow skills for disciplined AI work: use the right phase, keep boundaries clear, and prove the result. Keystone is a package of model-discoverable workflow skills for coding agents. Instead of sending every request through a single router, Keystone exposes the phases agents need for real work: survey, plan, break down, implement, refactor, diagnose, review, ship, and audit. Use Keystone when you want an agent to move deliberately: gather evidence before decisions, mutate only after isolation checks, separate review from fixing, and require proof before success claims. ## Why use Keystone? Agents usually fail in predictable ways: - they edit before understanding the repo - they treat a plan as proof - they debug by guessing - they review while changing files - they ship without evidence Keystone turns those habits into explicit skills: | You need... | Use... | |---|---| | inspect, research, inventory, compare, or answer “what is true here?” | `context-survey` | | shape product behavior, UX, copy, technical direction, architecture, or scope | `product-planning` | | turn approved direction into tasks, tickets, milestones, or handoffs | `task-creation` | | make scoped code, content, config, or documentation changes | `implementation` | | improve structure without intended behavior changes | `refactoring` | | reproduce, isolate, and explain a bug or failure before fixing | `root-cause-analysis` | | review a diff, branch, PR, or change read-only | `change-review` | | explicitly finalize completed work: commit, PR, release, publish, package, or hand off | `shipping` | | audit repository, tooling, package health, architecture, or maintenance risk | `project-audit` | There is no central routing skill. The host discovers the right Keystone skill from the user's prompt or the user invokes the matching slash command directly. ## Migrate from `/keystone` to direct skills Keystone 2.0 removes the old `/keystone` entrypoint. Use the matching public skill directly instead: ```text /context-survey inspect or summarize existing code /product-planning shape product, UX, scope, or technical direction /task-creation turn approved direction into implementation-ready tasks /implementation make scoped code, content, config, or documentation changes /refactoring improve structure without intended behavior changes /root-cause-analysis reproduce and explain bugs before fixing /change-review review a diff, branch, PR, or regression risk read-only /shipping explicitly commit, package, release, publish, or hand off completed work /project-audit audit repository, tooling, package health, or maintenance risk ``` Natural-language requests still work when the host supports skill discovery; the slash commands are the explicit migration path from `/keystone`. ## Install ### Pi ```bash pi install npm:@static-var/keystone ``` Then invoke a public skill by name, or ask naturally and let Pi's skill discovery choose: ```text /context-survey summarize the current package layout and risks /implementation update the docs to match the approved spec /change-review review the current branch for regressions ``` Optional Pi subagents: ```bash pi install npm:@tintinweb/pi-subagents ``` Keystone may use subagent tools only when the active Pi tool schema exposes them. It does not assume named roles, model selection, thinking controls, or profile support. ### Claude Code ```text /plugin marketplace add static-var/Keystone /plugin install keystone@keystone ``` Invoke the installed public skills from Claude Code's plugin surface, for example `context-survey`, `implementation`, or `shipping`. ### Codex ```bash codex plugin marketplace add static-var/Keystone --ref main codex plugin add keystone --marketplace keystone ``` Then ask Codex for the workflow phase you need or invoke the installed Keystone skill from your Codex surface. ## How to use it Ask for the phase you want in normal language: ```text Survey the repository and explain what has to change before the package can ship. ``` ```text Turn this approved product spec into implementation-ready tasks with checks. ``` ```text Refactor the duplicated parsing logic without changing behavior. ``` ```text Diagnose why the release workflow fails and identify the smallest supported fix path. ``` ```text Review the current branch for blockers, regressions, and packaging leaks. ``` ```text Ship this completed change: verify evidence, prepare the commit summary, and hand off the PR notes. ``` Keystone skills can hand off when the work changes shape. For example, `root-cause-analysis` may hand off to `implementation` after evidence supports a fix path, and `change-review` may hand off findings to `refactoring` or `implementation`. Handoffs use a shared packet so the next skill receives the goal, evidence, files, risks, and next check. ## Artifact defaults Keystone writes durable planning artifacts only when the workflow calls for them: ```text docs/keystone/specs/YYYY-MM-DD-.md # product-planning, after user approval docs/keystone/tasks/YYYY-MM-DD-.md # task-creation docs/keystone/refactors/YYYY-MM-DD-.md # large or cross-cutting refactoring ``` Before a plan is approved, `product-planning` works in conversation and asks focused questions instead of creating a spec file. `task-creation` keeps 1–5 top-level slices in conversation and writes 6 or more to its default artifact path; explicit chat-only or save requests override that threshold. ## Explicit-only shipping `shipping` is explicit-only. Keystone does not commit, open PRs, merge, tag, publish, release, deploy, perform destructive cleanup, or create external side effects just because implementation or review finished. Ask for those actions directly, and Keystone will require proof and review evidence unless you explicitly waive them. ## Shared gates and standards Keystone's public skills share internal gates and doctrine: - **checkpoint** — make the next action or stopping point explicit - **isolation** — check branch, worktree, scope, and dirty state before mutation - **red** — establish a failing check or reproduction when practical - **proof** — verify claims with evidence before success reports - **review** — keep critique separate from fixing - **ship** — confirm completed work is ready for handoff or delivery - **engineering standards** — language-agnostic guidance for ownership, boundaries, state, abstractions, duplication, and maintainability Gates are internal shared contracts, not public skills or commands. ## Project status - npm package: `@static-var/keystone` - public skills: `context-survey`, `product-planning`, `task-creation`, `implementation`, `refactoring`, `root-cause-analysis`, `change-review`, `shipping`, `project-audit` - distribution: one complete Keystone package containing all nine skills and one shared gate tree - license: MIT - supported surfaces: Pi, Claude Code, Codex For architecture, packaging, validation, and maintainer commands, read [`HOW_IT_WORKS.md`](https://github.com/static-var/Keystone/blob/HEAD/HOW_IT_WORKS.md). Invocation fixtures exercise all nine descriptions, ambiguous boundaries, and prompts that should select no Keystone skill. They validate the evaluation corpus, not model behavior. Before release, run the exported corpus against every supported host being claimed and record its selections: ```bash python3 scripts/export-invocation-eval.py ```