edkuksa/skills
1
0
Fork 0
mirror of https://github.com/mattpocock/skills.git synced 2026-07-29 02:52:42 +07:00
Code Issues Packages Projects Releases Wiki Activity

refactor: friendlier setup flow + one-file-per-ticket local tracker

Browse Source 
Rework /setup-matt-pocock-skills to ask fewer, friendlier questions and
align the local-markdown issue tracker with the current spec.

- Triage labels: asked only when the `triage` skill is installed, and then
  as a single recommended-yes question ("keep the default triage labels?")
  instead of an override interrogation. When triage isn't installed, the
  section and docs/agents/triage-labels.md are skipped.
- External PRs as a request surface: no longer a setup question. The
  GitHub/GitLab templates still carry the flag, defaulted off; flip it in
  docs/agents/issue-tracker.md later.
- Domain docs: default to single-context without asking; multi-context is
  only offered when the repo shows monorepo signals.
- Local-markdown tickets: one file per ticket under
  .scratch/<feature>/issues/<NN>-<slug>.md, never a single combined
  tickets.md. /to-tickets, ask-matt, and the local template now agree, and
  the spec file is spec.md (not PRD.md) to match /to-spec.
- Re-sync docs pages for setup-matt-pocock-skills and to-tickets; changeset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt Pocock
2026-07-10 09:37:25 +01:00
co-authored by Claude Opus 4.8
parent d574778f94
commit 44eed54518
7 changed files with 51 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/engineering/setup-matt-pocock-skills.md
+6 -6
View File
@@ -24,17 +24,17 @@ Reach for it **once per repo, before the first use of any other engineering skil
## The three decisions
It walks you through three choices, one at a time, each with a plain-language explainer (it assumes you don't already know the terms):
It leads each with a recommended answer you can accept in a word, and skips whatever it can already infer — so most runs are a couple of quick confirmations:
- **Issue tracker** — where work is tracked, so `triage`/`to-spec`/`to-tickets` know whether to call `gh`, `glab`, write markdown under `.scratch/`, or follow a workflow you describe. GitHub, GitLab, local markdown, or other.
- **Triage labels** — the strings behind the five canonical roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`), mapped to labels you've actually configured so `triage` applies real ones instead of creating duplicates.
- **Domain docs** — whether the repo has one `CONTEXT.md` or a multi-context map, so skills that read domain language look in the right place.
- **Issue tracker** — where work is tracked, so `triage`/`to-spec`/`to-tickets` know whether to call `gh`, `glab`, write markdown under `.scratch/`, or follow a workflow you describe. GitHub, GitLab, local markdown, or other. (It proposes the one that matches your `git remote`.)
- **Triage labels** — asked only if the `triage` skill is installed, and then just: keep the default labels (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`)? Say no only if your tracker already uses other names, so `triage` applies real ones instead of creating duplicates.
- **Domain docs** — assumed single-context (one `CONTEXT.md` + `docs/adr/` at the root), which fits almost every repo; it only raises a multi-context map when it spots monorepo signals.
The output is three files — `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md` — plus an `## Agent skills` block pointing to them in whichever of `CLAUDE.md` / `AGENTS.md` the repo already uses. Those files are the shared substrate the rest of the toolkit stands on.
The output is a set of files under `docs/agents/` — `issue-tracker.md`, `domain.md`, and `triage-labels.md` when `triage` is installed — plus an `## Agent skills` block pointing to them in whichever of `CLAUDE.md` / `AGENTS.md` the repo already uses. Those files are the shared substrate the rest of the toolkit stands on.
## It's working if
- Three files land under `docs/agents/`, and an `## Agent skills` section appears in your `CLAUDE.md` or `AGENTS.md`.
- `issue-tracker.md` and `domain.md` land under `docs/agents/` (plus `triage-labels.md` when `triage` is installed), and an `## Agent skills` section appears in your `CLAUDE.md` or `AGENTS.md`.
- The tracker it proposes matches your real `git remote`, and the labels match strings that already exist in your repo.
- Afterwards, `triage` and `to-tickets` act on the right place with the right labels instead of asking or guessing.
docs/engineering/to-tickets.md
+1 -1
View File
@@ -30,7 +30,7 @@ Reach for it once you have an agreed plan or a written spec and you want it spli
The blocking edges are the whole point. They make one set of tickets read two ways, depending on the tracker:
- **Local files** → a single `tickets.md` in the repo root, the edges written as text. You work it top-to-bottom, by hand, staying in the loop.
- **Local files** → one file per ticket under `.scratch/<feature>/issues/`, numbered blockers-first, the edges written as text. You work them top-to-bottom, by hand, staying in the loop.
- **A real tracker (GitHub, Linear)** → one issue per ticket, the edges as native blocking links (or sub-issues). Any ticket whose blockers are all done is on the **frontier** and can be grabbed — so several agents can run at once.
The edges live in the ticket regardless of medium; the medium only decides whether anything acts on them in parallel. `to-tickets` produces the artifact — how you run it (sequential by hand, or a parallel fleet) is up to you.