diff --git a/.claude/skills/log-future-addition/SKILL.md b/.claude/skills/log-future-addition/SKILL.md index ceebae89..18202a36 100644 --- a/.claude/skills/log-future-addition/SKILL.md +++ b/.claude/skills/log-future-addition/SKILL.md @@ -1,13 +1,13 @@ --- name: log-future-addition -description: File a single out-of-scope idea, feature, or improvement as one un-triaged GitHub issue. Use whenever the user raises something that would be a good future addition to the app but is out of scope for the current work ("we could also…", "would be nice to…", "let's do that later") — offer to log it. For a fleshed-out feature use to-prd; to break an existing plan into tickets use to-issues. +description: File a single out-of-scope idea, feature, or improvement as one un-triaged GitHub issue. Use whenever the user raises something that would be a good future addition to the app but is out of scope for the current work ("we could also…", "would be nice to…", "let's do that later") — offer to log it. For a fleshed-out feature use to-spec; to break an existing plan into tickets use to-tickets. --- # Log Future Addition Capture one rough, out-of-scope idea as a single un-triaged GitHub issue, so a good thought is not lost when it surfaces mid-work. -This is the lightweight counterpart to `to-prd`. Use it for a **brief, quick idea** — anything already thought through belongs in `to-prd` (a spec) or a `grill-with-docs` session. It is NOT for breaking down plans; that is `to-issues`. +This is the lightweight counterpart to `to-spec`. Use it for a **brief, quick idea** — anything already thought through belongs in `to-spec` (a spec) or a `grill-with-docs` session. It is NOT for breaking down plans; that is `to-tickets`. Issue tracker conventions (title, labels, backticks, assignment) live in `docs/agents/issue-tracker.md`. The `Idea` term is defined in `docs/agents/glossary.md`. Do not duplicate those here — link and follow. @@ -16,7 +16,7 @@ Issue tracker conventions (title, labels, backticks, assignment) live in `docs/a - An out-of-scope idea comes up in conversation and you want to keep it without derailing the current work. - You have a one-line feature/bug/improvement scrap and just want it on the tracker. -If the input is really a plan or spec — multiple features, acceptance criteria, phased work, or simply long and detailed — say so and point the user to `to-prd` (one PRD issue) or `to-issues` (many tracer-bullet issues). Suggest, do not hard-refuse; the user can override. +If the input is really a plan or spec — multiple features, acceptance criteria, phased work, or simply long and detailed — say so and point the user to `to-spec` (one spec issue) or `to-tickets` (many tracer-bullet issues). Suggest, do not hard-refuse; the user can override. ## Two-stage consent diff --git a/.claude/skills/to-issues/SKILL.md b/.claude/skills/to-issues/SKILL.md deleted file mode 100644 index 3017446e..00000000 --- a/.claude/skills/to-issues/SKILL.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -name: to-issues -description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues. ---- - -# To Issues - -Break a plan into independently-grabbable issues using vertical slices (tracer bullets). - -Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage label vocabulary lives in `docs/agents/triage-labels.md`. - -## Process - -### 1. Gather context - -Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker and read its full body and comments. - -### 2. Explore the codebase (optional) - -If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching. - -### 3. Draft vertical slices - -Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer. - -Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible. - - -- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests) -- A completed slice is demoable or verifiable on its own -- Prefer many thin slices over few thick ones - - -### 4. Quiz the user - -Present the proposed breakdown as a numbered list. For each slice, show: - -- **Title**: short descriptive name -- **Type**: HITL / AFK -- **Blocked by**: which other slices (if any) must complete first -- **User stories covered**: which user stories this addresses (if the source material has them) - -Ask the user: - -- Does the granularity feel right? (too coarse / too fine) -- Are the dependency relationships correct? -- Should any slices be merged or split further? -- Are the correct slices marked as HITL and AFK? - -Iterate until the user approves the breakdown. - -### 5. Publish the issues to the issue tracker - -For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. These issues are considered ready for AFK agents, so publish them with the correct triage label unless instructed otherwise. - -Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field. - - -## Parent - -A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section). - -## What to build - -A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation. - -Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it here and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. - -## Acceptance criteria - -- [ ] Criterion 1 -- [ ] Criterion 2 -- [ ] Criterion 3 - -## Blocked by - -- A reference to the blocking ticket (if any) - -Or "None - can start immediately" if no blockers. - - - -Do NOT close or modify any parent issue. diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-spec/SKILL.md similarity index 65% rename from .claude/skills/to-prd/SKILL.md rename to .claude/skills/to-spec/SKILL.md index c77fae46..b39d7d0d 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-spec/SKILL.md @@ -1,25 +1,24 @@ --- -name: to-prd -description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context. +name: to-spec +description: Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. +disable-model-invocation: true --- -This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know. +This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know. Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage label vocabulary lives in `docs/agents/triage-labels.md`. ## Process -1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching. +1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching. -2. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation. +2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better — the ideal number is one. -A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes. +Check with the user that these seams match their expectations. -Check with the user that these modules match their expectations. Check with the user which modules they want tests written for. +3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. -3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. - - + ## Problem Statement @@ -67,10 +66,10 @@ A list of testing decisions that were made. Include: ## Out of Scope -A description of the things that are out of scope for this PRD. +A description of the things that are out of scope for this spec. ## Further Notes Any further notes about the feature. - + diff --git a/.claude/skills/to-tickets/SKILL.md b/.claude/skills/to-tickets/SKILL.md new file mode 100644 index 00000000..c68ffc3e --- /dev/null +++ b/.claude/skills/to-tickets/SKILL.md @@ -0,0 +1,93 @@ +--- +name: to-tickets +description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the project issue tracker. Use when the user wants to convert a plan into issues, create implementation tickets, or break down work into issues. +disable-model-invocation: true +--- + +# To Tickets + +Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it. + +Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage label vocabulary lives in `docs/agents/triage-labels.md`. + +## Process + +### 1. Gather context + +Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments. + +### 2. Explore the codebase (optional) + +If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching. + +Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change." + +### 3. Draft vertical slices + +Break the work into **tracer bullet** tickets. + +Slices may be **HITL** or **AFK**. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible. + + + +- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer +- A completed slice is demoable or verifiable on its own +- Each slice is sized to fit in a single fresh context window +- Prefer many thin slices over few thick ones +- Any prefactoring should be done first + + + +Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately. + +**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there. + +### 4. Quiz the user + +Present the proposed breakdown as a numbered list. For each ticket, show: + +- **Title**: short descriptive name +- **Type**: HITL / AFK +- **Blocked by**: which other tickets (if any) must complete first +- **What it delivers**: the end-to-end behaviour this ticket makes work + +Ask the user: + +- Does the granularity feel right? (too coarse / too fine) +- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it? +- Should any tickets be merged or split further? +- Are the correct slices marked HITL and AFK? + +Iterate until the user approves the breakdown. + +### 5. Publish the tickets to the issue tracker + +Publish the approved tickets to the project issue tracker (GitHub Issues — see `docs/agents/issue-tracker.md`). Publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real issue identifiers. Use GitHub's native sub-issue / blocking relationship where it fits; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise — the tickets are agent-grabbable by construction. + +Do NOT close or modify any parent issue. + + + +## Parent + +A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section). + +## What to build + +The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation. + +## Acceptance criteria + +- [ ] Criterion 1 +- [ ] Criterion 2 +- [ ] Criterion 3 + +## Blocked by + +- A reference to each blocking ticket, or "None — can start immediately". + + + +Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. + +Work the frontier one ticket at a time, clearing context between tickets. diff --git a/CLAUDE.md b/CLAUDE.md index a00413aa..79670a86 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,7 +50,7 @@ Frontend and backend conventions live alongside their code and auto-load when ed ## Agent skills -Workflow skills (commit, open-pr, update-pr, address-pr-comments, run-local, verify-telemetry, verify-graph) and Matt Pocock's engineering and issue-authoring skills live in `.claude/skills/`. The AI issue-authoring flow is `grill-with-docs → to-prd → to-issues → triage`. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. The `caveman` terse mode is on by default in this repo as a pilot — see the Communication section above. +Workflow skills (commit, open-pr, update-pr, address-pr-comments, run-local, verify-telemetry, verify-graph) and Matt Pocock's engineering and issue-authoring skills live in `.claude/skills/`. The AI issue-authoring flow is `grill-with-docs → to-spec → to-tickets → triage`. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md` and `docs/adr/0003-misc-rename-to-spec-to-tickets.md`. The `caveman` terse mode is on by default in this repo as a pilot — see the Communication section above. ### Issue tracker diff --git a/docs/adr/0002-misc-adopt-matt-pocock-skills.md b/docs/adr/0002-misc-adopt-matt-pocock-skills.md index 93d4402a..37058f72 100644 --- a/docs/adr/0002-misc-adopt-matt-pocock-skills.md +++ b/docs/adr/0002-misc-adopt-matt-pocock-skills.md @@ -1,5 +1,7 @@ # Adopt Matt Pocock's agent skills for AI-driven issue authoring +> **Amended by [ADR-0003](0003-misc-rename-to-spec-to-tickets.md).** The `to-prd` and `to-issues` skills named throughout this ADR were later renamed to `to-spec` and `to-tickets` (tracking Matt Pocock's upstream renames) and refreshed with upstream content. Read the old skill names below as their current equivalents; the two-path rationale is unchanged. + Argos adopts Matt Pocock's `grill-with-docs → to-prd → to-issues → triage` skill flow as the AI-driven path for issue authoring and triage. The legacy `create-ticket` and `brainstorm-ticket` skills retire. Humans continue to author issues via Argos's GitHub form templates (`task.yml`, `bug-form.yml`, `feature-request.yml`, `epic.yml`); AI authors via Matt's baked-in body shapes filed through `gh issue create --body`. The `ready-for-agent` triage label distinguishes AI-filed issues. ## Considered Options diff --git a/docs/adr/0003-misc-rename-to-spec-to-tickets.md b/docs/adr/0003-misc-rename-to-spec-to-tickets.md new file mode 100644 index 00000000..adfb16d2 --- /dev/null +++ b/docs/adr/0003-misc-rename-to-spec-to-tickets.md @@ -0,0 +1,25 @@ +# Rename to-prd → to-spec and to-issues → to-tickets, refreshed from upstream + +Argos renames its two AI issue-authoring skills to track Matt Pocock's upstream renames and folds in the upstream content improvements, while preserving Argos-specific customizations. `to-prd` becomes `to-spec`; `to-issues` becomes `to-tickets`. The AI issue-authoring flow is now `grill-with-docs → to-spec → to-tickets → triage`. This amends [ADR-0002](0002-misc-adopt-matt-pocock-skills.md); the two-path rationale (humans author via GitHub form templates, AI authors via Matt's body shapes) is unchanged. + +## Considered Options + +- Rename only, keep the customized skill bodies as-is. +- Rename plus selectively adopt only the non-conflicting upstream additions. +- Rename plus fold in the full upstream content (chosen). + +## Why rename and fold + +- Upstream renamed the skills so "spec" is the single through-line term (`to-spec` still opens "you may know this document as a PRD" for discoverability), and merged `to-plan` + `to-issues` into one `to-tickets`. Keeping the old names left our copies as stale forks diverging from a source we still pull from. +- The upstream content carries real improvements worth having: the **wide-refactor / expand–contract** sequence for a mechanical change whose blast radius breaks vertical slicing; a **prefactoring** step ("make the change easy, then make the easy change"); single-fresh-context-window slice sizing; and `disable-model-invocation: true` so these user-invoked flow skills don't fire autonomously. +- `to-spec` adopts upstream's **seam** framing for step 2 (test at the highest, fewest seams) in place of our earlier deep-module framing. Deep-module vocabulary now lives with `codebase-design` upstream; this keeps `to-spec` focused on where tests go. + +## Consequences + +- `.claude/skills/to-prd/` → `.claude/skills/to-spec/`; `.claude/skills/to-issues/` → `.claude/skills/to-tickets/` (directory, frontmatter `name`, and `description` all updated). +- Argos customizations are preserved through the fold: both skills keep pointing at `docs/agents/issue-tracker.md` and `docs/agents/triage-labels.md` rather than upstream's `/setup-matt-pocock-skills` (which Argos does not vendor); `to-tickets` keeps the **HITL / AFK** slice classification in its rules and quiz; and `to-tickets` publishes only to Argos's GitHub Issues tracker, dropping upstream's tracker-agnostic local-file (`tickets.md`) path. +- `to-tickets` ends on the "work the frontier one ticket at a time" note without upstream's hard `/implement` reference, since Argos has not yet vendored the `implement` skill. +- References updated in `CLAUDE.md` (flow string), `docs/agents/glossary.md` (Tracer-bullet, Spec/PRD, Idea entries), `docs/agents/issue-tracker.md` (body-shape ownership line), and `.claude/skills/log-future-addition/SKILL.md` (three pointers). +- ADR-0002 gains an amendment banner pointing here; its body keeps the historical `to-prd` / `to-issues` names. + +See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`, `docs/agents/issue-tracker.md`, `docs/agents/glossary.md`. diff --git a/docs/agents/glossary.md b/docs/agents/glossary.md index 3f968525..1ce1a56b 100644 --- a/docs/agents/glossary.md +++ b/docs/agents/glossary.md @@ -10,8 +10,8 @@ Plain-language definitions of the workflow and agent-tooling terms used across t **AFK (Away From Keyboard).** Work an AI agent can finish on its own without supervision. The ready-for-agent label marks an issue as AFK-ready. -**Tracer-bullet issue / vertical slice.** A scoping pattern where each ticket cuts a thin slice through every layer it touches (database, API, UI, tests) end-to-end, instead of completing one layer at a time. Each slice stands on its own. The `to-issues` skill breaks plans into these. +**Tracer-bullet issue / vertical slice.** A scoping pattern where each ticket cuts a thin slice through every layer it touches (database, API, UI, tests) end-to-end, instead of completing one layer at a time. Each slice stands on its own. The `to-tickets` skill breaks plans into these. -**PRD (Product Requirements Document).** A feature spec. The `to-prd` skill writes one; `to-issues` then breaks it into tracer-bullet tickets. +**Spec (PRD).** A feature spec — you may also know this document as a PRD (Product Requirements Document). The `to-spec` skill writes one; `to-tickets` then breaks it into tracer-bullet tickets. -**Idea.** A raw, un-fleshed feature or bug scrap filed as a single needs-triage ticket before anyone has classified it — the lightweight counterpart to a PRD. Filed by the `log-future-addition` skill for `/triage` to classify like any other intake. Deliberately thin; anything already thought through belongs in `to-prd` or `grill-with-docs`. +**Idea.** A raw, un-fleshed feature or bug scrap filed as a single needs-triage ticket before anyone has classified it — the lightweight counterpart to a spec. Filed by the `log-future-addition` skill for `/triage` to classify like any other intake. Deliberately thin; anything already thought through belongs in `to-spec` or `grill-with-docs`. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 21631aaf..e0b1e9e6 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -15,7 +15,7 @@ Infer the repo from `git remote -v` — `gh` does this automatically when run in ## Argos ticket conventions -These apply when an AI skill files an issue with `gh issue create`. They govern the title, labels, body length, and assignment only. The body *shape* (which sections exist and how they are structured) is owned by the authoring skill (`to-issues`, `to-prd`), not by this file. See glossary.md for ADR, triage, AFK, and the other workflow terms. +These apply when an AI skill files an issue with `gh issue create`. They govern the title, labels, body length, and assignment only. The body *shape* (which sections exist and how they are structured) is owned by the authoring skill (`to-tickets`, `to-spec`), not by this file. See glossary.md for ADR, triage, AFK, and the other workflow terms. **Title:** concise, imperative mood (e.g. "Add pagination to the run list", "Fix redirect loop on login"). Do not prefix with `[Area] -`, even though the YAML form templates suggest it; real issues in this repo do not use that prefix.