From 7f597be5bd6592cc03b784efedfc5aec5eadea78 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 23 Aug 2026 13:24:30 +0300 Subject: [PATCH 1/2] Configure agent skills: issue tracker, triage labels, domain docs --- .gitignore | 1 + CLAUDE.md | 17 ++++++++++++ docs/agents/domain.md | 51 ++++++++++++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 30 +++++++++++++++++++++ docs/agents/triage-labels.md | 15 +++++++++++ 5 files changed, 114 insertions(+) create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/.gitignore b/.gitignore index a28e077..a7195a2 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ __pycache__/ .coverage uv.lock .superpowers/ +.scratch/ diff --git a/CLAUDE.md b/CLAUDE.md index 4c1dc4d..7594165 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -236,3 +236,20 @@ enough that code and docs must agree on it. - **Read marker** — a member's `last_read_message_id`, the highest id they have acknowledged. Advances only forward, via `GREATEST` inside the UPDATE. *Avoid:* read receipt, watermark. + +## Agent skills + +### Issue tracker + +Issues and specs live as markdown files under `.scratch//` +(gitignored). See [`docs/agents/issue-tracker.md`](docs/agents/issue-tracker.md). + +### Triage labels + +The five canonical triage roles, unchanged, recorded as a `Status:` line in each +issue file. See [`docs/agents/triage-labels.md`](docs/agents/triage-labels.md). + +### Domain docs + +Single-context: `CONTEXT.md` + `docs/adr/` at the repo root. See +[`docs/agents/domain.md`](docs/agents/domain.md). diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..3524904 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,51 @@ +# Domain Docs + +How the engineering skills should consume this repo's domain documentation when exploring the codebase. + +## Before exploring, read these + +- **`CONTEXT.md`** at the repo root, or +- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic. +- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. + +If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. + +## File structure + +Single-context repo (most repos): + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +Multi-context repo (presence of `CONTEXT-MAP.md` at the root): + +``` +/ +├── CONTEXT-MAP.md +├── docs/adr/ ← system-wide decisions +└── src/ + ├── ordering/ + │ ├── CONTEXT.md + │ └── docs/adr/ ← context-specific decisions + └── billing/ + ├── CONTEXT.md + └── docs/adr/ +``` + +## Use the glossary's vocabulary + +When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. + +If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). + +## Flag ADR conflicts + +If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: + +> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..0209a19 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,30 @@ +# Issue tracker: Local Markdown + +Issues and specs for this repo live as markdown files in `.scratch/`. + +## Conventions + +- One feature per directory: `.scratch//` +- The spec is `.scratch//spec.md` +- Implementation issues are one file per ticket at `.scratch//issues/-.md`, numbered from `01`, never a single combined tickets file +- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings) +- Comments and conversation history append to the bottom of the file under a `## Comments` heading + +## When a skill says "publish to the issue tracker" + +Create a new file under `.scratch//` (creating the directory if needed). + +## When a skill says "fetch the relevant ticket" + +Read the file at the referenced path. The user will normally pass the path or the issue number directly. + +## Wayfinding operations + +Used by `/wayfinder`. The **map** is a file with one **child** file per ticket. + +- **Map**: `.scratch//map.md` (the Notes / Decisions-so-far / Fog body). +- **Child ticket**: `.scratch//issues/NN-.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`. +- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`. +- **Frontier**: scan `.scratch//issues/` for files that are open, unblocked, and unclaimed; first by number wins. +- **Claim**: set `Status: claimed` and save before any work. +- **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`. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..b716855 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,15 @@ +# Triage Labels + +The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. + +| Label in mattpocock/skills | Label in our tracker | Meaning | +| -------------------------- | -------------------- | ---------------------------------------- | +| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | +| `needs-info` | `needs-info` | Waiting on reporter for more information | +| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation | +| `wontfix` | `wontfix` | Will not be actioned | + +When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. + +Edit the right-hand column to match whatever vocabulary you actually use. From 104a4d11a062173510a9f450d6435ddf7333b1cd Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 23 Aug 2026 13:32:02 +0300 Subject: [PATCH 2/2] Drop multi-context material from the domain docs pointer --- docs/agents/domain.md | 38 +++++++++++++------------------------- 1 file changed, 13 insertions(+), 25 deletions(-) diff --git a/docs/agents/domain.md b/docs/agents/domain.md index 3524904..32c32d5 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -2,41 +2,29 @@ How the engineering skills should consume this repo's domain documentation when exploring the codebase. +This repo is **single-context**: one glossary and one decision log, both at the root. There is no `CONTEXT-MAP.md`, no per-context `CONTEXT.md`, and no context-scoped ADR directory. + ## Before exploring, read these -- **`CONTEXT.md`** at the repo root, or -- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic. -- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. +- **`CONTEXT.md`** at the repo root: the glossary, and nothing but the glossary. +- **`docs/adr/`**: the ADRs that touch the area you're about to work in. `docs/adr/README.md` carries the local standard, which is stricter than the stock ADR format: rejected alternatives and a revisit trigger are required, not optional. -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. +If either doesn't exist yet, **proceed silently**. Don't flag its absence; don't suggest creating it upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. ## File structure -Single-context repo (most repos): - ``` / ├── CONTEXT.md -├── docs/adr/ -│ ├── 0001-event-sourced-orders.md -│ └── 0002-postgres-for-write-model.md -└── src/ +├── docs/ +│ └── adr/ +│ ├── 0001-sequence-ids-not-snowflakes.md +│ └── 0002-cookie-auth-not-bearer.md +├── app/ +└── tests/ ``` -Multi-context repo (presence of `CONTEXT-MAP.md` at the root): - -``` -/ -├── CONTEXT-MAP.md -├── docs/adr/ ← system-wide decisions -└── src/ - ├── ordering/ - │ ├── CONTEXT.md - │ └── docs/adr/ ← context-specific decisions - └── billing/ - ├── CONTEXT.md - └── docs/adr/ -``` +ADR numbers are permanent and assigned in dependency order, so reading from `0001` upward introduces the system in the order its decisions build on each other. A new ADR takes the next free number. ## Use the glossary's vocabulary @@ -48,4 +36,4 @@ If the concept you need isn't in the glossary yet, that's a signal: either you'r If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: -> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_ +> _Contradicts ADR-0007 (upsert via duplicate-key recovery), but worth reopening because…_