@static-var/keystone 0.1.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "description": "Use when the user invokes /keystone or asks Keystone to route product, research, writing, UI, design, planning, implementation, debugging, review, shipping, or health work through its canonical orchestrator.",
+  "displayName": "Keystone",
+  "keywords": [
+    "pi-package",
+    "agent-skills",
+    "keystone",
+    "claude-code",
+    "codex",
+    "opencode",
+    "copilot",
+    "pi-coding-agent",
+    "pi-extension",
+    "workflow",
+    "skills",
+    "agent-workflows"
+  ],
+  "license": "MIT",
+  "name": "keystone",
+  "skills": [
+    "keystone"
+  ],
+  "version": "0.1.0"
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "description": "Use when the user invokes /keystone or asks Keystone to route product, research, writing, UI, design, planning, implementation, debugging, review, shipping, or health work through its canonical orchestrator.",
+  "displayName": "Keystone",
+  "keywords": [
+    "pi-package",
+    "agent-skills",
+    "keystone",
+    "claude-code",
+    "codex",
+    "opencode",
+    "copilot",
+    "pi-coding-agent",
+    "pi-extension",
+    "workflow",
+    "skills",
+    "agent-workflows"
+  ],
+  "license": "MIT",
+  "name": "keystone",
+  "skills": [
+    "keystone"
+  ],
+  "version": "0.1.0"
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "description": "Use when the user invokes /keystone or asks Keystone to route product, research, writing, UI, design, planning, implementation, debugging, review, shipping, or health work through its canonical orchestrator.",
+  "license": "MIT",
+  "name": "keystone",
+  "skills": [
+    {
+      "name": "keystone",
+      "path": "../skills/keystone/SKILL.md"
+    }
+  ],
+  "version": "0.1.0"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "description": "Use when the user invokes /keystone or asks Keystone to route product, research, writing, UI, design, planning, implementation, debugging, review, shipping, or health work through its canonical orchestrator.",
+  "license": "MIT",
+  "name": "keystone",
+  "skills": [
+    {
+      "name": "keystone",
+      "path": "../skills/keystone/SKILL.md"
+    }
+  ],
+  "version": "0.1.0"
+}

package/.pi/extensions/keystone.ts

