Skip to content
This repository was archived by the owner on Oct 23, 2026. It is now read-only.

Reset agent workflow docs to Matt's defaults #74

Merged
Jpatching merged 1 commit into from
Oct 15, 2026
Merged

Reset agent workflow docs to Matt's defaults #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 4 additions & 9 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
9 changes: 4 additions & 5 deletions docs/WORKBENCH.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.
38 changes: 0 additions & 38 deletions docs/agents/current-context.md
View file
Open in desktop

This file was deleted.

59 changes: 48 additions & 11 deletions docs/agents/domain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<context>/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…_
153 changes: 40 additions & 113 deletions docs/agents/issue-tracker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <file>`.
Prepare multiline bodies in a temporary file and review them before publishing.
- Read current status: `gh issue view <number> --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 <number> --repo Jpatching/combine --body-file <file>`.
- Apply/remove labels: `gh issue edit <number> --repo Jpatching/combine --add-label "..."`
or `--remove-label "..."`.
- Close: `gh issue close <number> --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
<file> [<file> ...]`. 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/<name>` 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/<number> --jq .id`, then add it with
`gh api --method POST repos/Jpatching/combine/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`.
The database ID is not the issue number or node ID. If dependencies are unavailable,
record `Blocked by: #<number>` 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:<type>` and native sub-issue links. If sub-issues are unavailable,
use a task list in the map and `Part of #<map>` 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 <number> --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 <number> --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 <number> --body "..."`
- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
- **Close**: `gh issue close <number> --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 <number> --comments` and `gh pr diff <number>` 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 <number> --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 #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`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/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --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: #<n>, #<n>` 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 <n> --add-assignee @me`, the session's first write.
- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
Loading
Loading