@static-var/keystone 0.1.0 → 1.0.0

package/.agents/plugins/marketplace.json

@@ -1,24 +1,22 @@
 {
-  "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",
+  "interface": {
+    "displayName": "Keystone"
+  },
   "name": "keystone",
-  "skills": [
-    "keystone"
-  ],
-  "version": "0.1.0"
+  "plugins": [
+    {
+      "category": "Development & Workflow",
+      "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",
+      "name": "keystone",
+      "policy": {
+        "authentication": "ON_USE",
+        "installation": "AVAILABLE"
+      },
+      "source": {
+        "path": "./",
+        "source": "local"
+      }
+    }
+  ]
 }

package/.agents/skills/keystone/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: keystone
+description: Keystone adapter for Agent Skills hosts such as OpenCode, GitHub Copilot, and VS Code. Use when the user asks Keystone to route product, research, writing, UI, design, planning, implementation, debugging, review, shipping, or health work.
+---
+
+# Keystone Agent Skills Adapter
+
+This is a thin adapter for hosts that discover skills from `.agents/skills/<name>/SKILL.md`.
+
+The canonical Keystone skill lives at:
+
+```text
+../../../skills/keystone/SKILL.md
+```
+
+When this adapter is loaded:
+
+1. Read `../../../skills/keystone/SKILL.md`.
+2. Follow the canonical Keystone entrypoint exactly.
+3. Resolve Keystone module, gate, and helper paths relative to `skills/keystone/`, not relative to this adapter directory.
+4. Keep the public surface as one Keystone skill. Do not expose internal modules as separate public commands.

package/.claude-plugin/marketplace.json

