docs(agents): scaffold docs/agents/ skill config files

- docs/agents/issue-tracker.md — GitHub, gsd-build/get-shit-done, .envrc token required
- docs/agents/triage-labels.md — confirmed=AFK-ready, approved-*=human-ready, needs-reproduction=needs-info
- docs/agents/domain.md — single-context, CONTEXT.md sections explained
- CLAUDE.md — fix stale triage label (needs-maintainer-review doesn't exist),
  fix stale domain note ('neither exists yet'), add .envrc token reminder to issue tracker summary
This commit is contained in:
Tom Boucher
2026-05-07 09:12:12 -04:00
parent e3b52c70bb
commit 48b01e4c9f
3 changed files with 83 additions and 0 deletions

32
docs/agents/domain.md Normal file
View File

@@ -0,0 +1,32 @@
# Domain Docs
How engineering skills consume this repo's domain documentation.
## Layout: single-context
```
/
├── CONTEXT.md ← domain glossary + recurring PR rules + workflow learnings
├── docs/adr/ ← architectural decisions
│ ├── 0001-dispatch-policy-module.md
│ └── 0002-command-contract-validation-module.md
└── ...
```
## Before exploring, read these
1. **`CONTEXT.md`** at the repo root — domain terms, module names, recurring PR mistakes, workflow learnings. Read in full before naming anything or proposing architecture changes.
2. **`docs/adr/`** — read ADRs relevant to the area you're working in before proposing structural changes. If your output contradicts an ADR, surface it explicitly:
> *Contradicts ADR-0002 — but worth reopening because…*
If either file doesn't exist yet, proceed silently.
## Use the glossary's vocabulary
When naming modules, writing issue titles, test descriptions, or commit messages — use terms as defined in `CONTEXT.md`. Don't drift to synonyms. If you need a concept that isn't in the glossary, note it for `/grill-with-docs` rather than inventing language.
## CONTEXT.md sections
- **Domain terms** — canonical module names and seam vocabulary (Dispatch Policy Module, Command Contract Validation Module, etc.)
- **Recurring PR mistakes** — CodeRabbit findings that recur; check before writing tests, shell scripts, changesets, or docs
- **Workflow learnings** — patterns learned from triage + PR cycles; check before writing new command/workflow files or test paths

View File

@@ -0,0 +1,32 @@
# Issue tracker: GitHub
Issues for this repo live in **GitHub Issues** at `gsd-build/get-shit-done`.
## Auth
Always read the token from `.envrc` — never use the ambient `gh auth` session (it resolves to enterprise credentials that cannot access this repo):
```bash
export GITHUB_TOKEN=$(grep GITHUB_TOKEN .envrc | cut -d\' -f2)
# or inline:
GITHUB_TOKEN=$(grep GITHUB_TOKEN .envrc | cut -d\' -f2) gh issue create ...
```
## Conventions
- **Create**: `gh issue create --repo gsd-build/get-shit-done --title "..." --body "..."`
- **Read**: `gh issue view <number> --repo gsd-build/get-shit-done --comments`
- **List**: `gh issue list --repo gsd-build/get-shit-done --state open --json number,title,labels --jq '...'`
- **Comment**: `gh issue comment <number> --repo gsd-build/get-shit-done --body "..."`
- **Label**: `gh issue edit <number> --repo gsd-build/get-shit-done --add-label "..." --remove-label "..."`
- **Close**: `gh issue close <number> --repo gsd-build/get-shit-done --comment "..."`
Always pass `--repo gsd-build/get-shit-done` explicitly — the local clone has multiple remotes and `gh` may resolve to the wrong one.
## When a skill says "publish to the issue tracker"
Create a GitHub issue at `gsd-build/get-shit-done`.
## When a skill says "fetch the relevant ticket"
Run `gh issue view <number> --repo gsd-build/get-shit-done --comments`.

View File

@@ -0,0 +1,19 @@
# Triage Labels
Maps the five canonical triage roles to the actual label strings in `gsd-build/get-shit-done`.
| Canonical role | Label in this repo | Notes |
|-------------------|--------------------------|----------------------------------------------------------------|
| `needs-triage` | `needs-triage` | Auto-applied by GitHub Action on every new issue |
| `needs-info` | `needs-reproduction` | Waiting on reporter — cannot reproduce, more info required |
| `ready-for-agent` | `confirmed` | Bug verified + fully specified — AFK agent can pick up |
| `ready-for-human` | `approved-enhancement` / `approved-feature` | Enhancement/feature approved by maintainer — human codes it |
| `wontfix` | `wontfix` | Will not be actioned |
## Notes on this repo's label model
- `confirmed` is the AFK-agent-ready signal for **bugs**. It means "verified to exist and reproducible."
- For **enhancements** and **features**, maintainer approval is `approved-enhancement` / `approved-feature` respectively. A contributor (human or agent) may not write code until one of these is applied.
- There is no separate "ready-for-human" vs "ready-for-agent" distinction for enhancements — both flow through the same `approved-*` labels. If the work requires human judgment (design decisions, external access), note it in the issue body.
- `needs-triage` is removed when any other state label is applied.
- `needs-reproduction` is used instead of the generic `needs-info` — be specific in triage comments about what reproduction steps or information are missing.