From 901fbbc30aac0b0f941c7f9b22ceb2562de349b6 Mon Sep 17 00:00:00 2001 From: lex Date: Sun, 9 Aug 2026 14:56:36 +0800 Subject: [PATCH] docs: configure engineering skill workflow --- AGENTS.md | 14 +++++++++++++ CONTEXT-MAP.md | 11 ++++++++++ docs/agents/domain.md | 37 ++++++++++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 39 ++++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 13 ++++++++++++ 5 files changed, 114 insertions(+) create mode 100644 CONTEXT-MAP.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 index 065ef687d8..b6a7f32ee1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -214,3 +214,17 @@ Invariants for extending the SolidJS/opentui TUI. The DAG inspector (`src/featur - Keep delivery vocabulary explicit. Prompts steer by default and promote at the next safe provider-turn boundary while the current drain requires continuation. An explicit `queue` input remains pending until the Session would otherwise become idle; promote one queued input at that boundary, then reevaluate continuation before promoting another. Promoting any new user input resets the selected agent's provider-turn allowance; a batch of steers resets it once. - Keep EventV2 replay owner claims separate from clustered Session execution ownership. - Keep the System Context algebra, registry, and built-ins in `src/system-context`; keep Context Source producers with their observed domains, and keep Session History selection plus Context Epoch persistence Session-owned. + +## Agent skills + +### Issue tracker + +Issues and PRDs are tracked in this repository's GitHub Issues through the `gh` CLI. See `docs/agents/issue-tracker.md`. + +### Triage labels + +Triage uses the five canonical labels `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix`. See `docs/agents/triage-labels.md`. + +### Domain docs + +This repository uses a multi-context domain-document layout rooted at `CONTEXT-MAP.md`. See `docs/agents/domain.md`. diff --git a/CONTEXT-MAP.md b/CONTEXT-MAP.md new file mode 100644 index 0000000000..7de0a6c619 --- /dev/null +++ b/CONTEXT-MAP.md @@ -0,0 +1,11 @@ +# Context Map + +Read the context documents relevant to the code or decision under review. Do not load unrelated contexts by default. + +| Context | Domain document | Primary areas | +| --- | --- | --- | +| Session Runtime and Client Contract | [`CONTEXT.md`](CONTEXT.md) | `packages/opencode/src/session`, `packages/opencode/src/system-context`, `packages/protocol`, `packages/client`, `packages/sdk` | + +## Contexts created lazily + +DAG orchestration does not yet have a dedicated `CONTEXT.md`. The full DAG review must establish terminology from implementation, tests, existing specifications, and accepted decisions before `/domain-modeling` creates one. Add future contexts to this map only when they have a stable document to reference. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000000..c105390f44 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,37 @@ +# Domain Docs + +How engineering skills consume this repository's domain documentation while exploring the codebase. + +## Selected layout + +This repository uses a **multi-context** layout. `CONTEXT-MAP.md` is the entry point and points to the domain documents relevant to each bounded context. + +## Before exploring + +1. Read `CONTEXT-MAP.md` at the repository root. +2. Read each linked `CONTEXT.md` relevant to the work. +3. Read system-wide ADRs under `docs/adr/` and context-scoped ADRs linked by the map. + +If a referenced directory or document does not exist, proceed silently. Do not create speculative terminology or ADRs merely to fill the layout. `/domain-modeling`, reached through `/grill-with-docs` or `/improve-codebase-architecture`, creates them when terms or decisions are actually resolved. + +## File structure + +```text +/ +├── CONTEXT-MAP.md # context index +├── CONTEXT.md # existing Session Runtime context +├── docs/adr/ # system-wide decisions, created lazily +└── packages// + ├── CONTEXT.md # context vocabulary, created lazily + └── docs/adr/ # context decisions, created lazily +``` + +## Use the glossary vocabulary + +When an issue title, refactor proposal, hypothesis, or test names a domain concept, use the term defined in the relevant `CONTEXT.md`. Do not replace a defined term with a synonym that the glossary explicitly avoids. + +If the required concept is absent, reconsider whether the project already uses another term. If the gap is real, record it for `/domain-modeling`. + +## Flag ADR conflicts + +If proposed work contradicts an existing ADR, state the conflict 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 0000000000..0fb6455831 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,39 @@ +# Issue tracker: GitHub + +Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations. + +## Conventions + +- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies. +- **Read an issue**: `gh issue view --comments`, filtering comments by `jq` and also fetching labels. +- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters. +- **Comment on an issue**: `gh issue comment --body "..."` +- **Apply or remove labels**: `gh issue edit --add-label "..."` or `--remove-label "..."` +- **Close**: `gh issue close --comment "..."` + +Infer the repository from `git remote -v`; `gh` does this automatically when run inside this clone. + +## Pull requests as a triage surface + +**PRs as a request surface: no.** + +Pull requests are delivery artifacts, not incoming requests. `/triage` does not include them in its queue. + +GitHub shares one number space across issues and PRs. Resolve an ambiguous `#42` with `gh pr view 42`, then fall back to `gh issue view 42`. + +## Skill operations + +- When a skill says **publish to the issue tracker**, create a GitHub issue. +- When a skill says **fetch the relevant ticket**, run `gh issue view --comments`. +- Use GitHub's native blocking relationships when available. If unavailable, put `Blocked by: #` at the top of the issue body. + +## Wayfinding operations + +Used by `/wayfinder`. The map is one issue with child issues as tickets. + +- **Map**: an issue labelled `wayfinder:map`, holding Notes, Decisions-so-far, and Fog. +- **Child ticket**: a GitHub sub-issue labelled `wayfinder:` where type is `research`, `prototype`, `grilling`, or `task`. If sub-issues are unavailable, link it from a task list in the map and put `Part of #` at the top of the child body. +- **Blocking**: prefer GitHub native issue dependencies. Use the blocker's numeric database ID with the dependencies API, not its issue number or node ID. Fall back to a `Blocked by:` line only when native dependencies are unavailable. +- **Frontier query**: select the first open, unassigned child in map order whose blockers are all closed. +- **Claim**: `gh issue edit --add-assignee @me` is the working session's first write. +- **Resolve**: comment with the decision, close the child, and add its context pointer to the map's Decisions-so-far. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000000..80623348a4 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,13 @@ +# Triage Labels + +The engineering skills use five canonical triage roles. This table maps each role to the label used in this repository's GitHub Issues. + +| Canonical role | GitHub label | Meaning | +| --- | --- | --- | +| `needs-triage` | `needs-triage` | A maintainer needs to evaluate the issue | +| `needs-info` | `needs-info` | Waiting for more information from the reporter | +| `ready-for-agent` | `ready-for-agent` | Fully specified and ready for an agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation or judgment | +| `wontfix` | `wontfix` | Will not be actioned | + +When a skill mentions a triage role, use the corresponding GitHub label from this table.