RSS Reader using AT Protocol
rssbase.io
feed
atom
rss
reader
atproto
social
add mattpocock skills and setup
Romain Gautier
(Jul 7, 2026, 5:14 PM +0200)
1386b92a
f2066670
+2262
+89
.agents/skills/code-review/SKILL.md
+89
.agents/skills/code-review/SKILL.md
···
1
+
---
2
+
name: code-review
3
+
description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
4
+
---
5
+
6
+
Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
7
+
8
+
- **Standards** — does the code conform to this repo's documented coding standards?
9
+
- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
10
+
11
+
Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
12
+
13
+
The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
14
+
15
+
## Process
16
+
17
+
### 1. Pin the fixed point
18
+
19
+
Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
20
+
21
+
Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
22
+
23
+
Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
24
+
25
+
### 2. Identify the spec source
26
+
27
+
Look for the originating spec, in this order:
28
+
29
+
1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
30
+
2. A path the user passed as an argument.
31
+
3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
32
+
4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
33
+
34
+
### 3. Identify the standards sources
35
+
36
+
Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
37
+
38
+
On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
39
+
40
+
- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
41
+
- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
42
+
43
+
Each smell reads *what it is* → *how to fix*; match it against the diff:
44
+
45
+
- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
46
+
- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
47
+
- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
48
+
- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
49
+
- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
50
+
- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
51
+
- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
52
+
- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
53
+
- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
54
+
- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
55
+
- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
56
+
- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
57
+
58
+
### 4. Spawn both sub-agents in parallel
59
+
60
+
Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
61
+
62
+
**Standards sub-agent prompt** — include:
63
+
64
+
- The full diff command and commit list.
65
+
- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
66
+
- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
67
+
68
+
**Spec sub-agent prompt** — include:
69
+
70
+
- The diff command and commit list.
71
+
- The path or fetched contents of the spec.
72
+
- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
73
+
74
+
If the spec is missing, skip the Spec sub-agent and note this in the final report.
75
+
76
+
### 5. Aggregate
77
+
78
+
Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
79
+
80
+
End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
81
+
82
+
## Why two axes
83
+
84
+
A change can pass one axis and fail the other:
85
+
86
+
- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
87
+
- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
88
+
89
+
Reporting them separately stops one axis from masking the other.
+134
.agents/skills/diagnosing-bugs/SKILL.md
+134
.agents/skills/diagnosing-bugs/SKILL.md
···
1
+
---
2
+
name: diagnosing-bugs
3
+
description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
4
+
---
5
+
6
+
# Diagnosing Bugs
7
+
8
+
A discipline for hard bugs. Skip phases only when explicitly justified.
9
+
10
+
When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
11
+
12
+
## Phase 1 — Build a feedback loop
13
+
14
+
**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
15
+
16
+
Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
17
+
18
+
### Ways to construct one — try them in roughly this order
19
+
20
+
1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
21
+
2. **Curl / HTTP script** against a running dev server.
22
+
3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
23
+
4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
24
+
5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
25
+
6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
26
+
7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
27
+
8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
28
+
9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
29
+
10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
30
+
31
+
Build the right feedback loop, and the bug is 90% fixed.
32
+
33
+
### Tighten the loop
34
+
35
+
Treat the loop as a product. Once you have _a_ loop, **tighten** it:
36
+
37
+
- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
38
+
- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
39
+
- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
40
+
41
+
A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
42
+
43
+
### Non-deterministic bugs
44
+
45
+
The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
46
+
47
+
### When you genuinely cannot build a loop
48
+
49
+
Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
50
+
51
+
### Completion criterion — a tight loop that goes red
52
+
53
+
Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
54
+
55
+
- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
56
+
- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
57
+
- [ ] **Fast** — seconds, not minutes.
58
+
- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
59
+
60
+
If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
61
+
62
+
## Phase 2 — Reproduce + minimise
63
+
64
+
Run the loop. Watch it go red — the bug appears.
65
+
66
+
Confirm:
67
+
68
+
- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
69
+
- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
70
+
- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
71
+
72
+
### Minimise
73
+
74
+
Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
75
+
76
+
Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
77
+
78
+
Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
79
+
80
+
Do not proceed until you have reproduced **and** minimised.
81
+
82
+
## Phase 3 — Hypothesise
83
+
84
+
Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
85
+
86
+
Each hypothesis must be **falsifiable**: state the prediction it makes.
87
+
88
+
> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
89
+
90
+
If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
91
+
92
+
**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
93
+
94
+
## Phase 4 — Instrument
95
+
96
+
Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
97
+
98
+
Tool preference:
99
+
100
+
1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
101
+
2. **Targeted logs** at the boundaries that distinguish hypotheses.
102
+
3. Never "log everything and grep".
103
+
104
+
**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
105
+
106
+
**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
107
+
108
+
## Phase 5 — Fix + regression test
109
+
110
+
Write the regression test **before the fix** — but only if there is a **correct seam** for it.
111
+
112
+
A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
113
+
114
+
**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
115
+
116
+
If a correct seam exists:
117
+
118
+
1. Turn the minimised repro into a failing test at that seam.
119
+
2. Watch it fail.
120
+
3. Apply the fix.
121
+
4. Watch it pass.
122
+
5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
123
+
124
+
## Phase 6 — Cleanup + post-mortem
125
+
126
+
Required before declaring done:
127
+
128
+
- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
129
+
- [ ] Regression test passes (or absence of seam is documented)
130
+
- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
131
+
- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
132
+
- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
133
+
134
+
**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+41
.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh
+41
.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh
···
1
+
#!/usr/bin/env bash
2
+
# Human-in-the-loop reproduction loop.
3
+
# Copy this file, edit the steps below, and run it.
4
+
# The agent runs the script; the user follows prompts in their terminal.
5
+
#
6
+
# Usage:
7
+
# bash hitl-loop.template.sh
8
+
#
9
+
# Two helpers:
10
+
# step "<instruction>" → show instruction, wait for Enter
11
+
# capture VAR "<question>" → show question, read response into VAR
12
+
#
13
+
# At the end, captured values are printed as KEY=VALUE for the agent to parse.
14
+
15
+
set -euo pipefail
16
+
17
+
step() {
18
+
printf '\n>>> %s\n' "$1"
19
+
read -r -p " [Enter when done] " _
20
+
}
21
+
22
+
capture() {
23
+
local var="$1" question="$2" answer
24
+
printf '\n>>> %s\n' "$question"
25
+
read -r -p " > " answer
26
+
printf -v "$var" '%s' "$answer"
27
+
}
28
+
29
+
# --- edit below ---------------------------------------------------------
30
+
31
+
step "Open the app at http://localhost:3000 and sign in."
32
+
33
+
capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
34
+
35
+
capture ERROR_MSG "Paste the error message (or 'none'):"
36
+
37
+
# --- edit above ---------------------------------------------------------
38
+
39
+
printf '\n--- Captured ---\n'
40
+
printf 'ERRORED=%s\n' "$ERRORED"
41
+
printf 'ERROR_MSG=%s\n' "$ERROR_MSG"
+47
.agents/skills/domain-modeling/ADR-FORMAT.md
+47
.agents/skills/domain-modeling/ADR-FORMAT.md
···
1
+
# ADR Format
2
+
3
+
ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
4
+
5
+
Create the `docs/adr/` directory lazily — only when the first ADR is needed.
6
+
7
+
## Template
8
+
9
+
```md
10
+
# {Short title of the decision}
11
+
12
+
{1-3 sentences: what's the context, what did we decide, and why.}
13
+
```
14
+
15
+
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.
16
+
17
+
## Optional sections
18
+
19
+
Only include these when they add genuine value. Most ADRs won't need them.
20
+
21
+
- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
22
+
- **Considered Options** — only when the rejected alternatives are worth remembering
23
+
- **Consequences** — only when non-obvious downstream effects need to be called out
24
+
25
+
## Numbering
26
+
27
+
Scan `docs/adr/` for the highest existing number and increment by one.
28
+
29
+
## When to offer an ADR
30
+
31
+
All three of these must be true:
32
+
33
+
1. **Hard to reverse** — the cost of changing your mind later is meaningful
34
+
2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
35
+
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
36
+
37
+
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."
38
+
39
+
### What qualifies
40
+
41
+
- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
42
+
- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
43
+
- **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.
44
+
- **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.
45
+
- **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.
46
+
- **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."
47
+
- **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.
+60
.agents/skills/domain-modeling/CONTEXT-FORMAT.md
+60
.agents/skills/domain-modeling/CONTEXT-FORMAT.md
···
1
+
# CONTEXT.md Format
2
+
3
+
## Structure
4
+
5
+
```md
6
+
# {Context Name}
7
+
8
+
{One or two sentence description of what this context is and why it exists.}
9
+
10
+
## Language
11
+
12
+
**Order**:
13
+
{A one or two sentence description of the term}
14
+
_Avoid_: Purchase, transaction
15
+
16
+
**Invoice**:
17
+
A request for payment sent to a customer after delivery.
18
+
_Avoid_: Bill, payment request
19
+
20
+
**Customer**:
21
+
A person or organization that places orders.
22
+
_Avoid_: Client, buyer, account
23
+
```
24
+
25
+
## Rules
26
+
27
+
- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
28
+
- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
29
+
- **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.
30
+
- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
31
+
32
+
## Single vs multi-context repos
33
+
34
+
**Single context (most repos):** One `CONTEXT.md` at the repo root.
35
+
36
+
**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
37
+
38
+
```md
39
+
# Context Map
40
+
41
+
## Contexts
42
+
43
+
- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
44
+
- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
45
+
- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
46
+
47
+
## Relationships
48
+
49
+
- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
50
+
- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
51
+
- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
52
+
```
53
+
54
+
The skill infers which structure applies:
55
+
56
+
- If `CONTEXT-MAP.md` exists, read it to find contexts
57
+
- If only a root `CONTEXT.md` exists, single context
58
+
- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
59
+
60
+
When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
+74
.agents/skills/domain-modeling/SKILL.md
+74
.agents/skills/domain-modeling/SKILL.md
···
1
+
---
2
+
name: domain-modeling
3
+
description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
4
+
---
5
+
6
+
# Domain Modeling
7
+
8
+
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.)
9
+
10
+
## File structure
11
+
12
+
Most repos have a single context:
13
+
14
+
```
15
+
/
16
+
├── CONTEXT.md
17
+
├── docs/
18
+
│ └── adr/
19
+
│ ├── 0001-event-sourced-orders.md
20
+
│ └── 0002-postgres-for-write-model.md
21
+
└── src/
22
+
```
23
+
24
+
If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
25
+
26
+
```
27
+
/
28
+
├── CONTEXT-MAP.md
29
+
├── docs/
30
+
│ └── adr/ ← system-wide decisions
31
+
├── src/
32
+
│ ├── ordering/
33
+
│ │ ├── CONTEXT.md
34
+
│ │ └── docs/adr/ ← context-specific decisions
35
+
│ └── billing/
36
+
│ ├── CONTEXT.md
37
+
│ └── docs/adr/
38
+
```
39
+
40
+
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.
41
+
42
+
## During the session
43
+
44
+
### Challenge against the glossary
45
+
46
+
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?"
47
+
48
+
### Sharpen fuzzy language
49
+
50
+
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."
51
+
52
+
### Discuss concrete scenarios
53
+
54
+
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.
55
+
56
+
### Cross-reference with code
57
+
58
+
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?"
59
+
60
+
### Update CONTEXT.md inline
61
+
62
+
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).
63
+
64
+
`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.
65
+
66
+
### Offer ADRs sparingly
67
+
68
+
Only offer to create an ADR when all three are true:
69
+
70
+
1. **Hard to reverse** — the cost of changing your mind later is meaningful
71
+
2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
72
+
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
73
+
74
+
If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+7
.agents/skills/grill-with-docs/SKILL.md
+7
.agents/skills/grill-with-docs/SKILL.md
+16
.agents/skills/handoff/SKILL.md
+16
.agents/skills/handoff/SKILL.md
···
1
+
---
2
+
name: handoff
3
+
description: Compact the current conversation into a handoff document for another agent to pick up.
4
+
argument-hint: "What will the next session be used for?"
5
+
disable-model-invocation: true
6
+
---
7
+
8
+
Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
9
+
10
+
Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
11
+
12
+
Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
13
+
14
+
Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
15
+
16
+
If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
+15
.agents/skills/implement/SKILL.md
+15
.agents/skills/implement/SKILL.md
···
1
+
---
2
+
name: implement
3
+
description: "Implement a piece of work based on a PRD or set of issues."
4
+
disable-model-invocation: true
5
+
---
6
+
7
+
Implement the work described by the user in the PRD or issues.
8
+
9
+
Use /tdd where possible, at pre-agreed seams.
10
+
11
+
Run typechecking regularly, single test files regularly, and the full test suite once at the end.
12
+
13
+
Once done, use /code-review to review the work.
14
+
15
+
Commit your work to the current branch.
+123
.agents/skills/improve-codebase-architecture/HTML-REPORT.md
+123
.agents/skills/improve-codebase-architecture/HTML-REPORT.md
···
1
+
# HTML Report Format
2
+
3
+
The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
4
+
5
+
## Scaffold
6
+
7
+
```html
8
+
<!doctype html>
9
+
<html lang="en">
10
+
<head>
11
+
<meta charset="utf-8" />
12
+
<title>Architecture review — {{repo name}}</title>
13
+
<script src="https://cdn.tailwindcss.com"></script>
14
+
<script type="module">
15
+
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
16
+
mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
17
+
</script>
18
+
<style>
19
+
/* small custom layer for things Tailwind doesn't cover cleanly:
20
+
dashed seam lines, hand-drawn-feeling arrow heads, etc. */
21
+
.seam { stroke-dasharray: 4 4; }
22
+
.leak { stroke: #dc2626; }
23
+
.deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
24
+
</style>
25
+
</head>
26
+
<body class="bg-stone-50 text-slate-900 font-sans">
27
+
<main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
28
+
<header>...</header>
29
+
<section id="candidates" class="space-y-10">...</section>
30
+
<section id="top-recommendation">...</section>
31
+
</main>
32
+
</body>
33
+
</html>
34
+
```
35
+
36
+
## Header
37
+
38
+
Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
39
+
40
+
## Candidate card
41
+
42
+
The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
43
+
44
+
Each candidate is one `<article>`:
45
+
46
+
- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
47
+
- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
48
+
- **Files** — monospaced list, `font-mono text-sm`.
49
+
- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
50
+
- **Problem** — one sentence. What hurts.
51
+
- **Solution** — one sentence. What changes.
52
+
- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
53
+
- **ADR callout** (if applicable) — one line in an amber-tinted box.
54
+
55
+
No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
56
+
57
+
## Diagram patterns
58
+
59
+
Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
60
+
61
+
### Mermaid graph (the workhorse for dependencies / call flow)
62
+
63
+
Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
64
+
65
+
```html
66
+
<div class="rounded-lg border border-slate-200 bg-white p-4">
67
+
<pre class="mermaid">
68
+
flowchart LR
69
+
A[OrderHandler] --> B[OrderValidator]
70
+
B --> C[OrderRepo]
71
+
C -.leak.-> D[PricingClient]
72
+
classDef leak stroke:#dc2626,stroke-width:2px;
73
+
class C,D leak
74
+
</pre>
75
+
</div>
76
+
```
77
+
78
+
### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
79
+
80
+
Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
81
+
82
+
### Cross-section (good for layered shallowness)
83
+
84
+
Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
85
+
86
+
### Mass diagram (good for "interface as wide as implementation")
87
+
88
+
Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
89
+
90
+
### Call-graph collapse
91
+
92
+
Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
93
+
94
+
## Style guidance
95
+
96
+
- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
97
+
- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
98
+
- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
99
+
- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
100
+
- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
101
+
102
+
## Top recommendation section
103
+
104
+
One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
105
+
106
+
## Tone
107
+
108
+
Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
109
+
110
+
**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
111
+
112
+
**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
113
+
114
+
**Phrasings that fit the style:**
115
+
116
+
- "Order intake module is shallow — interface nearly matches the implementation."
117
+
- "Pricing leaks across the seam."
118
+
- "Deepen: one interface, one place to test."
119
+
- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
120
+
121
+
**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
122
+
123
+
No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.
+66
.agents/skills/improve-codebase-architecture/SKILL.md
+66
.agents/skills/improve-codebase-architecture/SKILL.md
···
1
+
---
2
+
name: improve-codebase-architecture
3
+
description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
4
+
disable-model-invocation: true
5
+
---
6
+
7
+
# Improve Codebase Architecture
8
+
9
+
Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
10
+
11
+
This command is _informed_ by the project's domain model and built on a shared design vocabulary:
12
+
13
+
- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
14
+
- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
15
+
16
+
## Process
17
+
18
+
### 1. Explore
19
+
20
+
Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
21
+
22
+
Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
23
+
24
+
- Where does understanding one concept require bouncing between many small modules?
25
+
- Where are modules **shallow** — interface nearly as complex as the implementation?
26
+
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
27
+
- Where do tightly-coupled modules leak across their seams?
28
+
- Which parts of the codebase are untested, or hard to test through their current interface?
29
+
30
+
Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
31
+
32
+
### 2. Present candidates as an HTML report
33
+
34
+
Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
35
+
36
+
The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
37
+
38
+
For each candidate, render a card with:
39
+
40
+
- **Files** — which files/modules are involved
41
+
- **Problem** — why the current architecture is causing friction
42
+
- **Solution** — plain English description of what would change
43
+
- **Benefits** — explained in terms of locality and leverage, and how tests would improve
44
+
- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
45
+
- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
46
+
47
+
End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
48
+
49
+
**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
50
+
51
+
**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
52
+
53
+
See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
54
+
55
+
Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
56
+
57
+
### 3. Grilling loop
58
+
59
+
Once the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
60
+
61
+
Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
62
+
63
+
- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
64
+
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
65
+
- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
66
+
- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern.
+130
.agents/skills/qa/SKILL.md
+130
.agents/skills/qa/SKILL.md
···
1
+
---
2
+
name: qa
3
+
description: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session".
4
+
---
5
+
6
+
# QA Session
7
+
8
+
Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.
9
+
10
+
## For each issue the user raises
11
+
12
+
### 1. Listen and lightly clarify
13
+
14
+
Let the user describe the problem in their own words. Ask **at most 2-3 short clarifying questions** focused on:
15
+
16
+
- What they expected vs what actually happened
17
+
- Steps to reproduce (if not obvious)
18
+
- Whether it's consistent or intermittent
19
+
20
+
Do NOT over-interview. If the description is clear enough to file, move on.
21
+
22
+
### 2. Explore the codebase in the background
23
+
24
+
While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:
25
+
26
+
- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
27
+
- Understand what the feature is supposed to do
28
+
- Identify the user-facing behavior boundary
29
+
30
+
This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.
31
+
32
+
### 3. Assess scope: single issue or breakdown?
33
+
34
+
Before filing, decide whether this is a **single issue** or needs to be **broken down** into multiple issues.
35
+
36
+
Break down when:
37
+
38
+
- The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")
39
+
- There are clearly separable concerns that different people could work on in parallel
40
+
- The user describes something that has multiple distinct failure modes or symptoms
41
+
42
+
Keep as a single issue when:
43
+
44
+
- It's one behavior that's wrong in one place
45
+
- The symptoms are all caused by the same root behavior
46
+
47
+
### 4. File the GitHub issue(s)
48
+
49
+
Create issues with `gh issue create`. Do NOT ask the user to review first — just file and share URLs.
50
+
51
+
Issues must be **durable** — they should still make sense after major refactors. Write from the user's perspective.
52
+
53
+
#### For a single issue
54
+
55
+
Use this template:
56
+
57
+
```
58
+
## What happened
59
+
60
+
[Describe the actual behavior the user experienced, in plain language]
61
+
62
+
## What I expected
63
+
64
+
[Describe the expected behavior]
65
+
66
+
## Steps to reproduce
67
+
68
+
1. [Concrete, numbered steps a developer can follow]
69
+
2. [Use domain terms from the codebase, not internal module names]
70
+
3. [Include relevant inputs, flags, or configuration]
71
+
72
+
## Additional context
73
+
74
+
[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]
75
+
```
76
+
77
+
#### For a breakdown (multiple issues)
78
+
79
+
Create issues in dependency order (blockers first) so you can reference real issue numbers.
80
+
81
+
Use this template for each sub-issue:
82
+
83
+
```
84
+
## Parent issue
85
+
86
+
#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"
87
+
88
+
## What's wrong
89
+
90
+
[Describe this specific behavior problem — just this slice, not the whole report]
91
+
92
+
## What I expected
93
+
94
+
[Expected behavior for this specific slice]
95
+
96
+
## Steps to reproduce
97
+
98
+
1. [Steps specific to THIS issue]
99
+
100
+
## Blocked by
101
+
102
+
- #<issue-number> (if this issue can't be fixed until another is resolved)
103
+
104
+
Or "None — can start immediately" if no blockers.
105
+
106
+
## Additional context
107
+
108
+
[Any extra observations relevant to this slice]
109
+
```
110
+
111
+
When creating a breakdown:
112
+
113
+
- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
114
+
- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately"
115
+
- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by"
116
+
- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously
117
+
118
+
#### Rules for all issue bodies
119
+
120
+
- **No file paths or line numbers** — these go stale
121
+
- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists)
122
+
- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"
123
+
- **Reproduction steps are mandatory** — if you can't determine them, ask the user
124
+
- **Keep it concise** — a developer should be able to read the issue in 30 seconds
125
+
126
+
After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"
127
+
128
+
### 5. Continue the session
129
+
130
+
Keep going until the user says they're done. Each issue is independent — don't batch them.
+12
.agents/skills/research/SKILL.md
+12
.agents/skills/research/SKILL.md
···
1
+
---
2
+
name: research
3
+
description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
4
+
---
5
+
6
+
Spin up a **background agent** to do the research, so you keep working while it reads.
7
+
8
+
Its job:
9
+
10
+
1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
11
+
2. Write the findings to a single Markdown file, citing each claim's source.
12
+
3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.
+127
.agents/skills/setup-matt-pocock-skills/SKILL.md
+127
.agents/skills/setup-matt-pocock-skills/SKILL.md
···
1
+
---
2
+
name: setup-matt-pocock-skills
3
+
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.
4
+
disable-model-invocation: true
5
+
---
6
+
7
+
# Setup Matt Pocock's Skills
8
+
9
+
Scaffold the per-repo configuration that the engineering skills assume:
10
+
11
+
- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
12
+
- **Triage labels** — the strings used for the five canonical triage roles
13
+
- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
14
+
15
+
This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
16
+
17
+
## Process
18
+
19
+
### 1. Explore
20
+
21
+
Look at the current repo to understand its starting state. Read whatever exists; don't assume:
22
+
23
+
- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
24
+
- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
25
+
- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
26
+
- `docs/adr/` and any `src/*/docs/adr/` directories
27
+
- `docs/agents/` — does this skill's prior output already exist?
28
+
- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
29
+
30
+
### 2. Present findings and ask
31
+
32
+
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.
33
+
34
+
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.
35
+
36
+
**Section A — Issue tracker.**
37
+
38
+
> 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.
39
+
40
+
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:
41
+
42
+
- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
43
+
- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
44
+
- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
45
+
- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
46
+
47
+
If — and only if — the user picked **GitHub** or **GitLab**, ask one follow-up:
48
+
49
+
> 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.
50
+
51
+
- **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.
52
+
53
+
**Section B — Triage label vocabulary.**
54
+
55
+
> 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.
56
+
57
+
The five canonical roles:
58
+
59
+
- `needs-triage` — maintainer needs to evaluate
60
+
- `needs-info` — waiting on reporter
61
+
- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
62
+
- `ready-for-human` — needs human implementation
63
+
- `wontfix` — will not be actioned
64
+
65
+
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.
66
+
67
+
**Section C — Domain docs.**
68
+
69
+
> 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.
70
+
71
+
Confirm the layout:
72
+
73
+
- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
74
+
- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
75
+
76
+
### 3. Confirm and edit
77
+
78
+
Show the user a draft of:
79
+
80
+
- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
81
+
- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
82
+
83
+
Let them edit before writing.
84
+
85
+
### 4. Write
86
+
87
+
**Pick the file to edit:**
88
+
89
+
- If `CLAUDE.md` exists, edit it.
90
+
- Else if `AGENTS.md` exists, edit it.
91
+
- If neither exists, ask the user which one to create — don't pick for them.
92
+
93
+
Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
94
+
95
+
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.
96
+
97
+
The block:
98
+
99
+
```markdown
100
+
## Agent skills
101
+
102
+
### Issue tracker
103
+
104
+
[one-line summary of where issues are tracked, plus whether external PRs are a triage surface]. See `docs/agents/issue-tracker.md`.
105
+
106
+
### Triage labels
107
+
108
+
[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
109
+
110
+
### Domain docs
111
+
112
+
[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
113
+
```
114
+
115
+
Then write the three docs files using the seed templates in this skill folder as a starting point:
116
+
117
+
- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
118
+
- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
119
+
- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
120
+
- [triage-labels.md](./triage-labels.md) — label mapping
121
+
- [domain.md](./domain.md) — domain doc consumer rules + layout
122
+
123
+
For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
124
+
125
+
### 5. Done
126
+
127
+
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.
+51
.agents/skills/setup-matt-pocock-skills/domain.md
+51
.agents/skills/setup-matt-pocock-skills/domain.md
···
1
+
# Domain Docs
2
+
3
+
How the engineering skills should consume this repo's domain documentation when exploring the codebase.
4
+
5
+
## Before exploring, read these
6
+
7
+
- **`CONTEXT.md`** at the repo root, or
8
+
- **`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.
9
+
- **`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.
10
+
11
+
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.
12
+
13
+
## File structure
14
+
15
+
Single-context repo (most repos):
16
+
17
+
```
18
+
/
19
+
├── CONTEXT.md
20
+
├── docs/adr/
21
+
│ ├── 0001-event-sourced-orders.md
22
+
│ └── 0002-postgres-for-write-model.md
23
+
└── src/
24
+
```
25
+
26
+
Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
27
+
28
+
```
29
+
/
30
+
├── CONTEXT-MAP.md
31
+
├── docs/adr/ ← system-wide decisions
32
+
└── src/
33
+
├── ordering/
34
+
│ ├── CONTEXT.md
35
+
│ └── docs/adr/ ← context-specific decisions
36
+
└── billing/
37
+
├── CONTEXT.md
38
+
└── docs/adr/
39
+
```
40
+
41
+
## Use the glossary's vocabulary
42
+
43
+
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.
44
+
45
+
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`).
46
+
47
+
## Flag ADR conflicts
48
+
49
+
If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
50
+
51
+
> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_
+45
.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md
+45
.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md
···
1
+
# Issue tracker: GitHub
2
+
3
+
Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
4
+
5
+
## Conventions
6
+
7
+
- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
8
+
- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
9
+
- **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.
10
+
- **Comment on an issue**: `gh issue comment <number> --body "..."`
11
+
- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
12
+
- **Close**: `gh issue close <number> --comment "..."`
13
+
14
+
Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
15
+
16
+
## Pull requests as a triage surface
17
+
18
+
**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
19
+
20
+
When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
21
+
22
+
- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
23
+
- **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`).
24
+
- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
25
+
26
+
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`.
27
+
28
+
## When a skill says "publish to the issue tracker"
29
+
30
+
Create a GitHub issue.
31
+
32
+
## When a skill says "fetch the relevant ticket"
33
+
34
+
Run `gh issue view <number> --comments`.
35
+
36
+
## Wayfinding operations
37
+
38
+
Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
39
+
40
+
- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
41
+
- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
42
+
- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
43
+
- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
44
+
- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
45
+
- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
+46
.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md
+46
.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md
···
1
+
# Issue tracker: GitLab
2
+
3
+
Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
4
+
5
+
## Conventions
6
+
7
+
- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
8
+
- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
9
+
- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
10
+
- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
11
+
- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
12
+
- **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.
13
+
- **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`.
14
+
15
+
Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
16
+
17
+
## Merge requests as a triage surface
18
+
19
+
**MRs as a request surface: no.** _(Set to `yes` if this repo treats external merge requests as feature requests; `/triage` reads this flag.)_
20
+
21
+
When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents:
22
+
23
+
- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff.
24
+
- **List external MRs for triage**: `glab mr list -F json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
25
+
- **Comment / label / close**: `glab mr note`, `glab mr update --label`/`--unlabel`, `glab mr close`.
26
+
27
+
Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface the maintainer means.
28
+
29
+
## When a skill says "publish to the issue tracker"
30
+
31
+
Create a GitLab issue.
32
+
33
+
## When a skill says "fetch the relevant ticket"
34
+
35
+
Run `glab issue view <number> --comments`.
36
+
37
+
## Wayfinding operations
38
+
39
+
Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
40
+
41
+
- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
42
+
- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
43
+
- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
44
+
- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
45
+
- **Claim**: `glab issue update <n> --assignee @me` — the session's first write.
46
+
- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
+30
.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md
+30
.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md
···
1
+
# Issue tracker: Local Markdown
2
+
3
+
Issues and PRDs for this repo live as markdown files in `.scratch/`.
4
+
5
+
## Conventions
6
+
7
+
- One feature per directory: `.scratch/<feature-slug>/`
8
+
- The PRD is `.scratch/<feature-slug>/PRD.md`
9
+
- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
10
+
- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
11
+
- Comments and conversation history append to the bottom of the file under a `## Comments` heading
12
+
13
+
## When a skill says "publish to the issue tracker"
14
+
15
+
Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
16
+
17
+
## When a skill says "fetch the relevant ticket"
18
+
19
+
Read the file at the referenced path. The user will normally pass the path or the issue number directly.
20
+
21
+
## Wayfinding operations
22
+
23
+
Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
24
+
25
+
- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
26
+
- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
27
+
- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
28
+
- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
29
+
- **Claim**: set `Status: claimed` and save before any work.
30
+
- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.
+15
.agents/skills/setup-matt-pocock-skills/triage-labels.md
+15
.agents/skills/setup-matt-pocock-skills/triage-labels.md
···
1
+
# Triage Labels
2
+
3
+
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.
4
+
5
+
| Label in mattpocock/skills | Label in our tracker | Meaning |
6
+
| -------------------------- | -------------------- | ---------------------------------------- |
7
+
| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
8
+
| `needs-info` | `needs-info` | Waiting on reporter for more information |
9
+
| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
10
+
| `ready-for-human` | `ready-for-human` | Requires human implementation |
11
+
| `wontfix` | `wontfix` | Will not be actioned |
12
+
13
+
When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
14
+
15
+
Edit the right-hand column to match whatever vocabulary you actually use.
+36
.agents/skills/tdd/SKILL.md
+36
.agents/skills/tdd/SKILL.md
···
1
+
---
2
+
name: tdd
3
+
description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
4
+
---
5
+
6
+
# Test-Driven Development
7
+
8
+
TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
9
+
10
+
When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
11
+
12
+
## What a good test is
13
+
14
+
Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
15
+
16
+
See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
17
+
18
+
## Seams — where tests go
19
+
20
+
A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
21
+
22
+
**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
23
+
24
+
Ask: "What's the public interface, and which seams should we test?"
25
+
26
+
## Anti-patterns
27
+
28
+
- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
29
+
- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
30
+
- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
31
+
32
+
## Rules of the loop
33
+
34
+
- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
35
+
- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
36
+
- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.
+59
.agents/skills/tdd/mocking.md
+59
.agents/skills/tdd/mocking.md
···
1
+
# When to Mock
2
+
3
+
Mock at **system boundaries** only:
4
+
5
+
- External APIs (payment, email, etc.)
6
+
- Databases (sometimes - prefer test DB)
7
+
- Time/randomness
8
+
- File system (sometimes)
9
+
10
+
Don't mock:
11
+
12
+
- Your own classes/modules
13
+
- Internal collaborators
14
+
- Anything you control
15
+
16
+
## Designing for Mockability
17
+
18
+
At system boundaries, design interfaces that are easy to mock:
19
+
20
+
**1. Use dependency injection**
21
+
22
+
Pass external dependencies in rather than creating them internally:
23
+
24
+
```typescript
25
+
// Easy to mock
26
+
function processPayment(order, paymentClient) {
27
+
return paymentClient.charge(order.total);
28
+
}
29
+
30
+
// Hard to mock
31
+
function processPayment(order) {
32
+
const client = new StripeClient(process.env.STRIPE_KEY);
33
+
return client.charge(order.total);
34
+
}
35
+
```
36
+
37
+
**2. Prefer SDK-style interfaces over generic fetchers**
38
+
39
+
Create specific functions for each external operation instead of one generic function with conditional logic:
40
+
41
+
```typescript
42
+
// GOOD: Each function is independently mockable
43
+
const api = {
44
+
getUser: (id) => fetch(`/users/${id}`),
45
+
getOrders: (userId) => fetch(`/users/${userId}/orders`),
46
+
createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
47
+
};
48
+
49
+
// BAD: Mocking requires conditional logic inside the mock
50
+
const api = {
51
+
fetch: (endpoint, options) => fetch(endpoint, options),
52
+
};
53
+
```
54
+
55
+
The SDK approach means:
56
+
- Each mock returns one specific shape
57
+
- No conditional logic in test setup
58
+
- Easier to see which endpoints a test exercises
59
+
- Type safety per endpoint
+77
.agents/skills/tdd/tests.md
+77
.agents/skills/tdd/tests.md
···
1
+
# Good and Bad Tests
2
+
3
+
## Good Tests
4
+
5
+
**Integration-style**: Test through real interfaces, not mocks of internal parts.
6
+
7
+
```typescript
8
+
// GOOD: Tests observable behavior
9
+
test("user can checkout with valid cart", async () => {
10
+
const cart = createCart();
11
+
cart.add(product);
12
+
const result = await checkout(cart, paymentMethod);
13
+
expect(result.status).toBe("confirmed");
14
+
});
15
+
```
16
+
17
+
Characteristics:
18
+
19
+
- Tests behavior users/callers care about
20
+
- Uses public API only
21
+
- Survives internal refactors
22
+
- Describes WHAT, not HOW
23
+
- One logical assertion per test
24
+
25
+
## Bad Tests
26
+
27
+
**Implementation-detail tests**: Coupled to internal structure.
28
+
29
+
```typescript
30
+
// BAD: Tests implementation details
31
+
test("checkout calls paymentService.process", async () => {
32
+
const mockPayment = jest.mock(paymentService);
33
+
await checkout(cart, payment);
34
+
expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
35
+
});
36
+
```
37
+
38
+
Red flags:
39
+
40
+
- Mocking internal collaborators
41
+
- Testing private methods
42
+
- Asserting on call counts/order
43
+
- Test breaks when refactoring without behavior change
44
+
- Test name describes HOW not WHAT
45
+
- Verifying through external means instead of interface
46
+
47
+
```typescript
48
+
// BAD: Bypasses interface to verify
49
+
test("createUser saves to database", async () => {
50
+
await createUser({ name: "Alice" });
51
+
const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
52
+
expect(row).toBeDefined();
53
+
});
54
+
55
+
// GOOD: Verifies through interface
56
+
test("createUser makes user retrievable", async () => {
57
+
const user = await createUser({ name: "Alice" });
58
+
const retrieved = await getUser(user.id);
59
+
expect(retrieved.name).toBe("Alice");
60
+
});
61
+
```
62
+
63
+
**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
64
+
65
+
```typescript
66
+
// BAD: Expected value is recomputed the way the code computes it
67
+
test("calculateTotal sums line items", () => {
68
+
const items = [{ price: 10 }, { price: 5 }];
69
+
const expected = items.reduce((sum, i) => sum + i.price, 0);
70
+
expect(calculateTotal(items)).toBe(expected);
71
+
});
72
+
73
+
// GOOD: Expected value is an independent, known literal
74
+
test("calculateTotal sums line items", () => {
75
+
expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
76
+
});
77
+
```
+84
.agents/skills/to-issues/SKILL.md
+84
.agents/skills/to-issues/SKILL.md
···
1
+
---
2
+
name: to-issues
3
+
description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.
4
+
disable-model-invocation: true
5
+
---
6
+
7
+
# To Issues
8
+
9
+
Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
10
+
11
+
The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
12
+
13
+
## Process
14
+
15
+
### 1. Gather context
16
+
17
+
Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker and read its full body and comments.
18
+
19
+
### 2. Explore the codebase (optional)
20
+
21
+
If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
22
+
23
+
Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
24
+
25
+
### 3. Draft vertical slices
26
+
27
+
Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
28
+
29
+
<vertical-slice-rules>
30
+
31
+
- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
32
+
- A completed slice is demoable or verifiable on its own
33
+
- Any prefactoring should be done first
34
+
35
+
</vertical-slice-rules>
36
+
37
+
### 4. Quiz the user
38
+
39
+
Present the proposed breakdown as a numbered list. For each slice, show:
40
+
41
+
- **Title**: short descriptive name
42
+
- **Blocked by**: which other slices (if any) must complete first
43
+
- **User stories covered**: which user stories this addresses (if the source material has them)
44
+
45
+
Ask the user:
46
+
47
+
- Does the granularity feel right? (too coarse / too fine)
48
+
- Are the dependency relationships correct?
49
+
- Should any slices be merged or split further?
50
+
51
+
Iterate until the user approves the breakdown.
52
+
53
+
### 5. Publish the issues to the issue tracker
54
+
55
+
For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. These issues are considered ready for AFK agents, so publish them with the correct triage label unless instructed otherwise.
56
+
57
+
Publish issues in dependency order (blockers first) so you can reference real issue identifiers. Where the tracker supports it, link each slice to its parent as a native **sub-issue** and wire each blocker as a native **blocking edge** (mechanics in the issue-tracker doc); the `## Parent` and `## Blocked by` body sections are the fallback otherwise.
58
+
59
+
<issue-template>
60
+
## Parent
61
+
62
+
A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
63
+
64
+
## What to build
65
+
66
+
A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation.
67
+
68
+
Avoid specific file paths or code snippets — they go stale fast. Exception: if the `/prototype` skill produced code that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), add a context pointer to where that prototype code lives rather than inlining it.
69
+
70
+
## Acceptance criteria
71
+
72
+
- [ ] Criterion 1
73
+
- [ ] Criterion 2
74
+
- [ ] Criterion 3
75
+
76
+
## Blocked by
77
+
78
+
- A reference to the blocking ticket (if any)
79
+
80
+
Or "None - can start immediately" if no blockers.
81
+
82
+
</issue-template>
83
+
84
+
Do NOT close or modify any parent issue.
+75
.agents/skills/to-prd/SKILL.md
+75
.agents/skills/to-prd/SKILL.md
···
1
+
---
2
+
name: to-prd
3
+
description: Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
4
+
disable-model-invocation: true
5
+
---
6
+
7
+
This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
8
+
9
+
The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
10
+
11
+
## Process
12
+
13
+
1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
14
+
15
+
2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
16
+
17
+
Check with the user that these seams match their expectations.
18
+
19
+
3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
20
+
21
+
<prd-template>
22
+
23
+
## Problem Statement
24
+
25
+
The problem that the user is facing, from the user's perspective.
26
+
27
+
## Solution
28
+
29
+
The solution to the problem, from the user's perspective.
30
+
31
+
## User Stories
32
+
33
+
A LONG, numbered list of user stories. Each user story should be in the format of:
34
+
35
+
1. As an <actor>, I want a <feature>, so that <benefit>
36
+
37
+
<user-story-example>
38
+
1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
39
+
</user-story-example>
40
+
41
+
This list of user stories should be extremely extensive and cover all aspects of the feature.
42
+
43
+
## Implementation Decisions
44
+
45
+
A list of implementation decisions that were made. This can include:
46
+
47
+
- The modules that will be built/modified
48
+
- The interfaces of those modules that will be modified
49
+
- Technical clarifications from the developer
50
+
- Architectural decisions
51
+
- Schema changes
52
+
- API contracts
53
+
- Specific interactions
54
+
55
+
Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
56
+
57
+
Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
58
+
59
+
## Testing Decisions
60
+
61
+
A list of testing decisions that were made. Include:
62
+
63
+
- A description of what makes a good test (only test external behavior, not implementation details)
64
+
- Which modules will be tested
65
+
- Prior art for the tests (i.e. similar types of tests in the codebase)
66
+
67
+
## Out of Scope
68
+
69
+
A description of the things that are out of scope for this PRD.
70
+
71
+
## Further Notes
72
+
73
+
Any further notes about the feature.
74
+
75
+
</prd-template>
+207
.agents/skills/triage/AGENT-BRIEF.md
+207
.agents/skills/triage/AGENT-BRIEF.md
···
1
+
# Writing Agent Briefs
2
+
3
+
An agent brief is a structured comment posted on a GitHub issue or PR when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original body and discussion are context — the agent brief is the contract.
4
+
5
+
The brief states **what the agent should do**, which stretches to both surfaces: for an issue, that's building the change from nothing; for a PR, it's what's left to do *to the existing diff* — finish it, close gaps, address review points. Same principles either way; the PR example below shows the difference.
6
+
7
+
## Principles
8
+
9
+
### Durability over precision
10
+
11
+
The issue may sit in `ready-for-agent` for days or weeks. The codebase will change in the meantime. Write the brief so it stays useful even as files are renamed, moved, or refactored.
12
+
13
+
- **Do** describe interfaces, types, and behavioral contracts
14
+
- **Do** name specific types, function signatures, or config shapes that the agent should look for or modify
15
+
- **Don't** reference file paths — they go stale
16
+
- **Don't** reference line numbers
17
+
- **Don't** assume the current implementation structure will remain the same
18
+
19
+
### Behavioral, not procedural
20
+
21
+
Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make its own implementation decisions.
22
+
23
+
- **Good:** "The `SkillConfig` type should accept an optional `schedule` field of type `CronExpression`"
24
+
- **Bad:** "Open src/types/skill.ts and add a schedule field on line 42"
25
+
- **Good:** "When a user runs `/triage` with no arguments, they should see a summary of issues needing attention"
26
+
- **Bad:** "Add a switch statement in the main handler function"
27
+
28
+
### Complete acceptance criteria
29
+
30
+
The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance criteria. Each criterion should be independently verifiable.
31
+
32
+
- **Good:** "Running `gh issue list --label needs-triage` returns issues that have been through initial classification"
33
+
- **Bad:** "Triage should work correctly"
34
+
35
+
### Explicit scope boundaries
36
+
37
+
State what is out of scope. This prevents the agent from gold-plating or making assumptions about adjacent features.
38
+
39
+
## Template
40
+
41
+
```markdown
42
+
## Agent Brief
43
+
44
+
**Category:** bug / enhancement
45
+
**Summary:** one-line description of what needs to happen
46
+
47
+
**Current behavior:**
48
+
Describe what happens now. For bugs, this is the broken behavior.
49
+
For enhancements, this is the status quo the feature builds on.
50
+
51
+
**Desired behavior:**
52
+
Describe what should happen after the agent's work is complete.
53
+
Be specific about edge cases and error conditions.
54
+
55
+
**Key interfaces:**
56
+
- `TypeName` — what needs to change and why
57
+
- `functionName()` return type — what it currently returns vs what it should return
58
+
- Config shape — any new configuration options needed
59
+
60
+
**Acceptance criteria:**
61
+
- [ ] Specific, testable criterion 1
62
+
- [ ] Specific, testable criterion 2
63
+
- [ ] Specific, testable criterion 3
64
+
65
+
**Out of scope:**
66
+
- Thing that should NOT be changed or addressed in this issue
67
+
- Adjacent feature that might seem related but is separate
68
+
```
69
+
70
+
## Examples
71
+
72
+
### Good agent brief (bug)
73
+
74
+
```markdown
75
+
## Agent Brief
76
+
77
+
**Category:** bug
78
+
**Summary:** Skill description truncation drops mid-word, producing broken output
79
+
80
+
**Current behavior:**
81
+
When a skill description exceeds 1024 characters, it is truncated at exactly
82
+
1024 characters regardless of word boundaries. This produces descriptions
83
+
that end mid-word (e.g. "Use when the user wants to confi").
84
+
85
+
**Desired behavior:**
86
+
Truncation should break at the last word boundary before 1024 characters
87
+
and append "..." to indicate truncation.
88
+
89
+
**Key interfaces:**
90
+
- The `SkillMetadata` type's `description` field — no type change needed,
91
+
but the validation/processing logic that populates it needs to respect
92
+
word boundaries
93
+
- Any function that reads SKILL.md frontmatter and extracts the description
94
+
95
+
**Acceptance criteria:**
96
+
- [ ] Descriptions under 1024 chars are unchanged
97
+
- [ ] Descriptions over 1024 chars are truncated at the last word boundary
98
+
before 1024 chars
99
+
- [ ] Truncated descriptions end with "..."
100
+
- [ ] The total length including "..." does not exceed 1024 chars
101
+
102
+
**Out of scope:**
103
+
- Changing the 1024 char limit itself
104
+
- Multi-line description support
105
+
```
106
+
107
+
### Good agent brief (enhancement)
108
+
109
+
```markdown
110
+
## Agent Brief
111
+
112
+
**Category:** enhancement
113
+
**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
114
+
115
+
**Current behavior:**
116
+
When a feature request is rejected, the issue is closed with a `wontfix` label
117
+
and a comment. There is no persistent record of the decision or reasoning.
118
+
Future similar requests require the maintainer to recall or search for the
119
+
prior discussion.
120
+
121
+
**Desired behavior:**
122
+
Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
123
+
files that capture the decision, reasoning, and links to all issues that
124
+
requested the feature. When triaging new issues, these files should be
125
+
checked for matches.
126
+
127
+
**Key interfaces:**
128
+
- Markdown file format in `.out-of-scope/` — each file should have a
129
+
`# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
130
+
and a `**Prior requests:**` list with issue links
131
+
- The triage workflow should read all `.out-of-scope/*.md` files early
132
+
and match incoming issues against them by concept similarity
133
+
134
+
**Acceptance criteria:**
135
+
- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
136
+
- [ ] The file includes the decision, reasoning, and link to the closed issue
137
+
- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
138
+
appended to its "Prior requests" list rather than creating a duplicate
139
+
- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
140
+
when a new issue matches a prior rejection
141
+
142
+
**Out of scope:**
143
+
- Automated matching (human confirms the match)
144
+
- Reopening previously rejected features
145
+
- Bug reports (only enhancement rejections go to `.out-of-scope/`)
146
+
```
147
+
148
+
### Good agent brief (PR)
149
+
150
+
For a PR, "Current behavior" describes the state of the diff, and the brief asks the agent to finish or fix it rather than build from scratch.
151
+
152
+
```markdown
153
+
## Agent Brief
154
+
155
+
**Category:** enhancement
156
+
**Summary:** Finish the contributor's `--json` output flag for `triage list`
157
+
158
+
**Current behavior:**
159
+
The PR adds a `--json` flag that serializes the issue list to JSON. The happy
160
+
path works and the diff matches the project's command structure. Two gaps
161
+
remain: errors are still printed as human text (not JSON), and the new flag has
162
+
no test coverage.
163
+
164
+
**Desired behavior:**
165
+
With `--json`, all output — including errors — is well-formed JSON on stdout,
166
+
and the command's exit codes are unchanged. The existing human-readable output
167
+
is untouched when the flag is absent.
168
+
169
+
**Key interfaces:**
170
+
- The command's error path should emit `{ "error": string }` under `--json`
171
+
instead of the plain-text error
172
+
- Reuse the existing serializer the PR already added; don't introduce a second
173
+
174
+
**Acceptance criteria:**
175
+
- [ ] `triage list --json` emits valid JSON for both success and error cases
176
+
- [ ] Exit codes match the non-JSON command
177
+
- [ ] A test covers the `--json` success output and one error case
178
+
- [ ] Default (non-JSON) output is byte-for-byte unchanged
179
+
180
+
**Out of scope:**
181
+
- Adding `--json` to any other command
182
+
- Changing the JSON shape of the success payload the PR already defined
183
+
```
184
+
185
+
### Bad agent brief
186
+
187
+
```markdown
188
+
## Agent Brief
189
+
190
+
**Summary:** Fix the triage bug
191
+
192
+
**What to do:**
193
+
The triage thing is broken. Look at the main file and fix it.
194
+
The function around line 150 has the issue.
195
+
196
+
**Files to change:**
197
+
- src/triage/handler.ts (line 150)
198
+
- src/types.ts (line 42)
199
+
```
200
+
201
+
This is bad because:
202
+
- No category
203
+
- Vague description ("the triage thing is broken")
204
+
- References file paths and line numbers that will go stale
205
+
- No acceptance criteria
206
+
- No scope boundaries
207
+
- No description of current vs desired behavior
+105
.agents/skills/triage/OUT-OF-SCOPE.md
+105
.agents/skills/triage/OUT-OF-SCOPE.md
···
1
+
# Out-of-Scope Knowledge Base
2
+
3
+
The `.out-of-scope/` directory in a repo stores persistent records of rejected feature requests. It serves two purposes:
4
+
5
+
1. **Institutional memory** — why a feature was rejected, so the reasoning isn't lost when the issue is closed
6
+
2. **Deduplication** — when a new issue comes in that matches a prior rejection, the skill can surface the previous decision instead of re-litigating it
7
+
8
+
## Directory structure
9
+
10
+
```
11
+
.out-of-scope/
12
+
├── dark-mode.md
13
+
├── plugin-system.md
14
+
└── graphql-api.md
15
+
```
16
+
17
+
One file per **concept**, not per issue. Multiple issues requesting the same thing are grouped under one file.
18
+
19
+
## File format
20
+
21
+
The file should be written in a relaxed, readable style — more like a short design document than a database entry. Use paragraphs, code samples, and examples to make the reasoning clear and useful to someone encountering it for the first time.
22
+
23
+
```markdown
24
+
# Dark Mode
25
+
26
+
This project does not support dark mode or user-facing theming.
27
+
28
+
## Why this is out of scope
29
+
30
+
The rendering pipeline assumes a single color palette defined in
31
+
`ThemeConfig`. Supporting multiple themes would require:
32
+
33
+
- A theme context provider wrapping the entire component tree
34
+
- Per-component theme-aware style resolution
35
+
- A persistence layer for user theme preferences
36
+
37
+
This is a significant architectural change that doesn't align with the
38
+
project's focus on content authoring. Theming is a concern for downstream
39
+
consumers who embed or redistribute the output.
40
+
41
+
```ts
42
+
// The current ThemeConfig interface is not designed for runtime switching:
43
+
interface ThemeConfig {
44
+
colors: ColorPalette; // single palette, resolved at build time
45
+
fonts: FontStack;
46
+
}
47
+
```
48
+
49
+
## Prior requests
50
+
51
+
- #42 — "Add dark mode support"
52
+
- #87 — "Night theme for accessibility"
53
+
- #134 — "Dark theme option"
54
+
```
55
+
56
+
### Naming the file
57
+
58
+
Use a short, descriptive kebab-case name for the concept: `dark-mode.md`, `plugin-system.md`, `graphql-api.md`. The name should be recognizable enough that someone browsing the directory understands what was rejected without opening the file.
59
+
60
+
### Writing the reason
61
+
62
+
The reason should be substantive — not "we don't want this" but why. Good reasons reference:
63
+
64
+
- Project scope or philosophy ("This project focuses on X; theming is a downstream concern")
65
+
- Technical constraints ("Supporting this would require Y, which conflicts with our Z architecture")
66
+
- Strategic decisions ("We chose to use A instead of B because...")
67
+
68
+
The reason should be durable. Avoid referencing temporary circumstances ("we're too busy right now") — those aren't real rejections, they're deferrals.
69
+
70
+
## When to check `.out-of-scope/`
71
+
72
+
During triage (Step 1: Gather context), read all files in `.out-of-scope/`. When evaluating a new issue:
73
+
74
+
- Check if the request matches an existing out-of-scope concept
75
+
- Matching is by concept similarity, not keyword — "night theme" matches `dark-mode.md`
76
+
- If there's a match, surface it to the maintainer: "This is similar to `.out-of-scope/dark-mode.md` — we rejected this before because [reason]. Do you still feel the same way?"
77
+
78
+
The maintainer may:
79
+
80
+
- **Confirm** — the new issue gets added to the existing file's "Prior requests" list, then closed
81
+
- **Reconsider** — the out-of-scope file gets deleted or updated, and the issue proceeds through normal triage
82
+
- **Disagree** — the issues are related but distinct, proceed with normal triage
83
+
84
+
## When to write to `.out-of-scope/`
85
+
86
+
Only when an **enhancement** (not a bug) is *rejected* as `wontfix`. This applies to enhancement PRs exactly as it does to issues — a rejected PR is recorded here so the same request doesn't return as fresh code.
87
+
88
+
Do **not** write here when something is closed as `wontfix` because it's **already implemented**. That's a built feature, not a rejected one; recording it would poison the dedup checks with false rejections. Instead, the closing comment points to where the feature already lives.
89
+
90
+
The flow:
91
+
92
+
1. Maintainer decides a feature request is out of scope
93
+
2. Check if a matching `.out-of-scope/` file already exists
94
+
3. If yes: append the new issue to the "Prior requests" list
95
+
4. If no: create a new file with the concept name, decision, reason, and first prior request
96
+
5. Post a comment on the issue explaining the decision and mentioning the `.out-of-scope/` file
97
+
6. Close the issue with the `wontfix` label
98
+
99
+
## Updating or removing out-of-scope files
100
+
101
+
If the maintainer changes their mind about a previously rejected concept:
102
+
103
+
- Delete the `.out-of-scope/` file
104
+
- The skill does not need to reopen old issues — they're historical records
105
+
- The new issue that triggered the reconsideration proceeds through normal triage
+112
.agents/skills/triage/SKILL.md
+112
.agents/skills/triage/SKILL.md
···
1
+
---
2
+
name: triage
3
+
description: Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.
4
+
disable-model-invocation: true
5
+
---
6
+
7
+
# Triage
8
+
9
+
Move issues on the project issue tracker through a small state machine of triage roles.
10
+
11
+
If this repo treats external pull requests as a request surface (see the issue-tracker config), triage covers them too: **a PR is an issue with attached code** — same roles, same states, same machine, with a few deltas marked "for a PR" below. Resolve a bare `#42` to an issue or PR per the tracker config.
12
+
13
+
Every comment or issue posted to the issue tracker during triage **must** start with this disclaimer:
14
+
15
+
```
16
+
> *This was generated by AI during triage.*
17
+
```
18
+
19
+
## Reference docs
20
+
21
+
- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs
22
+
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works
23
+
24
+
## Roles
25
+
26
+
Two **category** roles:
27
+
28
+
- `bug` — something is broken
29
+
- `enhancement` — new feature or improvement
30
+
31
+
Five **state** roles:
32
+
33
+
- `needs-triage` — maintainer needs to evaluate
34
+
- `needs-info` — waiting on reporter for more information
35
+
- `ready-for-agent` — fully specified, ready for an AFK agent
36
+
- `ready-for-human` — needs human implementation
37
+
- `wontfix` — will not be actioned
38
+
39
+
For a PR, the same states read against the attached code: `ready-for-agent` means a brief is attached and an agent should take the next step on the diff; `ready-for-human` means it's ready for a human to merge.
40
+
41
+
Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
42
+
43
+
These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
44
+
45
+
State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
46
+
47
+
## Invocation
48
+
49
+
The maintainer invokes `/triage` and describes what they want in natural language. Interpret the request and act. Examples:
50
+
51
+
- "Show me anything that needs my attention"
52
+
- "Let's look at #42" (issue or PR)
53
+
- "Move #42 to ready-for-agent"
54
+
- "What's ready for agents to pick up?"
55
+
56
+
## Show what needs attention
57
+
58
+
Query the issue tracker and present three buckets, oldest first:
59
+
60
+
1. **Unlabeled** — never triaged.
61
+
2. **`needs-triage`** — evaluation in progress.
62
+
3. **`needs-info` with reporter activity since the last triage notes** — needs re-evaluation.
63
+
64
+
When PRs are in scope, include external PRs in these buckets and tag each line `[PR]` or `[issue]`. Discovery surfaces only *external* PRs (the tracker config defines who counts as external) — a collaborator's in-flight PR is not triage work. This filter is discovery-only; an explicitly named PR is always triaged regardless of author.
65
+
66
+
Show counts and a one-line summary per item. Let the maintainer pick.
67
+
68
+
## Triage a specific issue or PR
69
+
70
+
1. **Gather context.** Read the full issue or PR (body, comments, labels, author, dates; for a PR, the diff too). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Run two checks against the codebase: (a) **redundancy** — search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, it's an already-implemented `wontfix` (step 5). (b) **prior rejection** — read `.out-of-scope/*.md` and surface any that resembles this request.
71
+
72
+
2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the request — including whether it's already implemented. Wait for direction.
73
+
74
+
3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
75
+
76
+
4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
77
+
78
+
5. **Apply the outcome:**
79
+
- `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
80
+
- `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
81
+
- `needs-info` — post triage notes (template below).
82
+
- `wontfix` — close, with the comment depending on *why*:
83
+
- **Already implemented** — the change already exists in the codebase. Point to where it lives; do **not** write to `.out-of-scope/` (that KB is for *rejected* requests, not built ones).
84
+
- **Rejected (bug)** — polite explanation, then close.
85
+
- **Rejected (enhancement)** — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
86
+
- `needs-triage` — apply the role. Optional comment if there's partial progress.
87
+
88
+
## Quick state override
89
+
90
+
If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent brief.
91
+
92
+
## Needs-info template
93
+
94
+
```markdown
95
+
## Triage Notes
96
+
97
+
**What we've established so far:**
98
+
99
+
- point 1
100
+
- point 2
101
+
102
+
**What we still need from you (@reporter):**
103
+
104
+
- question 1
105
+
- question 2
106
+
```
107
+
108
+
Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
109
+
110
+
## Resuming a previous session
111
+
112
+
If prior triage notes exist on the issue or PR, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.
+126
.agents/skills/wayfinder/SKILL.md
+126
.agents/skills/wayfinder/SKILL.md
···
1
+
---
2
+
name: wayfinder
3
+
description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of investigation tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
4
+
---
5
+
6
+
A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** on the repo's issue tracker, then works its tickets one at a time until the route is clear.
7
+
8
+
The destination varies per effort, and naming it is the first act of charting — it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
9
+
10
+
## Plan, don't do
11
+
12
+
Wayfinder is **planning** by default: each ticket resolves a decision, and the map is done when the way is clear — nothing left to decide before someone goes and does the thing. The pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off. An effort can override this in its **Notes** — carrying execution into the map itself — but absent that, produce decisions, not deliverables.
13
+
14
+
## Refer by name
15
+
16
+
Every map and ticket is an issue, so it has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride *inside* the name, never stand in for it.
17
+
18
+
## The Map
19
+
20
+
The map is a single issue on this repo's issue tracker, labelled `wayfinder:map` — the canonical artifact. Its tickets are child issues of the map.
21
+
22
+
The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
23
+
24
+
**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** Consult `docs/agents/issue-tracker.md` (the "Wayfinding operations" section) for how _this_ repo expresses them. If that doc is absent, default to the local-markdown tracker.
25
+
26
+
### The map body
27
+
28
+
The whole map at low resolution, loaded once per session. Open tickets are **not** listed — they are open child issues, found by query.
29
+
30
+
```markdown
31
+
## Destination
32
+
33
+
<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>
34
+
35
+
## Notes
36
+
37
+
<domain; skills every session should consult; standing preferences for this effort>
38
+
39
+
## Decisions so far
40
+
41
+
<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
42
+
43
+
- [<closed ticket title>](link) — <one-line gist of the answer>
44
+
45
+
## Not yet specified
46
+
47
+
<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->
48
+
49
+
## Out of scope
50
+
51
+
<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
52
+
```
53
+
54
+
### Tickets
55
+
56
+
Each ticket is a **child issue** of the map; the tracker's issue id is its identity. Its body is the question, sized to one 100K token agent session:
57
+
58
+
```markdown
59
+
## Question
60
+
61
+
<the decision or investigation this ticket resolves>
62
+
```
63
+
64
+
Each ticket carries a `wayfinder:<type>` label — one of `research`, `prototype`, `grilling`, `task` (see [Ticket Types](#ticket-types)).
65
+
66
+
A session **claims** a ticket by assigning it to the dev driving the map, **first**, before any work, so concurrent sessions skip it. That assignee _is_ the claim: an open, unassigned ticket is unclaimed.
67
+
68
+
Blocking uses the tracker's **native** dependency relationship — essential because it renders the frontier _visually_ in the tracker's own UI, so the human sees what's takeable without opening the map. Only a tracker that lacks native blocking falls back to a body convention. A ticket is **unblocked** when every ticket blocking it is closed; the **frontier** is the open, unblocked, unclaimed children — the edge of the known.
69
+
70
+
The answer isn't part of the body — it's recorded on resolution (see [Work through the map](#work-through-the-map)). Assets created while resolving a ticket are linked from the issue, not pasted in.
71
+
72
+
## Ticket Types
73
+
74
+
Every ticket is either **HITL** — human in the loop, worked *with* a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
75
+
76
+
- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases. Creates a markdown summary as a linked asset. Use when knowledge outside the current working directory is required.
77
+
- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
78
+
- **Grilling** (HITL): Conversation via the /grilling and /domain-modeling skills, one question at a time. The default case.
79
+
- **Task** (HITL or AFK): Manual work that must happen before a *decision* can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that *does* rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
80
+
81
+
## Fog of war
82
+
83
+
The map is _deliberately_ incomplete: don't chart what you can't yet see. Beyond the live tickets lies the **fog of war** — the dim view of decisions and investigations you can tell are coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating whatever's now specifiable into fresh tickets — one at a time, until the way to the destination is clear and no tickets remain.
84
+
85
+
The map's **Not yet specified** section is where that dim view is written down: the suspected question, the area to revisit later. It's the undiscovered frontier _toward_ the destination — everything here is in scope, just not sharp enough to ticket. Write as loosely or as fully as the view allows; it doubles as a signpost for collaborators reading where the effort is headed.
86
+
87
+
**Fog or ticket?** The test is whether you can state the question precisely now — _not_ whether you can answer it now.
88
+
89
+
- **Ticket when** the question is already sharp — even if it's blocked and you can't act on it yet.
90
+
- **Not yet specified when** you can't yet phrase it that sharply. Don't pre-slice the fog into ticket-sized pieces: it's coarser than a ticket, and one patch may graduate into several tickets, or none, once the frontier reaches it.
91
+
92
+
**Not yet specified** excludes what's already decided (Decisions so far), what's already a live ticket, and what's out of scope (the next section).
93
+
94
+
## Out of scope
95
+
96
+
Fog only ever gathers _toward_ the destination. The destination fixes the scope, so work beyond it is **out of scope** — it isn't fog, and it doesn't belong in **Not yet specified**. It gets its own **Out of scope** section on the map: work you've consciously ruled out of _this_ effort. Scope, not sharpness, lands it here.
97
+
98
+
Out-of-scope work never graduates — the frontier stops at the destination — so it returns only if the destination is redrawn, and then as a fresh effort, not a resumption.
99
+
100
+
Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination — mis-scoped in while charting, or exposed by a resolution — **close it** (a closed ticket is unambiguously off the frontier) and leave one line in the **Out of scope** section: the gist plus why it's out of scope, linking the closed ticket. It stays out of **Decisions so far**, which records the route actually walked — a scope boundary isn't a step on it.
101
+
102
+
## Invocation
103
+
104
+
Two modes. Either way, **never resolve more than one ticket per session.**
105
+
106
+
### Chart the map
107
+
108
+
User invokes with a loose idea.
109
+
110
+
1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
111
+
2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
112
+
3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
113
+
4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
114
+
5. Stop — charting the map is one session's work; do not also resolve tickets.
115
+
116
+
### Work through the map
117
+
118
+
User invokes with a map (URL or number). A ticket is **optional** — without one, you pick the next decision, not the user.
119
+
120
+
1. Load the **map** — the low-res view, not every ticket body.
121
+
2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself before any work.
122
+
3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the skills the `## Notes` block names. If in doubt, use `/grilling` and `/domain-modeling`.
123
+
4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far.
124
+
5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets.
125
+
126
+
The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.
+1
.pi/skills/code-review
+1
.pi/skills/code-review
···
1
+
../../.agents/skills/code-review
+1
.pi/skills/diagnosing-bugs
+1
.pi/skills/diagnosing-bugs
···
1
+
../../.agents/skills/diagnosing-bugs
+1
.pi/skills/domain-modeling
+1
.pi/skills/domain-modeling
···
1
+
../../.agents/skills/domain-modeling
+1
.pi/skills/grill-with-docs
+1
.pi/skills/grill-with-docs
···
1
+
../../.agents/skills/grill-with-docs
+1
.pi/skills/handoff
+1
.pi/skills/handoff
···
1
+
../../.agents/skills/handoff
+1
.pi/skills/implement
+1
.pi/skills/implement
···
1
+
../../.agents/skills/implement
+1
.pi/skills/improve-codebase-architecture
+1
.pi/skills/improve-codebase-architecture
···
1
+
../../.agents/skills/improve-codebase-architecture
+1
.pi/skills/qa
+1
.pi/skills/qa
···
1
+
../../.agents/skills/qa
+1
.pi/skills/research
+1
.pi/skills/research
···
1
+
../../.agents/skills/research
+1
.pi/skills/tdd
+1
.pi/skills/tdd
···
1
+
../../.agents/skills/tdd
+1
.pi/skills/to-issues
+1
.pi/skills/to-issues
···
1
+
../../.agents/skills/to-issues
+1
.pi/skills/to-prd
+1
.pi/skills/to-prd
···
1
+
../../.agents/skills/to-prd
+1
.pi/skills/triage
+1
.pi/skills/triage
···
1
+
../../.agents/skills/triage
+1
.pi/skills/wayfinder
+1
.pi/skills/wayfinder
···
1
+
../../.agents/skills/wayfinder
+14
AGENTS.md
+14
AGENTS.md
···
10
10
## Dev environment tips
11
11
If `DEVENV_ROOT` env variable is defined, just run project binaries (they are available).
12
12
If not, run them by prefixing with `devenv shell ...`
13
+
14
+
## Agent skills
15
+
16
+
### Issue tracker
17
+
18
+
Issues and pull requests are tracked on Tangled using the `tang` CLI; pull requests are also available at `https://tangled.org/mykiwi.dev/rssbase.io/pulls`. See `docs/agents/issue-tracker.md`.
19
+
20
+
### Triage labels
21
+
22
+
Use the default five-label triage vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
23
+
24
+
### Domain docs
25
+
26
+
Single-context domain docs: read root `CONTEXT.md`; ADRs live in `docs/architecture/decisions/` following the Diátaxis-inspired docs structure. See `docs/agents/domain.md`.
+17
docs/README.md
+17
docs/README.md
···
1
+
# Documentation
2
+
3
+
This repo uses a Diátaxis-inspired documentation structure.
4
+
5
+
- **Tutorials** teach by walking through a learning path.
6
+
- **How-to guides** solve a specific practical problem.
7
+
- **Reference** records facts, options, APIs, commands, and configuration.
8
+
- **Explanation** gives background, reasoning, architecture, and trade-offs.
9
+
10
+
## Structure
11
+
12
+
- `docs/agents/` — configuration consumed by agent skills.
13
+
- `docs/architecture/explanation/` — architectural background and system explanations.
14
+
- `docs/architecture/decisions/` — architectural decision records, named like `0001-use-atproto-for-user-data.md`.
15
+
- `docs/development/how-to/` — developer task recipes.
16
+
- `docs/development/reference/` — developer reference material.
17
+
- `docs/product/explanation/` — product and domain explanations.
+44
docs/agents/domain.md
+44
docs/agents/domain.md
···
1
+
# Domain Docs
2
+
3
+
How the engineering skills should consume this repo's domain documentation when exploring the codebase.
4
+
5
+
## Layout
6
+
7
+
This repo uses a single-context domain documentation layout.
8
+
9
+
## Before exploring, read these
10
+
11
+
- **`CONTEXT.md`** at the repo root, if it exists.
12
+
- Architectural decision docs, if they exist.
13
+
14
+
If any of these files don't exist, proceed silently. Don't flag their absence; don't suggest creating them upfront.
15
+
16
+
## Documentation structure
17
+
18
+
This repo uses a Diátaxis-inspired documentation structure under `docs/`:
19
+
20
+
- `docs/architecture/explanation/` — architectural background and reasoning.
21
+
- `docs/architecture/decisions/` — architectural decision records.
22
+
- `docs/development/how-to/` — goal-oriented developer recipes.
23
+
- `docs/development/reference/` — developer reference material.
24
+
- `docs/product/explanation/` — product and domain explanations.
25
+
26
+
## ADR location
27
+
28
+
Architectural decision records live in `docs/architecture/decisions/`.
29
+
30
+
Use classic numbered ADR filenames, for example:
31
+
32
+
```text
33
+
0001-use-atproto-for-user-data.md
34
+
```
35
+
36
+
## Use the glossary's vocabulary
37
+
38
+
When your output names a domain concept, use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
39
+
40
+
If the concept you need isn't in the glossary yet, either reconsider the language or note the gap for future domain modeling.
41
+
42
+
## Flag ADR conflicts
43
+
44
+
If your output contradicts an existing architectural decision, surface it explicitly rather than silently overriding.
+31
docs/agents/issue-tracker.md
+31
docs/agents/issue-tracker.md
···
1
+
# Issue tracker: Tangled
2
+
3
+
Issues and PRDs for this repo live as Tangled issues. Use the `tang` CLI for issue operations.
4
+
5
+
Pull requests are also managed through Tangled. Use the `tang` CLI when possible, and the web UI at <https://tangled.org/mykiwi.dev/rssbase.io/pulls> when needed.
6
+
7
+
## Conventions
8
+
9
+
- Inspect available commands with `tang --help`, `tang issue --help`, and `tang pr --help` before using a workflow for the first time.
10
+
- Use `tang issue list` to list issues.
11
+
- Use `tang issue create` to create issues.
12
+
- Use `tang issue view` or the closest available command to read an issue and comments.
13
+
- Use `tang issue comment`, `tang issue edit`, or the closest available command to update issues, labels, and comments.
14
+
- Use `tang pr list`, `tang pr view`, `tang pr create`, or the closest available commands for pull request workflows.
15
+
- Prefer the repository inferred from the current git remote: `git@tangled.org:mykiwi.dev/rssbase.io`.
16
+
17
+
Command names and flags may vary with the installed `tang` version. Verify with help output before writing.
18
+
19
+
## When a skill says "publish to the issue tracker"
20
+
21
+
Create a Tangled issue using `tang issue create`.
22
+
23
+
## When a skill says "fetch the relevant ticket"
24
+
25
+
Read the Tangled issue using `tang issue view` or the current equivalent from `tang issue --help`.
26
+
27
+
## Pull requests as a triage surface
28
+
29
+
Pull requests are available through Tangled using the `tang` CLI or the web UI at <https://tangled.org/mykiwi.dev/rssbase.io/pulls>.
30
+
31
+
Treat pull requests as related repo work, but prefer Tangled issues as the main request surface unless a skill or maintainer explicitly asks to triage PRs.
+13
docs/agents/triage-labels.md
+13
docs/agents/triage-labels.md
···
1
+
# Triage Labels
2
+
3
+
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.
4
+
5
+
| Label in mattpocock/skills | Label in our tracker | Meaning |
6
+
| -------------------------- | -------------------- | ---------------------------------------- |
7
+
| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
8
+
| `needs-info` | `needs-info` | Waiting on reporter for more information |
9
+
| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
10
+
| `ready-for-human` | `ready-for-human` | Requires human implementation |
11
+
| `wontfix` | `wontfix` | Will not be actioned |
12
+
13
+
When a skill mentions a role, use the corresponding label string from this table.
+6
docs/architecture/README.md
+6
docs/architecture/README.md
+12
docs/architecture/decisions/README.md
+12
docs/architecture/decisions/README.md
···
1
+
# Architectural Decision Records
2
+
3
+
Architectural decision records live here.
4
+
5
+
Use classic numbered filenames:
6
+
7
+
```text
8
+
0001-use-atproto-for-user-data.md
9
+
0002-choose-feed-fetching-strategy.md
10
+
```
11
+
12
+
Each decision should explain the context, decision, consequences, and any alternatives considered.
+3
docs/architecture/explanation/README.md
+3
docs/architecture/explanation/README.md
+3
docs/development/how-to/README.md
+3
docs/development/how-to/README.md
+3
docs/development/reference/README.md
+3
docs/development/reference/README.md
+3
docs/product/explanation/README.md
+3
docs/product/explanation/README.md
+90
skills-lock.json
+90
skills-lock.json
···
13
13
"skillPath": "skills/caveman/SKILL.md",
14
14
"computedHash": "1902fa0b569912d0c05736d8d98a72097d9b82719aac88c0c1d03bb546f9176d"
15
15
},
16
+
"code-review": {
17
+
"source": "mattpocock/skills",
18
+
"sourceType": "github",
19
+
"skillPath": "skills/engineering/code-review/SKILL.md",
20
+
"computedHash": "4a17d9d3e0fc87ae48544d371a820fac5a4a78f4c05e7e6b3229094fbf8a7e26"
21
+
},
16
22
"dagger-chores": {
17
23
"source": "dagger/dagger",
18
24
"ref": "main",
···
27
33
"skillPath": "skills/dagger-design-proposals/SKILL.md",
28
34
"computedHash": "2fcd51276cffed132e8b92b157473125bf0737facfe02a3ad796e537a60151be"
29
35
},
36
+
"diagnosing-bugs": {
37
+
"source": "mattpocock/skills",
38
+
"sourceType": "github",
39
+
"skillPath": "skills/engineering/diagnosing-bugs/SKILL.md",
40
+
"computedHash": "1a993ce9b2aaa653ee441c8d7efb7f27de03493c722be6dfb8137bcb8db1bc72"
41
+
},
42
+
"domain-modeling": {
43
+
"source": "mattpocock/skills",
44
+
"sourceType": "github",
45
+
"skillPath": "skills/engineering/domain-modeling/SKILL.md",
46
+
"computedHash": "67343881f5def98487d56243155716110afbcbf22ec92421c882d532b941cb17"
47
+
},
30
48
"engine-debugging": {
31
49
"source": "dagger/dagger",
32
50
"ref": "main",
···
40
58
"skillPath": "skills/frontend-design/SKILL.md",
41
59
"computedHash": "4eabc66183767153e404b39d1b839b1c37f2d82d86f0a0d7e880a579d8d62336"
42
60
},
61
+
"grill-with-docs": {
62
+
"source": "mattpocock/skills",
63
+
"sourceType": "github",
64
+
"skillPath": "skills/engineering/grill-with-docs/SKILL.md",
65
+
"computedHash": "e7ef25bbee50cda2eb7b3a8ef541db0a0396dad7d369f7d14fb610671dd1864b"
66
+
},
67
+
"handoff": {
68
+
"source": "mattpocock/skills",
69
+
"sourceType": "github",
70
+
"skillPath": "skills/productivity/handoff/SKILL.md",
71
+
"computedHash": "5d0f81e38abe6b984e1feaa731927de5291d040982106ac513cf54ec240e00ec"
72
+
},
73
+
"implement": {
74
+
"source": "mattpocock/skills",
75
+
"sourceType": "github",
76
+
"skillPath": "skills/engineering/implement/SKILL.md",
77
+
"computedHash": "5eedab2e36a68278662484e8e243624fe0bb74040299aa6c8a525feb65b0365c"
78
+
},
79
+
"improve-codebase-architecture": {
80
+
"source": "mattpocock/skills",
81
+
"sourceType": "github",
82
+
"skillPath": "skills/engineering/improve-codebase-architecture/SKILL.md",
83
+
"computedHash": "8bf292143ca93b00276a0de0fc5f84f2381f4690c5b0d32e99fa283a072f392f"
84
+
},
43
85
"nix-best-practices": {
44
86
"source": "alleneubank/claude-code",
45
87
"sourceType": "github",
46
88
"skillPath": ".claude/skills/nix-best-practices/SKILL.md",
47
89
"computedHash": "f6d14bf40d4b505dd50cb389711eae74bc1459740adb27f4641cd75c21042311"
90
+
},
91
+
"qa": {
92
+
"source": "mattpocock/skills",
93
+
"sourceType": "github",
94
+
"skillPath": "skills/deprecated/qa/SKILL.md",
95
+
"computedHash": "20c63e29b268b1f0762cff524b5e321d5e1a773b4f61b90d84811b755948a66c"
96
+
},
97
+
"research": {
98
+
"source": "mattpocock/skills",
99
+
"sourceType": "github",
100
+
"skillPath": "skills/engineering/research/SKILL.md",
101
+
"computedHash": "87d17f5103899fbe179b552a85485d50f2316ca5b3128f5716af7d88817533e1"
102
+
},
103
+
"setup-matt-pocock-skills": {
104
+
"source": "mattpocock/skills",
105
+
"sourceType": "github",
106
+
"skillPath": "skills/engineering/setup-matt-pocock-skills/SKILL.md",
107
+
"computedHash": "a7d798f49081ea5b2606e8bcafa3bc2b34177cfaa24d71c2ddf2d433f4006a4a"
48
108
},
49
109
"skill-creator": {
50
110
"source": "anthropics/skills",
···
256
316
"skillPath": "SKILL.md",
257
317
"computedHash": "9b4c75735748bfd66fd4c05765f02e1d46ccf13a35508f8c44c83a2cafa3d79d"
258
318
},
319
+
"tdd": {
320
+
"source": "mattpocock/skills",
321
+
"sourceType": "github",
322
+
"skillPath": "skills/engineering/tdd/SKILL.md",
323
+
"computedHash": "c9326b88419cfba1d54dd713b7ddb23020e6a93f4b0d13aea58cebba58cda2ee"
324
+
},
259
325
"telemetry-capture": {
260
326
"source": "dagger/dagger",
261
327
"ref": "main",
···
263
329
"skillPath": "skills/telemetry-capture/SKILL.md",
264
330
"computedHash": "d0eb55bfe6c66109e26fe237ab9f96bc06e0029bb8ebbd2c770ec28e6a8d2a1a"
265
331
},
332
+
"to-issues": {
333
+
"source": "mattpocock/skills",
334
+
"sourceType": "github",
335
+
"skillPath": "skills/engineering/to-issues/SKILL.md",
336
+
"computedHash": "4406ded5e0fb356b9ac8be777270f62d3c5d206a0bc848aaadb19919702a1892"
337
+
},
338
+
"to-prd": {
339
+
"source": "mattpocock/skills",
340
+
"sourceType": "github",
341
+
"skillPath": "skills/engineering/to-prd/SKILL.md",
342
+
"computedHash": "5a733e19d825f22e83de52e68b8840c9fd2fa7501282277a122c1aa28a922059"
343
+
},
344
+
"triage": {
345
+
"source": "mattpocock/skills",
346
+
"sourceType": "github",
347
+
"skillPath": "skills/engineering/triage/SKILL.md",
348
+
"computedHash": "b77ea99c2e6e97815b373cc476ad4cc1835d3e736867b764602147be71f6c131"
349
+
},
266
350
"tui-qa": {
267
351
"source": "dagger/dagger",
268
352
"ref": "main",
···
287
371
"sourceType": "github",
288
372
"skillPath": "skills/verification-before-completion/SKILL.md",
289
373
"computedHash": "9b446f0c7fe1cfb560b1d34439523b1a76d5f177290007b2c053a1c749a4a8ba"
374
+
},
375
+
"wayfinder": {
376
+
"source": "mattpocock/skills",
377
+
"sourceType": "github",
378
+
"skillPath": "skills/in-progress/wayfinder/SKILL.md",
379
+
"computedHash": "c4718b3a19aef81696c449a0b950335fca13fb74b5afc6588d1ae0785a42d898"
290
380
}
291
381
}
292
382
}