docs: add agent and domain guidance

docs/agents/domain.md

@@ -0,0 +1,60 @@
+# Domain docs
+
+Engineering skills must consult this repository's domain documentation before
+exploring code.
+
+## Read before exploring
+
+- Read `CONTEXT.md` at the repository root.
+- If `CONTEXT-MAP.md` exists, use it to find the `CONTEXT.md` files relevant to
+  the task.
+- Read ADRs under `docs/adr/` that affect the area you will change. In a
+  multi-context repository, also check `src/<context>/docs/adr/`.
+
+If these files do not exist, proceed without comment. Do not suggest creating
+them before the project resolves domain terms or architectural decisions. The
+`/domain-modeling` skill, reached through `/grill-with-docs` and
+`/improve-codebase-architecture`, creates them when needed.
+
+## File structure
+
+This repository uses the single-context layout:
+
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+A repository with multiple bounded contexts can use this layout:
+
+```text
+/
+├── CONTEXT-MAP.md
+├── docs/adr/
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use glossary terms
+
+Use the terms defined in `CONTEXT.md` in issue titles, refactor proposals,
+hypotheses, and test names. Do not substitute synonyms that the glossary
+rejects.
+
+If a needed concept is absent, reconsider whether the project uses that concept.
+If it represents a real gap, record it for `/domain-modeling`.
+
+## Flag ADR conflicts
+
+Call out any proposal that conflicts with an ADR:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

docs/agents/issue-tracker.md

@@ -0,0 +1,106 @@
+# Issue tracker: Gitea
+
+Issues and specs for this repo live as Gitea issues. Use the
+[`tea`](https://gitea.com/gitea/tea) CLI for all operations.
+
+## Repository context
+
+Run commands inside the clone so `tea` can infer the repository and login from
+its Git remote. If the clone has multiple Gitea remotes or logins, pass
+`--remote <name>` or `--login <name>`. Use `--repo <owner>/<repo>` only outside
+the clone.
+
+Before the first operation, verify the instance with
+`tea logins list --output json`. If it is missing, ask the user to run
+`tea login add`; never ask for or handle their access token.
+
+## Conventions
+
+- **Create an issue**: `tea issues create --title "..." --description "..."`.
+  For a multi-line body, use shell command substitution around a quoted heredoc:
+
+  ```bash
+  tea issues create --title "..." --description "$(cat <<'EOF'
+  Multi-line issue body.
+  EOF
+  )"
+  ```
+
+- **Read an issue with comments**:
+  `tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`.
+- **List issues**:
+  `tea issues list --state open --fields index,state,author,url,title,body,assignees,labels,comments --output json`,
+  adding `--labels "label-one,label-two"`, `--assignee <user>`, or another
+  supported filter as needed. Paginate with `--page` and `--limit`; do not
+  assume the default first 30 results are complete.
+- **Comment on an issue**: `tea comments add <number> --description "..."`.
+- **Apply or remove labels**: `tea issues edit <number> --add-labels "..."` or
+  `--remove-labels "..."`. Separate multiple labels with commas.
+- **Assign or unassign**: `tea issues edit <number> --add-assignees "..."` or
+  `--remove-assignees "..."`.
+- **Close**: post the closing explanation with
+  `tea comments add <number> --description "..."`, then run
+  `tea issues close <number>`.
+- **Reopen**: `tea issues reopen <number>`.
+- **Raw API fallback**: use `tea api '<endpoint>'` only for a Gitea feature
+  without a first-class `tea` command. Prefer `{owner}` and `{repo}`
+  placeholders so repository context remains explicit.
+
+Use `--output json` for machine-readable reads. Do not scrape table output.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set this to `yes` if this repo treats
+external pull requests as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs use the same labels and states as issues:
+
+- **Read a PR with comments and diff**:
+  `tea pulls <number> --comments --fields index,state,author,url,title,body,diff,assignees,labels,comments --output json`.
+- **List open PRs**:
+  `tea pulls list --state open --fields index,state,author,author-id,url,title,body,assignees,labels,comments --output json`.
+  Determine whether an author is external from the repository's Gitea membership
+  data; the PR listing does not classify author membership.
+- **Comment**: `tea comments add <number> --description "..."`.
+- **Apply or remove labels**: `tea pulls edit <number> --add-labels "..."` or
+  `--remove-labels "..."`.
+- **Close**: `tea pulls close <number>`.
+
+Gitea pull requests use the repository's issue index space, so `#42` may refer
+to either surface. If the context is unclear, inspect it with
+`tea pulls 42 --output json`; if that command reports no PR, read it with
+`tea issues 42 --output json`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue with `tea issues create`.
+
+## When a skill says "fetch the relevant ticket"
+
+Run
+`tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`.
+
+## Wayfinding operations
+
+`/wayfinder` uses one **map** issue with linked **child** issues. These
+conventions store relationships in issue bodies, so they work across Gitea
+versions.
+
+- **Map**: create one issue labelled `wayfinder:map` containing the Notes,
+  Decisions-so-far, and Fog sections. Use
+  `tea issues create --labels "wayfinder:map"` with its title and description.
+- **Child ticket**: start the body with `Part of #<map>` and apply a
+  `wayfinder:<type>` label: `research`, `prototype`, `grilling`, or `task`. Add
+  each child as a task-list item in the map body to preserve frontier order.
+- **Blocking**: put `Blocked by: #<n>, #<n>` near the top of the child body. A
+  ticket becomes unblocked after every referenced blocker closes.
+- **Frontier query**: list all open children, order them by the map's task list,
+  and discard tickets with an open blocker or an assignee. Select the first
+  remaining ticket. Fetch each referenced blocker; do not infer its state from
+  map text.
+- **Claim**: resolve the active username with `tea whoami`, then run
+  `tea issues edit <n> --add-assignees "<username>"` as the session's first
+  write. Do not assume `@me` works.
+- **Resolve**: run `tea comments add <n> --description "<answer>"`, close the
+  child with `tea issues close <n>`, then append a context pointer and link to
+  the map's Decisions-so-far section.

docs/agents/triage-labels.md

@@ -0,0 +1,14 @@
+# Triage labels
+
+Engineering skills use five canonical triage roles. This table maps each role to
+the label string in this repository's issue tracker.
+
+| Canonical role    | Tracker label     | Meaning                                |
+| ----------------- | ----------------- | -------------------------------------- |
+| `needs-triage`    | `needs-triage`    | A maintainer must evaluate the issue   |
+| `needs-info`      | `needs-info`      | Waiting for more information           |
+| `ready-for-agent` | `ready-for-agent` | Fully specified and ready for an agent |
+| `ready-for-human` | `ready-for-human` | Requires human implementation          |
+| `wontfix`         | `wontfix`         | Maintainers will not act on the issue  |
+
+When a skill names a canonical role, use the corresponding tracker label.