# How Keystone Works

Keystone is one complete package: nine public workflow skills backed by one shared internal gate tree. Each public skill names a phase of work, carries that phase's contract, and can hand off to another skill when the evidence says the job has changed.

There is no central routing layer. Keystone relies on strong model-visible skill descriptions and direct slash commands so the host can load the right workflow from the user's intent.

## Invocation eligibility

Automatic invocation has two gates. Work must be both:

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

Eligibility follows the prompt's subject, not the current working directory. Being inside a repository does not turn an unrelated search, explanation, or utility request into project work.

Use normal agent behavior for standalone public web search or recommendations, generic summaries or explanations, ordinary copywriting or brainstorming, mechanical single-file config or documentation edits, and one-off scripts. Project-specific external research still qualifies when it informs a project decision, and pure repository understanding or reconnaissance qualifies when the repository itself is the subject. Integrated project config or scripts, product copy decisions, diagnosis, review, audit, and explicitly requested shipping remain workflow-worthy.

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

| Normal agent behavior | Keystone project workflow |
|---|---|
| Research the latest laptop recommendations. | Research deployment providers against this project's runtime constraints. |
| Summarize this public article. | Survey this repository and map its current ownership boundaries. |
| Write a temporary log-cleanup script. | Add a repository maintenance script, integrate it with CI, and prove the behavior. |
| Fix a typo in one config comment. | Migrate the project's configuration contract across code, docs, and tests. |

## The short version

Keystone does five things:

1. **Exposes nine public skills** for the major phases of agent work.
2. **Lets the host or user choose the phase** from natural language or a matching command.
3. **Applies that skill's contract** so the agent knows its scope, boundaries, and completion criteria.
4. **Loads shared gates and standards** when mutation, proof, review, or shipping risk appears.
5. **Hands off with a packet** when another phase should continue the work.

This keeps the agent from mixing jobs. Survey stays evidence-gathering. Planning stays planning. Implementation changes files. Review stays read-only. Shipping only runs when the user explicitly asks for finalization.

## Why Keystone exists

Agent workflows often fail for predictable reasons:

- the agent starts editing before understanding the workspace
- a plan is treated as proof of completion
- review turns into implementation
- shipping happens before verification
- the agent finishes a build and forgets the review or handoff
- platform-specific packaging drifts away from source

Keystone counters those failures with public phase skills, shared gates, and explicit delivery boundaries.

## Public skill graph

The public skills are peers with their own model-visible triggers:

| Skill | Loads when the user asks to... | Usually hands off to... |
|---|---|---|
| `context-survey` | understand a repository or gather project-specific evidence before a project decision or change | `product-planning`, `task-creation`, `project-audit` |
| `product-planning` | shape a product initiative's behavior, UX, user-facing copy, architecture, scope, or approved spec | `task-creation`, `context-survey` |
| `task-creation` | turn approved project direction into sequenced, verifiable implementation work | `implementation`, `refactoring`, `change-review` |
| `implementation` | make an integrated project change that needs project context and proof | `change-review`, `shipping`, `root-cause-analysis` |
| `refactoring` | improve project structure without intended behavior change | `change-review`, `implementation`, `root-cause-analysis` |
| `root-cause-analysis` | reproduce, isolate, and explain a project bug, regression, failure, or anomaly | `implementation`, `refactoring` |
| `change-review` | assess a project diff, branch, PR, regression risk, or readiness without mutation | `implementation`, `refactoring`, `root-cause-analysis`, `shipping` |
| `shipping` | explicitly finalize completed project work through commit, push, PR preparation or creation, merge, tag, package, publish, release, deploy, repository handoff, or destructive cleanup | none unless the user asks for follow-up |
| `project-audit` | assess repository health, tooling, packaging, architecture, maintenance, or skill drift | `context-survey`, `task-creation`, `implementation`, `refactoring` |

The graph is evidence-driven rather than fixed. A skill continues only when the user's intent and current evidence support the next phase.

## Why no router exists

Keystone's old model made one public entrypoint choose internal modules. The multi-skill model removes that middle step.

A router is unnecessary because each public skill has a project-scoped trigger description. Hosts that support skill discovery can choose from those descriptions after the request passes the eligibility boundary, and users can still invoke the desired skill directly. Removing the router also removes a failure mode: the agent no longer has to spend a turn deciding which hidden module to use before doing the actual phase work.

## Migrate from `/keystone` to direct skills

Keystone 2.0 no longer ships `/keystone`. Use the matching public skill directly:

| Old request shape | Direct skill command |
|---|---|
| `/keystone survey ...` or research requests | `/context-survey ...` |
| `/keystone plan ...` or product/UX/scope shaping | `/product-planning ...` |
| `/keystone tasks ...` or task breakdowns | `/task-creation ...` |
| `/keystone implement ...` or scoped mutations | `/implementation ...` |
| `/keystone refactor ...` or cleanup without behavior change | `/refactoring ...` |
| `/keystone debug ...` or root-cause requests | `/root-cause-analysis ...` |
| `/keystone review ...` or diff/PR readiness checks | `/change-review ...` |
| `/keystone ship ...` or explicitly requested commit, push, PR preparation or creation, merge, tag, package, publish, release, deploy, repository handoff, or destructive cleanup | `/shipping ...` |
| `/keystone audit ...` or repo/tooling health checks | `/project-audit ...` |

