From 19d35958cf00a5157adca3be8e9e11ad5f841fd3 Mon Sep 17 00:00:00 2001 From: Justin Puah Date: Mon, 31 Aug 2026 21:14:09 +1000 Subject: [PATCH 1/9] chore(pi): migrate to @earendil-works/pi-coding-agent, bump stale package pins Rename the deprecated npm scope @mariozechner/pi-coding-agent to @earendil-works/pi-coding-agent in the install commands (setup.ps1, setup.sh, pi/README.md). Bump pi/settings.json pins: pi-web-access 0.17.1 -> 0.27.0, pi-subagents 0.40.0 -> 0.60.0. The pi-subagents bump is a breaking change upstream: the top-level tasks: [...] dispatch call shape was removed at 0.41.0 in favor of workflowScript/runs.all. Update every doc citing the old shape or the old pinned version (pi/README.md, deep-review/DISPATCH.md, storm-research/DISPATCH.md, SKILL-OWNERSHIP.md) to the new call shape, verified against the actual 0.60.0 shipped source rather than changelog prose. deep-review's per-dimension tools: frontmatter dispatch and the outputMode sole-writer default both still hold unchanged at 0.60.0. Not yet exercised as a live smoke test end to end (blocked by an account-wide Codex usage-limit at authoring time, unrelated to these changes) -- flagged as such in the docs. Closes #165 --- ai-agents/SKILL-OWNERSHIP.md | 6 ++- ai-agents/skills/deep-review/DISPATCH.md | 36 +++++++------ ai-agents/skills/storm-research/DISPATCH.md | 58 ++++++++++++-------- pi/README.md | 59 +++++++++++++-------- pi/settings.json | 4 +- setup.ps1 | 4 +- setup.sh | 4 +- 7 files changed, 104 insertions(+), 67 deletions(-) diff --git a/ai-agents/SKILL-OWNERSHIP.md b/ai-agents/SKILL-OWNERSHIP.md index 1f12eac0..24f824b6 100644 --- a/ai-agents/SKILL-OWNERSHIP.md +++ b/ai-agents/SKILL-OWNERSHIP.md @@ -25,8 +25,10 @@ is the orchestrating session's own top-level `sandbox_mode` — which may itself findings-store write path on Codex hosts remains an open gap. `storm-research` is portable too, as of #172 resolving the #95 spike below: its five expert-lens prompts and citation-verifier fan-out need only parallel dispatch with distinct per-child prompts, no -per-child tool scoping, on Pi via `pi-subagents`' `subagent({ tasks: [...] })` reusing the -builtin `researcher` agent; see `ai-agents/skills/storm-research/DISPATCH.md`. `walkthrough` +per-child tool scoping. At the pinned `pi-subagents@0.60.0` this is `subagent({ workflowScript: +"return runs.all([...])" })` reusing the builtin `researcher` agent — the top-level +`tasks: [...]` call shape this note previously named was removed upstream at 0.41.0; see +`ai-agents/skills/storm-research/DISPATCH.md`. `walkthrough` is portable too, as of #91: its `~/.claude/learner-profile.md` path now resolves to the runtime's own config home (`~/.claude/`, `~/.codex/`, `~/.pi/agent/`); its stale `.claude/tickets.md`/`.claude/specs/*.md` reference was corrected to the current diff --git a/ai-agents/skills/deep-review/DISPATCH.md b/ai-agents/skills/deep-review/DISPATCH.md index 8055ae18..b17c2d01 100644 --- a/ai-agents/skills/deep-review/DISPATCH.md +++ b/ai-agents/skills/deep-review/DISPATCH.md @@ -43,8 +43,8 @@ use; no change from current behavior. ### Pi (`pi-subagents`) Express the allowlist as the child agent's `tools:` frontmatter — confirmed present at the -pinned `pi-subagents@0.40.0` (`RunnerSubagentStep.tools?: string[]`, shipped source, -`package/src/runs/shared/parallel-utils.ts`; also `agent-serializer.ts:10,58-63`). A dimension +pinned `pi-subagents@0.60.0` (`RunnerSubagentStep.tools?: string[]`, shipped source, +`package/src/runs/shared/parallel-utils.ts:44`; also `agent-serializer.ts:11,67-72`). A dimension with `no` in "Reads beyond diff?" gets `tools: read, grep`; one with `yes` gets `tools: read, grep, glob`. Never include `bash`, `edit`, or `write` — a reviewer that needs to mutate anything is out of contract. @@ -151,19 +151,23 @@ adapter, not one of the seven dimension workers. ## Dispatch call shape (Pi) -Two shapes exist in the pinned `pi-subagents@0.40.0` source: an ad-hoc multi-call in one turn, -and the scripted `runs.all`/`workflowScript` batch API. **This skill uses ad-hoc multi-call**, -matching what `council` already exercises in practice (`council`'s `CRITIQUE` step: "Launch all -charter seats as fresh isolated workers, together when parallel dispatch is available" — no -scripted workflow). Rationale: +At the pinned `pi-subagents@0.60.0`, two shapes exist for launching several children: an ad-hoc +multi-call in one turn (repeated single-child `subagent({ agent, task })` calls), and the +scripted `runs.all`/`workflowScript` batch API. As of 0.41.0, the package removed the older +top-level `tasks: [...]` array shape entirely — `workflowScript` is now the only way to batch +children in a single tool call — but ad-hoc multi-call was never affected by that removal, since +it never used `tasks[]`. **This skill uses ad-hoc multi-call**, matching what `council` already +exercises in practice (`council`'s `CRITIQUE` step: "Launch all charter seats as fresh isolated +workers, together when parallel dispatch is available" — no scripted workflow). Rationale: - Consistency — `deep-review`/`quick-review` compose with `council`'s contract; diverging to a scripted API for one skill and ad-hoc for the rest adds a second dispatch idiom for no functional gain. -- Evidence asymmetry — the `tools:` scoping field and the parallel-batch *mechanism* are - confirmed in the pinned 0.40.0 shipped source; the exact `runs.all()` call-site spelling is - confirmed only against newer (0.44.0) docs, not source-verified at the pin. Ad-hoc multi-call - avoids depending on the unverified spelling. +- Evidence asymmetry no longer applies at the current pin — the `tools:` scoping field, the + parallel-batch mechanism, and the `runs.all()` call-site spelling (`docs/workflows.md:38,88-92` + at the pinned 0.60.0) are all now confirmed directly in the pinned version's own shipped + source and docs, not inferred from a newer version. Ad-hoc multi-call remains the choice for + the consistency reason above, not because the scripted shape is unverified. This is **source-verified against the pinned version, not executed as a live smoke test** — no live Pi session was driven interactively in this session to confirm ad-hoc multi-call actually @@ -265,8 +269,10 @@ way whether `config_file` honors per-role `sandbox_mode`. `findings-schema.md` requires reviewer/verifier/fixer workers to **return** results — never write the store themselves. Under Pi, a child's `outputMode` defaults to `"inline"` -(`package/src/api/preflight.ts:398` at the pinned 0.40.0: `outputMode: input.outputMode ?? -"inline"`), meaning the child's result resolves back to the caller as text rather than being +(`package/src/shared/settings.ts:387` at the pinned 0.60.0: `task.outputMode ?? config.outputMode +?? "inline"`), meaning the child's result resolves back to the caller as text rather than being written to a file by the child. This holds the invariant by default — the orchestrator stays -the sole writer as long as dispatch never sets `outputMode: "file-only"`. Do not set it for -reviewer, verifier, or fixer children. +the sole writer as long as dispatch never sets `outputMode: "file-only"` and no project/user +`subagents` config sets a global `outputMode: "file-only"` default (the added +`config.outputMode` term at this version); this repo's `pi/settings.json` sets no such config. +Do not set it for reviewer, verifier, or fixer children. diff --git a/ai-agents/skills/storm-research/DISPATCH.md b/ai-agents/skills/storm-research/DISPATCH.md index f04e7cd8..a63fb175 100644 --- a/ai-agents/skills/storm-research/DISPATCH.md +++ b/ai-agents/skills/storm-research/DISPATCH.md @@ -15,43 +15,55 @@ no change from prior behavior. Phase 4b uses the same shape, one call per citati ## Pi (`pi-subagents`) -Call the `subagent` tool once, with all five lens prompts as entries in its `tasks` array: +At the pinned `pi-subagents@0.60.0` the top-level `tasks: [...]` array no longer exists: the +package removed it at 0.41.0 in favor of `workflowScript` as the sole public multi-agent +orchestration surface (confirmed in the package's own `CHANGELOG.md` and in +`src/extension/schemas.ts`, whose public call schema carries no `tasks` field). Call the +`subagent` tool once, with a `workflowScript` that fans out all five lens prompts through +`runs.all`: ```js -subagent({ tasks: [ - { agent: "researcher", task: "", output: false }, - { agent: "researcher", task: "", output: false }, - ... -] }) +subagent({ workflowScript: ` + return runs.all([ + { key: "lens-1", agent: "researcher", task: "", output: false }, + { key: "lens-2", agent: "researcher", task: "", output: false }, + ... + ]); +` }) ``` Use the builtin `researcher` agent, not a new custom agent definition. `researcher` already ships with `tools: read, write, web_search, fetch_content, get_search_content, intercom` (`pi-subagents`' own `agents/researcher.md`) — exactly what a lens or a verifier needs, and those web tools require `pi-web-access` to be installed, which is pinned alongside -`pi-subagents` in `pi/settings.json`. `tasks` does not require distinct `agent` values, only -distinct `task` values, so one reusable agent invoked five times is sufficient — matching -this skill's "no per-child tool scoping" requirement exactly. +`pi-subagents` in `pi/settings.json`. `runs.all` items do not require distinct `agent` values, +only distinct `key` and `task` values, so one reusable agent invoked five times is sufficient — +matching this skill's "no per-child tool scoping" requirement exactly. `runs.all` resolves to +an ordered array, not a key map, so read results by index or `.map(...)`, not by key. `researcher`'s frontmatter defaults to `output: research.md`. Since five lenses run in parallel and this skill wants each brief returned as text, not written to a shared file, -override `output: false` on every task entry to disable that per-agent default and rely on +override `output: false` on every `runs.all` item to disable that per-agent default and rely on `outputMode`'s `"inline"` default (`pi-subagents`' sole-writer invariant: children return text, the orchestrator is the only writer — same invariant `../deep-review/DISPATCH.md` -documents for its own children). Phase 4b's citation verifiers use the identical shape, one -`tasks` entry per citation cluster. +documents for its own children). `output` is a recognized per-item execution param at this +version (`src/workflows/scripted-workflow.ts`'s `AUTO_RESUME_PARAM_KEYS` lists it alongside +`outputMode`), so the override still applies. Phase 4b's citation verifiers use the identical +shape, one `runs.all` item per citation cluster. -**Verification status**: the `tasks` call shape above is confirmed against the pinned -`pi-subagents@0.40.0` package's own shipped `README.md` (worked examples using exactly this -shape) — this is the on-disk artifact actually installed in this repo's dev environment, not -a summary of upstream docs. It has **not** been exercised as a live smoke test end-to-end: a -direct `pi -p` probe against the only authenticated provider available at authoring time -(`openai-codex`, OAuth) returned `Codex error: The usage limit has been reached` for every -model and every prompt tried, including a bare `--no-tools` call, while `pi auth check ---provider openai-codex` reported `{"status": "ready"}` — an account-wide usage-limit block, -not a credentials problem, and not specific to `pi-subagents` or to this skill. Retry the -smoke test (call `subagent` with 2+ distinct-prompt `tasks` entries) once the limit clears -before relying on this skill for a real run; see `pi/README.md`. +**Verification status**: the `workflowScript`/`runs.all` call shape above is confirmed against +the pinned `pi-subagents@0.60.0` package's own shipped source (`src/extension/schemas.ts`, +`src/workflows/scripted-workflow.ts`) and its `docs/workflows.md` (worked examples using +exactly this shape) — this is the on-disk artifact actually installed in this repo's dev +environment, not a summary of upstream docs. It has **not** been exercised as a live smoke +test end-to-end: a direct `pi -p` probe against the only authenticated provider available at +authoring time (`openai-codex`, OAuth) returned `Codex error: The usage limit has been reached` +for every model and every prompt tried, including a bare `--no-tools` call, while `pi auth +check --provider openai-codex` reported `{"status": "ready"}` — an account-wide usage-limit +block, not a credentials problem, and not specific to `pi-subagents` or to this skill. Retry +the smoke test (call `subagent` with a `workflowScript` containing 2+ distinct-prompt +`runs.all` entries) once the limit clears before relying on this skill for a real run; see +`pi/README.md`. ## Codex CLI diff --git a/pi/README.md b/pi/README.md index c85f85a8..30b8656b 100644 --- a/pi/README.md +++ b/pi/README.md @@ -10,9 +10,9 @@ on its own. Each entry under `packages` pins an exact version (`npm:@`); Pi does not auto-update them. To bump a pin, edit the version in `settings.json`, verify the package still behaves as expected, then re-run `setup.ps1 -Module pi` (or `-Module ai-agents`) to project the -change. The Pi CLI itself (`@mariozechner/pi-coding-agent`) is unpinned but only installed +change. The Pi CLI itself (`@earendil-works/pi-coding-agent`) is unpinned but only installed once — setup skips the `npm install` when `pi` is already on PATH, so later runs never update -it; bump it manually with `npm install --global @mariozechner/pi-coding-agent@latest`. +it; bump it manually with `npm install --global @earendil-works/pi-coding-agent@latest`. Pi credentials and session/authentication state remain in Pi's user directory and are never copied by setup. @@ -71,32 +71,49 @@ installed versions rather than a guessed command example. prior blocker (#95): its five expert-lens prompts (Practitioner, Academic, Skeptic, Economist, Historian) and its citation-verifier fan-out both dispatch as parallel children with distinct prompts and no per-child tool scoping — a lighter bar than `deep-review`'s per-dimension tool -allowlists. On Pi, dispatch is `subagent({ tasks: [{ agent: "researcher", task: "", output: false }, ...] })`, reusing the builtin `researcher` agent (already carrying +allowlists. At the pinned `pi-subagents@0.60.0`, the top-level `tasks: [...]` call shape no +longer exists: it was removed at 0.41.0 in favor of `workflowScript` as the sole public +multi-agent orchestration surface (confirmed in the package's own `CHANGELOG.md` and in +`src/extension/schemas.ts`, whose public call schema carries no `tasks` field). Dispatch is now +`subagent({ workflowScript: "return runs.all([{ key: 'lens-1', agent: 'researcher', task: '', output: false }, ...]);" })`, reusing the builtin `researcher` agent (already carrying `pi-web-access`'s tools) five times with distinct `task` strings rather than a new custom agent, since this repo has no `pi/agents/` projection to discover one; `output: false` overrides `researcher`'s default `output: research.md` so results return inline instead of -colliding on one shared file. See `ai-agents/skills/storm-research/DISPATCH.md` for the full -per-runtime contract. The `tasks` call shape is source-verified against the installed -`pi-subagents@0.40.0` package's own shipped `README.md`, not executed as a live smoke test: a -direct `pi -p` probe against the only authenticated provider here (`openai-codex`, OAuth) -returned `Codex error: The usage limit has been reached` for every model and every prompt -tried, including a bare `--no-tools` call, while `pi auth check --provider openai-codex` -reported `{"status": "ready"}` — an account-wide usage-limit block, not a credentials problem. -Retry the smoke test (call `subagent` with 2+ distinct-prompt `tasks` entries) once the limit -clears before relying on this skill for a real run. +colliding on one shared file. `output` is a recognized per-item `runs.all` param at this +version (`src/workflows/scripted-workflow.ts`'s `AUTO_RESUME_PARAM_KEYS` lists it alongside +`outputMode`), so the override still applies. See `ai-agents/skills/storm-research/DISPATCH.md` +for the full per-runtime contract. This `workflowScript`/`runs.all` call shape is +source-verified against the installed `pi-subagents@0.60.0` package's own shipped source and +`docs/workflows.md`, not executed as a live smoke test: a direct `pi -p` probe against the only +authenticated provider here (`openai-codex`, OAuth) returned `Codex error: The usage limit has +been reached` for every model and every prompt tried, including a bare `--no-tools` call, while +`pi auth check --provider openai-codex` reported `{"status": "ready"}` — an account-wide +usage-limit block, not a credentials problem. Retry the smoke test (call `subagent` with a +`workflowScript` containing 2+ distinct-prompt `runs.all` entries) once the limit clears before +relying on this skill for a real run. `quick-review`, `deep-review`, `review-fix-loop`, and `fix-findings` (the review→fix skill set) are portable too, projected here from `ai-agents/skills/` alongside `council`. `deep-review`'s seven reviewer dimensions need something `council`'s symmetric critics don't: a distinct read-only tool allowlist per dimension. On Pi this is expressed as each spawned child's `tools:` -frontmatter — confirmed present in the pinned `pi-subagents@0.40.0` shipped source -(`RunnerSubagentStep.tools?: string[]`) — per the (derived, not transcribed from `dimensions.md`) -mapping in `ai-agents/skills/deep-review/DISPATCH.md`. Dispatch uses ad-hoc multi-call rather -than the scripted `runs.all`/`workflowScript` API, reasoned from `council`'s unscripted -isolated-worker contract plus pinned-source evidence — not from a live Pi run driven this -session; see DISPATCH.md for the source-verified-vs-live-smoke-tested distinction behind that -choice. The +frontmatter — confirmed present in the pinned `pi-subagents@0.60.0` shipped source +(`RunnerSubagentStep.tools?: string[]`, `src/runs/shared/parallel-utils.ts`) — per the (derived, +not transcribed from `dimensions.md`) mapping in `ai-agents/skills/deep-review/DISPATCH.md`. +`tools` is an agent-definition frontmatter field, not a per-call parameter, at this version too +(there is no `tools` field on the public `subagent` tool-call schema), so the dispatch mechanism +is unaffected by 0.41.0 removing the top-level `tasks[]` call shape (see the `storm-research` +paragraph above). Dispatch uses ad-hoc multi-call rather than the scripted `runs.all`/ +`workflowScript` API, reasoned from `council`'s unscripted isolated-worker contract plus +pinned-source evidence — not from a live Pi run driven this session; see DISPATCH.md for the +source-verified-vs-live-smoke-tested distinction behind that choice. This choice held up well: +`workflowScript` is now the *only* way to batch several children in one call, since `tasks[]` +and `runs.all` are no longer alternatives but the sole surface, so ad-hoc multi-call (repeated +single-child `subagent({ agent, task })` calls in one turn) remains the simpler, still-valid +path deep-review always used. The findings store's sole-writer invariant (reviewers/fixers return text, never write the store themselves) holds under Pi because a child's `outputMode` defaults to `"inline"` at the pinned -version, confirmed in source (`package/src/api/preflight.ts`). +version, confirmed in source (`src/shared/settings.ts`: `task.outputMode ?? config.outputMode ?? +"inline"`). Note the added `config.outputMode` term: a project or user `subagents` config could +set a global `outputMode: "file-only"` default, which would override this default for every +child; this repo's `pi/settings.json` sets no such config, so the invariant holds as installed. diff --git a/pi/settings.json b/pi/settings.json index 249948da..d646566d 100644 --- a/pi/settings.json +++ b/pi/settings.json @@ -9,8 +9,8 @@ "defaultProjectTrust": "always", "packages": [ "npm:@sherif-fanous/pi-catppuccin@0.2.0", - "npm:pi-web-access@0.17.1", + "npm:pi-web-access@0.27.0", "npm:pi-ask-user@0.13.1", - "npm:pi-subagents@0.40.0" + "npm:pi-subagents@0.60.0" ] } diff --git a/setup.ps1 b/setup.ps1 index 47f69859..923566f0 100644 --- a/setup.ps1 +++ b/setup.ps1 @@ -1047,14 +1047,14 @@ function Install-Pi { if (Get-Command -Name pi -ErrorAction Ignore) { Write-Ok 'pi is already installed.' } elseif ($DryRun) { - Write-Info '[DRY RUN] would install Pi via npm (@mariozechner/pi-coding-agent)' + Write-Info '[DRY RUN] would install Pi via npm (@earendil-works/pi-coding-agent)' } else { if (-not (Get-Command -Name npm -ErrorAction Ignore)) { Write-Fail 'npm not found — Pi setup stopped before changing Pi configuration.' return } Write-Info 'Installing Pi via npm...' - & npm install --global '@mariozechner/pi-coding-agent' + & npm install --global '@earendil-works/pi-coding-agent' if ($LASTEXITCODE -ne 0 -or -not (Get-Command -Name pi -ErrorAction Ignore)) { Write-Fail 'Pi installation failed — no Pi configuration or resources were changed.' return diff --git a/setup.sh b/setup.sh index 4c5b31db..cb640a97 100644 --- a/setup.sh +++ b/setup.sh @@ -451,11 +451,11 @@ install_pi() { if command -v pi >/dev/null 2>&1; then ok 'pi is already installed.' elif [[ $DRY_RUN -eq 1 ]]; then - info '[DRY RUN] would install Pi via npm (@mariozechner/pi-coding-agent)' + info '[DRY RUN] would install Pi via npm (@earendil-works/pi-coding-agent)' elif ! command -v npm >/dev/null 2>&1; then fail 'npm not found — Pi setup stopped before changing Pi configuration.' return - elif ! npm install --global '@mariozechner/pi-coding-agent' || ! command -v pi >/dev/null 2>&1; then + elif ! npm install --global '@earendil-works/pi-coding-agent' || ! command -v pi >/dev/null 2>&1; then fail 'Pi installation failed — no Pi configuration or resources were changed.' return else From 35920d93eedf60ddb237370d2892bf395c65a4bc Mon Sep 17 00:00:00 2001 From: Justin Puah Date: Mon, 31 Aug 2026 21:15:32 +1000 Subject: [PATCH 2/9] feat(agents): import implement-spec and retro skills from mattpocock/skills Port two portable skills from github.com/mattpocock/skills (found under skills/in-progress/, not top-level), adapted to this repo's conventions: - implement-spec: implement a whole spec as one pull request, working the ticket frontier with concurrent implementer subagents until every ticket lands. Orchestrates existing portable skills (to-spec, to-tickets, dispatch-implement, review-fix-loop, to-pullrequest) rather than reimplementing their mechanics, so it inherits dispatch-implement's current Claude-Code-only dispatch and sequential-only gate. - retro: conduct a retrospective on a coding session, surfacing improvements to the agent's environment (docs, checks, conventions) rather than to the code itself. References this repo's actual conventions in place of upstream's generic ones (write/writing-great- skills for skill-file candidates, ai-agents/skills/_shared/review- rubric.md for the conventions/review-rubric category, the three-file AGENTS.md/CLAUDE.md steering hierarchy). Adds roster entries to ai-agents/README.md and ai-agents/SKILL-OWNERSHIP.md. --- ai-agents/README.md | 2 + ai-agents/SKILL-OWNERSHIP.md | 7 +- ai-agents/skills/implement-spec/SKILL.md | 60 +++++++++++++++++ ai-agents/skills/retro/SKILL.md | 80 +++++++++++++++++++++++ ai-agents/skills/retro/agents/openai.yaml | 5 ++ 5 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 ai-agents/skills/implement-spec/SKILL.md create mode 100644 ai-agents/skills/retro/SKILL.md create mode 100644 ai-agents/skills/retro/agents/openai.yaml diff --git a/ai-agents/README.md b/ai-agents/README.md index 183a3c9b..31e72581 100644 --- a/ai-agents/README.md +++ b/ai-agents/README.md @@ -61,6 +61,7 @@ own `SKILL.md` frontmatter, trimmed to one line. Claude-native skills live in `. - **`health`** — Manual engineering health audit of your agent setup: Claude/Codex config drift, hooks, MCP, skills, memory and skill supply-chain security, and AI-maintainability drift. - **`i-have-adhd`** — Shape output for a reader with ADHD: lead with the next action, number multi-step work, restate state across turns, suppress tangents, give specific time estimates, make wins visible. `disable-model-invocation: true` — invoke explicitly with `/i-have-adhd`; stays on until "stop adhd mode". Adapted from [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT). - **`implement`** — Implement a piece of work from a spec or set of tickets: TDD at agreed seams, review, then commit. +- **`implement-spec`** — Implement a whole spec as one pull request, working the ticket frontier with concurrent implementer subagents until every ticket lands, then review and open the PR. - **`improve-codebase-architecture`** — Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. - **`jj`** — Use when working in a Jujutsu (jj) repository: making/describing changes, syncing with a remote, rewriting history, managing bookmarks or workspaces, or recovering via the op log. - **`linkedin-jobs`** — Read LinkedIn job alert emails and recruiter InMails, extract role details, and present them as structured cards grouped by inferred category. @@ -74,6 +75,7 @@ own `SKILL.md` frontmatter, trimmed to one line. Claude-native skills live in `. - **`redraft`** — Scrap the current fix and redo it properly, using everything learned while building the mediocre version. - **`refactor-agents-md`** — Refactor an AGENTS.md file to follow progressive disclosure: split it into a minimal root file plus linked category files. - **`resolving-merge-conflicts`** — Use when you need to resolve an in-progress git merge/rebase conflict. +- **`retro`** — Conduct a retrospective on a coding session, surfacing improvements to the agent's environment (docs, checks, conventions) rather than to the code itself. - **`review-ado-pr`** — Review an Azure DevOps pull request locally, end-to-end. - **`review-fix-loop`** — Iterative review-fix cycle for a branch or PR. - **`review-me`** — Interrogate the user on the current diff as an adversarial reviewer and withhold the PR until they pass. diff --git a/ai-agents/SKILL-OWNERSHIP.md b/ai-agents/SKILL-OWNERSHIP.md index 24f824b6..6636ad91 100644 --- a/ai-agents/SKILL-OWNERSHIP.md +++ b/ai-agents/SKILL-OWNERSHIP.md @@ -47,7 +47,12 @@ all three runtimes, but only Claude Code's dispatch is wired (the `Agent` tool, `isolation: "worktree"` for parallel children so they do not race one shared `.git/index`); on Codex CLI (`[agents.implementer]` + `spawn_agent`, #211) and Pi (`pi-subagents`, #212) the skill stops and reports instead of dispatching until those tickets land. Parallel dispatch is gated off -in favor of sequential-only until #213 confirms the base flow against real usage. +in favor of sequential-only until #213 confirms the base flow against real usage. `implement-spec` +is portable too: it only orchestrates calls into `to-spec`, `to-tickets`, `dispatch-implement`, +`review-fix-loop`, and `to-pullrequest` — all already portable or tracked as such — so it carries +no runtime-specific mechanics of its own. It inherits `dispatch-implement`'s current Claude-Code- +only dispatch and sequential-only gate at each frontier batch until that skill's own blockers +clear. ## Portable support (`ai-agents/skills/_shared/`) diff --git a/ai-agents/skills/implement-spec/SKILL.md b/ai-agents/skills/implement-spec/SKILL.md new file mode 100644 index 00000000..8c464c0a --- /dev/null +++ b/ai-agents/skills/implement-spec/SKILL.md @@ -0,0 +1,60 @@ +--- +name: implement-spec +description: Implement a whole spec as one pull request — work the ticket frontier with concurrent implementer subagents until every ticket lands, then review and open the PR. +disable-model-invocation: true +--- + +# Implement Spec + +Takes a spec and its tickets (`to-spec` + `to-tickets`, or their tracker equivalents) and lands +the whole thing as a single PR. The tickets are not a checklist — they are a task graph with +blocking edges, so there is always a **frontier** (`to-tickets`, `wayfinder`) of tickets ready to +grab. This skill drives that frontier to empty, then reviews and opens the PR. + +This is an orchestrator, not an implementer: `dispatch-implement` already owns per-ticket +mechanics (parallel-vs-sequential judgment, per-child model pick, worktree isolation, cherry-pick +integration onto the branch) — this skill calls it per batch rather than reimplementing any of +that. Keep prompts to subagents sparse: point at the spec, the tickets, and prior commits rather +than restating their content. + +## Steps + +1. **Read the spec and tickets.** Resolve their location from `.agents/workflow.local.md` when + present, otherwise `.agents/workflow.md` (`.agents/specs/.md` + `.agents/tickets.md` by + default, or the configured tracker). Read enough to see the full task graph — which tickets + block which — not just the first frontier. + +2. **Explore first, if a ticket needs it (optional).** When a ticket depends on unfamiliar + codebase areas or external documentation, delegate that reading to a background research + agent before implementation starts. Have it save its notes to a file outside the repo so every + later subagent can read it by path — a context pointer, not something repeated in each + subagent's prompt. + +3. **Branch and open a draft PR.** Create the branch per `AGENTS.md` → "Git worktrees" if this + repo uses that layout, then run `/to-pullrequest` to open it as a draft that closes the spec + issue and its tickets (GitHub linking keywords, or the tracker's native relationship). + +4. **Work the frontier to empty.** While any ticket remains open: run `/dispatch-implement` with + every ticket in the current frontier in one call — it judges which can run in parallel, isolates + parallel children in their own worktree, and integrates each onto the branch. Once a batch + lands, recompute the frontier (the tickets it just unblocked) and dispatch again. Repeat until + no ticket remains. + +5. **Review the whole branch.** With every ticket closed, run `/review-fix-loop` on the branch — + this catches cross-ticket issues no single ticket's implementer could see. + +6. **Mark the PR ready for review.** `to-pullrequest` stops at PR creation, so undraft directly: + `gh pr ready ` (GitHub) or `az repos pr update --id --draft false` (Azure DevOps). + +7. **Report** the PR URL, the tickets landed, and any ticket that had to be resolved outside the + normal frontier flow (rescoped, split, or dropped as out of scope). + +## Related + +- `to-spec`, `to-tickets` — produce the spec and task graph this skill consumes. +- `dispatch-implement` — owns the per-batch subagent mechanics (parallel judgment, worktree + isolation, cherry-pick integration); this skill only decides which tickets go in each batch. +- `review-fix-loop` — the whole-branch quality gate before the PR goes up for review. +- `to-pullrequest` — opens the draft PR; this skill undrafts it directly once review passes. +- `wayfinder` — the frontier/task-graph vocabulary this skill reuses, for planning work larger + than one spec. diff --git a/ai-agents/skills/retro/SKILL.md b/ai-agents/skills/retro/SKILL.md new file mode 100644 index 00000000..2f8d485c --- /dev/null +++ b/ai-agents/skills/retro/SKILL.md @@ -0,0 +1,80 @@ +--- +name: retro +description: Conduct a retrospective on a coding session, surfacing improvements to the agent's environment (docs, checks, conventions) rather than to the code itself. +disable-model-invocation: true +--- + +The user has asked for a **retrospective**. The goal is improvements to the coding agent's +**environment** — its docs, checks, and conventions — that make future sessions go better. +This is not a code review of the session's diff; it is a review of the scaffolding around it. + +## Steps + +1. Call the `write` skill for this repo's tone rules before drafting any proposed wording (no + AI-sounding phrasing, no em-dash, plain prose). If a candidate touches a skill file, call + `writing-great-skills` too, for the vocabulary that keeps a skill predictable. + +2. Read the primary sources for the session the user specifies. This may mean searching + through session logs on this machine. If the user doesn't specify a session, default to + the current one. + +3. Look for candidates for improvement in these categories. + +- **Navigation**: how easy was it for the agent to find the right files? Are there hidden + dependencies between files? Would a pointer in `AGENTS.md`, `ai-agents/AGENTS.md`, or a + skill's own body make it easier? _Use when_ the session took a long time to find a piece + of information. +- **Automated checks**: are there automated checks that could catch errors the agent made? + Linting (`PSScriptAnalyzer`), typing, tests, filesystem linters? _Use when_ the agent made + a mistake that could have been caught by an automated check. +- **Conventions and review rubric**: should `quick-review`/`deep-review` (via + `ai-agents/skills/_shared/review-rubric.md`) be given a new rule to enforce, or the shared + `ai-agents/AGENTS.md` conventions gain a new standing rule? Should an existing rule be + removed or clarified? _Use when_ review missed a mistake, or the same correction keeps + recurring across sessions. +- **Root steering files**: are there instructions in the root `AGENTS.md`, `ai-agents/AGENTS.md`, + or `claude/CLAUDE.md` that would serve better as a review-rubric rule or an automated check + instead? _Use when_ one of these files is growing large relative to what every task needs. +- **Tool economy**: did the agent make expensive tool calls that could be streamlined? Is + there any custom tooling (CLIs, MCP servers, skills) that is particularly token-inefficient? + _Use when_ the agent made an expensive tool call. +- **No-ops**: look for instructions in steering files that don't change the agent's behavior. + _Use when_ the steering files are large and unwieldy. +- **Information access**: look for opportunities to widen the agent's access to information — + tailing logs, read-only access to a third-party service. _Use when_ a piece of information + the agent needed wasn't available to it. + +4. Present these candidates to the user, in order of severity. Do not apply any of them + without the user's go-ahead. + +## Reference + +### Implementation vs review + +Work in this repo goes through two stages: implementation and review (`quick-review`, +`deep-review`, or the `review-fix-loop`). The implementation agent carries the most context +pressure — it does the exploring, the writing, the debugging. The review agent carries the +least — it works from a diff, so it does no exploration and rarely writes or debugs code. + +That split is why the review rubric (`ai-agents/skills/_shared/review-rubric.md`), not the +implementation agent's own prompt, is the right place to add a new standing convention: it +reaches every diff without adding context load to every implementation session. + +### Files + +Relevant files in this repo: + +- Root `AGENTS.md` and `claude/CLAUDE.md`: pushed into the context window of every agent + working in this repo. Keep these lean — pointers to detail, not the detail itself (see the + Authority index in the root `AGENTS.md`). +- `ai-agents/AGENTS.md`: shared coding conventions for Claude Code and Codex CLI. The natural + home for a new standing rule, ahead of a one-off note in the root file. +- `ai-agents/skills/_shared/review-rubric.md` (plus `dimensions.md`, `findings-schema.md`): + read during review, not implementation. This is where a convention becomes an enforced + check rather than a hope. +- `docs/adr/`: historical rationale and rejected alternatives, not a second copy of current + instructions. +- Skills under `ai-agents/skills/`: use a skill for a workflow the agent should follow, or for + reference the agent should consult on demand — its description sits in context every turn + when model-invoked, so keep it earning that cost. See `writing-great-skills` for the full + vocabulary. diff --git a/ai-agents/skills/retro/agents/openai.yaml b/ai-agents/skills/retro/agents/openai.yaml new file mode 100644 index 00000000..a2f0bac3 --- /dev/null +++ b/ai-agents/skills/retro/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Retro" + short_description: "Conduct a retrospective on a coding session." +policy: + allow_implicit_invocation: false From 243ccfd2f373591808e29c4188e78972d0bb43f5 Mon Sep 17 00:00:00 2001 From: Justin Puah Date: Mon, 31 Aug 2026 21:16:04 +1000 Subject: [PATCH 3/9] feat(agents): add critique-plan skill (trial) from ayoubben18/ab-method Port critique-plan from github.com/ayoubben18/ab-method (MIT): dispatches one isolated read-only subagent to critique a drafted plan against the project's domain model before any code is written, firing only on five conflict types (terminology drift, wrong bounded context, ADR contradiction, bad dependency edge, reinvented concept). Silence is the expected outcome for a clean plan. Dropped upstream's .ab-method/structure/index.yaml and unresolved-questions.md conventions, which don't exist in this repo; reuses grill-with-docs' CONTEXT.md/ADR-FORMAT.md/CONTEXT-FORMAT.md conventions and this repo's actual plan sources (to-spec, to-tickets) instead. Marked (trial) in ai-agents/README.md, not yet a settled convention. --- ai-agents/README.md | 1 + ai-agents/SKILL-OWNERSHIP.md | 8 ++- ai-agents/skills/critique-plan/SKILL.md | 86 +++++++++++++++++++++++++ 3 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 ai-agents/skills/critique-plan/SKILL.md diff --git a/ai-agents/README.md b/ai-agents/README.md index 31e72581..9a8f3866 100644 --- a/ai-agents/README.md +++ b/ai-agents/README.md @@ -52,6 +52,7 @@ own `SKILL.md` frontmatter, trimmed to one line. Claude-native skills live in `. - **`council-code`** — Thin council alias for technical designs, ADRs, APIs, and approach documents. - **`council-doc`** — Thin council alias for presentations, proposals, and important documents. - **`council-plan`** — Thin council alias for project plans, roadmaps, and migrations. +- **`critique-plan`** *(trial)* — Stress-test a drafted plan against the project's domain model before any code is written: terminology drift, wrong bounded context, ADR contradictions, bad dependency edges, reinvented concepts. Adapted from [ayoubben18/ab-method](https://github.com/ayoubben18/ab-method) (MIT). - **`deep-review`** — Heavy multi-dimension cross-model code review of a branch diff or PR, the opt-in deep pass, not the default. - **`diagnosing-bugs`** — Diagnosis loop for hard bugs and performance regressions. - **`dispatch-implement`** — Dispatch one subagent per ticket to run `/implement` on it. diff --git a/ai-agents/SKILL-OWNERSHIP.md b/ai-agents/SKILL-OWNERSHIP.md index 6636ad91..02baea39 100644 --- a/ai-agents/SKILL-OWNERSHIP.md +++ b/ai-agents/SKILL-OWNERSHIP.md @@ -52,7 +52,13 @@ is portable too: it only orchestrates calls into `to-spec`, `to-tickets`, `dispa `review-fix-loop`, and `to-pullrequest` — all already portable or tracked as such — so it carries no runtime-specific mechanics of its own. It inherits `dispatch-implement`'s current Claude-Code- only dispatch and sequential-only gate at each frontier batch until that skill's own blockers -clear. +clear. `critique-plan` +is portable too, and new: it dispatches one isolated read-only subagent to critique a drafted +plan against the domain model, reusing `grill-with-docs`' `CONTEXT.md`/`ADR-FORMAT.md`/ +`CONTEXT-FORMAT.md` conventions rather than a runtime-specific mechanism. Marked trial in +`ai-agents/README.md` — adapted from +[ayoubben18/ab-method](https://github.com/ayoubben18/ab-method) (MIT); not yet a settled +convention. ## Portable support (`ai-agents/skills/_shared/`) diff --git a/ai-agents/skills/critique-plan/SKILL.md b/ai-agents/skills/critique-plan/SKILL.md new file mode 100644 index 00000000..27176f41 --- /dev/null +++ b/ai-agents/skills/critique-plan/SKILL.md @@ -0,0 +1,86 @@ +--- +name: critique-plan +description: Stress-test a drafted plan against the project's domain model before any code is written — terminology drift, wrong bounded context, ADR contradictions, bad dependency edges, reinvented concepts. Use before implementing from a spec or ticket set, or when the user asks to critique, pressure-test, or sanity-check a plan against the domain model. +metadata: + status: trial +--- + +# Critique Plan (pre-implementation) + +Stress-test a drafted plan against the project's domain model before any code is written. This +skill produces pushbacks, not suggestions — it never gold-plates a plan that is already sound. + +Silence is the expected outcome. A plan that speaks the canonical language and respects the +documented decisions gets a one-line "No objections." Do not manufacture concerns to look +thorough. + +"The plan" is whatever came out of `to-spec` or `to-tickets`, a set of tickets already on the +tracker, or whatever the user pastes in standalone. + +## Process + +### 1. Load the domain model + +Read only what exists; skip missing files silently — don't flag them or offer to create them. +Look for `CONTEXT.md` (or `CONTEXT-MAP.md` plus each context's own `CONTEXT.md`, per +[grill-with-docs](../grill-with-docs/SKILL.md#file-structure)) and `docs/adr/`. + +If neither exists, say so in one line and stop — there is no domain model to critique against. + +### 2. Spin up one read-only domain critic + +Dispatch a single isolated, read-only subagent with the plan verbatim and the files from step 1. +It returns pushbacks as text and edits nothing. Isolating it keeps the critique out of the +planning session's context. Its brief: + +Fire only on a genuine conflict, one of: + +- **Terminology drift** — the plan names a concept differently from the glossary/`CONTEXT.md`, or + reuses a canonical term for a new meaning. +- **Wrong bounded context** — work placed in the wrong context, or a unit that straddles a + documented boundary. +- **Contradicts an ADR** — reverses a recorded decision and the friction is real enough to reopen + it. Cite `ADR-NNNN`. +- **Bad dependency edge** (ticket set) — a "blocked by" edge crosses a context boundary the wrong + way, two "independent" tickets share a domain concept, or a ticket is mis-scoped (an epic, or + several tickets dressed as one). +- **Reinvents a named concept** — introduces a new abstraction for something the domain model + already names. + +For each, return: **What** (the ticket/decision in question), **Conflicts with** (the exact +term / `CONTEXT.md` section / `ADR-NNNN`), **Why it matters** (concrete cost, not taste), +**Suggested resolution**. + +Example pushback: "Ticket 3 calls it `archiveOrder`, but the glossary defines archiving as +retention only — this ticket also stops billing, which is Cancellation. Rename to `cancelOrder` +so the code matches the domain, or the two concepts will blur across the codebase." + +A deliberately deferred decision the plan already marks as such (a stated placeholder, an +explicit TBD) is not a gap to flag — the user chose to defer it. Fire on it only if the +placeholder itself conflicts with the domain model: it contradicts an ADR, or it quietly +redefines a canonical term. + +Out of scope for this critic: implementation quality, performance, tests, code style, "you could +also…" ideas — anything not anchored in the domain model. Those belong to `spec-review` (does the +diff match the spec) or `quick-review`/`deep-review` (code quality), which run after +implementation. With nothing anchored, the critic returns exactly: +`No objections — the plan is consistent with the domain model.` + +### 3. Surface pushbacks — advisory, never blocking + +Bring the pushbacks back into the planning session. The user resolves each their own way: + +- **Accept** → amend the plan (rename, re-scope, fix the edge, move contexts) right there. +- **Dismiss** → drop it. If the dismissal rests on a load-bearing reason a future planner would + need in order not to re-raise it, offer to record an ADR using + [grill-with-docs' ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). Skip ephemeral ("not now") + and self-evident reasons. + +When a resolution sharpens a term, update `CONTEXT.md` inline using +[grill-with-docs' CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md). + +If the critic returned "No objections," say so in one line and move on. Don't pad it. + +`grill-with-docs`/`grilling` is a full interactive re-grill of the design; `critique-plan` is a +single-pass, silent-by-default gate — one critic, real conflicts only, then straight back to the +workflow. From 59307ddd9744227a83e778a1e20ff0682fdeb31b Mon Sep 17 00:00:00 2001 From: Justin Puah Date: Mon, 31 Aug 2026 21:35:21 +1000 Subject: [PATCH 4/9] feat(agents): split grill-with-docs into grilling + domain-modeling skills Match github.com/mattpocock/skills' current design: grilling now owns the interview mechanics, domain-modeling (new) owns the CONTEXT.md/ADR discipline. grill-with-docs becomes a thin pointer invoking both. grilling also adopts upstream's frontier-round interview model (batch the whole frontier of decisions whose prerequisites are settled into one numbered round with a recommended answer each, instead of one question at a time), plus two rules folded in from comparing against the @firstpick/pi-extension-grill-me Pi extension: an explicit per-decision status vocabulary (resolved/open/needs-codebase-check, resolved only on the user's explicit answer) and a session-end wrap-up (agreed decisions, open risks, next decision needed) before implementation starts. domain-modeling is independently model-invocable, unlike the old grill-with-docs (disable-model-invocation stays only on the pointer skill and on grilling). Repoint every reference to the old grill-with-docs/CONTEXT-FORMAT.md and ADR-FORMAT.md paths (critique-plan, improve-codebase-architecture in a separate commit, claude/skills/router) to domain-modeling, and update the skill rosters in README.md and ai-agents/README.md. --- README.md | 5 +- ai-agents/README.md | 5 +- ai-agents/SKILL-OWNERSHIP.md | 8 +- ai-agents/skills/critique-plan/SKILL.md | 8 +- .../ADR-FORMAT.md | 0 .../CONTEXT-FORMAT.md | 0 ai-agents/skills/domain-modeling/SKILL.md | 74 +++++++++++++++++ ai-agents/skills/grill-with-docs/SKILL.md | 80 +------------------ ai-agents/skills/grilling/SKILL.md | 42 ++++++++-- claude/skills/router/SKILL.md | 2 +- 10 files changed, 130 insertions(+), 94 deletions(-) rename ai-agents/skills/{grill-with-docs => domain-modeling}/ADR-FORMAT.md (100%) rename ai-agents/skills/{grill-with-docs => domain-modeling}/CONTEXT-FORMAT.md (100%) create mode 100644 ai-agents/skills/domain-modeling/SKILL.md diff --git a/README.md b/README.md index 75822196..04130b29 100644 --- a/README.md +++ b/README.md @@ -104,8 +104,9 @@ Not sure which one fits? Run `/router` — a manual index that maps these as flo | Skill | Source | Purpose | |---|---|---| -| `grill-with-docs` | mattpocock/skills | Stateful grilling against the domain model; updates `CONTEXT.md`/ADRs inline | -| `grilling` | mattpocock/skills | Stateless relentless-interview primitive to stress-test a plan | +| `grill-with-docs` | mattpocock/skills | Thin pointer invoking `grilling` and `domain-modeling` together | +| `grilling` | mattpocock/skills | Relentless-interview primitive to stress-test a plan, in batched frontier rounds | +| `domain-modeling` | mattpocock/skills | Challenge terminology against `CONTEXT.md`, sharpen fuzzy language, record ADRs | | `prototype` | mattpocock/skills | Throwaway prototype for a state/logic question or UI exploration | | `to-spec` | mattpocock/skills | Turn the conversation into a spec | | `to-hld` | local | Turn the discussion into a high-level design doc — decisions + mermaid | diff --git a/ai-agents/README.md b/ai-agents/README.md index 9a8f3866..ea38a833 100644 --- a/ai-agents/README.md +++ b/ai-agents/README.md @@ -56,9 +56,10 @@ own `SKILL.md` frontmatter, trimmed to one line. Claude-native skills live in `. - **`deep-review`** — Heavy multi-dimension cross-model code review of a branch diff or PR, the opt-in deep pass, not the default. - **`diagnosing-bugs`** — Diagnosis loop for hard bugs and performance regressions. - **`dispatch-implement`** — Dispatch one subagent per ticket to run `/implement` on it. +- **`domain-modeling`** — Build and sharpen a project's domain model: challenge terminology against `CONTEXT.md`, sharpen fuzzy language, and record ADRs as decisions crystallise. - **`fix-findings`** — Apply fixes for findings produced by quick-review or deep-review. -- **`grilling`** — Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. -- **`grill-with-docs`** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. +- **`grilling`** — Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree in batched frontier rounds. +- **`grill-with-docs`** — Thin pointer invoking `grilling` and `domain-modeling` together for a grilling session that also updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. - **`health`** — Manual engineering health audit of your agent setup: Claude/Codex config drift, hooks, MCP, skills, memory and skill supply-chain security, and AI-maintainability drift. - **`i-have-adhd`** — Shape output for a reader with ADHD: lead with the next action, number multi-step work, restate state across turns, suppress tangents, give specific time estimates, make wins visible. `disable-model-invocation: true` — invoke explicitly with `/i-have-adhd`; stays on until "stop adhd mode". Adapted from [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT). - **`implement`** — Implement a piece of work from a spec or set of tickets: TDD at agreed seams, review, then commit. diff --git a/ai-agents/SKILL-OWNERSHIP.md b/ai-agents/SKILL-OWNERSHIP.md index 02baea39..28fa1064 100644 --- a/ai-agents/SKILL-OWNERSHIP.md +++ b/ai-agents/SKILL-OWNERSHIP.md @@ -54,11 +54,15 @@ no runtime-specific mechanics of its own. It inherits `dispatch-implement`'s cur only dispatch and sequential-only gate at each frontier batch until that skill's own blockers clear. `critique-plan` is portable too, and new: it dispatches one isolated read-only subagent to critique a drafted -plan against the domain model, reusing `grill-with-docs`' `CONTEXT.md`/`ADR-FORMAT.md`/ +plan against the domain model, reusing `domain-modeling`'s `CONTEXT.md`/`ADR-FORMAT.md`/ `CONTEXT-FORMAT.md` conventions rather than a runtime-specific mechanism. Marked trial in `ai-agents/README.md` — adapted from [ayoubben18/ab-method](https://github.com/ayoubben18/ab-method) (MIT); not yet a settled -convention. +convention. `domain-modeling` is portable too, split out of `grill-with-docs` to match +[mattpocock/skills](https://github.com/mattpocock/skills)' current design: the CONTEXT.md/ADR +discipline stands on its own, independently model-invocable, while `grilling` (also +mattpocock/skills) carries the interview mechanics and `grill-with-docs` is now a thin pointer +skill invoking both. No runtime-specific mechanism involved. ## Portable support (`ai-agents/skills/_shared/`) diff --git a/ai-agents/skills/critique-plan/SKILL.md b/ai-agents/skills/critique-plan/SKILL.md index 27176f41..477b9578 100644 --- a/ai-agents/skills/critique-plan/SKILL.md +++ b/ai-agents/skills/critique-plan/SKILL.md @@ -23,7 +23,7 @@ tracker, or whatever the user pastes in standalone. Read only what exists; skip missing files silently — don't flag them or offer to create them. Look for `CONTEXT.md` (or `CONTEXT-MAP.md` plus each context's own `CONTEXT.md`, per -[grill-with-docs](../grill-with-docs/SKILL.md#file-structure)) and `docs/adr/`. +[domain-modeling](../domain-modeling/SKILL.md#file-structure)) and `docs/adr/`. If neither exists, say so in one line and stop — there is no domain model to critique against. @@ -73,14 +73,14 @@ Bring the pushbacks back into the planning session. The user resolves each their - **Accept** → amend the plan (rename, re-scope, fix the edge, move contexts) right there. - **Dismiss** → drop it. If the dismissal rests on a load-bearing reason a future planner would need in order not to re-raise it, offer to record an ADR using - [grill-with-docs' ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). Skip ephemeral ("not now") + [domain-modeling's ADR-FORMAT.md](../domain-modeling/ADR-FORMAT.md). Skip ephemeral ("not now") and self-evident reasons. When a resolution sharpens a term, update `CONTEXT.md` inline using -[grill-with-docs' CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md). +[domain-modeling's CONTEXT-FORMAT.md](../domain-modeling/CONTEXT-FORMAT.md). If the critic returned "No objections," say so in one line and move on. Don't pad it. -`grill-with-docs`/`grilling` is a full interactive re-grill of the design; `critique-plan` is a +`grilling`/`domain-modeling` is a full interactive re-grill of the design; `critique-plan` is a single-pass, silent-by-default gate — one critic, real conflicts only, then straight back to the workflow. diff --git a/ai-agents/skills/grill-with-docs/ADR-FORMAT.md b/ai-agents/skills/domain-modeling/ADR-FORMAT.md similarity index 100% rename from ai-agents/skills/grill-with-docs/ADR-FORMAT.md rename to ai-agents/skills/domain-modeling/ADR-FORMAT.md diff --git a/ai-agents/skills/grill-with-docs/CONTEXT-FORMAT.md b/ai-agents/skills/domain-modeling/CONTEXT-FORMAT.md similarity index 100% rename from ai-agents/skills/grill-with-docs/CONTEXT-FORMAT.md rename to ai-agents/skills/domain-modeling/CONTEXT-FORMAT.md diff --git a/ai-agents/skills/domain-modeling/SKILL.md b/ai-agents/skills/domain-modeling/SKILL.md new file mode 100644 index 00000000..70711d2d --- /dev/null +++ b/ai-agents/skills/domain-modeling/SKILL.md @@ -0,0 +1,74 @@ +--- +name: domain-modeling +description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR. +--- + +# Domain Modeling + +Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.) + +## File structure + +Most repos have a single context: + +``` +/ +├── CONTEXT.md +├── docs/ +│ └── adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: + +``` +/ +├── CONTEXT-MAP.md +├── docs/ +│ └── adr/ ← system-wide decisions +├── src/ +│ ├── ordering/ +│ │ ├── CONTEXT.md +│ │ └── docs/adr/ ← context-specific decisions +│ └── billing/ +│ ├── CONTEXT.md +│ └── docs/adr/ +``` + +Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. + +## During the session + +### Challenge against the glossary + +When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" + +### Sharpen fuzzy language + +When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." + +### Discuss concrete scenarios + +When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. + +### Cross-reference with code + +When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" + +### Update CONTEXT.md inline + +When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). + +`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. + +### Offer ADRs sparingly + +Only offer to create an ADR when all three are true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will wonder "why did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons + +If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). diff --git a/ai-agents/skills/grill-with-docs/SKILL.md b/ai-agents/skills/grill-with-docs/SKILL.md index 1ac707c7..5665edaf 100644 --- a/ai-agents/skills/grill-with-docs/SKILL.md +++ b/ai-agents/skills/grill-with-docs/SKILL.md @@ -4,82 +4,6 @@ description: Grilling session that challenges your plan against the existing dom disable-model-invocation: true --- - +Run a [`grilling`](../grilling/SKILL.md) session — the relentless, frontier-round interview to reach shared understanding. While you grill, run [`domain-modeling`](../domain-modeling/SKILL.md) alongside it, so the project's domain docs (`CONTEXT.md`, ADRs) get maintained inline as decisions crystallise. -Run a `/grilling` session — the same relentless, one-question-at-a-time interview to reach shared understanding. While you grill, actively maintain the project's domain docs as decisions crystallise, per the discipline below. - - - - - -## Domain awareness - -During codebase exploration, also look for existing documentation: - -### File structure - -Most repos have a single context: - -``` -/ -├── CONTEXT.md -├── docs/ -│ └── adr/ -│ ├── 0001-event-sourced-orders.md -│ └── 0002-postgres-for-write-model.md -└── src/ -``` - -If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: - -``` -/ -├── CONTEXT-MAP.md -├── docs/ -│ └── adr/ ← system-wide decisions -├── src/ -│ ├── ordering/ -│ │ ├── CONTEXT.md -│ │ └── docs/adr/ ← context-specific decisions -│ └── billing/ -│ ├── CONTEXT.md -│ └── docs/adr/ -``` - -Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. - -## During the session - -### Challenge against the glossary - -When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" - -### Sharpen fuzzy language - -When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." - -### Discuss concrete scenarios - -When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. - -### Cross-reference with code - -When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" - -### Update CONTEXT.md inline - -When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). - -`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. - -### Offer ADRs sparingly - -Only offer to create an ADR when all three are true: - -1. **Hard to reverse** — the cost of changing your mind later is meaningful -2. **Surprising without context** — a future reader will wonder "why did they do it this way?" -3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons - -If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). - - +Invoke both skills together: `grilling` for the interview mechanics, `domain-modeling` for the docs discipline. diff --git a/ai-agents/skills/grilling/SKILL.md b/ai-agents/skills/grilling/SKILL.md index 497b4f34..ccf2211e 100644 --- a/ai-agents/skills/grilling/SKILL.md +++ b/ai-agents/skills/grilling/SKILL.md @@ -1,13 +1,45 @@ --- name: grilling -description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when the user wants to stress-test a plan before building, get grilled on their design, or uses any "grill" trigger phrase. +description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree in batched rounds. Use when the user wants to stress-test a plan before building, get grilled on their design, or uses any "grill" trigger phrase. disable-model-invocation: true --- -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. +Interview me relentlessly until we reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it. -Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. +Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask now without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for my answers before the next round. -If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer. +Format a round like so: -Do not enact the plan until I confirm we have reached a shared understanding. +``` +❓ **Q1** - ****: + +➡️ + +--- + +❓ **Q2** - ****: + +➡️ +``` + +Each round my answers reshape the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a later round, not this one. + +Finding *facts* is your job, never mine. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a subagent to find it; don't ask me for anything you could look up yourself. Don't block the round on it — a running exploration is an unsettled prerequisite, so only the questions downstream of it wait; ask the rest of the frontier now. The *decisions* are mine — put each one to me and wait for my answer. + +## Decision status + +Track every open branch of the tree under one of three states: + +- **Resolved** — I gave an explicit answer, captured verbatim or faithfully paraphrased. Never mark a decision resolved from my silence, from a follow-up that moved past it, or from your own recommended answer standing unchallenged. No answer means the decision stays open. +- **Open** — asked, not yet answered. +- **Needs codebase check** — a fact, not a decision; dispatched to a subagent, pending its result. + +## Session end + +The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Before handing off to implementation, give a short wrap-up: + +- **Agreed decisions** — the resolved list, one line each. +- **Open risks** — anything resolved with caveats, or a resolved decision worth flagging for revisit later. +- **Next decision needed** — if the session is cutting short with the frontier not actually empty, name what's still open. + +Do not act on any of this until I confirm we have reached a shared understanding. diff --git a/claude/skills/router/SKILL.md b/claude/skills/router/SKILL.md index 059430b6..dd3b65aa 100644 --- a/claude/skills/router/SKILL.md +++ b/claude/skills/router/SKILL.md @@ -51,7 +51,7 @@ Not feature work — upkeep. - **`/techdebt`** — the non-architectural counterpart: inventories dependency health, dead code, stale TODOs, test debt, duplication, suppressed checks, toolchain drift, and doc/config drift from existing tool output, then hands approved findings to `/to-tickets`. Not for shallow modules or tight coupling — that's `/improve-codebase-architecture`. - **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*. The bench you design a chosen candidate on. `/tdd` and `/improve-codebase-architecture` both speak it. -*Domain modeling has no separate skill because `/grill-with-docs` carries the full active discipline — challenging terms, keeping `CONTEXT.md` a clean glossary, recording ADRs, with its own `CONTEXT-FORMAT.md` / `ADR-FORMAT.md`. `/codebase-design` owns module shape. Between them the vocabulary is covered.* +*Domain modeling is its own skill, `/domain-modeling` — challenging terms, keeping `CONTEXT.md` a clean glossary, recording ADRs, with its own `CONTEXT-FORMAT.md` / `ADR-FORMAT.md`. `/grill-with-docs` is a thin pointer invoking it alongside `/grilling`. `/codebase-design` owns module shape. Between them the vocabulary is covered.* ## Reviewing & verifying — a ladder by target From ca6253aed892af2b4cfa556ed7498cf38e50fc13 Mon Sep 17 00:00:00 2001 From: Justin Puah Date: Mon, 31 Aug 2026 21:35:30 +1000 Subject: [PATCH 5/9] feat(agents): add parallel research dispatch to wayfinder Charting the map now fires a subagent per research ticket, invoking /quick-research to resolve it in parallel and capture findings on a throwaway research/ branch with a context pointer from the ticket. The one-ticket-per-session rule gains an exception for research tickets: a work session may resolve several, just not several non-research tickets. --- ai-agents/skills/wayfinder/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/ai-agents/skills/wayfinder/SKILL.md b/ai-agents/skills/wayfinder/SKILL.md index 69915f53..571fdce7 100644 --- a/ai-agents/skills/wayfinder/SKILL.md +++ b/ai-agents/skills/wayfinder/SKILL.md @@ -76,7 +76,7 @@ Every ticket is either **HITL** — human in the loop, worked *with* a human who - **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases. Creates a markdown summary as a linked asset. Use when knowledge outside the current working directory is required. - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question. -- **Grilling** (HITL): Conversation via the /grill-with-docs skill, one question at a time. The default case. +- **Grilling** (HITL): Conversation via the /grill-with-docs skill, in batched frontier rounds. The default case. - **Task** (HITL or AFK): Manual work that must happen before a *decision* can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that *does* rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on. ## Fog of war @@ -102,7 +102,7 @@ Ruling something out of scope is a scoping act, not a step on the route. When a ## Invocation -Two modes. Either way, **never resolve more than one ticket per session.** +Two modes. Either way, **never resolve more than one ticket per session**, except research tickets: a session may resolve several of those, just not several non-research tickets. ### Chart the map @@ -112,7 +112,8 @@ User invokes with a loose idea. 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed. 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**. 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section. -5. Stop — charting the map is one session's work; do not also resolve tickets. +5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent that invokes the `/quick-research` skill to resolve it in parallel, capturing its findings on a throwaway `research/` branch with a context pointer from the ticket. +6. Stop — charting the map is one session's work; do not also resolve non-research tickets. ### Work through the map From 3d3b5550ec0ac785a707c675fbc2f881aee99b1e Mon Sep 17 00:00:00 2001 From: Justin Puah Date: Mon, 31 Aug 2026 21:35:35 +1000 Subject: [PATCH 6/9] feat(agents): add hot-spot scoping to improve-codebase-architecture Insert a scoping step before the codebase scan: take a user-named direction if given, otherwise walk git log --oneline for hot spots (files/areas that keep recurring) and let those pull attention first, widening the net if changes are scattered. Previously the scan ran unconditionally over the whole codebase. Also repoints its grill-with-docs/CONTEXT-FORMAT.md and ADR-FORMAT.md links to domain-modeling, following the split committed earlier on this branch. --- ai-agents/skills/improve-codebase-architecture/SKILL.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/ai-agents/skills/improve-codebase-architecture/SKILL.md b/ai-agents/skills/improve-codebase-architecture/SKILL.md index d0ad951c..e0be21dc 100644 --- a/ai-agents/skills/improve-codebase-architecture/SKILL.md +++ b/ai-agents/skills/improve-codebase-architecture/SKILL.md @@ -32,6 +32,11 @@ This skill is _informed_ by the project's domain model. The domain language give ### 1. Explore +**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide where to look before you look: + +- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below. +- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net. + Read the project's domain glossary and any ADRs in the area you're touching first. Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: @@ -75,7 +80,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des Side effects happen inline as decisions crystallize: -- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. +- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/domain-modeling` (see [CONTEXT-FORMAT.md](../domain-modeling/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. -- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). +- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../domain-modeling/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** Use the parallel "design it twice" pattern — see [codebase-design's DESIGN-IT-TWICE.md](../codebase-design/DESIGN-IT-TWICE.md). From 7c8f418258984c95a90af0babd53325c8c8f1843 Mon Sep 17 00:00:00 2001 From: Justin Puah Date: Mon, 31 Aug 2026 21:35:44 +1000 Subject: [PATCH 7/9] feat(agents): add ready-for-human state to triage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New terminal state for fully-specified work that needs a human rather than an agent (judgment calls, external access, design decisions, manual testing) — same brief structure as an agent-ready ticket, plus a note on why it can't be delegated. Added alongside the existing four states (triaged, ready, needs-info, wontfix), not renaming them. Registered in .agents/workflow.md's label list. --- .agents/workflow.md | 2 +- ai-agents/skills/triage/SKILL.md | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/.agents/workflow.md b/.agents/workflow.md index 55463d72..c819da7d 100644 --- a/.agents/workflow.md +++ b/.agents/workflow.md @@ -11,6 +11,6 @@ A private `.agents/workflow.local.md` takes precedence when present. Run - **Specs**: `.agents/specs/` - **High-level designs**: `docs/design/` - **Tickets**: GitHub Issues in `jinyeow/dotfiles` -- **Labels**: `spec-ready`, `design-ready`, `triaged`, `ready`, `needs-info`, `wontfix` +- **Labels**: `spec-ready`, `design-ready`, `triaged`, `ready`, `ready-for-human`, `needs-info`, `wontfix` - **Domain docs**: single-context layout with root `CONTEXT.md` and `docs/adr/` - **Wayfinding**: GitHub parent/child issues for maps; use `wayfinder:map`, `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, and `wayfinder:task`; use GitHub's native blocking relationships; frontier means open, unblocked, unassigned child issues; claim by assigning the issue to the implementing developer. diff --git a/ai-agents/skills/triage/SKILL.md b/ai-agents/skills/triage/SKILL.md index e70ce3a2..24505b25 100644 --- a/ai-agents/skills/triage/SKILL.md +++ b/ai-agents/skills/triage/SKILL.md @@ -28,20 +28,21 @@ Two **category** roles: - `bug` — something is broken - `enhancement` — new feature or improvement -Four **state** roles: +Five **state** roles: - `triaged` — assessed and scoped, but not yet ready to implement - `ready` — fully specified; an agent may grab it and implement +- `ready-for-human` — needs human implementation - `needs-info` — waiting on reporter for more information - `wontfix` — will not be actioned -For a PR, the same states read against the attached code: `ready` means a brief is attached and an agent should take the next step on the diff; `triaged` means it's been assessed but the diff needs more work first. +For a PR, the same states read against the attached code: `ready` means a brief is attached and an agent should take the next step on the diff; `ready-for-human` means it's ready for a human to merge; `triaged` means it's been assessed but the diff needs more work first. Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else. These are canonical role names — the actual label strings used in the issue tracker may differ. Read the mapping from repository-root `.agents/workflow.local.md` when present, otherwise repository-root `.agents/workflow.md`; run `/setup-agent-skills` if neither exists. -State transitions: an unlabeled issue is untriaged; from there it moves to `triaged`, `needs-info`, `ready`, or `wontfix`. `needs-info` returns to untriaged for re-evaluation once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding. +State transitions: an unlabeled issue is untriaged; from there it moves to `triaged`, `needs-info`, `ready`, `ready-for-human`, or `wontfix`. `needs-info` returns to untriaged for re-evaluation once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding. ## Invocation @@ -72,10 +73,11 @@ Show counts and a one-line summary per item. Let the maintainer pick. 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief. -4. **Grill (if needed).** If the request needs fleshing out, pause and ask the maintainer to run `/grill-with-docs` — grill it into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land. +4. **Grill (if needed).** If the request needs fleshing out, pause and ask the maintainer to run `/grill-with-docs` — grill it into shape, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land. 5. **Apply the outcome:** - `ready` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)). An agent may grab and implement it autonomously. + - `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing). - `needs-info` — post triage notes (template below). - `wontfix` — close, with the comment depending on *why*: - **Already implemented** — the change already exists in the codebase. Point to where it lives; do **not** write to `.out-of-scope/` (that KB is for *rejected* requests, not built ones). From dda801c1ce512921dd294f77ca5fb2544dfd1051 Mon Sep 17 00:00:00 2001 From: Justin Puah Date: Mon, 31 Aug 2026 21:35:49 +1000 Subject: [PATCH 8/9] feat(agents): adopt HTML-demo and archival changes in prototype LOGIC-branch output changes from a terminal app to a single self-contained HTML file: a labelled-field state panel, free-play buttons, and guided walkthroughs as scenario tabs, so a non-developer can drive it too. Completion workflow changes from delete-or-absorb to archive: fold any validated decision into the real code, then commit the prototype itself to a throwaway branch (out of main) as a primary source, with a context pointer on the tracking issue. Losing UI variants and the branch switcher move to the throwaway branch instead of being deleted. --- ai-agents/skills/prototype/LOGIC.md | 72 ++++++++++++----------------- ai-agents/skills/prototype/SKILL.md | 12 ++--- ai-agents/skills/prototype/UI.md | 8 ++-- 3 files changed, 40 insertions(+), 52 deletions(-) diff --git a/ai-agents/skills/prototype/LOGIC.md b/ai-agents/skills/prototype/LOGIC.md index 526ecb18..603ab263 100644 --- a/ai-agents/skills/prototype/LOGIC.md +++ b/ai-agents/skills/prototype/LOGIC.md @@ -1,79 +1,67 @@ # Logic Prototype -A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases. +A single, self-contained HTML file (a **shareable demo**) that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape**: the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases. + +Because it's one file with nothing to install, you can hand it to a non-developer (a designer, a PM, a domain expert) and let them feel the model for themselves, in their own language, not the code's. ## When this is the right shape - "I'm not sure if this state machine handles the edge case where X then Y." - "Does this data model actually let me represent the case where..." - "I want to feel out what the API should look like before writing it." -- Anything where the user wants to **press buttons and watch state change**. +- Anything where someone wants to **press buttons and watch state change**. -If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md). +If the question is "what should this look like," this is the wrong branch. Use [UI.md](UI.md). ## Process ### 1. State the question -Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK. - -### 2. Pick the language - -Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask. - -Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype. +Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste, so make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK. -### 3. Isolate the logic in a portable module +### 2. Isolate the logic in a portable module -Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be. +Put the actual logic (the bit that's answering the question) in a single `