From 1249c08e6def0fd0e81504a4f9f91b727fae6ea3 Mon Sep 17 00:00:00 2001 From: Joshua Yanchar Date: Wed, 19 Aug 2026 16:41:41 -0700 Subject: [PATCH 1/6] feat(agents): configure the repo for the mattpocock engineering skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ran `setup-matt-pocock-skills` from the `mattpocock-skills` plugin, which scaffolds the per-repo configuration its other engineering skills read before they touch an issue or a codebase. - `docs/agents/issue-tracker.md`: GitHub Issues on `Syndic/unnatural_designs`, driven by `gh`. Seeded from the skill's GitHub template, plus a note that `gh` runs on the host rather than through `devcontainer exec` — the carve-out this repo's tooling rule already makes for read-side `git` and `gh`, and where the authenticated session lives. "PRs as a request surface" stays off, the skill's default. Read by `to-tickets`, `to-spec`, `triage`, `wayfinder`, `code-review`, and `ask-matt`. - `docs/agents/triage-labels.md`: the five canonical triage roles, each label string equal to its name. None of the five exist on the repo yet; `triage` creates them on first use. - `docs/agents/domain.md`: multi-context layout, adapted away from the template's `src//` assumption. A context here is a Bazel package tree under one of the README's top-level directories, and only `//meta/` and `//tools/network_infrastructure_maintenance/` hold code today. - `.claude/CLAUDE.md`: an `## Agent skills` block pointing at the three files. It goes here rather than in a new root `CLAUDE.md` — the skill's literal instruction — because the project instructions already live at this path, and a second root file would split them in two. `CONTEXT-MAP.md` and `docs/adr/` are deliberately absent: the skill's own consumer rule has `domain-modeling` create them lazily, when a term or decision actually needs recording, rather than seeding empty scaffolding. Markdown-only, so nothing is packaged: `bazel run //:gazelle` produces no BUILD changes and no `glob()` in the tree matches these files. --- .claude/CLAUDE.md | 17 +++++++++++ docs/agents/domain.md | 59 ++++++++++++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 50 ++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 15 +++++++++ 4 files changed, 141 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/.claude/CLAUDE.md b/.claude/CLAUDE.md index 95218b3..43f3f45 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -328,3 +328,20 @@ fine for both: Bazel namespaces its output base by workspace path, and the modul content-addressed. It does mean a mount-target change is visible from other worktrees' running containers, which still mount the old volume at the old path — a volume's content is shared, its mount point is per-container. + +## Agent skills + +### Issue tracker + +Issues live in GitHub Issues on `Syndic/unnatural_designs`, driven via the `gh` CLI. See +`docs/agents/issue-tracker.md`. + +### Triage labels + +The five canonical triage roles, each label string equal to its name. See +`docs/agents/triage-labels.md`. + +### Domain docs + +Multi-context: a root `CONTEXT-MAP.md` points at a per-context `CONTEXT.md`, one per Bazel package +tree. See `docs/agents/domain.md`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..8b5f7b6 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,59 @@ +# Domain Docs + +How the engineering skills should consume this repo's domain documentation when exploring the +codebase. + +## Before exploring, read these + +- **`CONTEXT-MAP.md`** at the repo root: it points at one `CONTEXT.md` per context. Read each one + relevant to the topic. +- **`docs/adr/`**: system-wide architectural decisions. +- **`/docs/adr/`**: decisions scoped to a single context. + +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. + +Note that `.claude/CLAUDE.md` is a separate artifact and is not a substitute for a `CONTEXT.md`: it +carries cross-cutting engineering invariants (CI, devcontainer, Renovate plumbing), not the domain +glossary. + +## File structure + +This repo is multi-context. A context is a Bazel package tree under one of the top-level +directories documented in the README (`//apps/`, `//libs/`, `//services/`, `//tools/`, `//infra/`, +`//meta/`, `//platforms/`), not a directory under `src/`. + +``` +/ +├── CONTEXT-MAP.md ← points at each context's CONTEXT.md +├── docs/adr/ ← system-wide decisions +├── meta/ +│ ├── CONTEXT.md +│ └── docs/adr/ +└── tools/network_infrastructure_maintenance/ + ├── CONTEXT.md + └── docs/adr/ +``` + +Only `//meta/` and `//tools/network_infrastructure_maintenance/` hold code today; the other +top-level directories are scaffolding. Add a context's `CONTEXT.md` when that context gains code, +and register it in `CONTEXT-MAP.md` at the same time. + +Markdown docs are not Bazel targets, so adding one needs no `BUILD.bazel` edit. If a test ever reads +one as data, add it to an `exports_files` block in that package. + +## 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 the relevant `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..fefaed6 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,50 @@ +# Issue tracker: GitHub + +Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations. + +## Conventions + +- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies. +- **Read an issue**: `gh issue view --comments`, filtering comments by `jq` and also fetching labels. +- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters. +- **Comment on an issue**: `gh issue comment --body "..."` +- **Apply / remove labels**: `gh issue edit --add-label "..."` / `--remove-label "..."` +- **Close**: `gh issue close --comment "..."` + +Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone. Here +that resolves to `Syndic/unnatural_designs`. + +Run `gh` on the **host**, not via `devcontainer exec`: this repo's rule that all tooling runs in +the devcontainer carves out read-side `git` and `gh` as host commands, and the host holds the +authenticated `gh` session. + +## Pull requests as a triage surface + +**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_ + +When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents: + +- **Read a PR**: `gh pr view --comments` and `gh pr diff ` for the diff. +- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`). +- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`. + +GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`. + +## When a skill says "publish to the issue tracker" + +Create a GitHub issue. + +## When a skill says "fetch the relevant ticket" + +Run `gh issue view --comments`. + +## Wayfinding operations + +Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets. + +- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`. +- **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 #` at the top of the child body. Labels: `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev. +- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos///issues//dependencies/blocked_by -F issue_id=`, where `` is the blocker's numeric **database id** (`gh api repos///issues/ --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: #, #` line at the top of the child body. A ticket is unblocked when every blocker is closed. +- **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. +- **Claim**: `gh issue edit --add-assignee @me`, the session's first write. +- **Resolve**: `gh issue comment --body ""`, then `gh issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. 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 8f9646b82de72573b55bd8e77895fb962157e32c Mon Sep 17 00:00:00 2001 From: Joshua Yanchar Date: Wed, 19 Aug 2026 19:03:29 -0700 Subject: [PATCH 2/6] docs(agents): seed CONTEXT-MAP.md with the two contexts that hold code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/agents/domain.md` declares this repo multi-context, which means the engineering skills look for a root `CONTEXT-MAP.md` to find where each context lives. Nothing was there to find, so every skill fell through to "proceed silently" and got no domain bearings at all. The map names the two contexts that hold code today — `tools/network_infrastructure_maintenance/` (the NetBox/UniFi domain) and `meta/` (the repo's own automation) — and records the one relationship worth stating: `meta/` operates on the repository as an artifact and shares no domain language with what it builds, so a change in one is not expected to move the other's vocabulary. Per-context `CONTEXT.md` files are still absent, and the map says so inline rather than linking at files that aren't there. Those stay lazily created by `/domain-modeling`, when a term actually gets resolved; seeding empty glossaries would just be scaffolding that reads as a gap. The five scaffolding directories are listed under "Not yet contexts" with the rule for promoting one, so the next person to add code under `//apps/` or `//services/` knows the map is theirs to update. --- CONTEXT-MAP.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 CONTEXT-MAP.md diff --git a/CONTEXT-MAP.md b/CONTEXT-MAP.md new file mode 100644 index 0000000..434872e --- /dev/null +++ b/CONTEXT-MAP.md @@ -0,0 +1,40 @@ +# Context Map + +This repo is multi-context. A context is a Bazel package tree under one of the top-level +directories in the [README](README.md), not a directory under `src/`. See +[`docs/agents/domain.md`](docs/agents/domain.md) for how the engineering skills consume this file. + +Each context owns its own `CONTEXT.md` (its glossary) and its own `docs/adr/` (decisions scoped to +it). Repo-wide decisions live in `docs/adr/`. + +## Contexts + +- **Network infrastructure maintenance** — `tools/network_infrastructure_maintenance/` + _(`CONTEXT.md` not yet written)_ + + A home network modelled in [NetBox](https://netboxlabs.com/products/netbox/) and controlled by + [UniFi Network](https://unifi.ui.com/), plus the tools that keep those two in agreement: an audit + of the NetBox model's internal consistency, drift detection between intended and live state, and + a NetBox → UniFi sync. This is the only context with a domain in the modelling sense — + devices, cables, IP addressing, VRFs, PoE budgets, DHCP reservations. + +- **Repo meta** — `meta/` + _(`CONTEXT.md` not yet written)_ + + The monorepo's own automation: `meta/scripts/` (pre-commit checks, changed-path classification, + Renovate proposal ratification and manual-job triggering, base-image pin sync) and + `meta/devcontainer-base/` (the shared devcontainer base image, whose README is the canonical home + for the container plumbing this repo and `Syndic/.dotfiles` both consume). + +## Relationships + +- **Repo meta → every other context**: build-time and CI-time only. `meta/` operates on the + repository as an artifact — its files, its lockfiles, its container — and shares no domain + language with what the code inside those contexts is about. A change in one is not expected to + move the vocabulary of the other. + +## Not yet contexts + +`//apps/`, `//libs/`, `//services/`, `//platforms/`, and `//infra/` exist as scaffolding and carry +only a `BUILD.bazel`. Add a `CONTEXT.md` under one when it gains code, and register it above in the +same change. From b8196baceb73789cafd133b8ace2738c549ba70b Mon Sep 17 00:00:00 2001 From: Joshua Yanchar Date: Wed, 19 Aug 2026 19:29:16 -0700 Subject: [PATCH 3/6] docs(agents): stop calling //platforms/ scaffolding in CONTEXT-MAP.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `//platforms/` was listed alongside `//apps/`, `//libs/`, `//services/`, and `//infra/` as a directory that "exists as scaffolding and carries only a `BUILD.bazel`". That was written without reading the file. The other four hold a `BUILD.bazel` containing one comment line and nothing else; `platforms/BUILD.bazel` defines the three `platform()` targets `.bazelrc` selects with `--config=linux_x86_64`, `--config=linux_arm64`, and `--config=darwin_arm64`, and README.md points at them as the platform definitions. Being wrong about the emptiness also made the placement wrong. "Not yet contexts" carries an implicit promise — add a `CONTEXT.md` here once there's code — and `//platforms/` is not waiting on that. It has code now, and three constraint tuples still have no vocabulary to model and no decisions to record, so a glossary there would stay empty for reasons that won't change. It gets its own section saying so. `docs/agents/domain.md` keeps `//platforms/` in its parenthetical, which enumerates the README's top-level directories rather than asserting any of them is a context; the exception belongs in the map, which is where a reader looks for what is and isn't one. --- CONTEXT-MAP.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/CONTEXT-MAP.md b/CONTEXT-MAP.md index 434872e..71fe813 100644 --- a/CONTEXT-MAP.md +++ b/CONTEXT-MAP.md @@ -35,6 +35,13 @@ it). Repo-wide decisions live in `docs/adr/`. ## Not yet contexts -`//apps/`, `//libs/`, `//services/`, `//platforms/`, and `//infra/` exist as scaffolding and carry -only a `BUILD.bazel`. Add a `CONTEXT.md` under one when it gains code, and register it above in the -same change. +`//apps/`, `//libs/`, `//services/`, and `//infra/` are scaffolding: each carries a `BUILD.bazel` +holding nothing but a one-line comment. Add a `CONTEXT.md` under one when it gains code, and +register it above in the same change. + +## Not a context + +`//platforms/` does hold code — the three `platform()` definitions `.bazelrc` selects with +`--config=linux_x86_64`, `--config=linux_arm64`, and `--config=darwin_arm64` — but it is build +configuration rather than a domain. Three constraint tuples carry no vocabulary to model and no +decisions to record, so it gets no `CONTEXT.md` and is not expected to grow one. From e6f5a450a110b73b56caf3e10e73435362a94a42 Mon Sep 17 00:00:00 2001 From: Joshua Yanchar Date: Wed, 19 Aug 2026 19:32:54 -0700 Subject: [PATCH 4/6] docs(agents): drop the template's setup prompt from triage-labels.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The seed template ends with "Edit the right-hand column to match whatever vocabulary you actually use." That line is addressed to the human running `setup-matt-pocock-skills`, and it was answered when the file was written: the column says `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`, and those five labels now exist on the repo. Left in place it is worse than redundant. This file is read by agents as configuration, and a standing imperative in a config file reads as a directive to act on rather than as scaffolding from the generator that produced it. The mapping table is the whole contract; a maintainer who wants different label strings edits the table, and needs no instruction in the file to know it. `issue-tracker.md` keeps its "Set to `yes` if…" parenthetical, which is not the same thing: it declares the flag's current value and defines what the other value means, and a reader needs both to interpret the flag. --- docs/agents/triage-labels.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index b716855..ad2d1ca 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -11,5 +11,3 @@ The skills speak in terms of five canonical triage roles. This file maps those r | `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 c849a62e61b5dbe2b2b1b23a86e56fe9da39dcfe Mon Sep 17 00:00:00 2001 From: Joshua Yanchar Date: Wed, 19 Aug 2026 19:35:21 -0700 Subject: [PATCH 5/6] docs(agents): split built from planned in the network context MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CONTEXT-MAP.md described the network context as "the tools that keep those two in agreement: an audit…, drift detection…, and a NetBox → UniFi sync" — one sentence covering one binary that exists and two that don't. `bazel query 'kind("go_binary", //tools/...)'` returns only `cmd/netbox_audit:netbox_audit`; the tool's README describes the other two with their command names elided as dots, so they have no names yet, let alone code. The reason this matters more than an ordinary inaccuracy: `/triage` reads exactly this kind of domain description. Its first step searches for an existing implementation *by domain concept rather than by the request's wording*, and a hit is an already-implemented `wontfix` that closes the issue. So a future request for drift detection could be matched against a sentence claiming drift detection is part of the context, and closed as already-done. That branch also skips writing to `.out-of-scope/` — that KB is for rejected requests, not built ones — so the bogus close would leave less of a trail than a real rejection. Built and planned are now separate paragraphs, and a closing line says the vocabulary describes the modelled network rather than the tools that exist against it, so the domain language can't be read as an inventory. --- CONTEXT-MAP.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/CONTEXT-MAP.md b/CONTEXT-MAP.md index 71fe813..c388579 100644 --- a/CONTEXT-MAP.md +++ b/CONTEXT-MAP.md @@ -13,10 +13,19 @@ it). Repo-wide decisions live in `docs/adr/`. _(`CONTEXT.md` not yet written)_ A home network modelled in [NetBox](https://netboxlabs.com/products/netbox/) and controlled by - [UniFi Network](https://unifi.ui.com/), plus the tools that keep those two in agreement: an audit - of the NetBox model's internal consistency, drift detection between intended and live state, and - a NetBox → UniFi sync. This is the only context with a domain in the modelling sense — - devices, cables, IP addressing, VRFs, PoE budgets, DHCP reservations. + [UniFi Network](https://unifi.ui.com/). This is the only context with a domain in the modelling + sense — devices, cables, IP addressing, VRFs, PoE budgets, DHCP reservations. + + **Built:** `cmd/netbox_audit`, which validates the NetBox model for internal consistency. It is + the context's only binary. + + **Planned, not built:** drift detection between NetBox's intended state and the live UniFi + controller, and a NetBox → UniFi sync. The tool's README describes both with their command names + still elided, so neither has a name yet, let alone code. + + The vocabulary above describes the modelled network, not the set of tools that exist against it. + Treat a request for anything under "planned" as unimplemented: a redundancy check that matched a + request against this domain language would otherwise close a real one as already-done. - **Repo meta** — `meta/` _(`CONTEXT.md` not yet written)_ From a19177b5bae263f796a3d9e4e7b001cd4e9f039a Mon Sep 17 00:00:00 2001 From: Joshua Yanchar Date: Wed, 19 Aug 2026 20:29:49 -0700 Subject: [PATCH 6/6] docs(agents): point domain.md at CONTEXT-MAP.md instead of restating it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit domain.md carried its own copy of the directory inventory — "Only `//meta/` and `//tools/network_infrastructure_maintenance/` hold code today; the other top-level directories are scaffolding" — which is the same false claim about `//platforms/` that CONTEXT-MAP.md was corrected for. Fixing one copy and not the other left the branch contradicting itself: the map says `//platforms/` holds the three `platform()` targets `.bazelrc` selects, while domain.md said every directory but two was scaffolding. Both files are read by the same skills. The duplication is the actual defect; the drift is what it produced, inside a single commit. Which directories are contexts is precisely what CONTEXT-MAP.md exists to record, so domain.md now points there rather than restating a corrected version. The instruction it was wrapped around — add a `CONTEXT.md` when a context gains code, and register it in the same change — is domain.md's to give and stays. The paragraph above it keeps the README directory list: that defines what a context *is* and where one may live, which is this file's job, not an inventory of which ones exist. --- docs/agents/domain.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/agents/domain.md b/docs/agents/domain.md index 8b5f7b6..7c5c608 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -36,9 +36,9 @@ directories documented in the README (`//apps/`, `//libs/`, `//services/`, `//to └── docs/adr/ ``` -Only `//meta/` and `//tools/network_infrastructure_maintenance/` hold code today; the other -top-level directories are scaffolding. Add a context's `CONTEXT.md` when that context gains code, -and register it in `CONTEXT-MAP.md` at the same time. +Which directories are contexts, which are scaffolding awaiting one, and which will never be one is +recorded in `CONTEXT-MAP.md`. Add a context's `CONTEXT.md` when that context gains code, and +register it there in the same change. Markdown docs are not Bazel targets, so adding one needs no `BUILD.bazel` edit. If a test ever reads one as data, add it to an `exports_files` block in that package.