Initialize Odin planning context

2026-09-25 23:15:51 +05:30
commit 017a3e53f3
5 changed files with 123 additions and 0 deletions
@@ -0,0 +1,29 @@
+# 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. If `CONTEXT-MAP.md` exists, use it to find the relevant context docs.
+- `docs/adr/`: read ADRs that touch the area you're about to work in.
+
+If any of these files don't exist, proceed silently. Don't flag their absence or suggest creating them upfront; `/domain-modeling` creates them when terms or decisions are resolved.
+
+## File structure
+
+This repo uses the single-context layout:
+
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept, use the term as defined in `CONTEXT.md`. If a needed concept isn't there, reconsider the terminology or note the gap for `/domain-modeling`.
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding it.
@@ -0,0 +1,43 @@
+# Issue tracker: Gitea
+
+Issues and specs for this repo live in Gitea Issues. Use the `tea` CLI from this clone. Authenticate to `https://git.bongbetic.com` with `tea login add` before using it.
+
+## Conventions
+
+- Create: `tea issues create --title "..." --description "..."`
+- Read an issue and its comments: `tea issues <number> --comments`
+- List open issues: `tea issues --state open`
+- List all issues: `tea issues --state all`
+- Get machine-readable output: `tea issues --output json`
+- List comments: `tea comments list <number>`
+- Add a comment: `tea comments add <number> "..."`
+- Add/remove labels: `tea issues edit <number> --add-labels "..."` / `--remove-labels "..."`
+- Assign: `tea issues edit <number> --add-assignees "<username>"`
+- Close: `tea issues close <number>`
+
+Use `--remote origin` if `tea` needs to select the Gitea login associated with this repo's remote.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** Triage applies to Gitea issues only.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `tea issues <number> --comments`.
+
+## Wayfinding operations
+
+The **map** is a Gitea issue with the Notes / Decisions-so-far / Fog sections.
+
+- **Map**: create one issue labelled `wayfinder:map`.
+- **Child ticket**: create one issue per ticket, with `Part of [<map title>](<map URL>)` at the top of its description, an HTML comment `<!-- wayfinder-map: <map number> -->` for exact membership filtering, and a `wayfinder:<type>` label (`research`/`prototype`/`grilling`/`task`). Refer to maps and tickets by linked titles in human-facing text.
+- **Blocking**: use Gitea's native issue dependencies, enabled on this repository. Add a blocker with `tea api --remote origin --method POST -f owner=xavierk -f repo=odin -F index=<blocker number> repos/xavierk/odin/issues/<ticket number>/dependencies`. Inspect blockers with a GET to the same endpoint. A ticket is unblocked when every blocker is closed. Fall back to a body convention only on an instance where native dependencies are unavailable.
+- **Frontier**: list open issues through `tea api`, paginating until exhausted, and filter by the map's membership marker. Skip any with an open native dependency or an assignee; first by issue creation order wins. Never claim an assigned issue.
+- **Claim**: assign yourself to the issue with `tea issues edit <number> --add-assignees "<username>"`. This is the session's first tracker write.
+- **Resolve**: add the answer with `tea comments add <number> "..."`, close the issue, then add a context pointer to the map's Decisions-so-far.
+
+For multiline issue bodies and comments, send JSON through `tea api --data @<file>` or `--data @-`; preserve literal text and newlines. For map edits, read the latest issue and PATCH its body with the returned `content_version`. On HTTP 409, reread and merge so another session's updates are preserved.
@@ -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.