From 017a3e53f382d906744facf51f694136deef6224 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 25 Sep 2026 23:15:51 +0530 Subject: [PATCH] Initialize Odin planning context --- AGENTS.md | 13 +++++++++++ CONTEXT.md | 23 +++++++++++++++++++ docs/agents/domain.md | 29 ++++++++++++++++++++++++ docs/agents/issue-tracker.md | 43 ++++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 15 +++++++++++++ 5 files changed, 123 insertions(+) create mode 100644 AGENTS.md create mode 100644 CONTEXT.md 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/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..361bf51 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,13 @@ +## Agent skills + +### Issue tracker + +Issues and specs live in this repo's Gitea Issues, managed with `tea`. See `docs/agents/issue-tracker.md`. + +### Triage labels + +Use the five default triage labels. See `docs/agents/triage-labels.md`. + +### Domain docs + +Single-context: root `CONTEXT.md` and `docs/adr/`. See `docs/agents/domain.md`. diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..a92bce5 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,23 @@ +# Odin + +Odin is Bongbetic's Linux benchmarking and system health suite. It helps people understand system performance, diagnose observed problems, and assess optimization advice. + +## Language + +**Benchmark run**: +One recorded execution of selected performance workloads and diagnostic checks on a system. + +**Run profile**: +A named selection of workloads and checks with an intended duration and stress level. Odin's profiles include quick, standard, and extended runs. + +**Capability coverage**: +The set of workloads and checks a system can perform with its available hardware, software, and permissions. Unavailable checks are reported with a reason. + +**Performance measurement**: +An observed result of a defined workload, with its units and execution conditions. + +**Health finding**: +An evidence-based statement about the condition or observed errors of a system component. + +**Optimization advice**: +A suggested action tied to an observed finding or measured limitation, together with its expected benefit and relevant tradeoffs. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..ebec914 --- /dev/null +++ b/docs/agents/domain.md @@ -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. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..69446c9 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -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 --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 ` +- Add a comment: `tea comments add "..."` +- Add/remove labels: `tea issues edit --add-labels "..."` / `--remove-labels "..."` +- Assign: `tea issues edit --add-assignees ""` +- Close: `tea issues close ` + +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 --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 []()` at the top of its description, an HTML comment `` for exact membership filtering, and a `wayfinder:` 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= repos/xavierk/odin/issues//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 --add-assignees ""`. This is the session's first tracker write. +- **Resolve**: add the answer with `tea comments add "..."`, 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 @` 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. 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.