cdragon 0.1.0

package/skills/herdr-cli/scripts/herdr-agent-wait-complete

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import subprocess
+import sys
+import time
+
+
+COMPLETION_STATUSES = ("idle", "done")
+ATTENTION_STATUSES = ("blocked",)
+WATCHED_STATUSES = COMPLETION_STATUSES + ATTENTION_STATUSES
+
+
+def run_json(args):
+    result = subprocess.run(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    if result.returncode != 0:
+        return None, result
+    try:
+        return json.loads(result.stdout), result
+    except json.JSONDecodeError:
+        return None, result
+
+
+def pane_status(pane_id):
+    data, result = run_json(["herdr", "pane", "get", pane_id])
+    if data is None:
+        return None, result
+    return data["result"]["pane"].get("agent_status"), result
+
+
+def wait_status(pane_id, status, timeout_ms):
+    return subprocess.Popen(
+        ["herdr", "wait", "agent-status", pane_id, "--status", status, "--timeout", str(timeout_ms)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+
+def wait_for_start(pane_id, start_timeout_ms):
+    deadline = time.time() + (start_timeout_ms / 1000)
+    last_status = None
+    last_error = None
+    while time.time() < deadline:
+        status, result = pane_status(pane_id)
+        if status is None:
+            last_error = result.stderr.strip() or result.stdout.strip()
+        else:
+            last_status = status
+            if status == "working":
+                return "working", None
+            if status in ATTENTION_STATUSES:
+                return status, None
+        time.sleep(0.1)
+    return last_status, last_error
+
+
+def race_completion(pane_id, timeout_ms):
+    procs = {status: wait_status(pane_id, status, timeout_ms) for status in WATCHED_STATUSES}
+    deadline = time.time() + (timeout_ms / 1000)
+    winner = None
+
+    while time.time() < deadline:
+        for status, proc in list(procs.items()):
+            rc = proc.poll()
+            if rc is not None:
+                stdout, stderr = proc.communicate()
+                if rc == 0:
+                    winner = (status, stdout.strip(), stderr.strip())
+                    break
+                procs.pop(status, None)
+        if winner:
+            break
+        time.sleep(0.1)
+
+    for proc in procs.values():
+        if proc.poll() is None:
+            proc.terminate()
+            try:
+                proc.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+
+    return winner
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Wait for a herdr agent task to complete as idle/done, or return promptly on blocked."
+    )
+    parser.add_argument("pane_id")
+    parser.add_argument("--timeout", type=int, default=120000, help="completion timeout in ms")
+    parser.add_argument(
+        "--start-timeout",
+        type=int,
+        default=10000,
+        help="time in ms to observe working before racing idle/done",
+    )
+    parser.add_argument(
+        "--no-wait-working",
+        action="store_true",
+        help="skip the initial working observation and immediately race idle/done",
+    )
+    args = parser.parse_args()
+
+    if not args.no_wait_working:
+        start_status, start_error = wait_for_start(args.pane_id, args.start_timeout)
+        if start_status in ATTENTION_STATUSES:
+            print(
+                json.dumps(
+                    {
+                        "completed_status": None,
+                        "status": start_status,
+                        "phase": "attention",
+                        "pane_id": args.pane_id,
+                        "event": None,
+                    }
+                )
+            )
+            return 2
+        if start_status != "working":
+            print(
+                json.dumps(
+                    {
+                        "error": "agent did not enter working before start timeout",
+                        "pane_id": args.pane_id,
+                        "last_status": start_status,
+                        "last_error": start_error,
+                    }
+                ),
+                file=sys.stderr,
+            )
+            return 1
+
+    winner = race_completion(args.pane_id, args.timeout)
+    if winner:
+        status, stdout, stderr = winner
+        phase = "attention" if status in ATTENTION_STATUSES else "completion"
+        print(
+            json.dumps(
+                {
+                    "completed_status": status if status in COMPLETION_STATUSES else None,
+                    "status": status,
+                    "phase": phase,
+                    "pane_id": args.pane_id,
+                    "event": json.loads(stdout) if stdout else None,
+                }
+            )
+        )
+        return 2 if status in ATTENTION_STATUSES else 0
+
+    status, result = pane_status(args.pane_id)
+    print(
+        json.dumps(
+            {
+                "error": "timed out waiting for idle, done, or blocked",
+                "pane_id": args.pane_id,
+                "last_status": status,
+                "pane_get_stderr": result.stderr.strip() if result else None,
+            }
+        ),
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/notion-presentation/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: notion-presentation
+description: Use this skill whenever the user wants to create, design, or restructure a presentation document inside Notion — especially for Notion's presentation mode (where `---` becomes a slide break and headings become slide titles). Trigger on phrases like "노션 프레젠테이션", "프레젠테이션 모드", "노션으로 발표자료", "슬라이드 문서", "Notion presentation", "make slides in Notion", or when the user pastes a Notion URL and asks to turn it into slides. Also use when the user has a topic, outline, or technical content that needs to be converted into a polished, designer-quality Notion slide deck. The skill blends traditional presentation craft (narrative arc, rule of three, visual hierarchy, contrast, metaphor) with Notion-native blocks (callouts, columns, toggles, Mermaid, tables, inline color) so the result reads like something a senior designer or technical evangelist would produce — not a wall of bullets.
+---
+
+# Notion Presentation Builder
+
+This skill produces **designer-grade Notion presentation documents** that work in Notion's presentation mode. The goal is not "a Notion page with headings" — it is a slide deck that survives standing on a stage, with deliberate rhythm, visual hierarchy, and a strong narrative arc.
+
+## When to use this skill
+
+- The user wants to turn a topic, outline, or raw content into a Notion presentation
+- The user references Notion's presentation mode (`---` as slide break, headings as titles)
+- The user shares a Notion URL and asks to restructure it into slides
+- The user gives you an existing slide spec and asks you to "build it properly" in Notion
+
+If the request is for a static document (report, wiki page, spec), this skill is **not** the right tool — use plain Notion markdown instead.
+
+## Core mental model
+
+Notion presentation mode has two non-negotiable rules:
+
+1. **`---` (a horizontal divider) starts a new slide.**
+2. **Headings (`#`, `##`, `###`) become the slide title.** Use `#` for the main title of each slide; reserve `##` / `###` for in-slide section headers.
+
+Everything else is just Notion blocks — but the *combination* of blocks is what separates a good deck from a bad one. A great Notion slide uses 2–4 different block types arranged with intent. A bad one is a bulleted list pretending to be a slide.
+
+## Before you start: interview the user (briefly)
+
+If the user hasn't already provided structure, ask just enough to design well. Don't over-ask — pick 1–3 of these depending on what's missing:
+
+- **Audience**: technical engineers? executives? mixed?
+- **Length**: how many slides? (default: 8–12 if not specified)
+- **Tone**: formal / conversational / technical-with-personality?
+- **Format constraints**: are they presenting live, or sharing the doc async? (Live = simpler slides, async = more text OK.)
+- **Existing material**: do they have an outline, or are you building from a topic?
+
+If they already gave a detailed slide-by-slide spec (like the Redis example), skip the interview and execute.
+
+## The narrative spine (apply to every deck)
+
+Strong decks follow a story, not a table of contents. Map the slides to this arc:
+
+| Phase | Purpose | Typical slides |
+|---|---|---|
+| **Hook** | Pull the audience in with tension, a counterintuitive claim, or a vivid number | 1 |
+| **Problem / Question** | Establish *why this matters now* | 1–2 |
+| **Tension / Tradeoff** | Show the conventional answer is incomplete | 1 |
+| **Core insight** | The "aha" — the central thesis of the deck | 1 |
+| **Body (deep dive)** | Evidence, mechanisms, examples — usually 3–5 sub-points (rule of three works) | 3–6 |
+| **Nuance / Counter** | Address the "yes but…" — shows intellectual honesty | 1 |
+| **Summary + action** | What to remember, what to do Monday morning | 1 |
+
+Not every deck needs all phases, but **every deck needs Hook → Insight → Body → Summary** at minimum. If you can't identify the hook and the insight, the deck isn't ready to build.
+
+## Slide design patterns
+
+A slide is one of these archetypes. Mixing archetypes is what creates visual rhythm — *never* build a deck where every slide looks the same.
+
+### 1. Title slide (Hook)
+- One bold H1 with the actual claim, not "Introduction"
+- One short framing paragraph (1–2 sentences)
+- One callout with the *provocative* version of the thesis
+- Optionally: inline-code keywords as a teaser
+
+### 2. Question / Tension slide
+- H1 phrased as a question or a contrarian statement (`🤔 의문: …` works well)
+- **Two-column layout**: conventional wisdom on the left, reality/data on the right
+- End with a callout that frames the actual problem
+
+### 3. Mechanism / Diagram slide
+- H1 names the mechanism
+- 2–4 lines of prose explaining the *what*
+- A Mermaid diagram (flowchart, sequence, or comparison)
+- Optional callout for the takeaway
+
+### 4. Comparison slide
+- Either a **table** (when 3+ items, 2+ attributes) or **two-column callouts** (when comparing exactly 2 things)
+- Use color coding: green for the "winning" side, red/orange for the losing side, never both neutral
+
+### 5. Progressive disclosure slide
+- H1 states the claim
+- 2–4 toggles (`<details>`) — each one a sub-point with the *headline* visible and the *details* hidden
+- This is great when you have a "3 reasons why X" structure and don't want to overwhelm the slide
+
+### 6. Numbered breakdown slide ("the rule of three")
+- H1 names the breakdown
+- 3 sub-headers (`##`) with short prose under each
+- Three is the magic number — two feels thin, four feels like a list
+
+### 7. Code / protocol slide
+- H1 names the artifact
+- A short prose lead-in
+- A code block (use the right language tag)
+- A callout explaining what's notable about it
+
+### 8. Summary slide
+- H1 with a recap claim
+- A checklist (`- [ ]`) of the things to remember / do
+- One final callout with the single sentence the audience should leave with
+
+## Notion block toolkit (when to use what)
+
+Use the [enhanced markdown spec](notion://docs/enhanced-markdown-spec) for exact syntax. Key blocks and their best use:
+
+- **Callout** (`<callout icon="…" color="…_bg">`): the single most important Notion block. Use 1–2 per slide to highlight the thesis, warning, or aha moment. Pick the icon and color deliberately:
+  - 💡 `blue_bg` — insight, tip
+  - ⚠️ `red_bg` — warning, anti-pattern
+  - 🎯 `yellow_bg` / `green_bg` — key claim, summary
+  - 📌 `gray_bg` — neutral note, aside
+  - 🔥 `orange_bg` — practical / hot tip
+- **Columns** (`<columns><column>…</column>…</columns>`): use for compare/contrast. Two columns is ideal; three only if the items are very short.
+- **Toggle** (`<details><summary>…</summary>…</details>`): use when you have a punchy headline and want to keep details available without cluttering the slide.
+- **Mermaid** (` ```mermaid `): use for flow, sequence, state, comparison. Always wrap node labels with special characters in double quotes (`A["Notion (App)"]`). Use `<br>` for line breaks, not `\n`.
+- **Tables**: use when you have ≥3 rows and ≥2 columns of structured data. With 1–2 rows, a callout or columns reads better.
+- **Inline color** (`<span color="red">…</span>`): use very sparingly — usually for a single number or word per slide. Overuse kills the effect.
+- **Inline code** (`` `text` ``): use for technical keywords, command names, API names. Adds visual texture and reads as "expert".
+- **Checklist** (`- [ ]`): use on summary slides for "things to remember" or "things to avoid". The unchecked-box visual reads as "action items".
+
+## Visual rhythm rules
+
+These are the rules that separate a designer-quality deck from a "Claude made me a slide deck" deck:
+
+1. **No two adjacent slides should use the same archetype.** If slide 3 is a two-column comparison, slide 4 shouldn't be. Vary the visual.
+2. **Every slide should have at least one non-text block** (callout, diagram, table, columns, code). A slide that is only headings + paragraphs + bullets is a weak slide.
+3. **Color is signal, not decoration.** Use the same color for the same meaning across the whole deck (e.g., red_bg always = warning; green_bg always = the answer). Don't randomly color callouts.
+4. **One thesis per slide.** If you can't summarize the slide in a single sentence, it's two slides.
+5. **Concrete numbers beat adjectives.** "Very fast" → "<1ms p99 latency". Every body slide should have at least one concrete data point if the topic allows it.
+6. **Metaphors carry mechanism slides.** The Redis epoll = restaurant waiter analogy was load-bearing in the example deck. When explaining a mechanism, reach for a vivid concrete analogy and lay it out in a two-column callout.
+7. **Whitespace is created with `<empty-block/>`**, but you almost never need it. Notion spaces blocks well by default — only add empty blocks inside columns or callouts where the rhythm feels too tight.
+
+## Working with Notion via MCP
+
+When the user provides a Notion URL:
+
+1. **Fetch the page first** with `mcp__notion__notion-fetch` to see current content and confirm you have the right page.
+2. **Read the enhanced markdown spec** if you haven't already in this session — fetch `notion://docs/enhanced-markdown-spec` via the MCP resource tool. Don't guess Notion-flavored markdown syntax; it has subtle differences from standard markdown (e.g., `<details>` not `<summary>` alone, tab indentation, escape rules).
+3. **Use `replace_content`** (via `mcp__notion__notion-update-page`) for full deck rewrites. Use `update_content` with `content_updates` for targeted slide edits.
+4. **Preserve child pages**: if the page has `<page>` or `<database>` blocks you want to keep, include them in the new content. `replace_content` will refuse to delete them unless you pass `allow_deleting_content: true`.
+
+If the user gives you content but no URL, write the markdown directly and ask where to put it.
+
+## Output checklist (run this before you finish)
+
+Before declaring the deck done, mentally walk through it:
+
+- [ ] Slide 1 has a real claim, not "Introduction" or "Agenda"
+- [ ] The narrative arc is identifiable (Hook → Insight → Body → Summary at minimum)
+- [ ] No two adjacent slides use the same archetype
+- [ ] Every slide has at least one non-text block
+- [ ] Callout colors are consistent in meaning across the deck
+- [ ] At least one Mermaid diagram, one table or columns layout, and one callout in the deck
+- [ ] The summary slide has actionable content, not just recap
+- [ ] All Mermaid node labels with parens or special chars are double-quoted
+- [ ] If presentation mode is the target: `---` between every slide, `#` as every slide title
+
+If any of these fail, fix before handing off.
+
+## Worked example (mini)
+
+For deeper reference patterns, see `references/example-redis-deck.md` — a complete 10-slide deck on a technical topic that demonstrates every archetype above.
+
+## Anti-patterns to avoid
+
+- **Wall-of-bullets slides.** If a slide is just `- item` × 6, it failed. Convert to columns, table, toggles, or split into two slides.
+- **Every slide has the same callout color.** That's not signal, it's wallpaper.
+- **Title slides that say "Agenda" or "Overview".** Lead with the claim.
+- **Mermaid diagrams with cramped labels.** If the label is >4 words, use `<br>` or rethink the diagram.
+- **Code blocks with no surrounding context.** Always sandwich code between a setup line and a callout-style takeaway.
+- **Forgetting the presentation mode rules.** A document with `##` titles and no `---` dividers does not work in presentation mode. Always use `#` + `---`.

package/skills/notion-presentation/references/example-redis-deck.md

@@ -0,0 +1,97 @@
+# Worked example: Redis singlethread deck (10 slides)
+
+This is a reference deck demonstrating every archetype and block pattern from SKILL.md. Read it when you need a concrete model of what a "designer-grade" Notion presentation looks like end-to-end.
+
+## Narrative arc used
+
+| Slide | Phase | Archetype |
+|---|---|---|
+| 1 | Hook | Title (claim + callout teaser) |
+| 2 | Problem | Question + two-column compare |
+| 3 | Tension | Mechanism + Mermaid flowchart |
+| 4 | Insight | Numbered breakdown via toggles |
+| 5 | Body ① | Comparison (table + Mermaid) |
+| 6 | Body ② | Mechanism + metaphor (two-column callouts) |
+| 7 | Body ③+④ | Code / protocol |
+| 8 | Body ⑤ | Mechanism + Mermaid sequence diagram |
+| 9 | Nuance | Counter-argument with versioned bullets |
+| 10 | Summary | Recap + checklist + final callout |
+
+Notice the rhythm: no two adjacent slides share an archetype. Mermaid appears on slides 3, 5, 8 — spaced out, not back-to-back. Callouts appear on every slide but with different colors meaning different things (blue=insight, red=warning, green=answer, yellow=key claim, orange=practical tip).
+
+## Full deck source
+
+```markdown
+# 싱글스레드 Redis가 수십만 QPS를 내는 아키텍처의 비밀
+
+**발표 목적**: 멀티코어 서버 시대에 Redis가 '싱글스레드'를 선택한 의도와, 그럼에도 불구하고 압도적인 성능(수십만~수백만 QPS)을 유지하는 **5가지 구조적 비밀**을 아키텍트의 시각에서 파헤칩니다.
+
+<callout icon="💡" color="blue_bg">
+	**싱글스레드니까 느리다?** 멀티코어가 무조건 빠르다는 편견을 깨는 Redis의 설계 철학
+</callout>
+
+키워드: `Single-Threaded` · `QPS(Queries Per Second)` · `Latency < 1ms`
+
+---
+
+# 🤔 의문: 8코어 서버에서 코어를 하나만 쓰면 7개는 노는 것 아닌가?
+
+<columns>
+	<column>
+		## 일반적인 통념
+		멀티코어를 병렬로 활용해야 무조건 빠른 시스템이다? ❌
+		<empty-block/>
+		8코어 중 1코어만 사용 ➡️ **"비효율적이다?"**
+	</column>
+	<column>
+		## 실제 벤치마크 성능
+		**평균 응답 시간**: <span color="green">**1ms 이하**</span>
+		<empty-block/>
+		**파이프라인 활용 시**
+		- Set: <span color="green">**153만 QPS**</span>
+		- Get: <span color="green">**181만 QPS**</span>
+	</column>
+</columns>
+
+<callout icon="⚠️" color="red_bg">
+	Redis가 느려지는 대부분의 경우는 싱글스레드여서가 아니라, **무거운 연산(O(N))이나 너무 큰 데이터**를 조작할 때입니다.
+</callout>
+
+---
+
+# ⚖️ 멀티스레드가 무조건 빠르지 않은 이유
+
+- **공유 자원 경쟁 및 락(Lock) 비용**
+- **컨텍스트 스위칭(Context Switching)**
+- **CPU 캐시 일관성(Cache Coherence) 유지 비용**
+
+`​``mermaid
+graph TD
+    A["멀티스레드 환경"] --> B("공유 자원 접근")
+    B --> C["락 획득 경쟁/대기"]
+    B --> D["컨텍스트 스위칭 오버헤드"]
+    C --> F(("성능 선형 증가 저해"))
+    D --> F
+    style F fill:#ffcccc,stroke:#333,stroke-width:2px
+`​``
+```
+
+(The deck continues for 10 slides total — see the actual Notion page if regenerating.)
+
+## Why each pattern worked
+
+- **Slide 1 callout** uses a question-as-claim ("싱글스레드니까 느리다?") instead of just stating the topic. This creates tension immediately.
+- **Slide 2 columns** put conventional wisdom against real data side-by-side. The reader does the comparison instinctively.
+- **Slide 3 Mermaid** uses convergence (multiple nodes → one) to visualize "all these costs add up". The styled end-node (`fill:#ffcccc`) acts as the punchline.
+- **Slide 4 toggles** hide details so the slide reads as "3 reasons, expand for depth" — perfect for a live presentation where the speaker discusses what's hidden.
+- **Slide 5 table** is used because there are 4 storage tiers × 3 attributes — too much for prose, just right for a table.
+- **Slide 6 two-column callouts** carry the restaurant-waiter metaphor. The metaphor is the slide; the technical content sits inside the analogy.
+- **Slide 10 checklist** uses `- [ ]` not `-` because unchecked boxes signal "things to do", which is exactly what the audience should leave with.
+
+## What to copy
+
+- The color discipline (red=warning, green=answer, blue=insight, yellow=claim, orange=tip)
+- The archetype rotation (no two adjacent slides look alike)
+- The use of metaphor on mechanism-heavy slides
+- The Mermaid styling for emphasis (filled end-nodes act like a punctuation mark)
+- The final callout that gives the audience one sentence to leave with

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

@@ -0,0 +1,127 @@
+---
+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/` — 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
+
+If — and only if — the user picked **GitHub** or **GitLab**, ask one follow-up:
+
+> Explainer: Open-source repos often receive feature requests as pull requests, not just issues — a PR is an issue with attached code. If you turn this on, `/triage` pulls *external* PRs into the same queue and runs them through the same labels and states as issues (collaborators' in-flight PRs are left alone). Leave it off if PRs aren't a request surface for you.
+
+- **PRs as a request surface** — yes / no (default: no). Record the answer in `docs/agents/issue-tracker.md`. For local-markdown and other trackers, skip this question — there are no PRs.
+
+**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`, `diagnosing-bugs`, `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, plus whether external PRs are a triage surface]. 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-matt-pocock-skills/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 `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) 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 `/domain-modeling`).
+
+## 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-matt-pocock-skills/issue-tracker-github.md

@@ -0,0 +1,34 @@
+# 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.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## 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`.