Keystone

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 project 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.

When Keystone loads

Keystone auto-loads only when the request is both project-bound and workflow-worthy:

• Project-bound means the request's subject is a software or product repository, initiative, feature, architecture, regression, release, or project decision.
• Workflow-worthy means a Keystone phase contract would materially change how the work should proceed.

The prompt's subject controls eligibility, not the current working directory. A public web search performed while the agent happens to be inside a repository remains normal agent work. Project-specific external research can qualify when its evidence informs that project's decision or change. Pure repository understanding or reconnaissance also qualifies when the repository itself is the subject, even without a downstream decision or change.

Normal agent behavior handles standalone public web search and recommendations, generic summaries and explanations, ordinary copywriting or brainstorming, mechanical single-file config or documentation edits, and one-off scripts. Keystone remains appropriate for integrated project config or scripts, product copy decisions, diagnosis, review, audit, and explicitly requested shipping.

Supporting artifacts only within an already-active behavior-changing implementation include project configuration, documentation, content, and scripts; standalone mechanical artifact edits stay normal/direct.

Near-pairs make the boundary concrete:

Normal agent behavior	Keystone project workflow
Compare current password-manager prices.	Compare authentication providers against this repository's architecture constraints.
Write a one-off script to rename local images.	Add a migration script integrated with this project's CI and verify it.
Change one value in a tool config.	Migrate the application's config schema across runtime code and tests.
Rewrite this standalone announcement.	Decide the in-product upgrade copy and acceptance criteria for this feature.

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...
understand a repository or gather project-specific evidence before a decision	context-survey
shape a product initiative's behavior, UX, copy, architecture, or scope	product-planning
turn approved project direction into implementation-ready work	task-creation
make an integrated project change with project-specific proof	implementation
improve project structure without intended behavior changes	refactoring
reproduce, isolate, and explain a project bug or regression before fixing	root-cause-analysis
review a project diff, branch, PR, or readiness decision read-only	change-review
explicitly finalize completed project work: commit, push, prepare or create a PR, merge, tag, package, publish, release, deploy, perform a repository handoff, or perform destructive cleanup	shipping
audit repository health, tooling, packaging, 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:

/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 explicitly edit project documentation, configuration, content, or scripts
/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, push, prepare or create a PR, merge, tag, package, publish, release, deploy, perform a repository handoff, or perform destructive cleanup
/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

pi install npm:@static-var/keystone

Then invoke a public skill by name, or ask naturally and let Pi's skill discovery choose:

/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:

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

/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

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:

Survey the repository and explain what has to change before the package can ship.

Turn this approved product spec into implementation-ready tasks with checks.

Refactor the duplicated parsing logic without changing behavior.

Diagnose why the release workflow fails and identify the smallest supported fix path.

Review the current branch for blockers, regressions, and packaging leaks.

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. A handoff to shipping carries authorization in the canonical packet's evidence field as the user's explicit delivery request and action set.

Artifact defaults

Keystone writes durable planning artifacts only when the workflow calls for them:

docs/keystone/specs/YYYY-MM-DD-<slug>.md      # product-planning, after user approval
docs/keystone/tasks/YYYY-MM-DD-<slug>.md      # task-creation
docs/keystone/refactors/YYYY-MM-DD-<slug>.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, push, prepare or create a PR, merge, tag, package, publish, release, deploy, perform a repository handoff, or perform destructive cleanup 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.

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:

python3 scripts/export-invocation-eval.py