axiom-coding-agent-setup 1.1.1 → 1.3.0

package/.agents/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why*, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/.agents/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/.agents/skills/domain-modeling/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily: only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up: capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/.agents/skills/domain-modeling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Domain Modeling"
+  short_description: "Build and sharpen a domain model"

package/.agents/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+---
+
+Call the Skill tool twice, for "grilling" and "domain-modeling".

package/.agents/skills/grill-with-docs/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill with Docs"
+  short_description: "Grill a design and write its docs"
+policy:
+  allow_implicit_invocation: false

package/.agents/skills/grilling/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/.agents/skills/grilling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Grilling"
+  short_description: "Stress-test thinking a round of questions at a time"

package/.agents/skills/huggingface-deployment/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: huggingface-deployment
+description: Deploy and auto-deploy apps to Hugging Face Spaces from a GitHub repository. Use when setting up HF Space deployment pipelines, fixing Space build/CONFIG errors, debugging failed deploys, checking Space state, or diagnosing HF rate-limit failures. Triggers - "deploy to huggingface", "hf space", "huggingface sync", "CONFIG_ERROR", "space rebuild", "429 hub", "git push space".
+---
+
+# Hugging Face Space Deployment via GitHub
+
+## Overview
+
+How to deploy a project to a Hugging Face Space automatically whenever a GitHub repository is updated, hard lessons learned from a real production failure (rate-limited mid-deploy, broken/emptied Space), and the APIs used to debug Space state.
+
+Core deployment strategies (in order of preference):
+
+| Strategy                                   | How                                                      | Pros                                                               | Cons                                                                                  |
+| ------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| **`git push space`** (recommended)         | CI pushes git history directly to the Space's git remote | 1 commit per push; incremental; native deletions; no SDK           | Pushes all git-tracked files; needs LFS tracked properly                              |
+| **Official `huggingface/hub-sync` action** | GitHub Action that mirrors files via the `hf` CLI        | Zero-config; auto-excludes `.github/` + `.git/`; handles deletions | Mirror-based (not git-to-git); still commit-per-hook under the hood for large folders |
+| **`hf upload` / `upload_folder` script**   | Python API bulk upload with `ignore_patterns`            | Full control over ignore list                                      | Easy to trip commit rate limits if implemented as delete-per-file + upload            |
+| ~~Wipe-everything-then-upload~~            | `delete_file()` loop + `upload_folder`                   | (none — anti-pattern)                                              | Burns ~1 commit **per deleted file**; a mid-run failure leaves the Space half-emptied |
+
+---
+
+## When to Use This Skill
+
+- Setting up auto-deployment: GitHub repo → Hugging Face Space (same as Vercel/GH Pages flow)
+- Space shows `CONFIG_ERROR` / "Missing configuration in README"
+- Deploy job fails with `429 Too Many Requests ... commit rate limit`
+- Space state looks wrong after a failed deploy (files missing, only partial tree)
+- Choosing between `git push`, `hub-sync`, and `upload_folder` for a Space
+
+---
+
+## Prerequisites (What a Working Space Needs)
+
+1. **`README.md` with YAML front matter at the very top** — this _is_ the Space's build config. Without it HF shows:
+
+   ```
+   configuration error
+   Missing configuration in README
+   Base README.md template:
+   ---
+   title: {{title}}
+   emoji: {{emoji}}
+   colorFrom: {{colorFrom}}
+   colorTo: {{colorTo}}
+   sdk: {{sdk}}
+   sdk_version: "{{sdkVersion}}"
+   {{#pythonVersion}}
+   python_version: "{{pythonVersion}}"
+   {{/pythonVersion}}
+   app_file: app.py
+   pinned: false
+   ---
+   ```
+
+   - `sdk`: `gradio` | `streamlit` | `static` | `docker` | `panel` | etc.
+   - The error above is ALSO shown when `README.md` is missing entirely (e.g. failed deploy) — don't assume the front matter is malformed; check whether the file exists on the Space first (see Debugging).
+
+2. **`requirements.txt` at repo root** — HF Spaces installs from this (it does NOT read `pyproject.toml`/`uv.lock` unless visible; keep `requirements.txt` authoritative).
+
+3. **App file in repo root** matching `app_file` (usually `app.py`).
+
+4. **GitHub secret `HF_TOKEN`** — a HF access token with write access to the Space, added in GitHub repo Settings → Secrets and variables → Actions.
+
+---
+
+## Recommended Setup: GitHub Workflow
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to Hugging Face Space
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: # manual re-run after rate-limit recovery
+
+jobs:
+  deploy-to-hf:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history — HF's pre-receive hook scans every pushed commit
+          lfs: true # required whenever any tracked file matches .gitattributes LFS patterns
+
+      - name: Push to HF Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          SPACE_REPO: <HF_USERNAME>/<SPACE_NAME>
+        run: |
+          git lfs install
+          git remote add space "https://user:${HF_TOKEN}@huggingface.co/spaces/${SPACE_REPO}"
+          git push space main --force
+```
+
+Key mechanics:
+
+- `git push --force` to the Space is **reconciling**: adds, updates, AND deletes files to match the repo — no wipe step needed, and a failed run can't half-emptied the Space (unlike a delete-all-then-upload script).
+- **1 git push = 1 commit on HF** — the entire commit-rate-limit problem disappears. There is no need to delete per file. Delete files in git; push; they're deleted on the Space.
+- LFS objects (assets, PDFs, models under `.gitattributes` tracking) upload automatically with the push because the Space remote supports Git LFS natively. `checkout` with `lfs: true` ensures the runner has the objects.
+- `fetch-depth: 0`: HF scans history on push; shallow pushes with binary blobs in parents can be rejected — full history + LFS avoids surprises.
+
+### Deployment scope is defined by git tracking, not an ignore list
+
+The workflow deploys exactly what `git ls-files` outputs. Before wiring it up, run:
+
+```bash
+git ls-files    # everything that will land on the Space
+```
+
+- Sensitive files (`.env`) must be `gitignored` — never rely on a deploy ignore list to catch them.
+- Data/runtime dirs (`data/output/*`, uploaded user files, model outputs) belong in `.gitignore`.
+- Non-needed extras (agent docs, local tool configs) may ride along harmlessly if you prefer parity-by-tracking over extra ignores — decide consciously.
+
+---
+
+## Alternative: Official Action
+
+```yaml
+steps:
+  - uses: actions/checkout@v6
+  - uses: huggingface/hub-sync@v0.1.0
+    with:
+      github_repo_id: ${{ github.repository }}
+      huggingface_repo_id: username/my-space
+      hf_token: ${{ secrets.HF_TOKEN }}
+```
+
+Mirrors file contents (not git history), excludes `.github/` and `.git/` automatically, and removes Hub files that were removed from GitHub. Files >10MB must be tracked with Git LFS. Use this when you don't want the Space to share your git history at all.
+
+---
+
+## Rate Limits (Failure Mode That Took Down a Real Space)
+
+Hub commit quota is a **user-action rate limit** (not part of the published 5-minute-window API/resolver tiers). Empirically observed on a free account:
+
+```
+429 Too Many Requests — You have exceeded the rate limit for repository commits
+(128 per hour). You can retry this action in about 1 hour.
+```
+
+Key facts:
+
+- The limit counts **commits regardless of success/failure**, including retried failed ones — a failed upload mid-run still spent budget.
+- `delete_file()` is **one commit per file**. Wiping a 70-file Space ≈ 70 commits.
+- `upload_folder` splits into multiple commits (auto-splits at ~50–100 files per commit for large folders).
+- Three deploys in one hour ≈ far over budget → mid-upload 429 → Space left empty → rebuild error.
+
+Recovery from a 429:
+
+1. Wait for the window to reset (the error message states the cooldown, usually ~1 hour).
+2. Re-run the workflow via `workflow_dispatch` (Actions tab → Run workflow) — no new commit needed if `main` is already correct.
+3. Local runs (running the same script locally with the HF token) hit the **same account-level** quota.
+
+If you must clean a repo where per-file deletes are otherwise unavoidable, batch them into a single commit:
+
+```python
+from huggingface_hub import HfApi
+from huggingface_hub.hf_api import CommitOperationDelete
+
+api.create_commit(
+    repo_id="user/space", repo_type="space", token=token,
+    operations=[CommitOperationDelete(path=f) for f in existing_files],
+    commit_message="Clear existing files",
+)
+```
+
+---
+
+## Debugging a Space
+
+### State inspection (works even when the UI is confusing)
+
+```python
+import os, requests
+from dotenv import load_dotenv
+load_dotenv()
+h = {"Authorization": f"Bearer {os.environ['HF_TOKEN']}"}
+
+# Files currently on the Space
+r = requests.get("https://huggingface.co/api/spaces/<USER>/<SPACE>/tree/main", headers=h)
+print(r.status_code, [f["path"] for f in r.json()])
+
+# Space runtime/config status (runtime stage: RUNNING | BUILDING | CONFIG_ERROR | ...)
+s = requests.get("https://huggingface.co/api/spaces/<USER>/<SPACE>", headers=h)
+print(s.json().get("runtime", {}).get("stage"))
+```
+
+- `CONFIG_ERROR` + tree missing `README.md`/`app.py` → deploy died mid-run; find the failing workflow run's log (`gh run view <run-id> --log-failed`) — usually a 429 or upload exception — then fix root cause and re-run.
+- `CONFIG_ERROR` + `README.md` present → front matter is actually malformed; the template block above tells you exactly what HF expects.
+
+### Workflow failures
+
+```bash
+gh run list -R <OWNER>/<REPO> --limit 3          # history
+gh run view <id> --log-failed -R <OWNER>/<REPO>  # the exception
+gh workflow run deploy.yml -R <OWNER>/<REPO>     # manual rerun (workflow_dispatch)
+```
+
+### Space runtime issues
+
+- **Logs tab** on the Space page is the only source of runtime (build/runtime) errors — config errors surface in the Space UI, not the GitHub Action log.
+- Wrong `app_file` / missing root entry file → build succeeds, app fails. `app_file` must match exactly.
+
+### After any Space-altering change
+
+Check: file tree is complete (`tree/main` shows expected set), README front matter intact, and the Space's runtime stage becomes `RUNNING` after build.
+
+---
+
+## Gotchas
+
+- **Rate limit is per account/token across everything**, so a local test run and a CI run share the same budget.
+- The Hub's pre-receive hook scans **every commit in the push**, not just the tip — and since the move to Xet storage it **rejects raw binary files** not stored via Xet/LFS anywhere in that history, even if the current tree is clean (symptom: `remote: Your push was rejected because it contains binary files` + `Offending files:` list). If that bites, push a single **orphan commit** of the current tree minus raw binaries instead of raw history. Historic binaries committed before an LFS rule was added to `.gitattributes` stay raw in ancestors — adding the LFS rule only changes future commits.
+- **LFS pointer vs file content**: if the runner checks out with `lfs: true`, files in the working copy are real content; pushing to the Space via `git push` uploads the real LFS objects over the remote's LFS endpoint. Without LFS checkout, the Space receives pointer files → 404 on the asset.
+- `upload_folder` failures mid-run are **not transactional** — partial state persists (this is what emptied a real Space down to one directory).
+- Deleting LFS files only frees guardrail-level storage after history is rewritten (`super_squash_history`), but for Spaces the OPPOSITE pattern is fine: force-push resets history, so old Storage-deleted files aren't a top concern.
+- Secrets on the Space come from Space Settings → Variables and secrets (HF side), NOT from GitHub secrets; a `.env` excluded from the repo is still not present at runtime unless you set it in HF Space settings too.
+
+---
+
+## Checklist (Per Deployment Change)
+
+- `README.md` front matter exists and matcher (`sdk`, `app_file`) targets the actual entrypoint and SDK version
+- `requirements.txt` authoritatively lists runtime deps (Free HF Spaces reads only it)
+- GitHub secret `HF_TOKEN` present and has write scope to the Space
+- All Space-relevant files tracked in git; private/user-data files gitignored
+- Workflow file under `.github/workflows/` with `push: branches: [main]` and `workflow_dispatch`
+- Trigger one deploy and watch it complete; verify Space tree completeness and rerun if throttled

package/.agents/skills/implement/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: implement
+description: "Implement a piece of work based on a spec or set of tickets."
+disable-model-invocation: true
+---
+
+Implement the work described by the user in the spec or tickets.
+
+Use /tdd where possible, at pre-agreed seams.
+
+Run typechecking regularly, single test files regularly, and the full test suite once at the end.
+
+Once done, use /code-review to review the work.
+
+Commit your work to the current branch.

package/.agents/skills/implement/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Implement"
+  short_description: "Build work from a spec or tickets"
+policy:
+  allow_implicit_invocation: false

package/.agents/skills/setup-matt-pocock-skills/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: setup-matt-pocock-skills
+description: "Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills."
+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/`: a sign that a local-markdown issue tracker convention is already in use
+- Is the `triage` skill installed? (a `triage` skill folder alongside this one, or `triage` in your available skills.) This decides whether Section B runs at all.
+- Monorepo signals: a `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. These are present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then take the sections in order. One section, one answer, then the next.
+
+Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it (Section B when `triage` isn't installed, Section C when there's no monorepo).
+
+**Section A: Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` 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
+
+Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off**. Leave it off and don't raise it: a user who wants external PRs in the triage queue can flip the flag in the file later.
+
+**Section B: Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you), since an uninstalled skill needs no labels.
+
+If it is installed, ask exactly one question:
+
+> Do you want to keep the default triage labels? (recommended: **yes**)
+
+The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no, usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`), collect the overrides so `triage` applies existing labels instead of creating duplicates.
+
+**Section C: Domain docs.** Default to **single-context** (one `CONTEXT.md` + `docs/adr/` at the repo root). This fits almost every repo; write it without asking.
+
+Offer **multi-context** (a root `CONTEXT-MAP.md` pointing to per-context `CONTEXT.md` files) only when exploration found monorepo signals. Then confirm which layout they want.
+
+### 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/domain.md`, and `docs/agents/triage-labels.md` (the last only when `triage` is installed)
+
+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`.
+```
+
+Include the `### Triage labels` sub-block, and write `docs/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
+
+Then write the 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 (only if `triage` is installed)
+- [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/.agents/skills/setup-matt-pocock-skills/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Setup Matt Pocock Skills"
+  short_description: "Configure a repo for the skills"
+policy:
+  allow_implicit_invocation: false