bad-agent-kit 0.0.0-stage → 0.1.0

package/GLOSSARY.md

@@ -0,0 +1,11 @@
+# BAK Glossary
+
+- **BAK** — Batman Agents Kit. The serious public brand: router + marketplace + orchestrator.
+- **bad-agent-kit** — the persona. The joke IS the rule: don't ship the bad agent kit.
+- **bak** — the router skill itself (`skills/bak/SKILL.md`). Formerly `chief`.
+- **Catalog of record** — the single source of truth for what's listed; README table today, `catalog/catalog.json` + generator past ~40 entries. Never hand-edit both.
+- **Compose, never own** — BAK pins and documents upstream skills; it does not fork or vendor them.
+- **Playbook** — a documented chain of skills for one class of real work (e.g. triage → to-spec → to-tickets → tdd → code-review → handoff).
+- **Routing matrix** — `skills/bak/references/routing-matrix.md`: trigger → smallest complete route.
+- **One channel per agent** — never install the same skill via two channels on one agent (silent hash drift).
+- **Privacy-scrub gate** — CI that fails on `$HOME`-literal leaks and personal-infra inventory before publish.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aniqaqill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# 🦇 BAK — bad-agent-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **BAK** (Batman Agents Kit) — a curated skills marketplace + workflow
+> orchestrator for coding agents. **Compose, never own.**
+>
+> *bad-agent-kit* is the persona: the punchline encodes the rules — don't ship
+> the bad agent kit. Never mutate on inspect. Never publish without authority.
+> Route every task through the smallest complete set of skills.
+
+[![npm version](https://img.shields.io/npm/v/bad-agent-kit?color=cb3837&logo=npm)](https://www.npmjs.com/package/bad-agent-kit)
+[![pi.dev gallery](https://img.shields.io/badge/pi.dev-gallery-6f6bff)](https://pi.dev/packages)
+[![skills.sh](https://img.shields.io/badge/skills.sh-install-6f42c1)](https://skills.sh)
+[![CI](https://img.shields.io/github/actions/workflow/status/aniqaqill/bad-agent-kit/ci.yml?label=CI)](https://github.com/aniqaqill/bad-agent-kit/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+<sub>Tags: `golang` · `go` · `skills` · `marketplace` · `agent-skills` · `claude-code` · `codex` · `cursor` · `pi` · `mattpocock` · `pstack-inspired` · `workflow-orchestrator` · `tdd` · `code-review`</sub>
+
+## Table of contents
+
+- [What is this?](#what-is-this)
+- [Install](#install)
+- [The catalog](#the-catalog)
+- [The BAK workflow](#the-bak-workflow)
+- [Go-first skills](#go-first-skills)
+- [Architecture](#architecture)
+- [Repo layout](#repo-layout)
+- [Contributing](#contributing)
+- [Privacy & security](#privacy--security)
+- [Acknowledgments](#acknowledgments)
+- [License](#license)
+
+## What is this?
+
+Two things, one repo:
+
+1. **Marketplace** — a curated catalog of battle-tested agent skills. The
+   catalog below is the catalog of record: every entry pins a source, an
+   install command, and its position in the BAK workflow. CI keeps the catalog
+   in lockstep with the pinned manifest.
+2. **Orchestrator** — the BAK router skill (`bak`) plus documented playbooks
+   encoding how the skills chain together in real work: triage → spec →
+   tickets → TDD → review → handoff, and a Go-first lane (plan → tdd →
+   review) with sensor gates at every phase exit.
+
+BAK never forks upstream. Skills stay owned by their authors; BAK pins them,
+composes them, and documents the chains.
+
+## Install
+
+```bash
+# pi
+pi install npm:bad-agent-kit
+
+# Claude Code / Codex / Cursor via skills.sh
+npx skills@latest add aniqaqill/bad-agent-kit -g --skill bak --agent cursor -y
+npx skills@latest add aniqaqill/bad-agent-kit -g --skill go-plan --agent cursor -y
+npx skills@latest add aniqaqill/bad-agent-kit -g --skill go-tdd --agent cursor -y
+npx skills@latest add aniqaqill/bad-agent-kit -g --skill go-review --agent cursor -y
+```
+
+> ⚠️ **Pick ONE channel per agent.** Installing through two channels on the
+> same agent duplicates every skill and drifts hashes silently.
+
+Bootstrap the full BAK stack for one agent (router + mattpocock suite +
+discovery + browser):
+
+```bash
+bash scripts/bootstrap.sh cursor   # cursor | claude | codex
+```
+
+## The catalog
+
+| Skill | Source | Install | Workflow position |
+|---|---|---|---|
+| `bak` | this repo | `pi install npm:bad-agent-kit` | router — start of every task |
+| `go-plan` | this repo | `pi install npm:bad-agent-kit` | Go plan phase — grill then spec |
+| `go-tdd` | this repo | `pi install npm:bad-agent-kit` | Go implement — sensor gates + e2e tests |
+| `go-review` | this repo | `pi install npm:bad-agent-kit` | Go review — standards + spec lenses |
+| `chief` (legacy) | this repo | — | superseded by `bak`; kept for backlink resolution |
+| `find-skills` | [vercel-labs/skills](https://github.com/vercel-labs/skills) | `npx skills@latest add vercel-labs/skills -g --skill find-skills --agent cursor -y` | discover new capabilities |
+| `tdd` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill tdd --agent cursor -y` | build/test-first |
+| `triage` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill triage --agent cursor -y` | issue intake |
+| `to-spec` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill to-spec --agent cursor -y` | synthesize plan |
+| `to-tickets` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill to-tickets --agent cursor -y` | split into tickets |
+| `wayfinder` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill wayfinder --agent cursor -y` | large/uncertain efforts |
+| `request-refactor-plan` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill request-refactor-plan --agent cursor -y` | planned refactors |
+| `code-review` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill code-review --agent cursor -y` | review before merge |
+| `setup-matt-pocock-skills` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill setup-matt-pocock-skills --agent cursor -y` | tracker setup |
+| `grilling` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill grilling --agent cursor -y` | stress-test ideas |
+| `handoff` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill handoff --agent cursor -y` | hand over work |
+| `research` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill research --agent cursor -y` | primary-source research |
+| `codebase-design` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill codebase-design --agent cursor -y` | deep-module design |
+| `diagnosing-bugs` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill diagnosing-bugs --agent cursor -y` | diagnosis loop |
+| `domain-modeling` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill domain-modeling --agent cursor -y` | GLOSSARY/ADRs |
+| `improve-codebase-architecture` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill improve-codebase-architecture --agent cursor -y` | architecture passes |
+| `migrate-to-shoehorn` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill migrate-to-shoehorn --agent cursor -y` | test type safety |
+| `prototype` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill prototype --agent cursor -y` | throwaway design probes |
+| `resolving-merge-conflicts` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill resolving-merge-conflicts --agent cursor -y` | merge/rebase conflicts |
+| `scaffold-exercises` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill scaffold-exercises --agent cursor -y` | course scaffolding |
+| `grill-with-docs` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill grill-with-docs --agent cursor -y` | grill with docs |
+| `implement` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill implement --agent cursor -y` | direct implementation |
+| `grill-me` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill grill-me --agent cursor -y` | get grilled |
+| `qa` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill qa --agent cursor -y` | issue filing |
+| `teach` | [mattpocock/skills](https://github.com/mattpocock/skills) | `npx skills@latest add mattpocock/skills -g --skill teach --agent cursor -y` | teach a topic |
+| `chrome-devtools` | [chromedevtools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | `npx skills@latest add chromedevtools/chrome-devtools-mcp -g --agent cursor -y` | browser automation |
+
+Full pinned manifest: [`manifest/upstream-sources.txt`](manifest/upstream-sources.txt).
+Playbooks: [`docs/playbooks/`](docs/playbooks/).
+
+## The BAK workflow
+
+```mermaid
+flowchart LR
+  T[triage] --> S[to-spec] --> K[to-tickets] --> D[tdd] --> R[code-review] --> H[handoff]
+  W[wayfinder] -.->|large/uncertain| S
+  P[request-refactor-plan] -.->|refactor| K
+  bak([bak router]) -. routes .-> T
+  bak -. routes .-> D
+  bak -. routes .-> W
+  subgraph GO[Go lane]
+    GP[go-plan] --> GT[go-tdd] --> GR[go-review]
+  end
+  bak -. "go.mod / race|goroutine|channel|mutex" .-> GP
+```
+
+## Go-first skills
+
+Go work gets first-principles treatment: mattpocock's conversation-first
+phases + pstack's evidence discipline + Go's real sensors.
+
+- **`go-plan`** — grills the design with the Go frontier taxonomy (goroutine
+  ownership, channel-vs-mutex, leak prevention, error strategy, test seams)
+  and synthesizes the spec. Human gate ON for concurrency decisions.
+- **`go-tdd`** — implements test-first at pre-agreed seams. Fail-fast sensor
+  chain at every phase exit: `gofmt -l` → `go vet` → `golangci-lint` →
+  `govulncheck` → `go test -race` + `goleak`. Mandatory end-to-end
+  expected-outcome tests.
+- **`go-review`** — two-axis review with lenses: perf (goperf.dev, hot paths
+  only), race (mandatory findings class), security (go.dev best practices),
+  SOLID (Cheney's five words).
+
+All rules live in one canonical contract —
+[`skills/go-tdd/references/GO_RULES.md`](skills/go-tdd/references/GO_RULES.md):
+24 sensor-tagged rules in HARD/REVIEW/EVIDENCE tiers. A finding survives only
+when a run proves it.
+
+```mermaid
+flowchart LR
+  GP[go-plan] -->|grilling -> to-spec| P["every shared datum named + owned"]
+  P --> G1["gate: go list / go build / go vet"]
+  G1 --> GT[go-tdd]
+  GT -->|tdd at pre-agreed seams| I[code + tests]
+  I --> G2["gate: gofmt -> vet -> golangci-lint -> govulncheck -> -race + goleak"]
+  G2 --> GR[go-review]
+  GR -->|two-axis + lenses| M[merge]
+```
+
+## Architecture
+
+```mermaid
+flowchart TD
+  subgraph UP["Upstream — source of truth"]
+    MP["mattpocock/skills 36+"]
+    VL["vercel-labs/skills"]
+    CD["chrome-devtools-mcp"]
+  end
+  subgraph REPO["bad-agent-kit — compose, never own"]
+    BAK["bak router<br/>(thin, routes only)"]
+    GO["go-plan / go-tdd / go-review<br/>(Go-first lane)"]
+    CAT["catalog table<br/>lockstep with manifest"]
+    PB["playbooks"]
+    MANIFEST["manifest/upstream-sources.txt<br/>pinned, never vendored"]
+  end
+  UP -->|pinned manifest| MANIFEST
+  MANIFEST --> CAT
+  BAK -->|routes into| UP
+  BAK --> GO
+  GO -->|reads| RULES["GO_RULES.md"]
+  CAT --> PB
+  subgraph CH["Distribution"]
+    NPM["npm → pi.dev gallery"]
+    NPX["npx skills add"]
+    CC["claude/codex plugin marketplace"]
+  end
+  REPO --> NPM
+  REPO --> NPX
+  REPO --> CC
+```
+
+## Repo layout
+
+```text
+skills/                BAK-owned skills (bak, go-plan, go-tdd, go-review)
+manifest/              pinned upstream sources — never vendored
+docs/playbooks/        how the skills chain in real work
+docs/design-evidence.md  decision provenance ($HOME-scrubbed)
+scripts/               bootstrap.sh / update.sh / scrub.sh / validate-catalog.js
+.github/               CI: privacy-scrub gate + catalog lockstep + link check
+```
+
+## Contributing
+
+Catalog edits follow the lockstep rule (manifest ↔ README, CI-enforced).
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Privacy & security
+
+A CI privacy-scrub gate fails the build on personal literals (home paths,
+vault names, private endpoints). This repo ships only the portable core;
+personal overlays stay local. See
+[docs/design-evidence.md](docs/design-evidence.md).
+
+## Acknowledgments
+
+- [Matt Pocock's skills](https://github.com/mattpocock/skills) — the workflow
+  stack BAK composes
+- [cursor/plugins — pstack](https://github.com/cursor/plugins/tree/main/pstack) —
+  the evidence discipline ("a finding survives only when a run proves it")
+- [vercel-labs/skills](https://github.com/vercel-labs/skills) — find-skills
+- [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) —
+  browser automation
+- [Effective Go](https://go.dev/doc/effective_go),
+  [Cheney's SOLID-Go](https://dave.cheney.net/2016/08/20/solid-go-design),
+  [goperf.dev](https://goperf.dev/), and
+  [go.dev security best practices](https://go.dev/doc/security/best-practices) —
+  the Go rulebook behind the go-* skills
+
+## License
+
+MIT — skills listed here remain property of their respective authors.

package/docs/design-evidence.md

@@ -0,0 +1,35 @@
+# Design Evidence — BAK (bad-agent-kit)
+
+Provenance for the decisions in this repo. Portable and `$HOME`-scrubbed;
+personal overlays stay local.
+
+## Why BAK exists
+
+The original `chief` router skill lived only on one machine. It routed every
+workspace task through the smallest complete set of installed skills. It
+worked — but it was unmanaged (absent from `.skill-lock.json`), its reference
+snapshot files rotted silently, and nothing was shareable.
+
+BAK is the same router, split in two:
+- **Portable core** (this repo): the `bak` skill, routing matrix, shared
+  contracts (documentation routing, GitHub publishing), and playbooks.
+- **Personal overlay** (local only): workspace paths, hook scripts, vault
+  locations, and the capability inventory.
+
+## Decisions
+
+1. **Compose, never own.** Upstream skills (mattpocock, vercel-labs,
+   chrome-devtools) are pinned, never vendored. BAK owns only the router and
+   the playbooks.
+2. **Two-level brand.** BAK = serious kit; bad-agent-kit = persona whose
+   punchline encodes the rules ("never mutate on inspect, never publish
+   without authority").
+3. **Catalog of record.** README table until ~40 entries; then
+   `catalog/catalog.json` + generator. CI enforces lockstep with the manifest
+   so the catalog can't drift.
+4. **Privacy-scrub gate.** CI fails on personal literals — an enforced rule,
+   not a manual risk.
+5. **One channel per agent.** Two install channels on one agent duplicates
+   skills and drifts hashes silently.
+6. **Deferred product tax.** changesets/CHANGELOG/release CI wait until a
+   second human installs the kit.

package/docs/playbooks/diagnosis.md

@@ -0,0 +1,14 @@
+# Playbook: diagnosis
+
+For "diagnose this" / "it's broken" / "it's slow":
+
+1. **diagnosing-bugs** — the diagnosis loop: reproduce, bisect, root-cause,
+   smallest fix.
+2. **grilling** (or `grill-with-docs`) — stress-test the proposed fix against
+   the docs before implementing.
+3. **prototype** — when the fix's shape is uncertain, throwaway prototype to
+   answer the design question.
+4. **code-review** — after the fix, review standards + spec axes.
+
+Sensors: the failing sensor gets re-run after every fix; flaky/always-green
+sensors are weak evidence.

package/docs/playbooks/feature-work.md

@@ -0,0 +1,23 @@
+# Playbook: feature work (the BAK default chain)
+
+The chain used for real feature work. Each step is an installed skill; `bak`
+routes into the right entry point.
+
+```mermaid
+flowchart LR
+  A[triage] --> B[to-spec] --> C[to-tickets] --> D[tdd] --> E[code-review] --> F[handoff]
+  G[wayfinder] -. large or uncertain .-> B
+  H[request-refactor-plan] -. refactor .-> C
+```
+
+1. **triage** — intake the issue/request; confirm labels, tracker state, and
+   confirmation steps before any Matt Pocock workflow.
+2. **to-spec** — synthesize the plan; produce the spec document.
+3. **to-tickets** — split the spec into executable tracer-bullet tickets.
+4. **tdd** — implement each ticket test-first (red → green → refactor).
+5. **code-review** — review the branch along standards + spec axes.
+6. **handoff** — close the loop: summary, remaining risks, learning captured.
+
+**Sensors throughout**: prehook.sh before material changes, posthook.sh after,
+prepush.sh only immediately before a user-authorized push. Fast deterministic
+checks first, broader checks proportional to risk.

package/docs/playbooks/go-work.md

@@ -0,0 +1,28 @@
+# Playbook: Go work (the go-* chain)
+
+Go module work routes through the go-* family; bak stays the orchestrator.
+
+```mermaid
+flowchart LR
+  GP[go-plan] -->|grilling -> to-spec| P["every shared datum named + owned"]
+  P --> G1["gate: go list / go build / go vet"]
+  G1 --> GT[go-tdd]
+  GT -->|tdd at pre-agreed seams| I[code + tests]
+  I --> G2["gate: gofmt -> vet -> golangci-lint -> govulncheck -> -race + goleak"]
+  G2 --> GR[go-review]
+  GR -->|two-axis + lenses| M[merge]
+```
+
+1. **go-plan** — grill with the five frontier questions (ownership,
+   channel-vs-mutex, leaks, error strategy, seam); synthesize the spec. Human
+   gate ON for concurrency decisions. Exit: plan artifact names every shared
+   datum and its owner; pre-flight `go list / go build / go vet`.
+2. **go-tdd** — implement at pre-agreed seams via tdd; fail-fast sensor chain
+   at every phase exit; mandatory end-to-end expected-outcome test (real
+   binary against the real artifact).
+3. **go-review** — two-axis review with the Go lenses (perf/race/security/
+   solid); race findings are a mandatory class gated on `-race`; rules-rot
+   upkeep at close.
+
+Contract: `skills/go-tdd/references/GO_RULES.md` is shared between go-tdd and
+go-review — never restate rules locally.

package/docs/playbooks/research-docs.md

@@ -0,0 +1,10 @@
+# Playbook: research & documentation
+
+1. **find-docs** — current primary docs for any library/SDK/CLI question;
+   never trust training data for API details.
+2. **research** — high-trust primary-source investigation, findings captured
+   as a Markdown file in the repo.
+3. **domain-modeling** — record durable terminology (GLOSSARY.md / ADR).
+
+Docs routing contract: OpenAI products → official OpenAI route; everything
+else → Context7. See `skills/bak/references/documentation-routing.md`.

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "bad-agent-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "BAK — bad-agent-kit: a curated skills marketplace + workflow orchestrator. The router that keeps you from being one. Compose, never own.",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "codex",
+    "workflow-orchestrator",
+    "mattpocock"
+  ],
+  "scripts": {
+    "prepublishOnly": "bash scripts/scrub.sh && node scripts/validate-catalog.js",
+    "test": "node scripts/validate-catalog.js"
+  },
+  "files": [
+    "skills",
+    "docs",
+    "README.md",
+    "GLOSSARY.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "skills": ["./skills/bak", "./skills/go-plan", "./skills/go-tdd", "./skills/go-review"],
+    "changelogPath": "CHANGELOG.md"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/skills/bak/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: bak
+description: formerly chief — Route and orchestrate every workspace task through the smallest complete set of installed skills, plugins, repository guidance, tools, feedback sensors, and durable learning surfaces. Use at the start of every task under your workspace, when the right workflow is unclear, when work crosses repositories or capabilities, or when deciding whether repeated workspace behavior should become an AGENTS.md rule, skill, hook, MCP app, or plugin.
+---
+
+# BAK — bad-agent-kit
+
+Thin workspace router, batman-flavored: preserve the user's real objective,
+select the right capability, coordinate its workflow, verify the result, and
+capture only durable learning. Don't ship the bad agent kit — never mutate on
+inspect, never publish without authority. Do not duplicate the detailed
+instructions owned by routed skills.
+
+## Route every task
+
+1. Extract the goal, target, constraints, authority, and proof of completion.
+2. Identify the active repository or workspace surface. Read the applicable
+   instruction chain and inspect repository state only when relevant.
+3. Read [routing-matrix.md](references/routing-matrix.md). Select the smallest
+   complete route; use no specialist skill when ordinary reasoning or a direct
+   edit is sufficient.
+4. Treat explicitly named skills as mandatory. Apply system and developer
+   trigger rules before this router. Never invent a skill or assume a connector
+   is available.
+5. Announce the selected skills and their order when a skill is used. Then
+   follow each selected `SKILL.md` faithfully.
+6. Execute within the user's authority. Do not turn a request to inspect,
+   explain, review, or diagnose into an unrequested mutation or publication.
+7. Run the feedback loop and verify the actual completion criteria before
+   reporting success.
+
+Do not invoke `bak` recursively. Do not chain one user-invoked Matt Pocock
+orchestrator into another silently. When such a workflow is the best top-level
+route, select it once and let it call only the model-invoked disciplines it
+permits.
+
+## Orient before engineering routes
+
+- Find the Git/project root, current branch, dirty state, relevant `AGENTS.md`,
+  `CLAUDE.md`, `README.md`, `CONTEXT.md`, ADRs, and commands.
+- Preserve unrelated user changes.
+- Before using tracker-aware Matt Pocock workflows, check for
+  `docs/agents/issue-tracker.md`, `domain.md`, and, when `triage` is installed,
+  `triage-labels.md`. If missing or inconsistent, route to
+  `$setup-matt-pocock-skills` and honor its confirmation steps.
+- Prefer repo-specific terms, commands, and acceptance checks over workspace
+  defaults.
+- In a Go module (go.mod present): note the module layout and go directive
+  version floor before entering any phase; Go triggers route to the `go-*`
+  family (see routing matrix).
+
+## Use guides and sensors
+
+Before acting, load the cheapest relevant feedforward guides: instructions,
+domain context, ADRs, specifications, examples, and current primary docs.
+
+After acting, run feedback sensors from cheapest and most deterministic to more
+expensive and inferential:
+
+1. Formatter, linter, type checker, focused tests, static or structural checks.
+2. Broader tests, build, runtime logs, browser or integration checks when the
+   blast radius warrants them.
+3. Diff/spec review, security and maintainability review, then human review for
+   judgment or irreversible decisions.
+
+For material code changes in a child repo under `$HOME/code`, use
+`$HOME/code/.codex/hooks/prehook.sh <repo-root>` as an orientation
+sensor unless the repo provides a more precise equivalent. After the change,
+use `$HOME/code/.codex/hooks/posthook.sh <repo-root>` as a baseline,
+then add the repo-specific checks the task requires. Run
+`prepush.sh <repo-root>` only immediately before a user-authorized push. These
+scripts are sensors, not substitutes for repository instructions or judgment.
+
+## Route current documentation
+
+For library, framework, SDK, API, CLI, or cloud-service questions, read and
+follow [documentation-routing.md](references/documentation-routing.md).
+
+## Route GitHub publication
+
+For GitHub authentication, issue/PR publication, sub-issues, or network checks,
+read and follow [github-publishing.md](references/github-publishing.md).
+Drafting is not publication; obtain explicit user authority before publishing,
+pushing, merging, or changing remote state.
+
+## Learn without bloating the harness
+
+- Capture task facts in the repository that owns them. Use the canonical knowledge vault through
+  `$obsidian-vault` for cross-workspace research,
+  planning, documentation, learning-loop updates, routing lessons, and plugin
+  candidates.
+- Search before creating; update the narrowest existing note; never store
+  secrets, credentials, raw private content, or noisy transcripts.
+- Assess the Learn step at the end of every task. Update an existing vault note
+  or its learning loop when the result is verified and reusable; do not create
+  a note merely to log routine activity.
+- After the same meaningful failure happens twice, record the pattern and
+  propose the smallest durable control: deterministic tool or hook first when
+  mechanically enforceable; repo doc for repo facts; `AGENTS.md` for durable
+  conventions; skill for a reusable workflow; MCP/app for live external data;
+  plugin for a stable shareable bundle.
+
+## Finish clearly
+
+Report the outcome, changed artifacts, checks run, skipped checks, remaining
+risks, and any durable learning captured. A task is complete only when its
+actual acceptance conditions are evidenced; otherwise keep working or state the
+specific blocker.

package/skills/bak/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "BAK (bad-agent-kit)"
+  short_description: "Route every task to the right workflow. Don't ship the bad agent kit."
+  default_prompt: "Use $bak to route and execute this task with the right workspace skills and checks."

package/skills/bak/references/documentation-routing.md

@@ -0,0 +1,42 @@
+# Current Documentation Routing
+
+## OpenAI and Codex
+
+Use `$openai-docs` and its official-source route for OpenAI products, APIs,
+models, and Codex behavior. Do not send OpenAI product questions through
+Context7 when the official Codex manual or OpenAI developer documentation owns
+the answer.
+
+## Other developer technologies
+
+Use `$find-docs`, then use the `ctx7` CLI for every library, framework, SDK,
+API, CLI tool, or cloud-service question, including syntax, configuration,
+migrations, setup, library-specific debugging, and CLI usage.
+
+Do not use Context7 for refactoring, scripts written from scratch, business
+logic debugging, code review, or general programming concepts.
+
+1. Resolve the official library name:
+
+   ```bash
+   npx ctx7@latest library <name> "<full user question>"
+   ```
+
+2. Select the best `/org/project` result by exact name, relevant description,
+   snippet count, High/Medium source reputation, and benchmark score. Retry with
+   an alternate official name or sharper query only when results are wrong.
+3. Fetch the documentation:
+
+   ```bash
+   npx ctx7@latest docs <libraryId> "<full user question>"
+   ```
+
+Use `/org/project/version` for version-specific documentation. Resolve first
+unless the user supplied a valid `/org/project` ID. Run at most three Context7
+commands per question and never include secrets or credentials in queries.
+
+Run Context7 outside the default sandbox. If an in-sandbox call reports DNS,
+`ENOTFOUND`, host-resolution, or fetch failures, rerun that specific command
+outside the sandbox. On quota errors, tell the user and suggest
+`npx ctx7@latest login` or `CONTEXT7_API_KEY`; do not silently answer from model
+memory.

package/skills/bak/references/github-publishing.md

@@ -0,0 +1,34 @@
+# GitHub Publishing Contract
+
+- Draft locally unless the user explicitly authorizes publishing, pushing,
+  merging, creating an issue/PR, commenting, or changing remote state.
+- Use `gh` for GitHub Issues; SSH proves git transport, not GitHub API access.
+- For explicit access, authentication, reachability, permissions, PR, issue, or
+  Actions checks, run the relevant `gh` or git network command outside the
+  default sandbox. Start with `gh auth status`.
+- If the token is invalid, ask the user to run `gh auth login -h github.com`.
+- If DNS or API access fails despite working local credentials, retry the
+  specific command outside the sandbox. If it still fails, report the failure
+  and suggest checking VPN/proxy DNS.
+- For pushes, use the existing working remote/auth transport; do not force SSH
+  or HTTPS.
+
+## Parent and child issues
+
+When publishing an epic/PRD with implementation tickets, create real GitHub
+sub-issue relationships rather than relying only on Markdown links:
+
+1. Create the parent and child issues with `gh issue create`.
+2. Resolve their node IDs:
+
+   ```bash
+   gh api graphql -f owner=OWNER -f name=REPO -F parent=PARENT_NUMBER -F child=CHILD_NUMBER -f query='query($owner:String!, $name:String!, $parent:Int!, $child:Int!) { repository(owner:$owner, name:$name) { parent: issue(number:$parent) { id url } child: issue(number:$child) { id url } } }'
+   ```
+
+3. Attach each child:
+
+   ```bash
+   gh api graphql -f parentId=PARENT_NODE_ID -f childId=CHILD_NODE_ID -f query='mutation($parentId:ID!, $childId:ID!) { addSubIssue(input:{issueId:$parentId, subIssueId:$childId}) { issue { id } subIssue { id } } }'
+   ```
+
+Create in dependency order and attach every implementation issue to the parent.

package/skills/bak/references/routing-matrix.md

@@ -0,0 +1,117 @@
+# Chief Routing Matrix
+
+Use this matrix as a decision aid, not a reason to invoke every matching skill.
+Explicit user skill mentions and current skill trigger rules win. Prefer one
+top-level workflow plus only the supporting disciplines it needs.
+
+## Matt Pocock engineering and productivity routes
+
+| Intent | Primary route | Supporting route or constraint |
+|---|---|---|
+| Configure a repo for this suite | `$setup-matt-pocock-skills` | Run once per repo; confirm tracker and labels before writing |
+| Ask which Matt workflow fits | `$ask-matt` | Use only when explicitly requested; `chief` otherwise routes directly |
+| Stress-test a code plan while building domain docs | `$grill-with-docs` | May use `$grilling` and `$domain-modeling` |
+| Stress-test a general plan | `$grill-me` or `$grilling` | Interview before implementation |
+| Triage issues or external PRs | `$triage` | Requires configured tracker and label vocabulary |
+| Synthesize an already-discussed spec | `$to-spec` | Do not add a new interview unless required by the skill |
+| Split scope into tracer-bullet tickets | `$to-tickets` | Preserve blocking edges and configured tracker |
+| Implement an accepted spec or tickets | `$implement` | Use `$tdd` at agreed seams and `$code-review` before close |
+| Map a task larger than one session | `$wayfinder` or `$decision-mapping` | Use tracker-backed decision tickets when configured |
+| Prototype a state, logic, or UI question | `$prototype` | Throwaway evidence, not production code |
+| Diagnose broken, failing, flaky, or slow behavior | `$diagnosing-bugs` | Reproduce before fixing; add regression coverage |
+| Build or fix test-first | `$tdd` | Red, green, refactor in vertical slices |
+| Establish terminology or record decisions | `$domain-modeling` | Update `CONTEXT.md` or ADRs only when the repo owns them |
+| Design deep module seams/interfaces | `$codebase-design` | Prefer narrow interfaces with hidden complexity |
+| Scan for architectural deepening opportunities | `$improve-codebase-architecture` | Use for an explicit architecture audit, not routine edits |
+| Review a diff against standards and spec | `$code-review` | Its parallel-agent behavior still requires applicable permission |
+| Run a conversational QA session and file findings | `$qa` | Treat publication as external mutation and require its configured tracker |
+| Plan a safe incremental refactor | `$request-refactor-plan` | Interview, design tiny commits, and publish only with authority |
+| Resolve an active merge or rebase | `$resolving-merge-conflicts` | Resolve by intent and primary history; do not abort silently |
+| Produce continuation context | `$handoff` | Use when the user asks or continuity materially needs it |
+| Teach over multiple sessions | `$teach` | Keep state in the teaching workspace |
+| Write or revise a skill | `$skill-creator` plus `$writing-great-skills` | Validate and forward-test when permitted |
+
+## Engineering, documentation, and extension routes
+
+| Intent | Route |
+|---|---|
+| Current docs for non-OpenAI developer technology | `$find-docs`, then the Context7 contract in `documentation-routing.md` |
+| OpenAI or Codex behavior/docs | `$openai-docs` |
+| Research from primary sources into Markdown | `$research` |
+| Browser debugging, automation, performance, network inspection | `$chrome-devtools` |
+| UI/product flow critique | `$product-design:index`, which selects `$product-design:audit` or its own subflow |
+| Visual variants or bitmap generation/editing | `$imagegen`; use `$product-design:ideate` for product-design exploration |
+| Implement a screenshot/mockup | `$product-design:image-to-code` |
+| Clone a live frontend URL | `$product-design:url-to-code` |
+| Create/update a reusable skill | `$skill-creator` |
+| Discover/install skills | `$find-skills` or `$skill-installer` |
+| Create/package a stable Codex plugin | `$plugin-creator` |
+| Set up Husky pre-commit checks | `$setup-pre-commit` |
+| Add Claude Code destructive-git hooks | `$git-guardrails-claude-code` |
+| Migrate tests to shoehorn | `$migrate-to-shoehorn` |
+| Scaffold course exercises | `$scaffold-exercises` |
+| Operate or debug Hatchet workflows | `$hatchet-cli` |
+| Create a manual setup wizard | `$wizard` |
+| Explore, shape, or edit prose | `$writing-fragments` -> `$writing-beats` -> `$writing-shape`; `$edit-article` for revision |
+
+## Connected-service and plugin routes
+
+| Intent | Route |
+|---|---|
+| General GitHub repository, issue, or PR context | `$github:github` |
+| Fix GitHub Actions checks | `$github:gh-fix-ci` |
+| Address PR review comments | `$github:gh-address-comments` |
+| Commit, push, and open a draft PR | `$github:yeet`, only with explicit publication authority |
+| Gmail search, summary, drafting, or triage | `$gmail:gmail` or `$gmail:gmail-inbox-triage` |
+| Calendar scheduling or briefs | The narrowest `$google-calendar:*` skill |
+| Drive, Docs, Sheets, Slides, or Drive comments | The narrowest `$google-drive:*` skill |
+| Notion CLI setup/authentication, general page or data-source CRUD, comments, files, terminal automation, or explicit no-MCP work | `$notion-cli` |
+| Notion capture, research, meeting prep, or spec implementation through the connected Notion app | The narrowest `$notion:*` skill; requires its MCP/app tools |
+| Sales workflow | `$sales:index` first, then its selected focused skill |
+| Obsidian knowledge search or capture | `$obsidian-vault` |
+
+### Choose the Notion transport
+
+1. Honor an explicitly named skill or transport first. `$notion-cli`, `ntn`,
+   terminal, automation, and no-MCP requests route to `$notion-cli`; an explicit
+   `$notion:*` request keeps that specialist workflow and its connector.
+2. For an unqualified general read/write task, use `$notion-cli` when its
+   advertised skill and authenticated CLI are available. It owns direct page,
+   block, property, data-source, comment, and file operations.
+3. Use the narrowest `$notion:*` skill when its semantic workflow—knowledge
+   capture, research synthesis, meeting intelligence, or spec-to-implementation—
+   materially improves the task and the connected Notion app is available.
+   Prove availability from callable Notion tools in the current session or a
+   successful tool call; an advertised skill alone is not evidence of a live
+   connector.
+4. Do not select both transports for the same operation or silently switch after
+   an auth/tool failure. Follow the selected skill's setup flow or ask before
+   changing transports; authentication and mutation authority do not transfer.
+5. Account for capability differences: hosted Notion MCP can search connected
+   external sources when the workspace plan permits it, while `$notion-cli`
+   follows the official CLI and public API surface.
+
+## Go routes
+
+| Intent | Primary route | Supporting route or constraint |
+|---|---|---|
+| Plan a Go feature or change | `$go-plan` | Grill before implementation; every shared datum named and owned |
+| Implement an accepted Go spec | `$go-tdd` | Use `$go-review` before close; sensor gates at every phase exit |
+| Review Go changes | `$go-review` | Two-axis: standards (GO_RULES.md) and spec |
+
+Go triggers (`race`, `goroutine`, `channel`, `mutex`, `deadlock`, `leak`, or a
+`go.mod` in the active repo) route to the `go-*` family; bak remains the sole
+phase orchestrator — the go skills delegate to grilling/to-spec/tdd/code-review,
+they do not replace them.
+
+## Fallback rules
+
+1. Use an explicitly named skill even if the matrix suggests another route.
+2. Use the advertised skill catalog before scanning disk. Disk discovery may
+   find unavailable, disabled, stale, or malformed skills; verify before use.
+3. If two routes overlap, choose the more specific one and use the other only
+   for a distinct supporting job.
+4. If no skill materially improves the task, proceed directly with ordinary
+   reasoning and the relevant tools.
+5. Do not use a connector unless it is present and authorized in the current
+   session. Do not substitute public web search for private connected data.

package/skills/go-plan/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: go-plan
+description: Plan a Go feature or change. Grill the design with the Go frontier taxonomy (goroutine ownership, channel-vs-mutex, leak prevention, error strategy, test seams) and synthesize an accepted spec. Use when planning Go work under your workspace before any Go implementation, or when Go triggers appear (race, goroutine, channel, mutex, deadlock, leak).
+---
+
+# go-plan
+
+Explicit-only wrapper — the real mechanics live in the skills this delegates to.
+Never re-implement their loops here.
+
+## Mechanics
+
+1. Call the Skill tool with **grilling** — run its full interview loop, driven
+   by the Go frontier taxonomy in
+   [go-frontier-questions.md](references/go-frontier-questions.md). Human gate
+   is ON for every concurrency-relevant decision (ownership, channel-vs-mutex,
+   goroutine lifecycle, error strategy); opt-in elsewhere.
+2. Call the Skill tool with **to-spec** — synthesize the plan with no second
+   interview. The spec must name every shared datum and its owner.
+
+## Grill rule (from pstack)
+
+A finding survives only when a run proves it. Every grill question carries the
+sensor that would prove its answer. "Never hand the human a check you could
+run." Every claim in the plan is labeled measured / inferred / guess.
+
+## Exit gate
+
+Every goroutine, channel, lock, and shared datum is **named and owned**; the
+plan pre-flights with `go list`, `go build`, `go vet` (zero findings) before
+implementation starts.
+
+## Lens → sensor quick map
+
+| Concern | Proving sensor |
+|---|---|
+| data races / ownership | `go test -race` (fires only on executed paths) |
+| goroutine leaks | `goleak.VerifyNone`, pprof goroutine profile |
+| sync-primitive copying | `go vet -copylocks` |
+| error handling | `errcheck`, `errorlint`, `wrapcheck` |
+| cancellation | ctx in every blocking `select` |
+| end-to-end outcome | real binary against the real artifact (required) |

package/skills/go-plan/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "go-plan"
+  short_description: "Plan a Go feature: grill the design with Go frontier questions, then synthesize an accepted spec."
+  default_prompt: "Use $go-plan to grill and spec this Go work."
+  allow_implicit_invocation: false

package/skills/go-plan/references/go-frontier-questions.md

@@ -0,0 +1,70 @@
+# Go Frontier Questions
+
+Drive the grilling interview with these five. Each carries the research-backed
+recommended answer and the sensor that proves it.
+
+## 1. Ownership — which goroutine owns this shared value?
+
+**Recommended (Effective Go + Share-by-Communicating codewalk):** transfer of
+ownership via channels. A shared value has exactly one goroutine-owner at any
+moment: "sending a Resource pointer on a channel passes ownership of the
+underlying data from the sender to the receiver." Producer closes its outbound
+channel after the last send; consumers range until close.
+
+- After sending a value on a channel, never touch it again.
+- Only the goroutine that owns an outbound channel may close it.
+
+**Sensor:** `go test -race` catches unsynchronized send/close; `go vet -copylocks`
+catches mutex copying. Ownership itself is a convention — sensors catch its
+violations.
+
+## 2. Channel or mutex — or eliminate the sharing entirely?
+
+**Recommended (Go wiki MutexOrChannel + 100 Go Mistakes #57):** parallel
+goroutines mutating shared data → mutex; concurrent goroutines coordinating or
+transferring ownership → channel. First ask: can we eliminate the shared write
+target entirely (pstack: separate-before-serializing-shared-state)? "We need a
+lock" is a smell to justify, not a default answer.
+
+- Ownership transfer → channel
+- Caches/guarded state → mutex (non-pointer, non-embedded field)
+- Read-mostly → `sync.RWMutex`
+- Single-word state / copy-on-write → atomic
+- Semaphore / rate limit → buffered channel
+- Buffer capacity 0 or 1, or a documented justification (Uber)
+
+**Sensor:** `-race` clean for whatever mode is chosen; `go test -timeout` for
+coordination hangs.
+
+## 3. Leak prevention — how does every goroutine exit?
+
+**Recommended (go.dev pipelines + context + errgroup):** the caller that starts
+work owns its lifetime: `ctx, cancel := ...; defer cancel()`. Every blocking
+send/receive wrapped in `select { case ch <- v: case <-ctx.Done(): return }`.
+Owner closes channels (`defer close(out)`). Prefer `errgroup.WithContext` over
+raw WaitGroup when errors exist; `wg.Add` before `go`, `defer wg.Done()`.
+Buffer size 1 for "send one result" channels. Any package that starts
+goroutines gets `goleak.VerifyNone` in tests.
+
+**Sensor:** `goleak.VerifyNone` / `VerifyTestMain`; pprof goroutine profile in
+production.
+
+## 4. Error strategy — sentinel, wrap, or opaque?
+
+**Recommended (Cheney SOLID-Go + Go 1.13 blog + Google best-practices):**
+opaque errors preferred; when callers must branch, assert behavior not type
+(`Temporary() bool` probes, `errors.Is` on narrow contracts). `%w` by default
+in-app; `%v` at API/system boundaries to hide third-party internals. Handle
+once — log XOR return, never both. Libraries return and wrap; only the
+top-level handler (main/HTTP) logs or maps to status codes.
+
+**Sensor:** `errcheck`, `errorlint`, `wrapcheck`, `staticcheck` ST1005.
+
+## 5. Test seam — where do tests live?
+
+**Required:** the highest possible package boundary or exported identifier that
+lets an implementer build without asking another question. Fixes the TDD
+vertical slices. **End-to-end expected-outcome tests are mandatory**: the
+expected outcome is an acceptance condition, and acceptance conditions must be
+tested — at least one test runs the real binary against the real artifact, not
+a mocked approximation.

package/skills/go-review/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: go-review
+description: Review Go changes on two axes — standards (GO_RULES.md, Effective Go, SOLID-Go, security best practices, goperf lenses) and spec. Use when reviewing Go changes before merge.
+---
+
+# go-review
+
+Explicit-only wrapper. Call the Skill tool with **code-review** on its two
+parallel axes; inject the Go specifics below into both review contexts.
+
+## Standards axis — Go sources
+
+- `../go-tdd/references/GO_RULES.md` — the canonical contract (read it; do not restate it)
+- Effective Go — https://go.dev/doc/effective_go
+- SOLID Go design — https://dave.cheney.net/2016/08/20/solid-go-design
+- Security best practices — https://go.dev/doc/security/best-practices
+- Performance — https://goperf.dev (hot paths only)
+
+## Lenses
+
+`references/lenses/` — perf, race, security, solid. Race/concurrency findings
+are a mandatory findings class, gated on `go test -race`.
+
+## Rules rot
+
+At review close: any rule in GO_RULES.md whose sensor never ran in this change
+gets deleted. A rule with no sensor is advice; a rule whose sensor never fires
+is rot.

package/skills/go-review/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "go-review"
+  short_description: "Review Go changes on standards and spec axes with Go lenses."
+  default_prompt: "Use $go-review to review these Go changes before merge."
+  allow_implicit_invocation: false

package/skills/go-review/references/lenses/perf.md

@@ -0,0 +1,13 @@
+# Perf lens (goperf.dev — hot paths only)
+
+Trigger: pprof marks a function hot. Never review perf folklore otherwise.
+
+- Escape analysis: `go build -gcflags=-m=2` — allocations must be claimed, not assumed
+- Pooling: `sync.Pool` only for short-lived reusable scratch, verified by escape analysis
+- Prealloc: `make([]T, 0, n)` where size is known; `prealloc`, `fieldalignment`
+- Interface boxing on hot paths — value vs pointer receivers
+- GC pressure: `GOGC` only after `go tool pprof` shows it matters
+- Worker pools: bounded concurrency, `errgroup.SetLimit`
+
+Evidence required: `go test -bench -benchmem` + `benchstat` before/after
+(ns/op, B/op, allocs/op). No benchmark → finding is labeled `[unverified]`.

package/skills/go-review/references/lenses/race.md

@@ -0,0 +1,17 @@
+# Race / concurrency lens (mandatory findings class)
+
+Gate: `go test -race` + `goleak.VerifyNone`. Caveat: -race fires only on
+executed paths, so every concurrent path needs a test that exercises it.
+
+Check, in order:
+1. Ownership — which goroutine owns each shared datum; is it named in the spec?
+2. Separate-before-serializing — could the shared write target be eliminated?
+3. Mixed atomic/non-atomic access to one variable (never allowed)
+4. Loop-variable capture in goroutines (vet loopclosure)
+5. WaitGroup misuse: Add before go, Done via defer (vet, staticcheck SA2)
+6. Send-on-closed-channel risk: only the owner closes (race detector)
+7. Goroutine leaks: every `go` has a reachable exit via ctx/done (goleak)
+8. Mutex copying: non-pointer, non-embedded, all access via owning methods
+   (vet copylocks)
+9. Channel buffer 0/1 or justified
+10. ctx propagation into every goroutine; `defer cancel()` everywhere

package/skills/go-review/references/lenses/security.md

@@ -0,0 +1,12 @@
+# Security lens (go.dev/doc/security/best-practices)
+
+Gate: `govulncheck ./...` clean; gosec zero findings.
+
+- Tainted input validated at trust boundaries; fuzz tests for every
+  parser/decoder of untrusted input (`go test -fuzz`)
+- `crypto/rand` for anything security-relevant; `math/rand` never
+- No secrets in logs, errors, or struct String() methods
+- Deadlines on every network I/O (ctx.WithTimeout); no `noctx` HTTP calls
+- Resource closure: bodyclose, sqlclosecheck
+- Go directive version floor in go.mod (drops unsupported toolchain CVEs)
+- Dependency hygiene: `go list -m -u all` reviewed; minimal transitive surface

package/skills/go-review/references/lenses/solid.md

@@ -0,0 +1,20 @@
+# SOLID / design lens (dave.cheney.net/2016/08/20/solid-go-design)
+
+Name the violation in Cheney's vocabulary — never say "this is bad":
+
+- Rigid — change forces cascade edits through unrelated packages
+- Fragile — change breaks distant parts
+- Immobile — can't be reused outside the current context
+- Complex — more cognitive load than the job needs
+- Verbose — more ceremony than information
+
+Probes:
+- Model the domain: sealed-interface state machines over scattered booleans
+- One package = one responsibility; no common/utils catch-alls
+- Consumer-defined narrow interfaces; accept interfaces, return structs
+- Deep modules: hide complexity behind a small interface
+- Dependency inversion: concrete wiring pushed up to main/top-level handlers;
+  low-level layers return errors, never decide policy
+
+Smell proxies (sensors, weak evidence): unused/unparam, gocyclo, funlen,
+revive iface-*, `go list -deps` for the import graph.

package/skills/go-tdd/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: go-tdd
+description: Implement an accepted Go spec test-first. Delegates to tdd at pre-agreed seams with a Go sensor gate at every phase exit, and mandatory end-to-end expected-outcome tests. Use when implementing Go changes after go-plan produced an accepted spec.
+---
+
+# go-tdd
+
+Explicit-only wrapper. Call the Skill tool with **tdd** at the pre-agreed seams
+from the spec. Every phase exit is a Go sensor run — "it compiles" is not
+evidence.
+
+## The contract
+
+All rules come from [GO_RULES.md](references/GO_RULES.md) — the single source
+shared with go-review. Read it before writing code; never restate rules
+locally.
+
+## Fail-fast sensor chain (run at every phase exit)
+
+1. `gofmt -l .` — zero output
+2. `go vet ./...` — zero findings (copylocks, atomic, loopclosure, lostcancel)
+3. `golangci-lint run` — zero findings (config: assets/.golangci.yml)
+4. `govulncheck ./...` — no known vulnerabilities
+5. `go test -race ./...` — green; `goleak` on any package that starts goroutines
+
+A missing binary is not a free pass — install it or use the documented
+degraded-mode fallback in [toolchain-setup.md](references/toolchain-setup.md).
+
+## End-to-end outcome tests (required)
+
+Beyond unit tests, at least one test exercises the expected end-to-end outcome:
+the real binary against the real artifact where feasible. The expected outcome
+is an acceptance condition, and acceptance conditions must be tested, not
+assumed.
+
+## Perf discipline (pstack)
+
+Optimize only on a pprof-identified hot path. Every perf change ships
+`benchstat` before/after (ns/op, B/op, allocs/op). No benchmark, no change.

package/skills/go-tdd/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "go-tdd"
+  short_description: "Implement an accepted Go spec test-first with sensor gates and e2e outcome tests."
+  default_prompt: "Use $go-tdd to implement this accepted Go spec."
+  allow_implicit_invocation: false

package/skills/go-tdd/assets/.golangci.yml

@@ -0,0 +1,39 @@
+version: "2"
+
+linters:
+  default: none
+  enable:
+    - errcheck
+    - errorlint
+    - wrapcheck
+    - govet
+    - staticcheck
+    - unused
+    - unparam
+    - gosec
+    - revive
+    - prealloc
+    - fieldalignment
+    - containedctx
+    - bodyclose
+    - noctx
+    - sqlclosecheck
+    - gocyclo
+    - funlen
+
+  settings:
+    revive:
+      rules:
+        - name: exported
+        - name: iface
+    wrapcheck:
+      ignoreSigs:
+        - .Errorf(
+    gocyclo:
+      min-complexity: 15
+
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - vendor$

package/skills/go-tdd/references/GO_RULES.md

@@ -0,0 +1,44 @@
+# GO_RULES.md — the canonical Go contract
+
+One line per rule + its `[sensor]`. Tiered: HARD gates block; REVIEW lenses are
+judgment; EVIDENCE gates apply to hot paths only. go-tdd and go-review both read
+this file — never restate rules locally, and delete any rule whose sensor never
+runs (rules rot).
+
+## HARD — failing blocks the phase exit
+
+1. `gofmt -l` and `goimports -l` print nothing — machine formatting is the standard. `[gofmt -l]`
+2. `go vet ./...` is clean — copylocks, atomic, loopclosure, lostcancel. `[go vet]`
+3. `golangci-lint run` is clean with assets/.golangci.yml. `[golangci-lint]`
+4. `govulncheck ./...` finds no known vulnerabilities. `[govulncheck]`
+5. `go test -race ./...` is green; `goleak.VerifyNone` in every package that starts goroutines. `[go test -race, goleak]`
+6. Every exported declaration has a doc comment beginning with its name. `[revive exported-comments]`
+7. Errors handled: no unchecked returns, no `==`/string matching — `errors.Is`/`errors.As` only. `[errcheck, errorlint]`
+8. `%w` for in-app wrapping, `%v` only at API/system boundaries; error strings lowercase, no trailing punctuation. `[wrapcheck, staticcheck ST1005]`
+9. `context.Context` is the explicit first parameter; never stored in a struct or global; `defer cancel()` for every derived context. `[go vet lostcancel, containedctx]`
+10. Every `go` statement has a reachable exit: blocking ops sit in `select { ... case <-ctx.Done(): return }`. `[goleak, review]`
+11. `wg.Add` before `go`, `defer wg.Done()`; prefer `errgroup.WithContext` when errors exist. `[go vet, go test -race]`
+12. Channel senders close their channel (`defer close(out)`); receivers never close it; buffer capacity 0 or 1 unless justified. `[go test -race, review]`
+13. Mutex as a non-pointer, non-embedded field; all access through the owning struct's methods. `[go vet -copylocks]`
+14. `crypto/rand`, never `math/rand` for anything security-relevant; no secrets in logs/errors; deadlines on every network I/O. `[gosec]`
+15. Fuzz tests exist for every parser/decoder of untrusted input. `[go test -fuzz]`
+16. At least one end-to-end expected-outcome test: the real binary against the real artifact. `[go test ./... e2e]`
+
+## REVIEW — judgment lenses, no direct sensor
+
+17. SOLID-Go by name: rigidity, fragility, immobility, complexity, verbosity — call them out with the specific violation. `[review]`
+18. Model the domain: sealed-interface state machines over scattered booleans. `[review]`
+19. One package = one responsibility; no `common`/`utils` catch-alls. `[gocyclo, funlen, review]`
+20. Consumer-defined narrow interfaces; accept interfaces, return structs (`Save(io.Writer)`, not `Save(*os.File)`). `[revive iface-*, review]`
+21. Zero value of every exported type usable without initialization. `[review]`
+
+## EVIDENCE — hot paths only, triggered by pprof
+
+22. Every perf claim ships `benchstat` before/after: ns/op, B/op, allocs/op — never folklore. `[go test -bench -benchmem, benchstat]`
+23. Preallocate when size is known (`make([]T, 0, n)`); order struct fields largest-to-smallest. `[prealloc, fieldalignment]`
+24. `sync.Pool` only for short-lived reusable scratch; verify stack residency with escape analysis before claiming zero-cost. `[go build -gcflags=-m=2]`
+
+## Upkeep
+
+At review close: delete any rule whose sensor never ran in this change. A rule
+with no sensor is advice; a rule whose sensor never fires is rot.

package/skills/go-tdd/references/toolchain-setup.md

@@ -0,0 +1,29 @@
+# Toolchain setup & degraded mode
+
+## Install the gate binaries once
+
+```bash
+go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
+go install golang.org/x/vuln/cmd/govulncheck@latest
+go install honnef.co/go/tools/cmd/staticcheck@latest
+go install golang.org/x/perf/cmd/benchstat@latest
+go install go.uber.org/goleak/cmd/goleak@latest  # or use as a test dependency
+go get go.uber.org/goleak                          # test dependency form (preferred)
+```
+
+Verify: `golangci-lint version`, `govulncheck -version`.
+
+## Degraded mode (missing binary)
+
+A missing sensor is a degraded phase, not a skipped one:
+
+| Missing | Degraded substitute |
+|---|---|
+| govulncheck | `golangci-lint run` (gosec linter) + `go list -m -u all` review |
+| golangci-lint | `go vet ./...` + `staticcheck ./...` |
+| staticcheck | `go vet ./...` (covers copylocks/atomic/loopclosure/lostcancel) |
+| benchstat | manual ns/op comparison — but label the claim `[unverified]` |
+| goleak | `runtime.NumGoroutine()` before/after assertions in the test |
+
+Note in the handoff which sensors ran degraded and why; the missing binary
+becomes the first task of the next session.