@@ -0,0 +1,172 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const EXTREMELY_IMPORTANT_MARKER = "<EXTREMELY_IMPORTANT>";
+const BOOTSTRAP_MARKER = "keystone:bootstrap for pi";
+
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(extensionDir, "../..");
+const skillsDir = resolve(packageRoot, "skills");
+const keystoneSkillPath = resolve(skillsDir, "keystone", "SKILL.md");
+
+let cachedSkillBody: string | null | undefined;
+let cachedBootstrap: string | null | undefined;
+
+export default function keystonePiExtension(pi: ExtensionAPI) {
+	let injectBootstrap = true;
+
+	pi.on("resources_discover", async () => ({
+		skillPaths: [skillsDir],
+	}));
+
+	pi.on("session_start", async () => {
+		injectBootstrap = true;
+	});
+
+	pi.on("session_compact", async () => {
+		injectBootstrap = true;
+	});
+
+	pi.on("agent_end", async () => {
+		injectBootstrap = false;
+	});
+
+	pi.on("context", async (event) => {
+		if (!injectBootstrap) return;
+		if (event.messages.some(messageContainsBootstrap)) return;
+
+		const bootstrap = getBootstrapContent();
+		if (!bootstrap) return;
+
+		const bootstrapMessage = {
+			role: "user" as const,
+			content: [{ type: "text" as const, text: bootstrap }],
+			timestamp: Date.now(),
+		};
+
+		const insertAt = firstNonCompactionSummaryIndex(event.messages);
+		return {
+			messages: [
+				...event.messages.slice(0, insertAt),
+				bootstrapMessage,
+				...event.messages.slice(insertAt),
+			],
+		};
+	});
+
+	pi.registerCommand("keystone", {
+		description: "Run the Keystone workflow router on a request",
+		handler: async (args, ctx) => {
+			const content = getCommandContent(args);
+			if (!content) {
+				ctx.ui.notify("Keystone skill not found in this package.", "error");
+				return;
+			}
+
+			if (ctx.isIdle()) {
+				pi.sendUserMessage(content);
+			} else {
+				pi.sendUserMessage(content, { deliverAs: "followUp" });
+				ctx.ui.notify("Queued Keystone as a follow-up.", "info");
+			}
+		},
+	});
+}
+
+function getBootstrapContent(): string | null {
+	if (cachedBootstrap !== undefined) return cachedBootstrap;
+
+	const body = getSkillBody();
+	if (!body) {
+		cachedBootstrap = null;
+		return null;
+	}
+
+	cachedBootstrap = `${EXTREMELY_IMPORTANT_MARKER}
+${BOOTSTRAP_MARKER}
+
+Keystone is available in this Pi session.
+
+Use Keystone when the user invokes \`/keystone\` or explicitly asks for Keystone/workflow routing. Otherwise continue normally and do not override user intent.
+
+The Keystone entrypoint is included below. When Keystone applies, follow it and route internally by reading the chosen module files. Do not expose internal modules as public slash commands.
+
+${body}
+
+${piToolMapping()}
+</EXTREMELY_IMPORTANT>`;
+	return cachedBootstrap;
+}
+
+function getCommandContent(args: string): string | null {
+	const body = getSkillBody();
+	if (!body) return null;
+
+	const request = args.trim() || "No request supplied. Briefly explain how to use `/keystone <task>` and ask for the task.";
+	return `${EXTREMELY_IMPORTANT_MARKER}
+${BOOTSTRAP_MARKER}
+
+You are running Keystone via Pi's \`/keystone\` command.
+
+Follow the Keystone entrypoint below. Route internally by reading the chosen module files. Do not expose internal modules as public slash commands.
+
+${body}
+
+${piToolMapping()}
+
+User request for Keystone:
+${request}
+</EXTREMELY_IMPORTANT>`;
+}
+
+function getSkillBody(): string | null {
+	if (cachedSkillBody !== undefined) return cachedSkillBody;
+
+	try {
+		cachedSkillBody = stripFrontmatter(readFileSync(keystoneSkillPath, "utf8"));
+		return cachedSkillBody;
+	} catch {
+		cachedSkillBody = null;
+		return null;
+	}
+}
+
+function stripFrontmatter(content: string): string {
+	const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+	return (match ? match[1] : content).trim();
+}
+
+function piToolMapping(): string {
+	return `## Pi tool mapping
+
+Pi has native skills, but Keystone should use this extension's \`/keystone\` command as the public entrypoint. Internal Keystone modules are Markdown files under \`skills/keystone/modules/\`; read the selected module file instead of inventing \`/shape\`, \`/breakdown\`, \`/build\`, \`/debug\`, \`/review\`, \`/ship\`, \`/health\`, or other public module commands.
+
+Pi's built-in coding tools are lowercase: \`read\`, \`write\`, \`edit\`, \`bash\`, plus optional \`grep\`, \`find\`, and \`ls\`. Use those for file inspection, mutation, shell commands, and search.
+
+If \`pi-subagents\` or another subagent tool is available, follow Keystone's \`modules/helpers/subagents.md\` guidance. If no subagent tool is available, do the work in this session and state that delegation was unavailable instead of inventing unsupported tools.`;
+}
+
+function messageContainsBootstrap(message: unknown): boolean {
+	const content = (message as { content?: unknown }).content;
+	if (typeof content === "string") return content.includes(BOOTSTRAP_MARKER);
+	if (!Array.isArray(content)) return false;
+	return content.some((part) => {
+		return (
+			part &&
+			typeof part === "object" &&
+			(part as { type?: unknown }).type === "text" &&
+			typeof (part as { text?: unknown }).text === "string" &&
+			(part as { text: string }).text.includes(BOOTSTRAP_MARKER)
+		);
+	});
+}
+
+function firstNonCompactionSummaryIndex(messages: unknown[]): number {
+	let index = 0;
+	while ((messages[index] as { role?: unknown } | undefined)?.role === "compactionSummary") {
+		index += 1;
+	}
+	return index;
+}

package/HOW_IT_WORKS.md

