chore(agents): install mattpocock skills + per-repo agent config

- 38 skills from mattpocock/skills into .agents/skills/ (symlinked into .claude/skills/ for Claude Code) - skills-lock.json for reproducible installs - docs/agents/: issue-tracker (Gitea via tea CLI), triage-labels (default five-role vocabulary), domain docs (single-context) - CLAUDE.md: add '## Agent skills' section pointing at docs/agents/ - .gitignore: un-ignore docs/agents/ under the local /docs/* rule
2026-09-24 13:24:29 -04:00
1 parent 0aeeb2d1f4
commit 5b5314631b
@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
@@ -0,0 +1,84 @@
+# Issue tracker: Gitea (self-hosted)
+
+Issues and specs for this repo live as issues on Gitea
+(`https://git.crkc.xyz/Apps/ImageApi`). Use the `tea` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `tea issues create --title "..." --description-file -`
+  (read the body from a heredoc on stdin), or `--description "..."` for a
+  one-liner. Add labels at creation with `--labels "..."`.
+- **Read an issue**: `tea issues <index> --comments`. Use
+  `tea issues list -f index,title,body,labels,comments -o json` for
+  machine-readable output.
+- **List issues**: `tea issues list --state open` (default state is open)
+  with appropriate `--labels` / `--keyword` filters.
+- **Comment on an issue**: `tea comments add <index> "..."` (alias:
+  `tea comments <index> "..."`).
+- **Apply / remove labels**: `tea issues edit <index> --add-labels "..."` /
+  `--remove-labels "..."`. Labels that don't exist yet are created by the
+  server on first use.
+- **Close**: `tea issues close <index>`. It does not accept a closing
+  comment, so post the explanation first with
+  `tea comments add <index> "..."`, then close.
+- **Raw API access** (for anything the `tea` subcommands don't cover):
+  `tea api <endpoint>` makes an authenticated request to the Gitea API
+  (prefixes `/api/v1/` when the path doesn't start with `/api/`).
+  Placeholders `{owner}` and `{repo}` are replaced from the current repo
+  context. Use `-F` for typed fields (numbers, booleans) and `-d` for raw
+  JSON bodies.
+
+Infer the repo from the `git remote` (`-R` lets `tea` discover the Gitea
+login from the remote); `tea` does this automatically when run inside a
+clone. Confirm the acting user with `tea whoami`.
+
+Unlike GitHub, Gitea numbers issues and pull requests separately, so a bare
+`#42` is unambiguous once you know which surface it refers to.
+
+## 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 `tea pulls` equivalents (`tea pulls list/view/edit`,
+`tea pulls close`, plus `tea comments` which covers PRs). Keep only PRs
+from outside collaborators (drop the repo owner and team members) when
+listing external PRs for triage.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `tea issues <index> --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.
+  `tea issues create --title "..." --labels wayfinder:map --description-file -`.
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its
+  description, labelled `wayfinder:<type>` (`research`/`prototype`/
+  `grilling`/`task`). Once claimed, the ticket is assigned to the driving
+  dev.
+- **Blocking**: Gitea's **native issue dependencies** (enabled on this
+  server), the canonical, UI-visible representation. Add an edge with
+  `tea api --method POST repos/{owner}/{repo}/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-issue-index>`
+  (the Gitea dependencies API takes the issue index, i.e. the visible
+  `#number`, not an internal database id). Where dependencies aren't
+  available, fall back to a `Blocked by: #<n>, #<n>` line at the top of
+  the child description. A ticket is unblocked when every blocker is
+  closed.
+- **Frontier query**: list the map's open children (issues whose
+  description carries `Part of #<map>`), drop any with an open blocker
+  (dependency or `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `tea issues edit <n> --add-assignees <username>` (the
+  session's first write; `<username>` from `tea whoami`).
+- **Resolve**: `tea comments add <n> "<answer>"`, then
+  `tea issues close <n>`, then append a context pointer (gist + link) to
+  the map's Decisions-so-far.
@@ -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.