docs: minimize AGENTS.md, extract skills and agent config

thedavidweng · thedavidweng · commit 96c867bd3c7c · 2026-05-31T15:02:39.000-07:00
AGENTS.md reduced from 49 to 25 lines using progressive disclosure:
- Removed project description (redundant with CONTEXT.md)
- Removed project rules (enforced by code structure)
- Moved donor policy to .claude/skills/donor-policy.md
- Moved command contract checklist to .claude/skills/command-contract.md
- Added docs/agents/ for issue tracker, triage labels, and domain docs
diff --git a/.claude/skills/command-contract.md b/.claude/skills/command-contract.md
@@ -0,0 +1,15 @@
+---
+name: command-contract
+description: Checklist for CLI contract changes — run when modifying commands, flags, or JSON output
+---
+
+# Command Contract Discipline
+
+When changing CLI commands, flags, JSON output structure, or command behavior, verify these are updated:
+
+1. **Command help** — the cobra command's Short/Long/Example text
+2. **`docs/PRD.md`** — if product requirements changed
+3. **`docs/ARCHITECTURE.md`** — if module boundaries changed
+4. **Contract tests** — once the command is stable
+
+This is a checklist, not a blocker. If the change is internal-only (refactor without behavior change), skip.
diff --git a/.claude/skills/donor-policy.md b/.claude/skills/donor-policy.md
@@ -0,0 +1,20 @@
+---
+name: donor-policy
+description: Rules for working with donor/reference repositories in donors/
+---
+
+# Donor Policy
+
+Use donor repositories for reference:
+
+- `donors/monarchmoney-cli`: CLI contract and safety design.
+- `donors/ray-finance`: provider sync and local data lessons.
+- `donors/actual`: local-first budgeting and automation lessons.
+- `donors/maybe`: finance product/domain modeling.
+
+## Rules
+
+- Copying code from donors requires checking license compatibility first.
+- **Maybe is AGPL** — do not copy code from it unless the project intentionally adopts a compatible license.
+- Do not commit `donors/`; it is local reference material only.
+- When using donor code as reference, adapt the pattern to this project's types and interfaces rather than copying verbatim.
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,34 +1,25 @@
 # Agent Instructions
 
-遵循奥卡姆剃刀和第一性原理，不写兜底代码，检查代码是否有过时/死代码。
+不写兜底代码。检查过时/死代码。遵循奥卡姆剃刀。
 
-This project is a local-first finance backend for external AI agents. Keep the core boring and deterministic.
+## Agent skills
 
-## Project Rules
+### Issue tracker
 
-- Do not embed AI chat, model providers, conversation memory, hosted billing, telemetry, or required web-server behavior in the core.
-- Keep provider-specific behavior behind provider adapters.
-- Keep JSON contracts stable and tested before expanding command scope.
-- Do not silently fall back to old config paths, old provider names, or donor project behavior.
-- Do not commit `donors/`; it is local reference material only.
-- Prefer small deep modules with simple interfaces over many pass-through wrappers.
+GitHub Issues. See `docs/agents/issue-tracker.md`.
 
-## Donor Policy
+### Triage labels
 
-Use donor repositories for reference:
+needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. See `docs/agents/triage-labels.md`.
 
-- `donors/monarchmoney-cli`: CLI contract and safety design.
-- `donors/ray-finance`: provider sync and local data lessons.
-- `donors/actual`: local-first budgeting and automation lessons.
-- `donors/maybe`: finance product/domain modeling.
+### Domain docs
 
-Copying code from donors requires checking license compatibility first. Maybe is AGPL, so do not copy code from it unless the project intentionally adopts a compatible license.
+`CONTEXT.md` + `docs/adr/` at repo root. See `docs/agents/domain.md`.
 
-## Command Contract Discipline
+### Donor policy
 
-When changing CLI commands, flags, JSON output structure, or command behavior, update:
+See `.claude/skills/donor-policy.md` (load when touching `donors/`).
 
-- Command help.
-- `docs/PRD.md` if product requirements change.
-- `docs/ARCHITECTURE.md` if module boundaries change.
-- Contract tests once the command is stable.
+### Command contract
+
+See `.claude/skills/command-contract.md` (load when changing CLI commands or JSON output).
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
@@ -0,0 +1,35 @@
+# 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 producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (this repo):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   └── (ADRs go here as they are created)
+└── src/
+```
+
+## 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 `/grill-with-docs`).
+
+## 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
@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs 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 <number> --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 <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## 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 <number> --comments`.
diff --git a/docs/agents/triage-labels.md 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.