@@ -0,0 +1,424 @@
+# How Keystone Works
+
+Keystone is easiest to understand as a building with one front door and many private rooms.
+
+The front door is `/keystone`. The private rooms are internal modules. The gates are checkpoints that stop the agent from doing risky work too early.
+
+## The short version
+
+Keystone does five things:
+
+1. **Receives a request** through one public skill: `/keystone`.
+2. **Routes the request** to exactly one internal module.
+3. **Applies that module's contract** so the agent knows what it may and may not do.
+4. **Loads gates only when needed** to protect mutation, verification, review, and shipping.
+5. **Hands off cleanly** to the next module when the work changes shape.
+
+When the host supports subagents, Keystone can delegate bounded work with the right reasoning level. When the host does not support that control, Keystone treats reasoning level as prompt guidance instead of a guaranteed setting.
+
+This keeps the agent from mixing jobs. Planning stays planning. Building stays building. Review stays read-only. Shipping only happens after proof and review.
+
+## 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
+- too many public commands overlap and conflict
+- platform-specific packaging drifts away from the real source
+
+Keystone counters those failures with a small public surface and explicit internal contracts.
+
+## The public surface
+
+There is one public skill:
+
+```text
+skills/keystone/SKILL.md
+```
+
+That file is the only public entrypoint. Users invoke Keystone with `/keystone` or by asking Keystone to route work.
+
+Everything else in the shipped skill is internal:
+
+```text
+skills/keystone/modules/*.md
+skills/keystone/modules/gates/*.md
+```
+
+Internal modules are named in the public skill, but they are not separate slash commands.
+
+Maintainer-only notes may live elsewhere in the repository, such as `maintainers/skill-engineering.md`. Those files are not part of the shipped product.
+
+## Request lifecycle
+
+```text
+1. User asks for work
+       │
+       ▼
+2. Keystone public skill loads
+       │
+       ▼
+3. Router selects one primary module
+       │
+       ▼
+4. The module contract controls the work
+       │
+       ▼
+5. Gates run only if the module needs them
+       │
+       ▼
+6. Keystone reports result or hands off to the next module
+```
+
+The important phrase is **one primary module**. Keystone avoids blending roles unless a module explicitly hands off.
+
+## Modules
+
+Each module has the same shape:
+
+- **Intent:** what the module is for
+- **Load when:** when Keystone should choose it
+- **Allowed mutation:** what files or artifacts it may change
+- **Must not:** hard boundaries
+- **May call:** allowed handoffs or gates
+- **Handoff:** what it should report when done
+- **Exit gate:** what must be true before leaving the module
+
+### Module catalogue
+
+| Module | Job | Hard boundary |
+|---|---|---|
+| `router` | Choose the right module | Does not do the work itself |
+| `research` | Inspect, summarize, gather evidence, and compare options | Does not edit or present guesses as facts |
+| `shape` | Draft prose, shape product direction, UI/UX, visual direction, and scope | Does not implement or treat a spec as proof |
+| `breakdown` | Convert approved direction into ordered tasks | Is not named `plan` |
+| `build` | Mutate scoped files | Must pass isolation before first mutation |
+| `debug` | Diagnose failures from evidence | Does not guess fixes |
+| `review` | Evaluate work without changing it | Read-only: no fixes, commits, or shipping |
+| `ship` | Finalize completed work | Does not start new implementation |
+| `health` | Assess project/tooling condition | Does not silently fix issues |
+
+## Subagents and reasoning
+
+Keystone's subagent guidance lives in:
+
+```text
+skills/keystone/modules/helpers/subagents.md
+```
+
+The helper records:
+
+- which target harnesses support subagents
+- whether they can set per-subagent reasoning or only model/prompt hints
+- how to configure each host when support exists
+- default reasoning levels for every Keystone module
+
+### Host capability summary
+
+| Harness | Subagents | Reasoning control |
+|---|---:|---|
+| Pi coding agent with `pi-subagents` | yes | native `thinking`, `model`, and `profile` per agent/invocation |
+| Claude Code | yes | model selection and built-in Explore detail; no general custom-agent reasoning field confirmed |
+| Codex CLI/app | host-dependent | global `model_reasoning_effort`; per-subagent effort not confirmed |
+| T3 Code | not confirmed | not confirmed |
+| OpenCode | yes | partial/provider-dependent: `model` plus provider-specific `variant`; no universal reasoning knob confirmed |
+| GitHub Copilot / VS Code | yes | custom agent `model`; no general reasoning field confirmed |
+
+### Module reasoning defaults
+
+| Module group | Default reasoning |
+|---|---|
+| router, simple reading, simple writing | `low` to `medium` |
+| research, shape, build, health, ship | `medium`, escalating to `high` for risk |
+| breakdown, debug, review, high-stakes shape decisions | `high`, escalating to `xhigh` for hard or irreversible work |
+| gates | `low`, escalating only when evidence is safety-critical |
+
+The rule is simple: use the narrowest subagent role and the lowest reasoning level that can safely complete the task. Escalate for ambiguity, irreversible decisions, security, data loss, release risk, or root-cause uncertainty.
+
+## Gates
+
+Gates are small checks loaded by modules when needed.
+
+| Gate | Purpose | Usually used by |
+|---|---|---|
+| `isolation` | Confirm mutation is safe before editing | `build` |
+| `red` | Establish a failing check or reproduction when practical | `build`, `debug` |
+| `proof` | Verify claims with evidence before success reports | `debug`, `ship`, `health` |
+| `review` | Confirm required review has no blockers | `ship` |
+| `ship` | Confirm verified, reviewed work is ready for handoff | `ship` |
+
+The gates are deliberately boring. Their job is to stop common mistakes, not to be clever.
+
+## Why `breakdown`, not `plan`
+
+Many tools already use `/plan`. Keystone keeps `/keystone` as the only public entrypoint and uses `breakdown` internally for task decomposition.
+
+So this is correct:
+
+```text
+/keystone → breakdown
+```
+
+This is not:
+
+```text
+/plan
+```
+
+The name also clarifies the job: `breakdown` turns an approved direction into verifiable work items. It does not mean the work is done.
+
+## Build vs. ship
+
+Keystone separates implementation from finalization.
+
+### Build
+
+`build` is for changing files. Before the first mutation it must check isolation:
+
+- What branch/worktree are we in?
+- What files are protected?
+- Are there unrelated dirty changes?
+- Is the requested scope clear?
+
+`build` may implement, refactor, edit, or create files. It does not merge, publish, or call the work shippable by itself.
+
+### Ship
+
+`ship` is for finalizing completed work. It can prepare delivery notes, package output, PR/merge handoff, or release readiness.
+
+It should only run after proof and review are satisfied or explicitly waived.
+
+## Review is read-only
+
+The `review` module never fixes. This is intentional.
+
+A reviewer that edits while reviewing blurs evidence. Keystone keeps review as a report:
+
+- blockers
+- non-blocking findings
+- evidence
+- recommended owner module for follow-up
+
+If something must be fixed, Keystone routes back to `build` or `debug`.
+
+## Packaging model
+
+Keystone uses a canonical-source packaging pipeline.
+
+```text
+canonical skill source
+   │
+   ▼
+make regenerate
+   │
+   ├─ .claude-plugin/plugin.json
+   ├─ .claude-plugin/marketplace.json
+   ├─ .codex-plugin/plugin.json
+   └─ .agents/plugins/marketplace.json
+   │
+   ▼
+make package
+   │
+   ▼
+dist/keystone.zip
+```
+
+The canonical source is:
+
+```text
+skills/keystone/
+```
+
+Generated manifests should not be hand-edited. Change the canonical source or package metadata, then run:
+
+```bash
+make regenerate
+```
+
+## Default-deny packaging
+
+The archive is built from `packaging.allowlist`.
+
+That means files are not shipped unless they are explicitly allowed.
+
+The package script rejects known local or generated noise:
+
+- `docs/`
+- `plans/`
+- `index.html`
+- `styles.css`
+- `dist/`
+- `.git/`
+- pycache and `.pyc`
+- `*.plan.md`, `*-plan.md`
+- `*.design.md`, `*-design.md`
+
+This keeps the release package focused on the Keystone skill system, not local planning or preview artifacts.
+
+## Validators
+
+Keystone has three validation layers.
+
+### Source validation
+
+```bash
+python3 scripts/validate-keystone.py
+```
+
+Checks include:
+
+- canonical skill exists
+- skill name is `keystone`
+- `breakdown` terminology is present
+- public `/plan` is not introduced
+- referenced modules/gates exist
+- ignored artifacts are not tracked
+- `package.json` has required package and Pi extension/skill metadata
+
+### Package validation
+
+```bash
+python3 scripts/validate-package.py dist/keystone.zip
+```
+
+Checks include:
+
+- required package files exist in the archive
+- forbidden files are absent
+- archive contents match the expanded allowlist
+
+### Routing validation
+
+```bash
+python3 -m unittest tests/test_routing.py
+```
+
+Checks include:
+
+- routing fixtures are valid
+- every Keystone module has coverage
+- `/plan` routes to `breakdown`, not a public planner
+- fixture prompts match the routing table in `skills/keystone/SKILL.md`
+
+## Full verification
+
+Run everything with:
+
+```bash
+make test
+```
+
+This runs metadata generation, packaging, source validation, package validation, routing tests, and Python compile checks.
+
+## Platform outputs
+
+Keystone currently provides:
+
+| Host | Output |
+|---|---|
+| Pi | `.pi/extensions/keystone.ts` plus `package.json` with `pi.extensions` and `pi.skills` |
+| Claude Code | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` |
+| Codex | `.codex-plugin/plugin.json` |
+| Agents/Copilot-style hosts | `.agents/plugins/marketplace.json` |
+
+The Pi extension mirrors the Superpowers packaging pattern: it discovers bundled skills, registers `/keystone` as the public command, and injects a compact Pi-specific bootstrap while keeping internal modules private.
+
+The Pi package gallery at `https://pi.dev/packages` indexes npm packages. Keystone publishes as `@static-var/keystone` with the `pi-package` keyword, so installs use:
+
+```bash
+pi install npm:@static-var/keystone
+```
+
+## Common maintainer workflows
+
+### Change routing language
+
+1. Edit `skills/keystone/SKILL.md`.
+2. Update `tests/routing/cases.yaml` if behavior changes.
+3. Run `make test`.
+
+### Release Keystone
+
+1. Confirm the npm scope in `package.json` is owned by the publisher. Keystone currently uses `@static-var/keystone`.
+2. If the npm package does not exist yet, bootstrap it once with `npm login`, `npm run typecheck`, `make test`, and `npm publish --access public --provenance=false`; append `--otp <code>` if npm requires 2FA. npm only exposes Trusted Publisher settings after the package exists.
+3. In npm package access settings for `@static-var/keystone`, configure Trusted Publisher → GitHub Actions with user `static-var`, repository `Keystone`, workflow filename `release.yml`, no environment, and allowed action `npm publish`.
+4. Bump `package.json` with `npm version <patch|minor|major> --no-git-tag-version`.
+5. Run `npm run typecheck` and `make test`.
+6. Commit `package.json` and `package-lock.json`.
+7. Tag the commit as `v<package.json version>` and push `main` plus tags.
+8. The release workflow publishes npm via Trusted Publishing/OIDC with provenance and creates a GitHub Release containing the npm tarball plus `dist/keystone.zip`.
+
+### Add a shipped module
+
+1. Add `skills/keystone/modules/<name>.md`.
+2. Add a routing row in `skills/keystone/SKILL.md`.
+3. Add routing fixture coverage.
+4. Add a `Subagents and reasoning` section to the module.
+5. Add a module row to `skills/keystone/modules/helpers/subagents.md`.
+6. Ensure packaging includes the module directory through `packaging.allowlist`.
+7. Run `make test`.
+
+### Add maintainer-only guidance
+
+1. Put it outside `skills/keystone/`, for example under `maintainers/`.
+2. Do not add it to `skills/keystone/SKILL.md` routing.
+3. Do not add it to `packaging.allowlist` unless it is meant to ship.
+4. Run `make test` and inspect `dist/keystone.zip` if packaging changed.
+
+### Change packaging metadata
+
+1. Edit `package.json` or canonical skill frontmatter.
+2. Run `make regenerate`.
+3. Inspect generated manifests if needed.
+4. Run `make test`.
+
+### Prepare a release package
+
+```bash
+make package
+```
+
+Then inspect:
+
+```text
+dist/keystone.zip
+```
+
+## 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. Is `/keystone` still the only public entrypoint?
+2. Did we avoid creating `/plan`?
+3. Does each request still route to one primary module?
+4. Does `build` still check isolation before mutation?
+5. Is `review` still read-only?
+6. Does `ship` only finalize already-completed work?
+7. Are generated manifests regenerated from source?
+8. Does `make test` pass?
+
+If the answer to any question is no, Keystone's contract has drifted.
+
+## Design principle
+
+Keystone is not trying to make agents more autonomous by removing structure.
+
+It makes agents safer by giving each phase a name, a boundary, and a proof requirement.

package/Makefile

@@ -0,0 +1,19 @@
+.PHONY: test validate package regenerate routing py-compile
+
+test: validate routing py-compile
+
+validate: package
+	python3 scripts/validate-keystone.py
+	python3 scripts/validate-package.py dist/keystone.zip
+
+routing:
+	python3 -m unittest tests/test_routing.py
+
+py-compile:
+	python3 -m py_compile scripts/build-metadata.py scripts/validate-keystone.py scripts/validate-package.py tests/test_routing.py
+
+package: regenerate
+	scripts/package-keystone.sh
+
+regenerate:
+	python3 scripts/build-metadata.py