pi-dev 0.1.1

package/skills/migrate/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: migrate
+description: Audit a repo's existing AI/agent conventions (AGENTS.md, CLAUDE.md, scoped agent dirs, handoff systems, context/ADR variants) and migrate them to the canonical engineering framework. STRICT GATE — `/do` refuses to run on un-migrated repos. Also enforces GitHub readiness when GitHub is the tracker.
+disable-model-invocation: true
+---
+
+# Migrate Repo Conventions
+
+The engineering framework assumes a single canonical shape. Mixed systems cause confusion and drop efficiency. This skill is the **strict gate** that ensures every repo conforms before any engineering work begins.
+
+## Canonical end state
+
+```
+<repo>/
+├── AGENTS.md                          # hard rules + ## Agent skills block (canonical)
+├── docs/
+│   ├── agents/
+│   │   ├── domain.md
+│   │   ├── issue-tracker.md
+│   │   ├── triage-labels.md
+│   │   └── preferences.md             # ends with migration marker
+│   ├── adr/  (or docs/decisions/, documented in domain.md)
+│   └── ...
+└── .archive/<date>-pre-migration/     # original artifacts, if migration changed them
+```
+
+**Forbidden after migration:**
+- Standalone handoff systems (`docs/handoff/SESSION_*.md`, `.scratch/flow/`, `.handoff/`, etc.)
+- Duplicate process docs in AGENTS.md (anything our skills cover)
+- Multiple competing rule files (CLAUDE.md + AGENTS.md both alive — pick one)
+
+State of work lives in three places only: **code (git), issue tracker, merged preferences**.
+
+## Process
+
+### 1. Inventory
+
+Scan and list:
+
+**A. Agent rule files**
+- `AGENTS.md`, `CLAUDE.md` — root and scoped (subdir)
+- `.agents/`, `.claude/`, `.opencode/`, `.omc/`, `.hermes/`, `.sisyphus/`, `.cursor/`, `.windsurf/`
+
+**B. Handoff systems**
+- `docs/handoff/`, `docs/sessions/`, `.handoff/`, `.scratch/flow/`, `.ref/`
+- Anything matching `SESSION_*.md`, `HANDOFF_*.md`, session-log naming
+
+**C. Context / ADR variants**
+- `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/contexts/*/CONTEXT.md`
+- `docs/adr/`, `docs/decisions/`, `docs/architecture/`
+
+**D. GitHub readiness** (if user picks GitHub during setup)
+- `git remote -v` — GitHub remote present?
+- `gh --version` — CLI installed?
+- `gh auth status` — authenticated?
+- `gh repo view <owner>/<repo>` — repo accessible?
+- `gh issue list --limit 1 --repo <owner>/<repo>` — issue API works?
+
+### 2. Classify each artifact
+
+| Class       | Action                                                                                       |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| PRESERVE    | Hard rules (NEVER/MUST/BLOCKING/CRITICAL/MANDATORY) — domain-specific, survive migration     |
+| TRANSLATE   | Process/workflow docs that duplicate our skills — replace with `## Agent skills` block       |
+| ARCHIVE     | Handoff logs, session notes — move to `.archive/<date>-pre-migration/` or delete with OK     |
+| NORMALIZE   | Context/ADR variants — either move to canonical paths OR document the variant in domain.md   |
+
+Heuristics:
+- A bullet that starts with `NEVER`, `MUST`, `BLOCKING`, `CRITICAL`, `MANDATORY`, `ALWAYS` → PRESERVE.
+- A section titled `Build & Run`, `Test`, `Session Onboarding`, `Session Handoff`, `Validation Before Commit`, `Long-Running Commands`, etc. → TRANSLATE if generic, PRESERVE if domain-specific (e.g. fetchflow's `pnpm test` is generic, but `BUZZ formula differs per platform` is domain).
+- File with timestamp in name under `docs/handoff/` or `.scratch/` → ARCHIVE.
+
+### 3a. Local-live readiness gate
+
+Before declaring migration complete, the agent must confirm it can drive the project locally without the user playing test runner. This is a one-time conversation per project; the answers go into preferences free notes and become the agent's playbook for every future run.
+
+```
+[migration] Local-live readiness
+
+Detected:
+  • language/runtime:   <node | python | go | rust | mixed>
+  • dev script(s):      <list of package.json scripts matching dev|start|serve>
+  • docker presence:    <docker-compose*.yml | Dockerfile*>
+  • infra deps:         <postgres | mysql | oracle | redis | s3 | ... if hinted in env example>
+  • playwright/e2e:     <yes/no>
+  • complexity:         <light | medium | heavy>
+```
+
+Branch:
+
+- **light** (single `npm run dev` / `pnpm dev` boots everything, no infra): record the exact command. No interview.
+- **medium** (one or two services, simple env): record the boot command and the env-source command (e.g. `source .env.development &&`). No interview.
+- **heavy** (multi-service compose, real DB/queue, ops-only secrets): **ask the user 3 questions, once**:
+  1. **Local boot path** — exact command(s) to bring the app/subsystem up locally (or "not yet possible — agent will build a harness").
+  2. **Infra strategy** — `local-everything` / `borrow-ops-conn` (DB/queue from prod read-only) / `mock-infra-only-app-live` / other.
+  3. **Smoke probe** — one HTTP/CLI/log signal that proves the system is alive (e.g. `curl localhost:8080/healthz`, log line pattern, queue depth metric).
+
+Record answers in `docs/agents/preferences.md` under a new section:
+
+```markdown
+## Local-live playbook
+
+- boot: <command(s)>
+- env: <source / docker / k8s context>
+- infra-strategy: <one of the four above>
+- alive-probe: <one signal>
+- known-gotchas: <free text>
+```
+
+After this is set, the agent boots and verifies on its own for the rest of the project's life. The user is asked again only if the playbook breaks (probe fails for a structural reason, not a flaky network).
+
+If the user picks "not yet possible — agent will build a harness", record that fact and `/migrate` exits with the playbook in TODO state. The first `/do` run will build the harness and update the playbook in place.
+
+### 3b. GitHub readiness gate (if applicable)
+
+If user already chose / will choose GitHub as tracker:
+
+```
+[migration] GitHub readiness check
+
+  git remote (github):  <ok | missing | non-github>
+  gh CLI installed:     <ok | missing>
+  gh auth status:       <ok | unauth>
+  repo accessible:      <ok | denied | unknown>
+  issue API:            <ok | failed>
+
+Status: <READY | BLOCKED>
+```
+
+If BLOCKED, print exact fix commands and stop. Examples:
+
+- gh missing: `brew install gh` (mac) / `apt install gh` (linux)
+- unauth: `gh auth login`
+- no remote: `gh repo create <owner>/<repo> --source . --push --private`
+
+Do not proceed with migration body until READY, OR until user picks a non-GitHub tracker (then `/setup` handles it).
+
+### 4. Present diff plan
+
+One screen, no surprises:
+
+```
+[migration] plan for <repo>
+
+PRESERVE (hard rules → AGENTS.md ## Hard rules + docs/agents/preferences.md ## Project taboos):
+  • <rule 1>  [from: AGENTS.md:42]
+  • <rule 2>  [from: api/AGENTS.md:15]
+  • ...
+
+TRANSLATE (delete from AGENTS.md, covered by skills):
+  • "## Build & Run"        → tdd / repo scripts
+  • "## Session Onboarding" → `/do` Step 0
+  • "## Session Handoff"    → not needed (no handoffs in this framework)
+  • ...
+
+ARCHIVE (move to .archive/<date>-pre-migration/):
+  • docs/handoff/SESSION_2025-04-10.md
+  • .scratch/flow/*
+  • ...
+
+NORMALIZE:
+  • docs/decisions/ → keep, document in docs/agents/domain.md
+  • CONTEXT-MAP.md  → keep (multi-context layout)
+
+WRITE/UPDATE:
+  • AGENTS.md                       (rewrite)
+  • docs/agents/issue-tracker.md    (via `/setup`)
+  • docs/agents/triage-labels.md
+  • docs/agents/domain.md
+  • docs/agents/preferences.md      (via `/taste` onboarding)
+
+DELETE (with user OK):
+  • CLAUDE.md  (if AGENTS.md is the keeper)
+  • <empty/duplicate dirs>
+```
+
+Wait for user OK. Show exact text being preserved or translated if user asks.
+
+### 5. Execute
+
+In order:
+
+1. **Backup**: `mv` everything in ARCHIVE to `.archive/<date>-pre-migration/`. Add `.archive/` to `.gitignore` if not present.
+2. **Setup docs**: invoke `/setup` if any of `docs/agents/{issue-tracker,triage-labels,domain}.md` missing.
+3. **Rewrite AGENTS.md** with the canonical skeleton:
+   ```markdown
+   # <Repo> — Operating Rules
+
+   <one-liner repo summary>
+
+   ## Hard rules
+
+   <preserved rules, deduplicated, grouped by topic>
+
+   ## Agent skills
+
+   ### Issue tracker
+   <one-liner>. See `docs/agents/issue-tracker.md`.
+
+   ### Triage labels
+   <one-liner>. See `docs/agents/triage-labels.md`.
+
+   ### Domain docs
+   <one-liner>. See `docs/agents/domain.md`.
+
+   ### Preferences
+   <one-liner>. See `docs/agents/preferences.md` (overrides on `~/.pi/agent/preferences.md`).
+   ```
+4. **Sub-AGENTS.md**: if scoped `<subdir>/AGENTS.md` exists, leave it but strip duplicated process docs; preserve only hard rules specific to that subtree.
+5. **Onboard preferences**: invoke `/taste` in onboarding mode.
+6. **Mark migrated**: append to `docs/agents/preferences.md`:
+   ```
+   <!-- migrated: <ISO-date> by `/migrate` -->
+   ```
+7. **Print summary**: counts of preserved / translated / archived / written, plus any FYI items needing manual review.
+
+### 6. Idempotency
+
+This skill is safe to re-run. On second run:
+- If marker present and no drift detected → print "already migrated, no changes" and exit.
+- If drift detected (new handoff files appeared, AGENTS.md got a generic process section bolted on, etc.) → present a diff for those drifts only.
+
+## When migration cannot proceed
+
+- User refuses to delete a competing rule file (CLAUDE.md vs AGENTS.md both alive) → migration stops, `/do` stays blocked. The decision must be made.
+- GitHub gate fails and user does not pick alternative → blocked.
+- User wants to keep a handoff system → migration writes a one-paragraph exception in `docs/agents/preferences.md` free notes ("this repo retains `docs/handoff/` because <reason>") and skill respects it. But the canonical posture is no-handoff.
+
+## Why this is strict
+
+Hybrid systems silently degrade. A skill thinks it should write a handoff because the repo has `docs/handoff/`; another skill thinks it shouldn't because the framework says no handoff. The agent ends up writing handoffs no one reads, OR skipping state-of-work tracking entirely. The migration gate prevents this class of bug at the source.

package/skills/recon-with-vision/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: recon-with-vision
+description: Reconnaissance for HTML extractors and external-site adapters. Captures the rendered page at the canonical desktop viewport, reads it as an image, and locks the schema against what a human actually sees — not what raw HTML grep happens to find. Use before designing or revising an extractor / scraper / adapter, before writing parser regex, and before committing a response schema for an external page.
+---
+
+<what-to-do>
+
+You are about to design or revise an extractor against a third-party HTML page. Do not trust raw HTML grep alone — modern pages hydrate fields client-side, embed values in attributes you didn't anticipate, and split visual sections across DOM blocks that don't resemble the rendered layout. Verify against what a human actually sees, then lock the schema.
+
+Work the recipe, one target page at a time. Each target produces a fixture and a verified field list. Stop and present findings to the user before writing parser code.
+
+</what-to-do>
+
+<recipe>
+
+## Recipe — per target page
+
+1. **Raw fetch baseline.** `curl -sS -L -A '<desktop UA>' <url> -o /tmp/<name>.html -w '%{http_code} %{size_download}\n'`. Confirm 200 + reasonable size. This is your fixture candidate.
+
+2. **Quick raw probe.** Grep / regex the obvious fields you expect (full_name, description, counts, etc.). Note which ones extract cleanly and which don't. Do not yet infer "the field doesn't exist" from grep failure — hydration may hide it.
+
+3. **Vision capture.** Render the page through Playwright at the canonical desktop viewport `1280 × 1560` and screenshot the first viewport (no fullPage). Save to a stable path. The capture script is a one-off — write it inline, do not commit it.
+
+   - 1280 = standard desktop max-width many sites optimise for.
+   - 1560 = enough vertical space to see most "above the fold" + first content section without infinite scroll.
+   - `waitUntil: 'networkidle'` + 1.5s extra timeout to let React hydration finish.
+   - Use a real desktop User-Agent. Do not use the default Playwright UA.
+
+4. **Vision read.** Read the screenshot with the Read tool (image input). List every field a human actually sees on the rendered page: tabs, filters, badges, sidebar metadata, repeated card structure, counts, relative-time strings, language breakdowns, "X by Y" attributions.
+
+5. **Delta the two lists.** Fields visible in vision but missing from raw grep are your discovery. These are usually the most valuable fields — they tend to be hydrated counters (stars, watchers, releases), language %, contributor avatars, sidebar metadata.
+
+6. **Lock the schema.** Decide for each visible field: include / exclude / defer. State the reason for each exclusion (LLM-noise, visual-only, requires-second-fetch, phase-2). Capture the locked schema in the PRD or ADR before any parser code is written.
+
+7. **Save the fixture.** Move the raw HTML (not the screenshot) into `tests/fixtures/<adapter>/<page-name>.html` with a fixture README documenting source URL, capture date, and refresh policy: "fixture refresh and parser refresh must land together in the same PR."
+
+</recipe>
+
+<known-traps>
+
+## Traps this skill exists to prevent
+
+- **Hydration blindness.** Counters like stars / forks / watching often render via client-side JS and end up in `<span title="N">` or data-attributes that don't match the obvious selector. Vision sees them; grep doesn't.
+- **Section blindness.** Sidebars (About / Topics / Languages / Releases / Packages / Contributors) are often a separate DOM tree. Reading the screenshot makes them visible at a glance; reading the HTML buries them.
+- **Filter blindness.** Tabs and filters (e.g. `Repositories | Developers`, `Spoken Language: Any`, `Sort: Most stars`) are obvious in vision and easy to miss in HTML.
+- **"This field doesn't exist" false negatives.** Raw grep returns 0 → don't conclude "absent". Conclude "I don't yet have the right selector" until vision confirms.
+- **Field-name drift.** What looks like "watchers" in your model may render as "watching" in the UI. Use the rendered label as the canonical name when nothing else is at stake.
+- **Mobile vs desktop layout drift.** Some sites collapse sidebars on smaller viewports and the schema gets gutted. Desktop 1280 stays consistent.
+
+</known-traps>
+
+<schema-decisions>
+
+## Decisions to make once vision delta is in hand
+
+For every field in the vision list:
+
+- **Include and always-present (`null`-explicit).** Default for typed-client / MCP-tool / CLI consumers — schema stable across calls.
+- **Include but optional.** Only when the field is genuinely rare (e.g. topic page `created_by` exists for ~5% of topics) and including it as `null` would dominate the response.
+- **Exclude — visual-only noise.** Avatars without identity value, social preview images, sponsor button states, internal telemetry attributes.
+- **Exclude — requires extra fetch.** Note in the PRD; defer to Phase 2 unless one extra request gives high value.
+- **Exclude — REST gives this better.** State the boundary explicitly. Don't double-source.
+
+State the reason next to each exclusion in the PRD body. A future reader must be able to ask "why isn't this field here?" and find the answer without re-running the recon.
+
+</schema-decisions>
+
+<fixture-policy>
+
+## Fixture policy
+
+- One captured HTML per page-class, stored under `tests/fixtures/<adapter>/`.
+- Add a `README.md` to the fixture directory listing source URL, capture date, and the refresh-with-parser rule.
+- Parser unit tests run against the fixture, not the live network. Network tests live in smoke runners, not unit tests.
+- When the live page changes and parser tests fail against prod, refresh the fixture in the same PR as the parser fix. Never refresh the fixture without updating the parser, and vice versa.
+
+</fixture-policy>
+
+<scope>
+
+## When to use
+
+- Building a new HTML extractor / scraper / adapter for an external site.
+- Revising an existing extractor after upstream HTML drift.
+- Locking a response schema for an external-page-derived endpoint.
+- Designing fixture-based unit tests for a parser.
+
+## When not to use
+
+- The data source is a stable JSON API. Vision adds nothing; the API response is the schema.
+- The page is fully server-rendered HTML with no React/Vue hydration. Raw grep is sufficient — but it costs nothing to spot-check one screenshot anyway.
+- The page is behind authentication that the vision-capture browser can't pass. Resolve the auth path first.
+
+</scope>
+
+<runtime-vs-design-time>
+
+## Design-time only — runtime extraction stays on the project's existing path
+
+This skill uses Playwright at design time to capture one fixture and verify a schema. That one-off capture script is not committed and is not part of the runtime adapter.
+
+If the host repo prohibits Playwright / Puppeteer / Selenium for runtime extraction (typical for production scraping pipelines that must run through `curl` + a proxy lane for cost / detection / metering reasons), this skill stays compatible: the runtime extractor still uses the project's blessed HTTP client. The vision capture is a one-shot recon tool, not a runtime dependency.
+
+State this distinction in the PRD or ADR so future readers don't conflate the two.
+
+</runtime-vs-design-time>

package/skills/setup/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: setup
+description: Scaffolds the per-repo configuration the engineering skills assume — issue tracker (GitHub by default), triage label vocabulary, and domain doc layout. Auto-invoked by `/migrate` during repo onboarding; manual call only when the setup docs are missing or need to be redone.
+disable-model-invocation: true
+---
+
+# Setup Matt Pocock's Skills
+
+Scaffold the per-repo configuration that the engineering skills assume:
+
+- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
+- **Triage labels** — the strings used for the five canonical triage roles
+- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+## Process
+
+### 1. Explore
+
+Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+
+- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
+- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
+- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
+- `docs/adr/` and any `src/*/docs/adr/` directories
+- `docs/agents/` — does this skill's prior output already exist?
+- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
+
+Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
+
+**Section A — Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+
+Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
+
+- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
+- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
+- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
+- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+
+**Section B — Triage label vocabulary.**
+
+> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
+
+The five canonical roles:
+
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter
+- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
+
+**Section C — Domain docs.**
+
+> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
+
+Confirm the layout:
+
+- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
+- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
+
+### 3. Confirm and edit
+
+Show the user a draft of:
+
+- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
+
+Let them edit before writing.
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- If `CLAUDE.md` exists, edit it.
+- Else if `AGENTS.md` exists, edit it.
+- If neither exists, ask the user which one to create — don't pick for them.
+
+Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
+```
+
+Then write the three docs files using the seed templates in this skill folder as a starting point:
+
+- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
+- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
+- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
+- [triage-labels.md](./triage-labels.md) — label mapping
+- [domain.md](./domain.md) — domain doc consumer rules + layout
+
+For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
+
+### 5. Done
+
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

package/skills/setup/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/skills/setup/issue-tracker-github.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/skills/setup/issue-tracker-gitlab.md

@@ -0,0 +1,23 @@
+# Issue tracker: GitLab
+
+Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list --state opened -F json` with appropriate `--label` filters. Note that GitLab uses `opened` (not `open`) for the state value.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.

package/skills/setup/issue-tracker-local.md

@@ -0,0 +1,19 @@
+# Issue tracker: Local Markdown
+
+Issues and PRDs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The PRD is `.scratch/<feature-slug>/PRD.md`
+- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.

package/skills/setup/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.