@static-var/keystone 0.1.0

package/README.md

@@ -0,0 +1,253 @@
+# Keystone
+
+> One public `/keystone` doorway for disciplined AI workflows.
+
+Keystone is a hybrid workflow/skill system for coding agents. It keeps the public surface small, routes each request to one internal module, and uses gates to prevent the common failure modes: editing too early, planning without proof, reviewing while mutating, or shipping unverified work.
+
+Keystone borrows the best parts of Waza-style routing/review/release discipline and Superpowers-style planning, TDD, debugging, and verification habits.
+
+## What Keystone gives you
+
+- **One public entrypoint:** `/keystone`
+- **Private internal modules:** router, research, shape, breakdown, build, debug, review, ship, and health
+- **A renamed planner:** `breakdown`, not `plan`, to avoid `/plan` collisions
+- **Safety gates:** isolation, red, proof, review, and ship
+- **Subagent guidance:** host capability matrix plus recommended reasoning level per module
+- **Package tooling:** generated platform manifests, allowlisted archive builds, validators, and routing tests
+- **Multi-host packaging:** Pi extension + skill package metadata plus Claude/Codex/agents plugin manifests
+
+## Quick start
+
+```bash
+# Validate source, package, routing fixtures, and Python scripts
+make test
+
+# Regenerate host metadata
+make regenerate
+
+# Build the distributable archive
+make package
+```
+
+The package archive is written to:
+
+```text
+dist/keystone.zip
+```
+
+`dist/` is generated and ignored by git.
+
+Install in Pi from npm after release:
+
+```bash
+pi install npm:@static-var/keystone
+```
+
+Or install directly from GitHub:
+
+```bash
+pi install git:github.com/static-var/Keystone
+```
+
+Then invoke:
+
+```text
+/keystone <task>
+```
+
+Pi package gallery listing: once `@static-var/keystone` is published to npm with the `pi-package` keyword, it appears on `https://pi.dev/packages`.
+
+## How it works in one picture
+
+```text
+User request
+   │
+   ▼
+/keystone public skill
+   │
+   ▼
+Router chooses exactly one primary module
+   │
+   ├─ router / research / shape / breakdown
+   └─ build / debug / review / ship / health
+   │
+   ▼
+Module contract decides what is allowed
+   │
+   ▼
+Gate checks when required
+   │
+   ├─ isolation: safe before mutation
+   ├─ red: failing check before implementation when practical
+   ├─ proof: evidence before success claims
+   ├─ review: no blocking review findings
+   └─ ship: verified, reviewed, ready to hand off
+```
+
+## Core rule
+
+Keystone exposes **one public skill**:
+
+```text
+skills/keystone/SKILL.md
+```
+
+Everything else under `skills/keystone/modules/` is internal. Internal modules are not public slash commands.
+
+## Routing map
+
+| User wants to... | Keystone routes to... |
+|---|---|
+| classify an ambiguous request | `router` |
+| inspect, summarize, research, or compare sources | `research` |
+| draft prose, shape product direction, design UI, or make architecture/scope tradeoffs | `shape` |
+| turn approved direction into tasks | `breakdown` |
+| edit files or implement work | `build` |
+| diagnose bugs or failures | `debug` |
+| review work without changing it | `review` |
+| finalize completed work | `ship` |
+| assess project/tooling health | `health` |
+
+## Repository-only maintainer notes
+
+Keystone maintainer guidance can live in the repository without shipping as product. Current maintainer-only notes are in:
+
+```text
+maintainers/skill-engineering.md
+```
+
+This file is not included in `dist/keystone.zip` and is not part of `/keystone` routing.
+
+## Repository layout
+
+```text
+.
+├── skills/keystone/              # canonical skill source
+│   ├── SKILL.md                  # public /keystone entrypoint
+│   └── modules/                  # internal modules, helpers, and gates
+├── scripts/                      # metadata, validation, packaging
+├── tests/routing/cases.yaml      # routing fixture cases
+├── tests/test_routing.py         # stdlib routing test runner
+├── 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
+├── packaging.allowlist           # default-deny package contents
+├── Makefile                      # test/package/regenerate targets
+└── HOW_IT_WORKS.md               # human-readable architecture guide
+```
+
+## Subagent and reasoning support
+
+Keystone documents host-specific subagent support in:
+
+```text
+skills/keystone/modules/helpers/subagents.md
+```
+
+Current summary:
+
+| 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 |
+
+Each Keystone module includes a `Subagents and reasoning` section with its default reasoning level.
+
+## Platform support
+
+Keystone currently ships as:
+
+- **Pi extension + skill package** via `package.json`:
+  ```json
+  {
+    "pi": {
+      "extensions": ["./.pi/extensions/keystone.ts"],
+      "skills": ["./skills"]
+    }
+  }
+  ```
+- **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/`
+
+## Release automation
+
+Pi package discovery is npm-based. The package name is `@static-var/keystone`; the unscoped `keystone` name is already taken on npm.
+
+CI/CD:
+
+- `.github/workflows/ci.yml` runs on PRs and `main`: `npm ci`, Pi extension typecheck, `make test`, npm pack dry-run, and uploads `dist/keystone.zip`.
+- `.github/workflows/release.yml` runs on `v*.*.*` tags or manual dispatch: verifies the tag matches `package.json` version, validates, publishes to npm through Trusted Publishing/OIDC with provenance, and creates a GitHub Release with both `dist/keystone.zip` and the npm tarball.
+
+Trusted Publishing setup on npm:
+
+1. Confirm you own the npm scope in `package.json`. Keystone currently publishes as `@static-var/keystone`; if your npm username/org is different, rename the package before publishing.
+2. Bootstrap the package once, because npm only shows the package access / Trusted Publisher UI after the package exists:
+   ```bash
+   npm login
+   npm run typecheck
+   make test
+   npm publish --access public --provenance=false
+   ```
+   If npm requires 2FA, append `--otp <code>`. Local bootstrap disables provenance because provenance is provided by future OIDC releases.
+3. Open `https://www.npmjs.com/package/@static-var/keystone/access`.
+4. In **Trusted Publisher**, choose **GitHub Actions**.
+5. Configure:
+   - Organization or user: `static-var`
+   - Repository: `Keystone`
+   - Workflow filename: `release.yml`
+   - Environment name: leave blank unless you add a GitHub deployment environment
+   - Allowed actions: `npm publish`
+6. Save. Future releases use OIDC; no `NPM_TOKEN` secret is needed.
+
+Release:
+
+```bash
+npm version patch --no-git-tag-version  # or minor/major; edit changelog if added later
+make test
+VERSION=$(node -p "require('./package.json').version")
+git add package.json package-lock.json
+git commit -m "chore: release v${VERSION}"
+git tag "v${VERSION}"
+git push origin main --tags
+```
+
+## Maintainer commands
+
+```bash
+make regenerate      # rebuild generated plugin/marketplace metadata
+make validate        # build package, validate source, validate archive
+make routing         # run routing fixture tests
+make package         # write dist/keystone.zip from packaging.allowlist
+make test            # run the full local check suite
+npm run typecheck    # typecheck the Pi extension
+npm run pack:dry-run # preview npm package contents
+```
+
+## Guardrails
+
+- Do not add public slash commands for internal modules.
+- Do not rename `breakdown` to `plan`.
+- Do not let `build` edit before the isolation gate.
+- Do not let `review` fix, commit, or ship.
+- Do not let `ship` start new implementation.
+- Do not hand-edit generated manifests; update source and run `make regenerate`.
+- Do not package ignored local artifacts such as `index.html`, `styles.css`, `plans/`, `docs/`, `dist/`, or pycache files.
+
+## Read next
+
+For the full mental model, routing lifecycle, packaging flow, and maintainer workflow, read:
+
+```text
+HOW_IT_WORKS.md
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@static-var/keystone",
+  "version": "0.1.0",
+  "description": "Keystone: one-router AI engineering workflow extension and skill system for Pi.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/static-var/Keystone.git"
+  },
+  "bugs": {
+    "url": "https://github.com/static-var/Keystone/issues"
+  },
+  "homepage": "https://github.com/static-var/Keystone#readme",
+  "keywords": [
+    "pi-package",
+    "agent-skills",
+    "keystone",
+    "claude-code",
+    "codex",
+    "opencode",
+    "copilot",
+    "pi-coding-agent",
+    "pi-extension",
+    "workflow",
+    "skills",
+    "agent-workflows"
+  ],
+  "files": [
+    "README.md",
+    "HOW_IT_WORKS.md",
+    "package.json",
+    "packaging.allowlist",
+    "Makefile",
+    "scripts/build-metadata.py",
+    "scripts/validate-keystone.py",
+    "scripts/validate-package.py",
+    "scripts/package-keystone.sh",
+    "skills/keystone/SKILL.md",
+    "skills/keystone/modules/router.md",
+    "skills/keystone/modules/research.md",
+    "skills/keystone/modules/shape.md",
+    "skills/keystone/modules/breakdown.md",
+    "skills/keystone/modules/build.md",
+    "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",
+    "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",
+    ".pi/extensions/keystone.ts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "pi": {
+    "extensions": [
+      "./.pi/extensions/keystone.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.2",
+    "@types/node": "26.0.1",
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "regenerate": "python3 scripts/build-metadata.py",
+    "validate": "make validate",
+    "package": "scripts/package-keystone.sh",
+    "test": "make test",
+    "typecheck": "tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck .pi/extensions/keystone.ts",
+    "pack:dry-run": "npm pack --dry-run"
+  }
+}

package/packaging.allowlist

@@ -0,0 +1,32 @@
+# Default-deny shipping allowlist for Keystone packaging.
+# Entries are newline-delimited paths relative to the repository root.
+README.md
+HOW_IT_WORKS.md
+package.json
+packaging.allowlist
+Makefile
+scripts/build-metadata.py
+scripts/validate-keystone.py
+scripts/validate-package.py
+scripts/package-keystone.sh
+skills/keystone/SKILL.md
+skills/keystone/modules/router.md
+skills/keystone/modules/research.md
+skills/keystone/modules/shape.md
+skills/keystone/modules/breakdown.md
+skills/keystone/modules/build.md
+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
+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
+.pi/extensions/keystone.ts

package/scripts/build-metadata.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Generate Keystone platform metadata from the canonical skill source."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SKILL = ROOT / "skills" / "keystone" / "SKILL.md"
+PACKAGE = ROOT / "package.json"
+NAME = "keystone"
+
+
+def read_package() -> dict:
+    if PACKAGE.exists():
+        return json.loads(PACKAGE.read_text())
+    return {}
+
+
+def parse_frontmatter(text: str) -> dict:
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+    data: dict[str, object] = {}
+    current_key = None
+    for raw in text[4:end].splitlines():
+        line = raw.rstrip()
+        if not line or line.lstrip().startswith("#"):
+            continue
+        if line.startswith("  - ") and current_key:
+            data.setdefault(current_key, []).append(line[4:].strip().strip('"\''))
+            continue
+        if ":" in line:
+            key, value = line.split(":", 1)
+            current_key = key.strip()
+            value = value.strip()
+            if value == "":
+                data[current_key] = []
+            else:
+                data[current_key] = value.strip('"\'')
+    return data
+
+
+def skill_summary(text: str) -> str:
+    fm = parse_frontmatter(text)
+    for key in ("description", "summary"):
+        if isinstance(fm.get(key), str) and fm[key]:
+            return str(fm[key])
+    match = re.search(r"^#\s+(.+)$", text, re.M)
+    if match:
+        return match.group(1).strip()
+    return "Keystone skill."
+
+
+def write_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+
+
+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 = {
+        "name": NAME,
+        "version": version,
+        "description": description,
+        "license": license_name,
+        "skills": [{"name": NAME, "path": "../skills/keystone/SKILL.md"}],
+    }
+    marketplace = {
+        "name": NAME,
+        "displayName": "Keystone",
+        "version": version,
+        "description": description,
+        "license": license_name,
+        "keywords": keywords,
+        "skills": [NAME],
+    }
+    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)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/package-keystone.sh

@@ -0,0 +1,59 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+ALLOWLIST="$ROOT/packaging.allowlist"
+DIST="$ROOT/dist"
+ARCHIVE="$DIST/keystone.zip"
+TMP_LIST="$DIST/keystone.files"
+
+cd "$ROOT"
+
+if [ ! -f "$ALLOWLIST" ]; then
+  echo "package-keystone: missing packaging.allowlist" >&2
+  exit 1
+fi
+
+python3 scripts/build-metadata.py
+python3 scripts/validate-keystone.py
+
+mkdir -p "$DIST"
+: > "$TMP_LIST"
+
+while IFS= read -r path || [ -n "$path" ]; do
+  case "$path" in
+    ''|'#'*) continue ;;
+  esac
+  case "$path" in
+    docs|docs/*|plans|plans/*|maintainers|maintainers/*|index.html|styles.css|.git|.git/*|dist|dist/*|skill-engineering.md|*/skill-engineering.md|*.plan.md|*-plan.md|*.design.md|*-design.md|*/__pycache__/*|*.pyc|.DS_Store)
+      echo "package-keystone: forbidden allowlist entry: $path" >&2
+      exit 1
+      ;;
+  esac
+  if [ ! -e "$path" ]; then
+    echo "package-keystone: allowlisted path missing: $path" >&2
+    exit 1
+  fi
+  if [ -d "$path" ]; then
+    find "$path" -type f \
+      ! -name '.DS_Store' \
+      ! -name '*.pyc' \
+      ! -path '*/__pycache__/*' \
+      ! -path 'docs/*' \
+      ! -path 'plans/*' \
+      ! -path 'maintainers/*' \
+      ! -name 'skill-engineering.md' \
+      ! -name '*.plan.md' \
+      ! -name '*-plan.md' \
+      ! -name '*.design.md' \
+      ! -name '*-design.md' >> "$TMP_LIST"
+  else
+    printf '%s\n' "$path" >> "$TMP_LIST"
+  fi
+done < "$ALLOWLIST"
+
+sort -u "$TMP_LIST" -o "$TMP_LIST"
+rm -f "$ARCHIVE"
+zip -q -X "$ARCHIVE" -@ < "$TMP_LIST"
+python3 scripts/validate-package.py "$ARCHIVE"
+echo "package-keystone: wrote $ARCHIVE"