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,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.