@@ -1,24 +1,28 @@
 {
-  "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",
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "description": "Keystone plugin marketplace for Claude Code.",
   "name": "keystone",
-  "skills": [
-    "keystone"
+  "owner": {
+    "name": "static-var"
+  },
+  "plugins": [
+    {
+      "author": {
+        "name": "static-var"
+      },
+      "category": "productivity",
+      "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.",
+      "name": "keystone",
+      "source": "./",
+      "tags": [
+        "workflow",
+        "skills",
+        "engineering",
+        "review",
+        "planning"
+      ],
+      "version": "1.0.0"
+    }
   ],
-  "version": "0.1.0"
+  "version": "1.0.0"
 }

package/.claude-plugin/plugin.json

@@ -1,12 +1,11 @@
 {
+  "$schema": "https://json.schemastore.org/claude-code-plugin.json",
+  "author": {
+    "name": "static-var"
+  },
   "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"
+  "repository": "https://github.com/static-var/Keystone",
+  "version": "1.0.0"
 }

package/.codex-plugin/plugin.json

@@ -1,12 +1,6 @@
 {
   "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"
+  "skills": "./skills/",
+  "version": "1.0.0"
 }

package/.pi/extensions/keystone.ts

@@ -145,7 +145,7 @@ Pi has native skills, but Keystone should use this extension's \`/keystone\` com
 
 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.`;
+Keystone is configured for \`@tintinweb/pi-subagents\` (https://github.com/tintinweb/pi-subagents). If that extension is installed, use its \`Agent\` tool for bounded delegation, \`get_subagent_result\` for background results, and \`steer_subagent\` only to redirect live work. Do not assume named roles, model selection, or thinking controls; use only the fields exposed by the active tool schema. Keep read-only work read-only. Use background/parallel subagents only for independent tasks with no shared mutable files. Do not invent unsupported subagent tools. If no subagent tool is available, do the work in this session.`;
 }
 
 function messageContainsBootstrap(message: unknown): boolean {

package/HOW_IT_WORKS.md

@@ -103,29 +103,28 @@ Each module has the same shape:
 
 ## Subagents and reasoning
 
-Keystone's subagent guidance lives in:
+Keystone keeps subagent guidance inline in `skills/keystone/SKILL.md`, the Pi extension bootstrap, and each module's `Subagents and reasoning` section. There is no separate helper file to load.
 
-```text
-skills/keystone/modules/helpers/subagents.md
-```
+Use subagents only when the active host exposes them and delegation has a clear boundary, useful artifact, and lower coordination cost than inline work.
 
-The helper records:
+For Pi, Keystone is configured for `@tintinweb/pi-subagents` (https://github.com/tintinweb/pi-subagents):
+
+```bash
+pi install npm:@tintinweb/pi-subagents
+```
 
-- 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
+When installed, Keystone may use `Agent`, `get_subagent_result`, and `steer_subagent` if the active tool schema exposes them. It does not assume named roles, model selection, or thinking controls from Pi; otherwise it works inline.
 
 ### Host capability summary
 
 | Harness | Subagents | Reasoning control |
 |---|---:|---|
-| Pi coding agent with `pi-subagents` | yes | native `thinking`, `model`, and `profile` per agent/invocation |
+| Pi coding agent with `@tintinweb/pi-subagents` | yes | use only controls exposed by the active tool schema; do not assume named roles, `model`, or `thinking` |
 | 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 |
+| OpenCode | yes | partial/provider-dependent: `model` plus provider-specific `variant`; no universal reasoning knob confirmed; discovers Keystone through `.agents/skills` or symlinked canonical skill |
+| GitHub Copilot / VS Code | yes | custom agent `model`; no general reasoning field confirmed; discovers Keystone through `.agents/skills`, `.github/skills`, or personal skill dirs |
 
 ### Module reasoning defaults
 
@@ -136,7 +135,7 @@ The helper records:
 | 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.
+The rule is simple: delegate the narrowest bounded task and request the lowest reasoning intensity that can safely complete it. Only use role names, model selection, or thinking controls when the active host schema exposes them. Escalate for ambiguity, irreversible decisions, security, data loss, release risk, or root-cause uncertainty.
 
 ## Gates
 
@@ -217,7 +216,8 @@ make regenerate
    ├─ .claude-plugin/plugin.json
    ├─ .claude-plugin/marketplace.json
    ├─ .codex-plugin/plugin.json
-   └─ .agents/plugins/marketplace.json
+   ├─ .agents/plugins/marketplace.json
+   └─ .agents/skills/keystone/SKILL.md
    │
    ▼
 make package
@@ -320,12 +320,19 @@ 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` |
+| Claude Code | `.claude-plugin/plugin.json` plus `.claude-plugin/marketplace.json` marketplace |
+| Codex | `.codex-plugin/plugin.json` plus `.agents/plugins/marketplace.json` repo marketplace |
+| OpenCode / GitHub Copilot / VS Code | `.agents/skills/keystone/SKILL.md` adapter plus canonical `skills/keystone/` |
+| T3 Code | use the underlying Codex, Claude Code, or OpenCode install path |
+
+The Claude Code plugin path uses Claude's marketplace pattern: `.claude-plugin/plugin.json` identifies the repository root as a plugin, and `.claude-plugin/marketplace.json` exposes a single installable `keystone` entry with source `./`. Users add it with `/plugin marketplace add static-var/Keystone`, install with `/plugin install keystone@keystone`, then invoke `/keystone:keystone`.
 
 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 Codex plugin path uses the Codex plugin marketplace pattern: `.codex-plugin/plugin.json` declares the bundled skill directory, while `.agents/plugins/marketplace.json` exposes a single installable Keystone entry whose local source is the repository root. Users can add it with `codex plugin marketplace add static-var/Keystone --ref main`, then install Keystone from `codex /plugins` or `codex plugin add keystone --marketplace keystone`.
+
+OpenCode, GitHub Copilot, and VS Code support the Agent Skills standard directly. Keystone ships `.agents/skills/keystone/SKILL.md` as a thin adapter that points those hosts back to the canonical `skills/keystone/SKILL.md`, preserving one source of truth and one public Keystone skill.
+
 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
@@ -357,8 +364,7 @@ pi install npm:@static-var/keystone
 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`.
+5. Ensure packaging includes the module directory through `packaging.allowlist`.
 7. Run `make test`.
 
 ### Add maintainer-only guidance

package/Makefile

@@ -1,6 +1,6 @@
-.PHONY: test validate package regenerate routing py-compile
+.PHONY: test validate package regenerate routing unit py-compile
 
-test: validate routing py-compile
+test: validate unit py-compile
 
 validate: package
 	python3 scripts/validate-keystone.py
@@ -9,8 +9,11 @@ validate: package
 routing:
 	python3 -m unittest tests/test_routing.py
 
+unit:
+	python3 -m unittest discover -s tests -p 'test_*.py'
+
 py-compile:
-	python3 -m py_compile scripts/build-metadata.py scripts/validate-keystone.py scripts/validate-package.py tests/test_routing.py
+	python3 -m py_compile scripts/build-metadata.py scripts/validate-keystone.py scripts/validate-package.py tests/test_routing.py tests/test_package_validator.py
 
 package: regenerate
 	scripts/package-keystone.sh

package/README.md

@@ -124,14 +124,16 @@ This file is not included in `dist/keystone.zip` and is not part of `/keystone`
 .
 ├── skills/keystone/              # canonical skill source
 │   ├── SKILL.md                  # public /keystone entrypoint
-│   └── modules/                  # internal modules, helpers, and gates
+│   └── modules/                  # internal modules and gates
 ├── scripts/                      # metadata, validation, packaging
 ├── tests/routing/cases.yaml      # routing fixture cases
 ├── tests/test_routing.py         # stdlib routing test runner
+├── tests/test_package_validator.py # package validator unit coverage
 ├── maintainers/                  # repo-only, not shipped in package
 ├── .claude-plugin/               # generated Claude plugin metadata
 ├── .codex-plugin/                # generated Codex plugin metadata
-├── .agents/plugins/              # generated agents marketplace metadata
+├── .agents/plugins/              # generated Codex repo marketplace
+├── .agents/skills/               # generated Agent Skills adapter for OpenCode/Copilot-compatible hosts
 ├── packaging.allowlist           # default-deny package contents
 ├── Makefile                      # test/package/regenerate targets
 └── HOW_IT_WORKS.md               # human-readable architecture guide
@@ -139,22 +141,15 @@ This file is not included in `dist/keystone.zip` and is not part of `/keystone`
 
 ## Subagent and reasoning support
 
-Keystone documents host-specific subagent support in:
+Keystone keeps subagent guidance inline in the root skill and each module. Use subagents only when the active host exposes them and delegation is cheaper than doing the work inline.
 
-```text
-skills/keystone/modules/helpers/subagents.md
-```
+For Pi, install the supported subagent extension:
 
-Current summary:
+```bash
+pi install npm:@tintinweb/pi-subagents
+```
 
-| Harness | Subagents | Per-subagent reasoning |
-|---|---:|---:|
-| Pi with `pi-subagents` | yes | yes: `thinking`, `model`, `profile` |
-| Claude Code | yes | partial: model/detail controls, no general custom-agent reasoning knob |
-| Codex CLI/app | host-dependent | partial/global: use prompt advisory unless host exposes per-agent effort |
-| T3 Code | unconfirmed | unconfirmed |
-| OpenCode | yes | partial/provider-dependent: `model` and provider `variant`; no universal reasoning knob confirmed |
-| GitHub Copilot | yes | partial: custom agent `model`, no general reasoning knob |
+Then Keystone can use `Agent`, `get_subagent_result`, and `steer_subagent` when the active tool schema exposes them. Keystone does not assume named roles, model selection, or thinking controls from Pi; if those controls are unavailable, it works inline or encodes intent in the prompt instead of inventing unsupported fields.
 
 Each Keystone module includes a `Subagents and reasoning` section with its default reasoning level.
 
@@ -172,9 +167,81 @@ Keystone currently ships as:
   }
   ```
 - **Pi extension source** in `.pi/extensions/keystone.ts`, which registers `/keystone`, discovers the bundled skill, and adds a small Pi-specific bootstrap.
-- **Claude plugin metadata** in `.claude-plugin/`
-- **Codex plugin metadata** in `.codex-plugin/`
-- **Agents marketplace metadata** in `.agents/plugins/`
+- **Claude Code plugin manifest + marketplace** in `.claude-plugin/`
+- **Codex plugin manifest** in `.codex-plugin/plugin.json`
+- **Codex repo marketplace** in `.agents/plugins/marketplace.json`
+- **Agent Skills adapter** in `.agents/skills/keystone/SKILL.md` for OpenCode, GitHub Copilot, VS Code, and other Agent Skills hosts
+
+## Claude Code plugin install
+
+Keystone is installable as a Claude Code plugin marketplace from this GitHub repo.
+
+In Claude Code:
+
+```text
+/plugin marketplace add static-var/Keystone
+/plugin install keystone@keystone
+```
+
+Then invoke the namespaced Keystone skill:
+
+```text
+/keystone:keystone <task>
+```
+
+## Codex plugin install
+
+Keystone is also installable as a Codex plugin from this GitHub repo marketplace.
+
+```bash
+codex plugin marketplace add static-var/Keystone --ref main
+```
+
+Then open the plugin browser and install Keystone:
+
+```bash
+codex /plugins
+```
+
+CLI install equivalent:
+
+```bash
+codex plugin add keystone --marketplace keystone
+# or: codex plugin add keystone@keystone
+```
+
+After installation, invoke Keystone explicitly with `@keystone` / `$keystone` depending on your Codex surface, or ask Codex to use Keystone for workflow routing.
+
+## OpenCode / Copilot / VS Code skills
+
+Keystone ships a `.agents/skills/keystone` adapter because OpenCode and GitHub Copilot-compatible hosts discover Agent Skills from `.agents/skills`.
+
+Project-local use: clone or vendor this repo into a project and those hosts can discover `.agents/skills/keystone/SKILL.md`.
+
+Personal/global use is best done by linking the canonical skill directory, so module references stay intact:
+
+```bash
+# From a repo checkout
+KS=/path/to/Keystone
+
+# Or from global npm install
+npm install -g @static-var/keystone
+KS="$(npm root -g)/@static-var/keystone"
+
+# OpenCode
+mkdir -p ~/.config/opencode/skills
+ln -s "$KS/skills/keystone" ~/.config/opencode/skills/keystone
+
+# GitHub Copilot / VS Code
+mkdir -p ~/.copilot/skills
+ln -s "$KS/skills/keystone" ~/.copilot/skills/keystone
+
+# Shared Agent Skills path for compatible hosts
+mkdir -p ~/.agents/skills
+ln -s "$KS/skills/keystone" ~/.agents/skills/keystone
+```
+
+T3 Code currently rides on underlying agents. Use the matching Codex, Claude Code, or OpenCode install path for the provider you run inside T3 Code.
 
 ## Release automation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@static-var/keystone",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Keystone: one-router AI engineering workflow extension and skill system for Pi.",
   "type": "module",
   "license": "MIT",
@@ -46,7 +46,6 @@
     "skills/keystone/modules/review.md",
     "skills/keystone/modules/ship.md",
     "skills/keystone/modules/health.md",
-    "skills/keystone/modules/helpers/subagents.md",
     "skills/keystone/modules/gates/isolation.md",
     "skills/keystone/modules/gates/proof.md",
     "skills/keystone/modules/gates/red.md",
@@ -56,6 +55,7 @@
     ".claude-plugin/marketplace.json",
     ".codex-plugin/plugin.json",
     ".agents/plugins/marketplace.json",
+    ".agents/skills/keystone/SKILL.md",
     ".pi/extensions/keystone.ts"
   ],
   "publishConfig": {

package/packaging.allowlist

@@ -19,7 +19,6 @@ skills/keystone/modules/debug.md
 skills/keystone/modules/review.md
 skills/keystone/modules/ship.md
 skills/keystone/modules/health.md
-skills/keystone/modules/helpers/subagents.md
 skills/keystone/modules/gates/isolation.md
 skills/keystone/modules/gates/proof.md
 skills/keystone/modules/gates/red.md
@@ -29,4 +28,5 @@ skills/keystone/modules/gates/ship.md
 .claude-plugin/marketplace.json
 .codex-plugin/plugin.json
 .agents/plugins/marketplace.json
+.agents/skills/keystone/SKILL.md
 .pi/extensions/keystone.ts

package/scripts/build-metadata.py

@@ -12,6 +12,13 @@ PACKAGE = ROOT / "package.json"
 NAME = "keystone"
 
 
+AGENT_SKILL_DESCRIPTION = (
+    "Keystone adapter for Agent Skills hosts such as OpenCode, GitHub Copilot, and VS Code. "
+    "Use when the user asks Keystone to route product, research, writing, UI, design, planning, "
+    "implementation, debugging, review, shipping, or health work."
+)
+
+
 def read_package() -> dict:
     if PACKAGE.exists():
         return json.loads(PACKAGE.read_text())
@@ -60,38 +67,96 @@ def write_json(path: Path, data: dict) -> None:
     path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
 
 
+def write_agent_skill_adapter() -> None:
+    path = ROOT / ".agents" / "skills" / "keystone" / "SKILL.md"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        f"""---
+name: keystone
+description: {AGENT_SKILL_DESCRIPTION}
+---
+
+# Keystone Agent Skills Adapter
+
+This is a thin adapter for hosts that discover skills from `.agents/skills/<name>/SKILL.md`.
+
+The canonical Keystone skill lives at:
+
+```text
+../../../skills/keystone/SKILL.md
+```
+
+When this adapter is loaded:
+
+1. Read `../../../skills/keystone/SKILL.md`.
+2. Follow the canonical Keystone entrypoint exactly.
+3. Resolve Keystone module, gate, and helper paths relative to `skills/keystone/`, not relative to this adapter directory.
+4. Keep the public surface as one Keystone skill. Do not expose internal modules as separate public commands.
+"""
+    )
+
+
 def main() -> int:
     package = read_package()
     skill_text = SKILL.read_text() if SKILL.exists() else ""
-    fm = parse_frontmatter(skill_text)
     description = skill_summary(skill_text) if skill_text else package.get("description", "Keystone skill.")
     version = package.get("version", "0.0.0")
     license_name = package.get("license", "UNLICENSED")
-    keywords = package.get("keywords", ["keystone", "skill"])
 
-    plugin = {
+    claude_plugin = {
+        "$schema": "https://json.schemastore.org/claude-code-plugin.json",
         "name": NAME,
         "version": version,
         "description": description,
+        "author": {"name": "static-var"},
+        "repository": "https://github.com/static-var/Keystone",
         "license": license_name,
-        "skills": [{"name": NAME, "path": "../skills/keystone/SKILL.md"}],
     }
-    marketplace = {
+    claude_marketplace = {
+        "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+        "name": NAME,
+        "version": version,
+        "description": "Keystone plugin marketplace for Claude Code.",
+        "owner": {"name": "static-var"},
+        "plugins": [
+            {
+                "name": NAME,
+                "source": "./",
+                "description": description,
+                "version": version,
+                "author": {"name": "static-var"},
+                "category": "productivity",
+                "tags": ["workflow", "skills", "engineering", "review", "planning"],
+            }
+        ],
+    }
+
+    codex_plugin = {
         "name": NAME,
-        "displayName": "Keystone",
         "version": version,
         "description": description,
-        "license": license_name,
-        "keywords": keywords,
-        "skills": [NAME],
+        "skills": "./skills/",
+    }
+    codex_marketplace = {
+        "name": NAME,
+        "interface": {"displayName": "Keystone"},
+        "plugins": [
+            {
+                "name": NAME,
+                "displayName": "Keystone",
+                "source": {"source": "local", "path": "./"},
+                "policy": {"installation": "AVAILABLE", "authentication": "ON_USE"},
+                "category": "Development & Workflow",
+                "description": description,
+            }
+        ],
     }
-    if isinstance(fm.get("author"), str):
-        marketplace["author"] = fm["author"]
 
-    write_json(ROOT / ".claude-plugin" / "plugin.json", plugin)
-    write_json(ROOT / ".claude-plugin" / "marketplace.json", marketplace)
-    write_json(ROOT / ".codex-plugin" / "plugin.json", plugin)
-    write_json(ROOT / ".agents" / "plugins" / "marketplace.json", marketplace)
+    write_json(ROOT / ".claude-plugin" / "plugin.json", claude_plugin)
+    write_json(ROOT / ".claude-plugin" / "marketplace.json", claude_marketplace)
+    write_json(ROOT / ".codex-plugin" / "plugin.json", codex_plugin)
+    write_json(ROOT / ".agents" / "plugins" / "marketplace.json", codex_marketplace)
+    write_agent_skill_adapter()
     return 0
 
 

package/scripts/validate-keystone.py

@@ -13,9 +13,13 @@ SKILL_DIR = ROOT / "skills" / "keystone"
 SKILL = SKILL_DIR / "SKILL.md"
 MODULE_DIR = SKILL_DIR / "modules"
 PI_EXTENSION = ROOT / ".pi" / "extensions" / "keystone.ts"
+CLAUDE_PLUGIN = ROOT / ".claude-plugin" / "plugin.json"
+CLAUDE_MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json"
+CODEX_PLUGIN = ROOT / ".codex-plugin" / "plugin.json"
+CODEX_MARKETPLACE = ROOT / ".agents" / "plugins" / "marketplace.json"
+AGENTS_SKILL_ADAPTER = ROOT / ".agents" / "skills" / "keystone" / "SKILL.md"
 ALLOWLIST = ROOT / "packaging.allowlist"
 SUBAGENT_HELPER = MODULE_DIR / "helpers" / "subagents.md"
-TARGET_HARNESSES = ("Pi", "Claude", "Codex", "T3", "OpenCode", "Copilot")
 COMMON_PLAYBOOK_HEADINGS = (
     "## Core principle",
     "## Load when",
@@ -165,28 +169,118 @@ def check_module_playbooks(skill_text: str) -> None:
             fail(f"module {name} missing playbook headings: " + ", ".join(missing))
 
 
-def check_subagent_helper(skill_text: str) -> None:
-    if not SUBAGENT_HELPER.is_file():
-        fail("missing subagent reasoning helper modules/helpers/subagents.md")
-    helper_text = SUBAGENT_HELPER.read_text()
-    missing_harnesses = [name for name in TARGET_HARNESSES if name not in helper_text]
-    if missing_harnesses:
-        fail("subagent helper missing target harnesses: " + ", ".join(missing_harnesses))
+def check_inline_subagent_guidance(skill_text: str) -> None:
+    if SUBAGENT_HELPER.exists():
+        fail("subagent helper file must not be shipped; keep subagent guidance inline")
+    forbidden = "modules/helpers/subagents.md"
+    if forbidden in skill_text:
+        fail("Keystone skill must not reference the removed subagent helper file")
+    required_skill_phrases = (
+        "Use subagents when the active host exposes them",
+        "@tintinweb/pi-subagents",
+        "Agent",
+        "get_subagent_result",
+        "steer_subagent",
+        "Do not assume named roles, model selection, or thinking controls",
+    )
+    for phrase in required_skill_phrases:
+        if phrase not in skill_text:
+            fail(f"Keystone skill missing inline subagent guidance phrase: {phrase}")
+    for phrase in forbidden_pi_subagent_claims():
+        if phrase in skill_text:
+            fail(f"Keystone skill advertises non-portable pi-subagents capability: {phrase}")
+
     primary_modules = routing_modules(skill_text)
     if not primary_modules:
         fail("no primary modules found in Keystone routing table")
-    missing_modules = [
-        name for name in sorted(primary_modules)
-        if f"modules/{name}.md" not in helper_text
-    ]
-    if missing_modules:
-        fail("subagent helper missing module reasoning rows: " + ", ".join(missing_modules))
     for name in sorted(primary_modules):
         module = MODULE_DIR / f"{name}.md"
         if not module.is_file():
             fail(f"missing primary module file: modules/{name}.md")
-        if "## Subagents and reasoning" not in module.read_text():
+        module_text = module.read_text()
+        if "## Subagents and reasoning" not in module_text:
             fail(f"module missing subagent reasoning section: modules/{name}.md")
+        if forbidden in module_text or "helpers/subagents.md" in module_text:
+            fail(f"module references removed subagent helper file: modules/{name}.md")
+        for phrase in forbidden_module_subagent_role_claims():
+            if phrase in module_text:
+                fail(f"module advertises named/non-portable subagent role language: modules/{name}.md: {phrase}")
+
+
+def forbidden_module_subagent_role_claims() -> tuple[str, ...]:
+    return (
+        "subagent roles",
+        "researcher subagents",
+        "architecture reviewer subagents",
+        "risk reviewer subagents",
+        "worker subagents",
+        "subagents/workers",
+        "oracle/debug subagents",
+        "oracle subagents",
+        "debug subagents",
+        "scout subagents",
+        "reviewer subagents",
+        "writer subagents",
+        "writer, UI, design, or architecture subagents",
+        "specify role,",
+        "<role, reasoning, context packet, expected artifact>",
+    )
+
+
+def forbidden_pi_subagent_claims(markdown_escaped: bool = False) -> tuple[str, ...]:
+    tick = "\\`" if markdown_escaped else "`"
+    return (
+        "Prefer narrow roles",
+        "narrowest subagent role",
+        f"{tick}scout{tick}",
+        f"{tick}worker{tick}",
+        f"{tick}reviewer{tick}",
+        f"{tick}oracle{tick}",
+        f"{tick}writer{tick}",
+        f"{tick}thinking{tick} or {tick}model{tick}",
+        f"{tick}model{tick} or {tick}thinking{tick}",
+        f"{tick}thinking{tick} and {tick}model{tick}",
+        f"{tick}model{tick} and {tick}thinking{tick}",
+        f"{tick}thinking{tick}, {tick}model{tick}",
+        f"{tick}model{tick}, {tick}thinking{tick}",
+        f"{tick}profile{tick}",
+    )
+
+
+def check_pi_subagent_docs() -> None:
+    for path in (ROOT / "README.md", ROOT / "HOW_IT_WORKS.md"):
+        if not path.is_file():
+            fail(f"missing {path.name}")
+        text = path.read_text()
+        if "@tintinweb/pi-subagents" not in text:
+            fail(f"{path.name} missing @tintinweb/pi-subagents install guidance")
+        if "Do not assume named roles" not in text and "does not assume named roles" not in text:
+            fail(f"{path.name} must say not to assume named roles or Pi subagent controls")
+        for phrase in forbidden_pi_subagent_claims():
+            if phrase in text:
+                fail(f"{path.name} advertises non-portable pi-subagents capability: {phrase}")
+
+
+def check_pi_subagents_extension_guidance() -> None:
+    if not PI_EXTENSION.is_file():
+        fail("missing Pi extension .pi/extensions/keystone.ts")
+    extension = PI_EXTENSION.read_text()
+    required_phrases = (
+        "@tintinweb/pi-subagents",
+        "Agent",
+        "get_subagent_result",
+        "steer_subagent",
+        "Do not invent unsupported subagent tools",
+        "Do not assume named roles, model selection, or thinking controls",
+    )
+    for phrase in required_phrases:
+        if phrase not in extension:
+            fail(f"Pi extension missing pi-subagents guidance phrase: {phrase}")
+    for phrase in forbidden_pi_subagent_claims(markdown_escaped=True) + ("`profile`",):
+        if phrase in extension:
+            fail(f"Pi extension advertises non-portable pi-subagents capability: {phrase}")
+    if "modules/helpers/subagents.md" in extension or "helpers/subagents.md" in extension:
+        fail("Pi extension must not reference removed subagent helper file")
 
 
 def check_ignored_not_tracked() -> None:
@@ -209,6 +303,65 @@ def allowlist_entries() -> set[str]:
     }
 
 
+def check_agents_skill_adapter() -> None:
+    if not AGENTS_SKILL_ADAPTER.is_file():
+        fail("missing .agents/skills/keystone/SKILL.md adapter for OpenCode/Copilot-compatible hosts")
+    text = AGENTS_SKILL_ADAPTER.read_text()
+    if "../../../skills/keystone/SKILL.md" not in text:
+        fail(".agents skill adapter must point to canonical skills/keystone/SKILL.md")
+    if "Do not expose internal modules" not in text:
+        fail(".agents skill adapter must preserve one public Keystone surface")
+
+
+def check_claude_metadata() -> None:
+    if not CLAUDE_PLUGIN.is_file():
+        fail("missing Claude plugin manifest .claude-plugin/plugin.json")
+    plugin = json.loads(CLAUDE_PLUGIN.read_text())
+    if plugin.get("name") != "keystone":
+        fail("Claude plugin name must be keystone")
+    if "skills" in plugin:
+        fail("Claude plugin manifest should rely on the bundled skills/ directory, not legacy skills entries")
+    if not CLAUDE_MARKETPLACE.is_file():
+        fail("missing Claude marketplace .claude-plugin/marketplace.json")
+    marketplace = json.loads(CLAUDE_MARKETPLACE.read_text())
+    if marketplace.get("name") != "keystone":
+        fail("Claude marketplace name must be keystone")
+    if not isinstance(marketplace.get("owner"), dict) or not marketplace["owner"].get("name"):
+        fail("Claude marketplace must include owner.name")
+    plugins = marketplace.get("plugins")
+    if not isinstance(plugins, list) or len(plugins) != 1:
+        fail("Claude marketplace must expose exactly one Keystone plugin entry")
+    entry = plugins[0]
+    if entry.get("name") != "keystone" or entry.get("source") != "./":
+        fail('Claude marketplace plugin entry must be keystone with source "./"')
+
+
+def check_codex_metadata() -> None:
+    if not CODEX_PLUGIN.is_file():
+        fail("missing Codex plugin manifest .codex-plugin/plugin.json")
+    plugin = json.loads(CODEX_PLUGIN.read_text())
+    if plugin.get("name") != "keystone":
+        fail("Codex plugin name must be keystone")
+    if plugin.get("skills") != "./skills/":
+        fail('Codex plugin must expose bundled skills with skills: "./skills/"')
+    if not CODEX_MARKETPLACE.is_file():
+        fail("missing Codex marketplace .agents/plugins/marketplace.json")
+    marketplace = json.loads(CODEX_MARKETPLACE.read_text())
+    plugins = marketplace.get("plugins")
+    if not isinstance(plugins, list) or len(plugins) != 1:
+        fail("Codex marketplace must expose exactly one Keystone plugin entry")
+    entry = plugins[0]
+    if entry.get("name") != "keystone":
+        fail("Codex marketplace plugin entry must be named keystone")
+    if entry.get("source") != {"source": "local", "path": "./"}:
+        fail('Codex marketplace plugin source must be {"source": "local", "path": "./"}')
+    policy = entry.get("policy", {})
+    if policy.get("installation") != "AVAILABLE":
+        fail("Codex marketplace plugin must be installable")
+    if policy.get("authentication") not in {"ON_USE", "ON_INSTALL"}:
+        fail("Codex marketplace plugin authentication policy must be ON_USE or ON_INSTALL")
+
+
 def check_package_json() -> None:
     package_path = ROOT / "package.json"
     if not package_path.is_file():
@@ -250,8 +403,13 @@ def main() -> int:
     check_references(text)
     check_product_modules(text)
     check_module_playbooks(text)
-    check_subagent_helper(text)
+    check_inline_subagent_guidance(text)
+    check_pi_subagent_docs()
+    check_pi_subagents_extension_guidance()
     check_ignored_not_tracked()
+    check_agents_skill_adapter()
+    check_claude_metadata()
+    check_codex_metadata()
     check_package_json()
     print("validate-keystone: ok")
     return 0

package/scripts/validate-package.py

@@ -30,13 +30,16 @@ REQUIRED = {
     "skills/keystone/modules/review.md",
     "skills/keystone/modules/ship.md",
     "skills/keystone/modules/health.md",
-    "skills/keystone/modules/helpers/subagents.md",
     "skills/keystone/modules/gates/isolation.md",
     "skills/keystone/modules/gates/proof.md",
+    "skills/keystone/modules/gates/red.md",
+    "skills/keystone/modules/gates/review.md",
+    "skills/keystone/modules/gates/ship.md",
     ".claude-plugin/plugin.json",
     ".claude-plugin/marketplace.json",
     ".codex-plugin/plugin.json",
     ".agents/plugins/marketplace.json",
+    ".agents/skills/keystone/SKILL.md",
 }
 FORBIDDEN_NAMES = {
     "index.html",

package/skills/keystone/SKILL.md

@@ -18,6 +18,7 @@ Use these common paths unless the user's immediate next action clearly points el
 - Product or feature work: `research -> shape -> breakdown -> build -> review -> ship`.
 - Existing plan or approved design: `breakdown -> build -> review -> ship`.
 - Direct implementation request: `build -> review -> ship`, loading `breakdown` first only when execution order or verification is unclear.
+- Bug fix: `debug -> build -> proof gate -> review -> ship`.
 - Debug loop: `debug -> build -> proof gate -> review`; return to `debug` if proof fails or new symptoms appear.
 - Health finding that needs repair: `health -> build` for contained fixes, or `health -> review` when the finding needs independent validation before mutation.
 
@@ -48,7 +49,11 @@ When a module temporarily routes to another module and then resumes, the returni
 
 ## Subagents and reasoning
 
-When a module may delegate work, consult `modules/helpers/subagents.md` for host capability, safe delegation rules, and the recommended reasoning level for each Keystone module. If the host cannot enforce per-subagent reasoning, include the desired level in the subagent prompt or work inline.
+Use subagents when the active host exposes them and delegation has a clear boundary, useful artifact, and lower coordination cost than doing the work inline.
+
+For Pi, Keystone is tuned for `@tintinweb/pi-subagents` (https://github.com/tintinweb/pi-subagents). Install it with `pi install npm:@tintinweb/pi-subagents`. When available, use `Agent` for bounded work, `get_subagent_result` for background results, and `steer_subagent` only to redirect live work. Do not assume named roles, model selection, or thinking controls; use only the fields exposed by the active tool schema.
+
+Keep subagents read-only unless mutation is explicitly requested. Use background/parallel agents only for independent tasks with no shared mutable files. Treat subagent output as evidence, not truth; the parent must verify before acting. If the host cannot provide subagents or per-subagent reasoning, include the desired reasoning in the prompt or work inline. Do not invent unsupported subagent tools.
 
 ## Routing table
 

package/skills/keystone/modules/breakdown.md

@@ -57,7 +57,7 @@ Use for new projects, tools, services, apps, packages, or substantial standalone
 Use when behavior should remain stable while internals change. Focus on the current behavior contract, compatibility expectations, affected surfaces, consumers, migration seams, adapters, flags, dual-run paths, rollback strategy, observability, and characterization tests. Prefer strangler-style or seam-first slices over broad rewrites.
 
 ### Subagent-parallel breakdown
-Use when independent workstreams can proceed safely in isolated workspaces. Build the dependency graph before delegation. Name shared files, interfaces, merge-risk hotspots, subagent roles, reasoning levels, context packets, expected artifacts, integration order, and review checkpoints. Only parallelize slices that can be verified independently or integrated behind a clear contract.
+Use when independent workstreams can proceed safely in isolated workspaces. Build the dependency graph before delegation. Name shared files, interfaces, merge-risk hotspots, delegation purpose, desired reasoning intensity, context packets, expected artifacts, integration order, and review checkpoints. Only parallelize slices that can be verified independently or integrated behind a clear contract.
 
 ## Process
 
@@ -137,12 +137,12 @@ Default reasoning: `high`.
 
 Use subagents when planning benefits from independent context gathering, critique, or parallel workstream design:
 
-- researcher subagents for separate code areas, external APIs, or prior art
-- architecture reviewer subagents for greenfield foundations and migrations
-- risk reviewer subagents for security, data loss, compatibility, or release plans
-- worker subagents only after slices are independent and interfaces are stable
+- read-only research on separate code areas, external APIs, or prior art
+- architecture critique for greenfield foundations and migrations
+- risk critique for security, data loss, compatibility, or release plans
+- implementation delegation only after slices are independent and interfaces are stable
 
-For each proposed subagent, specify role, reasoning level, context packet, expected output artifact, files or areas off limits, and integration/review checkpoint. Do not use subagents to bypass ambiguity. Resolve shared interfaces and sequencing first.
+For each proposed delegation, specify purpose, desired reasoning intensity, context packet, expected output artifact, files or areas off limits, and integration/review checkpoint. Do not use subagents to bypass ambiguity. Resolve shared interfaces and sequencing first.
 
 ## Hard rules
 
@@ -230,7 +230,7 @@ Use this structure unless the user requested a different planning artifact:
 - <risk, impact, mitigation>
 
 ## Subagent opportunities
-- <role, reasoning, context packet, expected artifact>
+- <delegation purpose, desired reasoning intensity, context packet, expected artifact>
 
 ## Handoff
 Next module: `<research|build|debug|review|health|ship|shape>` because <reason>.

package/skills/keystone/modules/build.md

@@ -15,7 +15,7 @@ Use Build when the user asks to:
 - refactor existing code while preserving behavior
 - change architecture, module boundaries, interfaces, or contracts
 - apply an approved plan from `breakdown`
-- delegate independent implementation work to subagents/workers
+- delegate independent implementation work when a subagent tool is available
 - make focused content or configuration changes that require mutation
 
 ## Not for
@@ -220,7 +220,7 @@ Escalate to `high` when:
 - data loss, security, billing, release, or migration risk exists
 - the user asks for broad refactoring or platform-specific architecture judgment
 
-Use subagents/workers when:
+Use subagents when:
 
 - slices can be verified independently
 - files do not overlap, or ownership is explicitly assigned

package/skills/keystone/modules/debug.md

@@ -127,7 +127,7 @@ Escalation/stuck criteria:
 - Escalation output must include symptom, impact, attempts, disproven hypotheses, missing evidence, requested help/access, and safest next action.
 
 ## Subagents and reasoning
-Default reasoning: `high`. Use oracle/debug subagents for independent root-cause analysis, log review, performance profile interpretation, bisect planning, or hypothesis generation. Use `xhigh` for intermittent, cross-system, security, performance, data-loss, privacy, destructive, or production-impacting failures.
+Default reasoning: `high`. Use subagents for independent root-cause analysis, log review, performance profile interpretation, bisect planning, or hypothesis generation when the active host exposes safe delegation. Use `xhigh` for intermittent, cross-system, security, performance, data-loss, privacy, destructive, or production-impacting failures.
 
 Subagents may inspect and reason independently, but fixes should converge on one evidence-backed root cause. Ask subagents for competing hypotheses and evidence gaps, not broad code review. When subagents disagree, run the smallest test that distinguishes their explanations. Do not let parallel analysis become parallel guess-and-check edits.
 

package/skills/keystone/modules/health.md

@@ -64,7 +64,7 @@ Health priority rubric:
 9. Stop at reporting unless the user explicitly requested fixes. If repairs are requested, route to the appropriate module instead of silently switching modes.
 
 ## Subagents and reasoning
-Default reasoning: `medium`. Use read-only scout subagents for broad inventory and reviewer subagents for independent risk triage. Use `high` for release readiness, security-sensitive audits, large monorepos, severe tooling drift, instruction drift affecting agent behavior, or when health findings affect go/no-go decisions. Subagents must remain read-only unless repairs are explicitly requested.
+Default reasoning: `medium`. Use read-only subagents for broad inventory or independent risk triage when the active host exposes safe delegation. Use `high` for release readiness, security-sensitive audits, large monorepos, severe tooling drift, instruction drift affecting agent behavior, or when health findings affect go/no-go decisions. Subagents must remain read-only unless repairs are explicitly requested.
 
 ## Hard rules
 - Read-only by default: no fixing, formatting, dependency updates, cleanup, generation, or config changes unless explicitly requested.

package/skills/keystone/modules/research.md

@@ -39,7 +39,7 @@ Deliver a research brief that states:
 8. Recommend the smallest next step: `shape`, `debug`, `health`, `breakdown`, `build`, `review`, or stop.
 
 ## Subagents and reasoning
-Default reasoning: `medium`. Use read-only scout subagents when the search space is large or evidence can be gathered independently. Use `low` for narrow file summaries. Use `high` when findings affect architecture, security, safety, release decisions, legal/market claims, or irreversible product direction. Subagents must remain read-only unless the user requested an artifact.
+Default reasoning: `medium`. Use read-only subagents when the search space is large or evidence can be gathered independently. Use `low` for narrow file summaries. Use `high` when findings affect architecture, security, safety, release decisions, legal/market claims, or irreversible product direction. Subagents must remain read-only unless the user requested an artifact.
 
 ## Hard rules
 - No mutation by default: do not edit files, run formatters, or alter state except harmless read-only commands.

package/skills/keystone/modules/review.md

@@ -179,7 +179,7 @@ Ask for every non-trivial review:
 ## Subagents and reasoning
 Default reasoning: `high`.
 
-Use read-only reviewer subagents for separable risks: security/privacy, test coverage,
+Use read-only subagents for separable risks: security/privacy, test coverage,
 architecture/API compatibility, persistence/migration, accessibility/user impact,
 performance, concurrency, or release risk. Escalate to `xhigh` for security-sensitive,
 data-loss, billing, permissions, public API, migration, or cross-system reviews.

package/skills/keystone/modules/router.md

@@ -16,7 +16,7 @@ Modify files, perform implementation, or expose internal modules as public slash
 One primary module after classification. Gates only if that primary module requires them.
 
 ## Subagents and reasoning
-Default reasoning: `low`. Do not deploy subagents for simple routing; ask one clarifying question if a safe single route is not clear. See `helpers/subagents.md`.
+Default reasoning: `low`. Do not deploy subagents for simple routing; ask one clarifying question if a safe single route is not clear.
 
 ## Routing heuristics
 Prefer the module indicated by the user's strongest current need, not the first verb alone. Weigh multiple signals together:

package/skills/keystone/modules/shape.md

@@ -50,7 +50,7 @@ Deliver a shaped proposal that includes:
 9. Stop at the spec boundary. If the user asks for design plus build, finish Shape with the spec and recommended handoff to `build`; do not implement code.
 
 ## Subagents and reasoning
-Default reasoning: `medium`. Use writer, UI, design, or architecture subagents for bounded alternatives, critique, or parallel concepts. Use `high` for multi-screen flows, accessibility-sensitive experiences, design-system impact, pricing/positioning, architecture boundaries, or major scope decisions. Subagents should produce options or critique, not unrequested implementation.
+Default reasoning: `medium`. Use subagents for bounded alternatives, critique, or parallel concepts when the active host exposes safe delegation. Use `high` for multi-screen flows, accessibility-sensitive experiences, design-system impact, pricing/positioning, architecture boundaries, or major scope decisions. Subagents should produce options or critique, not unrequested implementation.
 
 ## Hard rules
 - Shape is not build: do not edit production code or runtime behavior.

package/skills/keystone/modules/helpers/subagents.md

@@ -1,134 +0,0 @@
-# Keystone Subagents and Reasoning Helper
-
-## Purpose
-Teach Keystone when subagents can be used, which hosts support them, and what reasoning level each Keystone module should prefer.
-
-This helper is advisory. Host capability wins over Keystone preference. If the current harness cannot set reasoning per subagent, encode the desired reasoning in the subagent prompt or do the work inline.
-
-## Delegation rule
-Use subagents only when the task has a clear boundary and a useful handoff artifact.
-
-Good delegation targets:
-- read-only reconnaissance
-- independent implementation slices
-- focused debugging/root-cause analysis
-- read-only review
-- documentation/copy drafting
-
-Do not delegate when:
-- the task needs tight conversational clarification
-- one agent must continuously coordinate shared mutable state
-- the host cannot preserve enough context for safe handoff
-- the subagent would need secrets or permissions the parent should not share
-- delegation setup, context packaging, merge/review effort, or verification overhead is likely greater than doing the task inline
-
-## Delegation cost heuristic
-
-Before spawning a subagent, compare expected benefit with coordination cost.
-
-Delegate when at least one is true:
-- the subtask can run in parallel with other independent work
-- the subtask requires a different role, perspective, or reasoning depth
-- the repository/source search is large enough that a scout can save parent context
-- independent review or root-cause analysis materially reduces release risk
-
-Do not delegate when most of these are true:
-- the task can be done inline in a few minutes
-- the parent would need to explain more context than the subagent can save
-- outputs will require complex merge arbitration
-- the work touches the same mutable files as another active agent without isolation
-- verification cannot be independently stated in the prompt
-
-If uncertain, prefer one narrow read-only scout/reviewer over multiple workers.
-
-## Host capability matrix
-
-| Harness | Subagents | Per-subagent reasoning/effort | How to configure | Keystone policy |
-|---|---:|---:|---|---|
-| Pi coding agent with `pi-subagents` | yes | yes | `.pi/agents/<name>.md` frontmatter `model`, `thinking`, `profile`, or `Agent({ subagent_type, thinking, model, profile })` | Use native roles; prefer role defaults unless Keystone needs a one-off override. |
-| Claude Code | yes | partial | `.claude/agents/<name>.md` supports subagent config and `model`; built-in Explore accepts quick/medium/very-thorough style detail, but custom agents do not expose a general reasoning knob | Use `model` plus explicit prompt instructions; use built-in Explore detail when applicable. |
-| Codex CLI/app | unclear/host-dependent | partial/global | known global config includes `model_reasoning_effort`; no stable per-subagent effort schema confirmed | Treat Keystone reasoning as advisory text unless the active Codex host exposes a per-agent effort control. |
-| T3 Code | not confirmed | not confirmed | no confirmed public/local schema | Treat as unsupported; run inline or through the underlying Claude/Codex/OpenCode provider if available. |
-| OpenCode | yes | partial/provider-dependent | agent config supports `mode: "subagent"`, `model`, and provider-specific `variant`; no universal reasoning field is confirmed | Use subagent mode; map Keystone reasoning to model/variant only where the provider exposes effort variants, otherwise write the desired reasoning in the prompt. |
-| GitHub Copilot / VS Code | yes | partial | `.github/agents/*.agent.md` supports `model`, `agents`, `user-invocable`, `disable-model-invocation`; no general reasoning knob found | Use custom agents and model choice; put reasoning expectation in the agent prompt. |
-
-## Canonical reasoning scale
-
-Keystone uses this host-neutral scale:
-
-| Level | Use for |
-|---|---|
-| `off` | deterministic formatting, mechanical edits, no reasoning needed |
-| `minimal` | tiny lookups, simple classification, trivial copy changes |
-| `low` | ordinary reading, straightforward writing, small scoped tasks |
-| `medium` | normal implementation, UI decisions, moderate research |
-| `high` | architecture, debugging, review, planning, ambiguous tradeoffs |
-| `xhigh` | hard root-cause analysis, security-sensitive review, major design decisions |
-
-If a host uses another vocabulary, map to the nearest equivalent. If no setting exists, write the desired level into the prompt, for example: "Use high reasoning; explore alternatives before deciding."
-
-## Keystone module defaults
-
-| Keystone file | Preferred role | Default reasoning | Escalate when |
-|---|---|---:|---|
-| `modules/router.md` | none or lightweight classifier | `low` | request is ambiguous across several irreversible actions |
-| `modules/research.md` | scout/read-only explorer or oracle | `medium` | repository is large, source relationships are unclear, or claims affect architecture, market, safety, or release decisions (`high`) |
-| `modules/shape.md` | writer, UI/design reviewer, or oracle | `medium` | visual systems, accessibility, complex positioning, architecture, product viability, or irreversible scope decisions are involved (`high`/`xhigh`) |
-| `modules/breakdown.md` | planner plus reviewer | `high` | plan spans multiple independent agents or risky sequencing (`xhigh`) |
-| `modules/build.md` | worker | `medium` | concurrency, migrations, broad refactors, or unfamiliar stack (`high`) |
-| `modules/debug.md` | oracle/root-cause investigator | `high` | intermittent, cross-system, performance, or data-loss failures (`xhigh`) |
-| `modules/review.md` | reviewer/read-only | `high` | security, release, data migration, or public API review (`xhigh`) |
-| `modules/ship.md` | ship coordinator | `medium` | release has unresolved risk or multi-host packaging (`high`) |
-| `modules/health.md` | scout plus reviewer | `medium` | broad repository/tooling drift or release readiness audit (`high`) |
-| `modules/gates/*.md` | none | `low` | evidence is contradictory or safety-critical (`medium`) |
-
-## Pi role mapping
-
-When Pi subagents are available, use the narrowest role and usually keep its configured defaults:
-
-| Need | Pi role | Typical thinking |
-|---|---|---:|
-| codebase exploration | `scout` | `low` |
-| implementation | `worker` | `medium` |
-| code/spec review | `reviewer` | `high` |
-| architecture/root-cause second opinion | `oracle` | `high` or `xhigh` |
-| docs/copy | `writer` | `low` |
-
-Only override `thinking` when the module table says to escalate or de-escalate.
-
-## Safe parallel work pattern
-
-1. `breakdown` identifies independent tasks and their verification commands.
-2. `build` passes `gates/isolation.md` before any mutation.
-3. If the host supports isolated worktrees, each worker gets a separate worktree or host-isolated workspace.
-4. Each worker reports files changed, tests run, and concerns.
-5. Parent reconciles outputs before further mutation: accept, reject, or send back with a narrower prompt.
-6. `review` runs as read-only, preferably in a separate reviewer subagent.
-7. `ship` finalizes only after proof and review gates pass.
-
-## Prompt contract for delegated work
-
-Every subagent prompt should include:
-
-- exact task scope
-- files or areas allowed to change/read
-- protected files
-- expected output artifact or report
-- reasoning level requested if the host cannot enforce it
-- verification command expected
-- instruction not to broaden scope
-- timeout or stopping condition when the host supports it
-
-For read-only subagents, explicitly say: "Do not edit files." For review subagents, explicitly say: "Return findings only; do not fix."
-
-## Subagent result handling
-
-Treat subagent output as evidence, not truth. The parent remains responsible for verification and final routing.
-
-- Timeout or no response: mark the subtask incomplete, preserve any partial logs, and either finish inline or re-delegate with a smaller scope if the remaining work is still worth the overhead.
-- Bad output or scope creep: reject the result, record why, and re-delegate only with a tighter prompt, protected-file list, and explicit expected artifact. Otherwise do it inline.
-- Partial completion: accept only independently verified pieces; carry unfinished work in the handoff packet with files touched, tests run, and remaining risks.
-- Conflicting outputs: compare evidence and reproduction/proof commands first. If both are plausible and risk is material, ask an oracle/reviewer for read-only arbitration or route to `debug`; do not merge contradictory fixes blindly.
-- Failed verification: route through the appropriate Keystone module (`debug` for unexplained failures, `build` for contained fixes, `review` for risk assessment) and rerun the original proof before continuing.
-
-Re-delegate only when the next prompt can be narrower than the failed one, the expected artifact is concrete, and the benefit still exceeds coordination cost. Otherwise continue inline and record the reason.