From 4e7a9e6d1f371bc0a36a7c186314cb00c00b6cc5 Mon Sep 17 00:00:00 2001 From: Wang Zhuoxuan Date: Wed, 27 May 2026 22:53:14 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20agents=20=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/agents/domain.md | 36 ++++++++++++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 23 +++++++++++++++++++++++ docs/agents/triage-labels.md | 15 +++++++++++++++ 3 files changed, 74 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/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..9404a83 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,36 @@ +# 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 producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved. + +## File structure + +Single-context repo: + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── 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 new file mode 100644 index 0000000..506de5e --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,23 @@ +# Issue tracker: Gitea + +Issues and PRDs for this repo live as Gitea issues on git.duoqi.me. Use the [`tea`](https://gitea.com/gitea/tea) CLI for all operations. + +## Conventions + +- **Create an issue**: `tea issues create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. +- **Read an issue**: `tea issues view `. Use `--output json` for machine-readable output. +- **List issues**: `tea issues list --output json` with appropriate `--labels` filters. +- **Comment on an issue**: `tea issues add-comment --message "..."`. +- **Apply / remove labels**: `tea issues edit --labels "..."`. +- **Close**: `tea issues close `. Post the explanation first with `tea issues add-comment --message "..."`, then close. +- **Pull requests**: Use `tea pr create`, `tea pr view`, `tea pr add-comment`, etc. — similar shape to `gh pr ...`. + +Infer the repo from `git remote -v` — `tea` does this automatically when run inside a clone. + +## When a skill says "publish to the issue tracker" + +Create a Gitea issue. + +## When a skill says "fetch the relevant ticket" + +Run `tea issues view `. 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.