From fc7fd9b9235752a877b508434e43ab6ec2cec560 Mon Sep 17 00:00:00 2001 From: jpdev <192751547+Jpatching@users.noreply.github.com> Date: Thu, 15 Oct 2026 19:47:59 +0100 Subject: [PATCH] Reset agent workflow docs to Matt's defaults (#73) Restore the default issue-tracker, triage-label and domain docs, retire the current-context procedure and its links, and shrink the AGENTS.md agent-skills section to one pointer per subsection. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 13 +-- docs/WORKBENCH.md | 9 +- docs/agents/current-context.md | 38 -------- docs/agents/domain.md | 59 ++++++++++--- docs/agents/issue-tracker.md | 153 +++++++++------------------------ docs/agents/triage-labels.md | 23 ++--- scripts/workbench.py | 2 +- 7 files changed, 109 insertions(+), 188 deletions(-) delete mode 100644 docs/agents/current-context.md diff --git a/AGENTS.md b/AGENTS.md index b66577d..a5112cd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,26 +6,21 @@ Preserve the existing implementation and local changes. ## Agent skills -Use Matt Pocock's original skills; `ask-matt` selects the appropriate flow. - ### Issue tracker -New specs and tickets use Jpatching/combine GitHub Issues. Before repository edits -(including documentation), resuming work or tracker operations, read -[workspace and slice conventions](docs/agents/issue-tracker.md). +Issues and specs live in GitHub Issues (Jpatching/combine). See `docs/agents/issue-tracker.md`. ### Triage labels -Use Matt's five default labels. Before triage, read the [label mapping](docs/agents/triage-labels.md). +The five default triage labels, unchanged. See `docs/agents/triage-labels.md`. ### Domain docs -Use a root glossary and `docs/adr/`, created when needed. Before exploration, -read the [domain documentation rules](docs/agents/domain.md). +Single-context: root `GLOSSARY.md` and `docs/adr/`. See `docs/agents/domain.md`. ## Project reference -- Start/resume: the selected issue; for GTA, [#61 current summary](https://github.com/Jpatching/combine/issues/61) and [#20 acceptance](https://github.com/Jpatching/combine/issues/20). At a task boundary, use [context maintenance](docs/agents/current-context.md). +- Start/resume: the selected issue; for GTA, [#61 current summary](https://github.com/Jpatching/combine/issues/61) and [#20 acceptance](https://github.com/Jpatching/combine/issues/20). - Fortnite + Skate requirements: [interactive-world contract](docs/FORTNITE_SKATE.md). - Purpose and entry points: [README](README.md). - Parked Synergy: [menu guide](docs/TRICKSHOT_MENU.md); actual pinned GSC. diff --git a/docs/WORKBENCH.md b/docs/WORKBENCH.md index 8568201..d3f1f48 100644 --- a/docs/WORKBENCH.md +++ b/docs/WORKBENCH.md @@ -94,8 +94,7 @@ To present captured evidence directly, run This requests the local default viewers (Windows viewers when running in WSL); `--print-only` prints locations without opening anything. Confirm that the owner can see the evidence before requesting acceptance. A successful open request -does not prove that playback was visible or accepted. Follow the -[approval and squash-merge workflow](agents/issue-tracker.md#implementation-slices). +does not prove that playback was visible or accepted. Owner approval precedes merge. Select a reference and candidate clip or screenshot, record the expected/observed behaviour, and save the private JSON record beside the original media. The page previews local files, @@ -159,6 +158,6 @@ required. The checks pane reports the checkout identity before offering a run. Run `python3 scripts/verify.py` for the repository gate. Run relevant adapter and runtime checks for changed behaviour. Keep test, build, launch, gameplay, -owner acceptance and release claims separate. At the task boundary, follow -[context maintenance](agents/current-context.md) so the next session can recover -the goal, evidence, exact blocker and next action without relying on memory. +owner acceptance and release claims separate. At the task boundary, record the +goal, evidence, exact blocker and next action on the issue so the next session can +recover them without relying on memory. diff --git a/docs/agents/current-context.md b/docs/agents/current-context.md deleted file mode 100644 index c42dc7c..0000000 --- a/docs/agents/current-context.md +++ /dev/null @@ -1,38 +0,0 @@ -# Context maintenance - -## Start or resume - -1. Read the owner's selected issue and its acceptance criteria. For the GTA ride, - read [#61's current summary](https://github.com/Jpatching/combine/issues/61) - and [#20](https://github.com/Jpatching/combine/issues/20). -2. Verify the directory, branch, revision and local changes using - [workspace conventions](issue-tracker.md). Check installed runtime identity - separately before a runtime trial; a source revision is not loading evidence. -3. Consult historical comments or Git history for a specific question. Reuse - qualified setup unless a changed prerequisite calls for a fresh check. - -## Task boundary - -Update the existing issue's current summary when evidence changes the verdict: -candidate revision, passed behavior, blocker and next action. For GTA, #61 owns -that summary and #20 owns acceptance criteria. Keep routine diagnostic progress -in private run records; preserve historical comments without duplicating them. -Source checks, observed gameplay and owner acceptance remain separate claims. - -Keep unique build procedures in [reproduction instructions](../REPRODUCING.md), -resolved terms in the glossary and consequential decision rationale in ADRs. -Code and behavior tests explain implementation. Do not create permanent progress -snapshots or test-audit narratives. - -Follow [workspace conventions](issue-tracker.md) for review, publication and owner -approval. `python3 scripts/verify.py` checks tracked links and behavior tests; -it cannot establish factual freshness or gameplay acceptance. Review public -content before staging; keep private measurements, identities and media local. - -## Context transfer - -Use Matt's `ask-matt` phase-boundary guidance. A temporary handoff may transfer -work to another session, directory or person. Date the snapshot, identify its -source revision and link the owning issue and durable evidence. On arrival, -read the current issue and recheck Git; verify runtime identity before input. -A handoff supplies navigation, not current task authority or acceptance. diff --git a/docs/agents/domain.md b/docs/agents/domain.md index f5917d1..4032de0 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -1,14 +1,51 @@ -# Domain docs +# Domain Docs -Use a single context: `GLOSSARY.md` at the repository root and architecture -decision records (ADRs) under `docs/adr/`. +How the engineering skills should consume this repo's domain documentation when exploring the codebase. -Before exploring, read the glossary if it exists and any ADRs relevant to the -area being changed. If they are absent, proceed silently. `domain-modeling` -creates them only when terms or decisions are resolved; setup creates no empty -glossary or ADR directory. +## Before exploring, read these -Use the glossary's terms in issue titles, proposals, hypotheses and tests. -If a needed concept is missing, reconsider the wording or note the gap for -`domain-modeling`. Surface conflicts with an existing ADR explicitly instead -of silently overriding it. +- **`GLOSSARY.md`** at the repo root, or +- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic. +- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. + +If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. + +## File structure + +Single-context repo (most repos): + +``` +/ +├── GLOSSARY.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +Multi-context repo (presence of `GLOSSARY-MAP.md` at the root): + +``` +/ +├── GLOSSARY-MAP.md +├── docs/adr/ ← system-wide decisions +└── src/ + ├── ordering/ + │ ├── GLOSSARY.md + │ └── docs/adr/ ← context-specific decisions + └── billing/ + ├── GLOSSARY.md + └── docs/adr/ +``` + +## Use the glossary's vocabulary + +When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids. + +If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). + +## Flag ADR conflicts + +If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: + +> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index df7da13..b258aeb 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,118 +1,45 @@ # Issue tracker: GitHub -New specs and tickets live in [Jpatching/combine Issues](https://github.com/Jpatching/combine/issues). -Use the `gh` CLI with `--repo Jpatching/combine` for issue operations. -The repository is public: publish source-safe task descriptions and acceptance -criteria; keep private diagnostics, logs, settings, identities and game assets -outside Issues and Git. +Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations. ## Conventions -- Create: `gh issue create --repo Jpatching/combine --title "..." --body-file `. - Prepare multiline bodies in a temporary file and review them before publishing. -- Read current status: `gh issue view --repo Jpatching/combine --json body,title,state`. - Fetch `--comments` for a named evidence question or when the selected skill - requires the full ticket. -- List: `gh issue list --repo Jpatching/combine --state open --json number,title,body,labels,comments`, - with appropriate label and state filters. -- Comment: `gh issue comment --repo Jpatching/combine --body-file `. -- Apply/remove labels: `gh issue edit --repo Jpatching/combine --add-label "..."` - or `--remove-label "..."`. -- Close: `gh issue close --repo Jpatching/combine --comment "..."`. - -When a skill says “publish to the issue tracker”, create a GitHub issue. -When it says “fetch the relevant ticket”, read its full body, labels and comments. -GitHub shares issue and PR numbers; resolve ambiguous references before acting. - -**PRs as a request surface: no.** External PRs are not part of the triage queue. - -## Implementation slices - -Follow `ask-matt`: larger, multi-session work goes through `to-spec` and -`to-tickets`; small, clear work can go directly to `implement`. -Use `to-tickets`' existing rules: each slice delivers a complete behavior that -can be verified independently, fits one fresh context window, and declares -acceptance criteria and blockers. Obtain the owner's approval of the breakdown -before publishing tickets. Tickets produced by `to-tickets` are already ready -for implementation; apply `ready-for-agent` without sending them through triage. - -Complete each authorized source slice through: - -**One observable behavior → implement and test → review → commit and push → draft PR with evidence → owner approval → squash merge → synchronize local `main`.** - -Before requesting approval for a visible change, capture and automatically open -the actual clip or screenshots locally with `python3 scripts/workbench.py evidence - [ ...]`. Identify the demonstrated behavior and its limitations. -Keep private media local; the draft PR records source-safe evidence descriptions -and checks. A file path, passing test or viewer launch is not owner acceptance. -Wait for explicit approval of the presented candidate before marking the PR ready -and merging. Material behavior changes after approval require renewed evidence -and approval. Do not enable automatic merge while acceptance is pending. - -Bundle source, tests and durable documentation into one focused commit when practical. -Use additional commits for meaningful fixes or review responses, then squash the -finished PR into one commit on `main`. Record the final merged revision on the -issue; the issue summary owns the final revision. -Preserve published history and retained recovery branches. A superseded PR may -be closed after verifying its commits are contained in the selected candidate, -or preserving its useful findings in the owning issue or durable reference. -Link the replacement when closing; closure does not mean gameplay acceptance. - -For the owner-approved GTA evidence workflow (#61), keep retained riding, -collector and workflow changes in one integration candidate and draft PR. -Present source checks, runtime verdicts, unresolved criteria and private clips -for one explicit owner decision. Bounded diagnosis requires current runtime -authority; stop unchanged scenarios after two identical failures. This exception -replaces fragment-by-fragment approvals, not ground or gameplay acceptance. - -Use one focused branch and PR per other implementation slice. Resume existing -unfinished issues/branches/PRs and reuse their worktree with explicit command -working directories and edited paths. Before edits, after handoff and before -commit/push, verify `git rev-parse --show-toplevel`, `git branch --show-current`, -`git rev-parse HEAD` and `git status --short --branch`. Match the exact selected -directory and task branch; stop writes on a wrong target, `main` or detached HEAD. -Preserve unrelated changes; never force-switch, reset or stash them. Pass the -same directory and branch to delegated agents. A different chat attachment or -UI branch label does not block verified worktree operations; report the mismatch -without claiming the UI moved. Create new slice branches from synchronized `main`. - -Before pushing, inspect the remote and destination branch; publish the task branch, -not a refspec targeting `main`. - -Work only on slices whose blockers are complete. When blocked, record the exact -blocker on the existing issue/PR and preserve the branch. The owner may select -independent work while it is blocked. Review, required checks and owner approval must pass before -merging. Start the next new slice from updated `main` after completion. -Verify completion with a clean working tree, a merged PR, and identical local -`main` and `origin/main` revisions after fetching. Source integration does not -establish gameplay acceptance or authorize launch, deployment or release. -Keep experimental checkpoints on a separate `prototype/` branch and link -its question and verdict from the issue. A preserved experiment need not merge; -promote useful implementation through a reviewed source slice. Verify branch, -worktree and starting revision before edits. Remove completed worktrees only -after preserving commits and checking ignored local files. -This convention supplements Matt's original skills without modifying them. -If a routed skill is unavailable, report that fact and inspect its upstream -availability before installing or choosing an applicable installed skill. Never -claim an unavailable skill ran. - -The old Project cards and deleted plans remain historical. Leave the cards -untouched and do not import old plans or use them to select new work. - -## Blocking and wayfinding - -Publish approved tickets in dependency order. Use native GitHub issue dependencies: -fetch the blocker's database ID with -`gh api repos/Jpatching/combine/issues/ --jq .id`, then add it with -`gh api --method POST repos/Jpatching/combine/issues//dependencies/blocked_by -F issue_id=`. -The database ID is not the issue number or node ID. If dependencies are unavailable, -record `Blocked by: #` in the ticket body. A ticket is ready only when every -blocker is closed; the native `issue_dependencies_summary.blocked_by` counts open blockers. - -When `wayfinder` is selected, its map is an issue labelled `wayfinder:map`; children -use `wayfinder:` and native sub-issue links. If sub-issues are unavailable, -use a task list in the map and `Part of #` in each child. Create those additional -labels only when needed. Choose an unassigned open child with no open blockers, -in map order; claim with `gh issue edit --repo Jpatching/combine --add-assignee @me`. -Resolve with an answer comment, close the child, and add its result link to the -map's decisions. Preserve `to-tickets`' rule against changing or closing its parent issue. +- **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 / remove labels**: `gh issue edit --add-label "..."` / `--remove-label "..."` +- **Close**: `gh issue close --comment "..."` + +Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone. + +## Pull requests as a triage surface + +**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_ + +When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents: + +- **Read a PR**: `gh pr view --comments` and `gh pr diff ` for the diff. +- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`). +- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`. + +GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`. + +## 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`. + +## Wayfinding operations + +Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets. + +- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`. +- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #` at the top of the child body. Labels: `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev. +- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos///issues//dependencies/blocked_by -F issue_id=`, where `` is the blocker's numeric **database id** (`gh api repos///issues/ --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #, #` line at the top of the child body. A ticket is unblocked when every blocker is closed. +- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins. +- **Claim**: `gh issue edit --add-assignee @me`, the session's first write. +- **Resolve**: `gh issue comment --body ""`, then `gh issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index 01ea863..b716855 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -1,14 +1,15 @@ -# Triage labels +# Triage Labels -Use Matt's five default roles as labels in Jpatching/combine Issues. +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. -| Role in Matt's skills | Repository label | Meaning | -| --- | --- | --- | -| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | -| `needs-info` | `needs-info` | Waiting on the reporter for more information | -| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for agent implementation | -| `ready-for-human` | `ready-for-human` | Requires human implementation | -| `wontfix` | `wontfix` | Will not be actioned | +| 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 | -Triage incoming requests only; `to-tickets` output is already ready for implementation. -Create missing labels without replacing existing labels or their metadata. +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. diff --git a/scripts/workbench.py b/scripts/workbench.py index f366379..7579d6e 100644 --- a/scripts/workbench.py +++ b/scripts/workbench.py @@ -63,7 +63,7 @@ def open_views(session): shell_command = shlex.join(command) + "; exec bash" run("tmux", "new-window", "-d", "-t", target + ":", "-n", window, "-c", str(ROOT), shell_command) print(f"Created {window}") - print("Existing Codex/editor panes and selected window were preserved.") + print("Existing agent/editor panes and selected window were preserved.") def guide(tool, args):