Hosts with skill discovery may still choose from natural language, but explicit invocations should name one of the nine public skills.

For an explicit artifact-edit override:

```text
/implementation explicitly edit project docs, config, content, or scripts
```

## Why gates stay internal

Gates are shared safety checks, not user goals. A user asks to implement, review, or ship; the skill decides whether it needs isolation, proof, review, or ship checks.

Keeping gates internal gives Keystone one source of truth for repeated contracts without adding extra public commands. It also keeps the public surface focused on outcomes rather than mechanics.

Shared gate paths:

```text
skills/_shared/gates/checkpoint.md
skills/_shared/gates/isolation.md
skills/_shared/gates/proof.md
skills/_shared/gates/red.md
skills/_shared/gates/review.md
skills/_shared/gates/ship.md
```

## Shared standards and handoff packets

Keystone also shares two non-gate references:

```text
skills/_shared/engineering-standards.md
skills/_shared/handoff-packet.md
```

`engineering-standards.md` is language-agnostic guidance for implementation, refactoring, review, and audit work. It keeps attention on ownership, state, boundaries, source of truth, abstraction quality, duplication, and maintainability.

`handoff-packet.md` defines what one skill passes to another:

- source skill
- target skill
- goal
- evidence
- files and mutability
- risks
- next check
- explicit user overrides or waivers

The packet prevents context drift when a workflow crosses phases. For a `shipping` handoff, its canonical `evidence` field must carry the user's explicit delivery request and authorized action set.

## Artifact lifecycle

Keystone creates durable artifacts when the work has enough agreement or scope to justify them.

| Artifact | Created by | Default path | Rule |
|---|---|---|---|
| Spec | `product-planning` | `docs/keystone/specs/YYYY-MM-DD-<slug>.md` | Create only after the user approves the plan details. Before approval, work in conversation. |
| Task breakdown | `task-creation` | `docs/keystone/tasks/YYYY-MM-DD-<slug>.md` | Keep 1–5 top-level slices in conversation; create an artifact for 6 or more. Explicit chat/save requests override the threshold. |
| Refactor doc | `refactoring` | `docs/keystone/refactors/YYYY-MM-DD-<slug>.md` | Create for large or cross-cutting refactors. Small local refactors may proceed after checks. |

Implementation proof, review findings, audit results, and shipping notes may live in conversation unless the user or repository convention asks for a file.

## Mutation and delivery boundaries

### Implementation

`implementation` changes behavior in identified project code. During an already-active behavior-changing implementation, it may also update supporting configuration, documentation, content, or scripts. Standalone natural-language requests for mechanical artifact edits stay on the normal/direct path unless the user explicitly invokes `implementation`. Before mutation it uses the isolation gate to check branch/worktree state, dirty files, protected paths, and requested scope. For code-quality-sensitive changes it consults shared engineering standards.

### Refactoring

`refactoring` changes internal structure without intended behavior changes. It preserves behavior through existing tests, characterization checks, or other proof. If intended behavior changes, the work belongs in `implementation`. If the failure cause is unknown, it belongs in `root-cause-analysis`.

### Review

`change-review` is read-only. It reports blockers, non-blocking findings, evidence, and a recommended owner skill for follow-up. It does not fix, commit, or ship.

### Shipping

`shipping` finalizes completed project work only when explicitly requested. Its delivery actions are commit, push, PR preparation or creation, merge, tag, package, publish, release, deploy, repository handoff, and destructive cleanup; it must require proof and review evidence or an explicit user waiver.

Every delivery action in that set is explicit-only.

## Host capability notes

Keystone installs as a complete bundle and adapts to each supported surface's capabilities. Individual skills are entry points, not separately supported packages.

| Harness | Discovery and invocation | Subagents / reasoning |
|---|---|---|
| Pi | npm package plus Pi extension registers public skill commands matching skill names | Uses subagent tools only if the active schema exposes them; no assumed named roles, model selection, or thinking controls |
| Claude Code | plugin marketplace installs the Keystone skill package | Use host-supported delegation only when available; otherwise run inline |
| Codex | plugin marketplace installs bundled skills | Reasoning controls are host-dependent; do not assume per-skill controls |

Subagents are optional. A Keystone skill should delegate only when the boundary is clear, the artifact is useful, and coordination cost is lower than inline work.

## Packaging model

Keystone uses a canonical-source packaging pipeline.

```text
canonical skill source
   │
   ▼
npm run regenerate
   │
   ├─ .agents/plugins/marketplace.json
   ├─ .claude-plugin/plugin.json
   ├─ .claude-plugin/marketplace.json
   └─ .codex-plugin/plugin.json
   │
   ▼
npm run pack:dry-run / package build
```

The canonical public skill directories are expected to be:

```text
skills/context-survey/
skills/product-planning/
skills/task-creation/
skills/implementation/
skills/refactoring/
skills/root-cause-analysis/
skills/change-review/
skills/shipping/
skills/project-audit/
skills/_shared/
```

Generated manifests should not be hand-edited. Change the canonical source or package metadata, then regenerate.

## Default-deny packaging

The archive is built from `packaging.allowlist`. Files are not shipped unless they are explicitly allowed.

The package script rejects local or generated noise such as:

- `docs/`
- `plans/`
- preview files such as `index.html` and `styles.css`
- `dist/`
- `.git/`
- pycache and `.pyc`
- local plan or design drafts not meant to ship

This keeps the release package focused on the Keystone skill system and generated host surfaces.

## Validation model

Keystone validation should cover three layers.

### Source validation

```bash
python3 scripts/validate-keystone.py
```

This focused validator checks:

- discovered public skill directories have matching frontmatter names and model-visible descriptions
- shared gates and shared references exist under `skills/_shared/`
- stale central-router and one-entrypoint claims are absent from shipped surfaces
- generated plugin manifests stay synchronized with package metadata and canonical skill paths
- package and plugin metadata satisfy their structural contracts

### Package validation

```bash
python3 scripts/validate-package.py dist/keystone.zip
```

Expected checks include:

- required package files exist in the archive
- forbidden files are absent
- archive contents match the expanded allowlist
- Claude, Codex, and Pi package surfaces expose the same public skill set

### Full verification

`make test` adds the exact nine-skill catalog invariant, invocation-corpus coverage,
complete-bundle reference checks, package validation, and Python compilation.

Known project commands:

```bash
npm run regenerate
npm run validate
npm run typecheck
npm run pack:dry-run
```

If packaging scripts change, update this document and the implementation task with the actual commands.

### Invocation evaluation

`tests/routing/cases.yaml` covers each public skill, ambiguous neighboring phases, and explicit no-skill prompts, including project-versus-standalone near-pairs. Automated tests verify corpus shape, exact nine-skill coverage, and that every case is exported with the full catalog of candidate descriptions. Static tests do not prove which skill a model will select.

Export JSONL for a supported host/model runner:

```bash
python3 scripts/export-invocation-eval.py
```

Before release, run every exported prompt against each host and model listed as supported, expose all nine descriptions at once, allow either one skill or no skill, and compare the observed selection with `expected`. Record host version, model, case ID, observed selection, and result. Treat unexpected selections as release evidence to fix or explicitly waive; a passing unit test alone is not invocation proof.

## Platform outputs

Keystone provides:

| Host | Output |
|---|---|
| Pi | `.pi/extensions/keystone.ts` plus `package.json` `pi.extensions` and `pi.skills` entries for public skill commands |
| Claude Code | `.claude-plugin/plugin.json` plus `.claude-plugin/marketplace.json` |
| Codex | `.codex-plugin/plugin.json` plus `.agents/plugins/marketplace.json` repo marketplace |

The Pi extension should discover bundled skills and register commands matching the skill names. It should not inject a single-command bootstrap.

## Common maintainer workflows

### Change a public skill

1. Edit `skills/<skill-name>/SKILL.md` or disclosed reference files.
2. Keep shared rules in `skills/_shared/` when more than one skill needs them.
3. Run `npm run regenerate`.
4. Run `npm run validate` and any targeted tests.

### Add or change a shared gate

1. Edit the gate under `skills/_shared/gates/`.
2. Update only the public skills that need to point at it.
3. Regenerate the complete bundle and manifests.
4. Validate source and package contents.

### Change packaging metadata

1. Edit `package.json`, `packaging.allowlist`, or canonical skill frontmatter.
2. Run `npm run regenerate`.
3. Inspect generated manifests.
4. Run `npm run validate` and `npm run pack:dry-run`.

### Prepare a release package

1. Run `npm run typecheck`.
2. Run `npm run validate`.
3. Run `npm run pack:dry-run` and inspect the included files.
4. Use `shipping` only when the user explicitly asks to commit, push, prepare or create a PR, merge, tag, package, publish, release, deploy, perform a repository handoff, or perform destructive cleanup.

## What should stay out of git

These are local or generated artifacts:

```text
dist/
index.html
styles.css
plans/
scripts/__pycache__/
tests/__pycache__/
```

They may exist locally, but they should remain ignored.

## Mental checklist for Keystone behavior

Before changing Keystone, ask:

1. Are exactly nine public skills exposed?
2. Do public skill names match the agreed names?
3. Are gates internal shared docs rather than commands?
4. Does mutation pass isolation before file changes?
5. Does RCA establish evidence before a fix path?
6. Is review read-only?
7. Is shipping explicit-only?
8. Are specs, tasks, and refactor docs written to documented default paths when needed?
9. Are generated manifests regenerated from canonical source?
10. Do validation and package dry-run pass, or are blockers documented with exact evidence?

## Design principle

Keystone is not trying to make agents more autonomous by removing structure.

It makes agents safer by giving each phase a clear name, a boundary, shared gates, and a proof requirement.