From 31574a218fc49b535d55f7b531d5499551db446f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 25 Jun 2026 17:50:49 +0000 Subject: [PATCH 01/15] #668 - add branch-based research pipeline and ai-workflow label Move the AI issue-authoring flow onto a branch gated by PR review: research ticket opens the work, the grilling session commits its artifacts (CONTEXT.md, ADRs, PRD) to the branch, reviewed as a draft PR before implementation issues are broken out. Adds ADR 0003, docs/agents/research-pipeline.md, docs/research/ home with the #668 PRD as the prototype instance, the ai-workflow label in the palette, glossary terms, and pipeline guidance in grill-with-docs and to-prd. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/grill-with-docs/SKILL.md | 4 ++ .claude/skills/to-prd/SKILL.md | 6 ++- CLAUDE.md | 2 +- docs/adr/0003-misc-research-pipeline.md | 25 +++++++++++ docs/agents/glossary.md | 6 +++ docs/agents/issue-tracker.md | 7 +++ docs/agents/research-pipeline.md | 38 ++++++++++++++++ .../668-build-research-pipeline/prd.md | 43 +++++++++++++++++++ docs/research/README.md | 13 ++++++ 9 files changed, 142 insertions(+), 2 deletions(-) create mode 100644 docs/adr/0003-misc-research-pipeline.md create mode 100644 docs/agents/research-pipeline.md create mode 100644 docs/research/668-build-research-pipeline/prd.md create mode 100644 docs/research/README.md diff --git a/.claude/skills/grill-with-docs/SKILL.md b/.claude/skills/grill-with-docs/SKILL.md index 5ea0aa91..4fa14b16 100644 --- a/.claude/skills/grill-with-docs/SKILL.md +++ b/.claude/skills/grill-with-docs/SKILL.md @@ -85,4 +85,8 @@ Only offer to create an ADR when all three are true: If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). +## Research pipeline + +When this session is part of Argos's research pipeline (see docs/agents/research-pipeline.md), it runs on a branch tied to a research ticket. The CONTEXT.md edits and ADRs you create are committed to that branch and reviewed as a draft PR against develop before any implementation issues are broken out — not filed straight from chat. Keep capturing artifacts inline as decisions crystallise; the branch is where they durably land. + diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index c77fae46..110a985a 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -17,7 +17,11 @@ A deep module (as opposed to a shallow module) is one which encapsulates a lot o Check with the user that these modules match their expectations. Check with the user which modules they want tests written for. -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. +3. Write the PRD using the template below. + + **Pipeline mode** — when operating within the research pipeline (docs/agents/research-pipeline.md), you are on a branch tied to a research ticket. Write the PRD to docs/research//prd.md and commit it on the branch instead of filing it as an issue. It is reviewed in the branch's draft PR; implementation issues are broken out with `to-issues` after merge. is the kebab-case branch name. + + **Standalone mode** — otherwise, publish the PRD to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. diff --git a/CLAUDE.md b/CLAUDE.md index d82d813f..c51960ac 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-prd → to-issues → triage`. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. Research-heavy work runs through the branch-based research pipeline — the grilling session's artifacts are committed to a branch and reviewed before issues spawn; see `docs/agents/research-pipeline.md` (ADR 0003). 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/0003-misc-research-pipeline.md b/docs/adr/0003-misc-research-pipeline.md new file mode 100644 index 00000000..0228d705 --- /dev/null +++ b/docs/adr/0003-misc-research-pipeline.md @@ -0,0 +1,25 @@ +# Branch-based research pipeline for AI-authored issues + +The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produces its research, terminology decisions, ADRs, and PRD inside one ephemeral chat session, then files implementation issues directly from chat with no review gate. Argos moves that flow onto a branch: a research ticket opens the work, the grilling session's artifacts (CONTEXT.md edits, ADRs, PRD) are committed to a branch tied to that ticket, and the branch is reviewed as a draft PR against develop before any implementation issues are spawned. Implementation issues are broken out after merge. A new ai-workflow label marks tickets whose subject is the AI dev workflow itself. + +## Considered Options + +- Keep the chat-only flow: file implementation issues directly from the grilling session. Rejected — no durable, reviewable record of the reasoning, and issues spawn before anyone reviews the research. +- Commit the artifacts but skip the research ticket and PR review gate. Rejected — it keeps the artifacts but loses the review step, which is the whole point. + +## Why branch-based + +- Research artifacts become reviewable git history. The PRD and any ADRs land in a PR diff teammates can comment on before the work fans out into issues. +- A research ticket gives the branch a tracked entry point, consistent with the existing {issue}-{kebab-title} branch convention — no new branch namespace to learn. +- Decoupling issue creation from the chat session is what makes stage-4 automation possible later: implementation issues can be generated from the merged PRD, keyed off its committed file path. +- The ai-workflow label gives meta-work (changes to the skills and docs/agents themselves) a first-class category, instead of mis-filing it under a product area label. + +## Consequences + +- PRDs and grilling notes live in docs/research//; ADRs still go in docs/adr/, and CONTEXT.md stays at the repo root. +- to-prd gains a pipeline mode: write the PRD to docs/research// and commit it on the research branch, rather than only filing an issue from chat. Standalone mode (no research branch) still publishes to the tracker. +- grill-with-docs's CONTEXT.md and ADR edits are committed to the research branch and reviewed in the draft PR. +- Stage 4 (auto-create implementation issues on merge) is not built here — to-issues is still run manually after merge. Tracked as a follow-up. +- The ai-workflow label must exist in the tracker, created via gh label create; it is documented in docs/agents/issue-tracker.md. + +See docs/agents/research-pipeline.md for the operative stages and conventions. diff --git a/docs/agents/glossary.md b/docs/agents/glossary.md index 3a0eea1f..6f75ec53 100644 --- a/docs/agents/glossary.md +++ b/docs/agents/glossary.md @@ -13,3 +13,9 @@ Plain-language definitions of the workflow and agent-tooling terms used across t **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. **PRD (Product Requirements Document).** A feature spec. The `to-prd` skill writes one; `to-issues` then breaks it into tracer-bullet tickets. + +**Research pipeline.** The branch-based flow that carries research-heavy work from an open question to implementation issues as reviewable git history: a research ticket opens the work, a grill-with-docs / to-prd session commits its artifacts (CONTEXT.md edits, ADRs, PRD) to a branch tied to that ticket, and the branch is reviewed as a draft PR before issues are broken out. See research-pipeline.md; ADR 0003 records the decision. + +**Research ticket.** The entry-point ticket of the research pipeline. It describes what is being researched or triaged — the question, not the answer — and names the branch the session runs on. + +**ai-workflow label.** Marks tickets whose subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline), as opposed to product code. See issue-tracker.md. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index eefcfd8c..67e798b1 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -26,9 +26,16 @@ These apply when an AI skill files an issue with `gh issue create`. They govern | Area | `angular-client`, `scylla-server`, `DevOps` | | Type | `bug`, `new feature`, `feature enhancement`, `good first issue`, `epic` | | Difficulty | `straightforward`, `medium`, `difficult` | +| Workflow | `ai-workflow` | + +Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — the skills, docs/agents, or the issue pipeline — rather than product code. It is orthogonal to the area labels (a ticket is about the workflow or about a product component, not both). Created via `gh label create`, like the triage roles. The triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) are applied by `/triage`, not at creation time. See triage-labels.md. +## Research tickets + +Research-heavy tickets — anything that needs a grill-with-docs / to-prd session before implementation — flow through the branch-based research pipeline: the session's artifacts are committed to a branch tied to the ticket and reviewed as a draft PR before implementation issues are broken out. See research-pipeline.md. + **Backticks:** at most three backtick usages in the entire issue body. Reference files, functions, and identifiers in plain text; reserve backticks for commands worth copy-pasting or short snippets. **Assignment:** pass `--assignee @me` by default. This repo self-assigns issues. diff --git a/docs/agents/research-pipeline.md b/docs/agents/research-pipeline.md new file mode 100644 index 00000000..d0d7f668 --- /dev/null +++ b/docs/agents/research-pipeline.md @@ -0,0 +1,38 @@ +# Research pipeline + +How AI-authored work moves from an open question to implementation issues as reviewable git history, instead of an ephemeral chat session. Decision and rationale: ADR 0003. + +## When to use it + +Reach for the pipeline when the work needs research, terminology decisions, or an architecture call before implementation — the kind of session that runs grill-with-docs and to-prd. Small, well-understood tickets don't need it; file them and go. + +## Stages + +1. **Research ticket.** A human files a lightweight ticket describing what is being researched or triaged — the question, not the answer. This is the entry point and the thing the branch is named for. If the ticket's subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline), apply the ai-workflow label; otherwise label it by the product area being researched. + +2. **Grilling session on a branch.** Branch from develop as {issue}-{kebab-title}. Run grill-with-docs (and to-prd) against the ticket. Every artifact the session produces is committed to that branch: + - CONTEXT.md edits at the repo root (glossary). + - New ADRs in docs/adr/. + - The PRD in docs/research//prd.md, plus any grilling notes in the same folder. + +3. **Push + review.** Push the branch and open a draft PR against develop. Humans review the research, terminology, ADRs, and PRD in the diff before any implementation work is broken out. + +4. **Merge to implementation issues.** Once the PR merges, the PRD is broken into tracer-bullet issues with to-issues, linked back to the research ticket. Today this is run manually after merge; auto-creating the issues on merge is a planned follow-up (keyed off the committed PRD path). + +## Where artifacts live + +| Artifact | Location | +| --- | --- | +| PRD + grilling notes | docs/research// | +| ADRs | docs/adr/ (see domain.md for the naming convention) | +| Glossary updates | CONTEXT.md (root) | + + is the kebab-case branch name, e.g. docs/research/668-build-research-pipeline/. + +## Conventions + +- **Branch:** {issue}-{kebab-title}, same as feature branches — no separate namespace. +- **PR:** draft, against develop, per the repo PR convention. +- **ai-workflow label:** marks tickets whose subject is the AI dev workflow itself, distinct from the product area labels. See issue-tracker.md for the palette. + +See glossary.md for research ticket, research pipeline, PRD, and the triage roles. diff --git a/docs/research/668-build-research-pipeline/prd.md b/docs/research/668-build-research-pipeline/prd.md new file mode 100644 index 00000000..ecb79ab8 --- /dev/null +++ b/docs/research/668-build-research-pipeline/prd.md @@ -0,0 +1,43 @@ +# PRD: Branch-based research-to-issues pipeline + +Research ticket: #668. This PRD is the prototype instance of the pipeline it describes — it was committed to the 668-build-research-pipeline branch and reviewed before any implementation issues were broken out. + +## Problem Statement + +As a maintainer running the AI issue-authoring flow (grill-with-docs to-prd to-issues triage), I do all the research, terminology work, and PRD drafting inside one chat session and then file implementation issues straight from that chat. Nobody reviews the research or the decisions before issues spawn, and the reasoning evaporates with the conversation — it never becomes durable, reviewable git history. Separately, a ticket whose subject is the AI dev workflow itself has no category; it gets mis-filed under a product area label. + +## Solution + +Move the research flow onto a branch gated by PR review. A research ticket opens the work and names the branch. The grilling session commits its artifacts — CONTEXT.md edits, ADRs, and the PRD — to that branch. The branch is pushed and reviewed as a draft PR against develop. Only after merge are implementation issues broken out. A new ai-workflow label marks tickets about the workflow itself. + +## User Stories + +1. As a maintainer, I want a research ticket that states the open question, so that the branch and PR have a tracked entry point. +2. As a maintainer, I want the grilling session's CONTEXT.md and ADR edits committed to the research branch, so that the reasoning is durable git history instead of chat. +3. As a maintainer, I want the PRD written to docs/research// and committed, so that it is reviewable in the PR diff. +4. As a reviewer, I want the research, terminology, ADRs, and PRD in one draft PR, so that I can comment before any implementation issues exist. +5. As a maintainer, I want implementation issues broken out only after the PRD merges, so that issues never get ahead of the reviewed plan. +6. As a maintainer, I want an ai-workflow label, so that changes to the skills and docs/agents are a recognized category, not mis-filed under product areas. +7. As a contributor, I want the pipeline documented in docs/agents, so that I can follow it without reverse-engineering it from skills. + +## Implementation Decisions + +- Research artifacts (PRD + grilling notes) live in docs/research//. ADRs stay in docs/adr/; CONTEXT.md stays at the root. +- Branch naming reuses the existing {issue}-{kebab-title} convention — no new namespace. +- to-prd gains a pipeline mode (commit PRD to the branch) alongside its existing standalone mode (file an issue). +- grill-with-docs documents that, in pipeline mode, its edits are committed to the branch and reviewed in the PR. +- ai-workflow is a workflow-group label, orthogonal to area labels, created via gh label create. +- The decision is recorded in ADR 0003 (misc-research-pipeline); operative mechanics live in docs/agents/research-pipeline.md. + +## Testing Decisions + +This slice is documentation and skill guidance — no automated tests. Verification is by review: the pipeline page, ADR, label-palette entry, and skill edits are read in the PR, and this PRD's own presence on the branch demonstrates the structure end-to-end. + +## Out of Scope + +- Stage 4 automation: auto-creating implementation issues on merge (a GitHub Action or merge hook running to-issues, keyed off the PRD path). Tracked as a separate follow-up PR. Until then, to-issues is run manually after merge. +- Creating the ai-workflow label in the tracker (run via gh label create when access allows). + +## Further Notes + +The pipeline applies to research-heavy work generally; the ai-workflow label is an orthogonal marker for the subset whose subject is the workflow itself. diff --git a/docs/research/README.md b/docs/research/README.md new file mode 100644 index 00000000..d7b750cf --- /dev/null +++ b/docs/research/README.md @@ -0,0 +1,13 @@ +# Research artifacts + +One folder per research ticket, named for its branch (`-`). Each holds the committed output of a research-pipeline session — the PRD and any grilling notes — reviewed as a draft PR before implementation issues are broken out. + +``` +docs/research/ +└── 668-build-research-pipeline/ + └── prd.md +``` + +ADRs do not live here — they go in docs/adr/. Glossary updates go in the root CONTEXT.md. See docs/agents/research-pipeline.md for the full flow and ADR 0003 for the decision. + +prd.md follows the template in the to-prd skill (.claude/skills/to-prd/SKILL.md). From f155c3ddda6074ac078294b85dcd5165256039d3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 25 Jun 2026 18:34:34 +0000 Subject: [PATCH 02/15] #668 - rename research pipeline to planning pipeline The flow spans terminology, ADRs, and PRD authoring through issue breakout, not just research. Renames the docs page, ADR, docs/planning/ artifact folder, glossary terms (planning pipeline / planning ticket), and all references in issue-tracker.md, grill-with-docs, to-prd, and CLAUDE.md. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/grill-with-docs/SKILL.md | 4 ++-- .claude/skills/to-prd/SKILL.md | 2 +- CLAUDE.md | 2 +- ...line.md => 0003-misc-planning-pipeline.md} | 21 ++++++++++--------- docs/agents/glossary.md | 4 ++-- docs/agents/issue-tracker.md | 4 ++-- ...earch-pipeline.md => planning-pipeline.md} | 20 +++++++++--------- .../668-build-planning-pipeline}/prd.md | 21 ++++++++++--------- docs/planning/README.md | 13 ++++++++++++ docs/research/README.md | 13 ------------ 10 files changed, 53 insertions(+), 51 deletions(-) rename docs/adr/{0003-misc-research-pipeline.md => 0003-misc-planning-pipeline.md} (66%) rename docs/agents/{research-pipeline.md => planning-pipeline.md} (62%) rename docs/{research/668-build-research-pipeline => planning/668-build-planning-pipeline}/prd.md (64%) create mode 100644 docs/planning/README.md delete mode 100644 docs/research/README.md diff --git a/.claude/skills/grill-with-docs/SKILL.md b/.claude/skills/grill-with-docs/SKILL.md index 4fa14b16..36f87003 100644 --- a/.claude/skills/grill-with-docs/SKILL.md +++ b/.claude/skills/grill-with-docs/SKILL.md @@ -85,8 +85,8 @@ Only offer to create an ADR when all three are true: If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). -## Research pipeline +## Planning pipeline -When this session is part of Argos's research pipeline (see docs/agents/research-pipeline.md), it runs on a branch tied to a research ticket. The CONTEXT.md edits and ADRs you create are committed to that branch and reviewed as a draft PR against develop before any implementation issues are broken out — not filed straight from chat. Keep capturing artifacts inline as decisions crystallise; the branch is where they durably land. +When this session is part of Argos's planning pipeline (see docs/agents/planning-pipeline.md), it runs on a branch tied to a planning ticket. The CONTEXT.md edits and ADRs you create are committed to that branch and reviewed as a draft PR against develop before any implementation issues are broken out — not filed straight from chat. Keep capturing artifacts inline as decisions crystallise; the branch is where they durably land. diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index 110a985a..f6f51d8e 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -19,7 +19,7 @@ Check with the user that these modules match their expectations. Check with the 3. Write the PRD using the template below. - **Pipeline mode** — when operating within the research pipeline (docs/agents/research-pipeline.md), you are on a branch tied to a research ticket. Write the PRD to docs/research//prd.md and commit it on the branch instead of filing it as an issue. It is reviewed in the branch's draft PR; implementation issues are broken out with `to-issues` after merge. is the kebab-case branch name. + **Pipeline mode** — when operating within the planning pipeline (docs/agents/planning-pipeline.md), you are on a branch tied to a planning ticket. Write the PRD to docs/planning//prd.md and commit it on the branch instead of filing it as an issue. It is reviewed in the branch's draft PR; implementation issues are broken out with `to-issues` after merge. is the kebab-case branch name. **Standalone mode** — otherwise, publish the PRD to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. diff --git a/CLAUDE.md b/CLAUDE.md index c51960ac..a5e52e01 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`. Research-heavy work runs through the branch-based research pipeline — the grilling session's artifacts are committed to a branch and reviewed before issues spawn; see `docs/agents/research-pipeline.md` (ADR 0003). 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-prd → to-issues → triage`. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. Planning-heavy work runs through the branch-based planning pipeline — the grilling session's artifacts are committed to a branch and reviewed before issues spawn; see `docs/agents/planning-pipeline.md` (ADR 0003). 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/0003-misc-research-pipeline.md b/docs/adr/0003-misc-planning-pipeline.md similarity index 66% rename from docs/adr/0003-misc-research-pipeline.md rename to docs/adr/0003-misc-planning-pipeline.md index 0228d705..f3abd311 100644 --- a/docs/adr/0003-misc-research-pipeline.md +++ b/docs/adr/0003-misc-planning-pipeline.md @@ -1,25 +1,26 @@ -# Branch-based research pipeline for AI-authored issues +# Branch-based planning pipeline for AI-authored issues -The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produces its research, terminology decisions, ADRs, and PRD inside one ephemeral chat session, then files implementation issues directly from chat with no review gate. Argos moves that flow onto a branch: a research ticket opens the work, the grilling session's artifacts (CONTEXT.md edits, ADRs, PRD) are committed to a branch tied to that ticket, and the branch is reviewed as a draft PR against develop before any implementation issues are spawned. Implementation issues are broken out after merge. A new ai-workflow label marks tickets whose subject is the AI dev workflow itself. +The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produces its research, terminology decisions, ADRs, and PRD inside one ephemeral chat session, then files implementation issues directly from chat with no review gate. Argos moves that flow onto a branch: a planning ticket opens the work, the grilling session's artifacts (CONTEXT.md edits, ADRs, PRD) are committed to a branch tied to that ticket, and the branch is reviewed as a draft PR against develop before any implementation issues are spawned. Implementation issues are broken out after merge. A new ai-workflow label marks tickets whose subject is the AI dev workflow itself. ## Considered Options -- Keep the chat-only flow: file implementation issues directly from the grilling session. Rejected — no durable, reviewable record of the reasoning, and issues spawn before anyone reviews the research. -- Commit the artifacts but skip the research ticket and PR review gate. Rejected — it keeps the artifacts but loses the review step, which is the whole point. +- Keep the chat-only flow: file implementation issues directly from the planning session. Rejected — no durable, reviewable record of the reasoning, and issues spawn before anyone reviews the plan. +- Commit the artifacts but skip the planning ticket and PR review gate. Rejected — it keeps the artifacts but loses the review step, which is the whole point. +- Name it the "research pipeline." Rejected — the flow is more than research; it covers terminology, ADRs, and PRD authoring through to issue breakout. ## Why branch-based -- Research artifacts become reviewable git history. The PRD and any ADRs land in a PR diff teammates can comment on before the work fans out into issues. -- A research ticket gives the branch a tracked entry point, consistent with the existing {issue}-{kebab-title} branch convention — no new branch namespace to learn. +- Planning artifacts become reviewable git history. The PRD and any ADRs land in a PR diff teammates can comment on before the work fans out into issues. +- A planning ticket gives the branch a tracked entry point, consistent with the existing {issue}-{kebab-title} branch convention — no new branch namespace to learn. - Decoupling issue creation from the chat session is what makes stage-4 automation possible later: implementation issues can be generated from the merged PRD, keyed off its committed file path. - The ai-workflow label gives meta-work (changes to the skills and docs/agents themselves) a first-class category, instead of mis-filing it under a product area label. ## Consequences -- PRDs and grilling notes live in docs/research//; ADRs still go in docs/adr/, and CONTEXT.md stays at the repo root. -- to-prd gains a pipeline mode: write the PRD to docs/research// and commit it on the research branch, rather than only filing an issue from chat. Standalone mode (no research branch) still publishes to the tracker. -- grill-with-docs's CONTEXT.md and ADR edits are committed to the research branch and reviewed in the draft PR. +- PRDs and planning notes live in docs/planning//; ADRs still go in docs/adr/, and CONTEXT.md stays at the repo root. +- to-prd gains a pipeline mode: write the PRD to docs/planning// and commit it on the branch, rather than only filing an issue from chat. Standalone mode (no planning branch) still publishes to the tracker. +- grill-with-docs's CONTEXT.md and ADR edits are committed to the planning branch and reviewed in the draft PR. - Stage 4 (auto-create implementation issues on merge) is not built here — to-issues is still run manually after merge. Tracked as a follow-up. - The ai-workflow label must exist in the tracker, created via gh label create; it is documented in docs/agents/issue-tracker.md. -See docs/agents/research-pipeline.md for the operative stages and conventions. +See docs/agents/planning-pipeline.md for the operative stages and conventions. diff --git a/docs/agents/glossary.md b/docs/agents/glossary.md index 6f75ec53..3b90d3e8 100644 --- a/docs/agents/glossary.md +++ b/docs/agents/glossary.md @@ -14,8 +14,8 @@ Plain-language definitions of the workflow and agent-tooling terms used across t **PRD (Product Requirements Document).** A feature spec. The `to-prd` skill writes one; `to-issues` then breaks it into tracer-bullet tickets. -**Research pipeline.** The branch-based flow that carries research-heavy work from an open question to implementation issues as reviewable git history: a research ticket opens the work, a grill-with-docs / to-prd session commits its artifacts (CONTEXT.md edits, ADRs, PRD) to a branch tied to that ticket, and the branch is reviewed as a draft PR before issues are broken out. See research-pipeline.md; ADR 0003 records the decision. +**Planning pipeline.** The branch-based flow that carries planning-heavy work from an open question to implementation issues as reviewable git history: a planning ticket opens the work, a grill-with-docs / to-prd session commits its artifacts (CONTEXT.md edits, ADRs, PRD) to a branch tied to that ticket, and the branch is reviewed as a draft PR before issues are broken out. Covers research, terminology, ADRs, and PRD authoring — not just research. See planning-pipeline.md; ADR 0003 records the decision. -**Research ticket.** The entry-point ticket of the research pipeline. It describes what is being researched or triaged — the question, not the answer — and names the branch the session runs on. +**Planning ticket.** The entry-point ticket of the planning pipeline. It describes what is being researched or triaged — the question, not the answer — and names the branch the session runs on. **ai-workflow label.** Marks tickets whose subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline), as opposed to product code. See issue-tracker.md. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 67e798b1..fbeee8d5 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -32,9 +32,9 @@ Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — The triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) are applied by `/triage`, not at creation time. See triage-labels.md. -## Research tickets +## Planning tickets -Research-heavy tickets — anything that needs a grill-with-docs / to-prd session before implementation — flow through the branch-based research pipeline: the session's artifacts are committed to a branch tied to the ticket and reviewed as a draft PR before implementation issues are broken out. See research-pipeline.md. +Planning-heavy tickets — anything that needs a grill-with-docs / to-prd session before implementation — flow through the branch-based planning pipeline: the session's artifacts are committed to a branch tied to the ticket and reviewed as a draft PR before implementation issues are broken out. See planning-pipeline.md. **Backticks:** at most three backtick usages in the entire issue body. Reference files, functions, and identifiers in plain text; reserve backticks for commands worth copy-pasting or short snippets. diff --git a/docs/agents/research-pipeline.md b/docs/agents/planning-pipeline.md similarity index 62% rename from docs/agents/research-pipeline.md rename to docs/agents/planning-pipeline.md index d0d7f668..99423491 100644 --- a/docs/agents/research-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -1,33 +1,33 @@ -# Research pipeline +# Planning pipeline -How AI-authored work moves from an open question to implementation issues as reviewable git history, instead of an ephemeral chat session. Decision and rationale: ADR 0003. +How AI-authored work moves from an open question to implementation issues as reviewable git history, instead of an ephemeral chat session. It covers the whole planning step — research, terminology, ADRs, and PRD authoring — not just research. Decision and rationale: ADR 0003. ## When to use it -Reach for the pipeline when the work needs research, terminology decisions, or an architecture call before implementation — the kind of session that runs grill-with-docs and to-prd. Small, well-understood tickets don't need it; file them and go. +Reach for the pipeline when the work needs planning before implementation — research, terminology decisions, or an architecture call — the kind of session that runs grill-with-docs and to-prd. Small, well-understood tickets don't need it; file them and go. ## Stages -1. **Research ticket.** A human files a lightweight ticket describing what is being researched or triaged — the question, not the answer. This is the entry point and the thing the branch is named for. If the ticket's subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline), apply the ai-workflow label; otherwise label it by the product area being researched. +1. **Planning ticket.** A human files a lightweight ticket describing what is being researched or triaged — the question, not the answer. This is the entry point and the thing the branch is named for. If the ticket's subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline), apply the ai-workflow label; otherwise label it by the product area being planned. -2. **Grilling session on a branch.** Branch from develop as {issue}-{kebab-title}. Run grill-with-docs (and to-prd) against the ticket. Every artifact the session produces is committed to that branch: +2. **Planning session on a branch.** Branch from develop as {issue}-{kebab-title}. Run grill-with-docs (and to-prd) against the ticket. Every artifact the session produces is committed to that branch: - CONTEXT.md edits at the repo root (glossary). - New ADRs in docs/adr/. - - The PRD in docs/research//prd.md, plus any grilling notes in the same folder. + - The PRD in docs/planning//prd.md, plus any planning notes in the same folder. 3. **Push + review.** Push the branch and open a draft PR against develop. Humans review the research, terminology, ADRs, and PRD in the diff before any implementation work is broken out. -4. **Merge to implementation issues.** Once the PR merges, the PRD is broken into tracer-bullet issues with to-issues, linked back to the research ticket. Today this is run manually after merge; auto-creating the issues on merge is a planned follow-up (keyed off the committed PRD path). +4. **Merge to implementation issues.** Once the PR merges, the PRD is broken into tracer-bullet issues with to-issues, linked back to the planning ticket. Today this is run manually after merge; auto-creating the issues on merge is a planned follow-up (keyed off the committed PRD path). ## Where artifacts live | Artifact | Location | | --- | --- | -| PRD + grilling notes | docs/research// | +| PRD + planning notes | docs/planning// | | ADRs | docs/adr/ (see domain.md for the naming convention) | | Glossary updates | CONTEXT.md (root) | - is the kebab-case branch name, e.g. docs/research/668-build-research-pipeline/. + is the kebab-case branch name, e.g. docs/planning/668-build-planning-pipeline/. ## Conventions @@ -35,4 +35,4 @@ Reach for the pipeline when the work needs research, terminology decisions, or a - **PR:** draft, against develop, per the repo PR convention. - **ai-workflow label:** marks tickets whose subject is the AI dev workflow itself, distinct from the product area labels. See issue-tracker.md for the palette. -See glossary.md for research ticket, research pipeline, PRD, and the triage roles. +See glossary.md for planning ticket, planning pipeline, PRD, and the triage roles. diff --git a/docs/research/668-build-research-pipeline/prd.md b/docs/planning/668-build-planning-pipeline/prd.md similarity index 64% rename from docs/research/668-build-research-pipeline/prd.md rename to docs/planning/668-build-planning-pipeline/prd.md index ecb79ab8..acbca1a3 100644 --- a/docs/research/668-build-research-pipeline/prd.md +++ b/docs/planning/668-build-planning-pipeline/prd.md @@ -1,20 +1,20 @@ -# PRD: Branch-based research-to-issues pipeline +# PRD: Branch-based planning pipeline -Research ticket: #668. This PRD is the prototype instance of the pipeline it describes — it was committed to the 668-build-research-pipeline branch and reviewed before any implementation issues were broken out. +Planning ticket: #668. This PRD is the prototype instance of the pipeline it describes — it was committed to this branch and reviewed before any implementation issues were broken out. ## Problem Statement -As a maintainer running the AI issue-authoring flow (grill-with-docs to-prd to-issues triage), I do all the research, terminology work, and PRD drafting inside one chat session and then file implementation issues straight from that chat. Nobody reviews the research or the decisions before issues spawn, and the reasoning evaporates with the conversation — it never becomes durable, reviewable git history. Separately, a ticket whose subject is the AI dev workflow itself has no category; it gets mis-filed under a product area label. +As a maintainer running the AI issue-authoring flow (grill-with-docs to-prd to-issues triage), I do all the research, terminology work, and PRD drafting inside one chat session and then file implementation issues straight from that chat. Nobody reviews the plan or the decisions before issues spawn, and the reasoning evaporates with the conversation — it never becomes durable, reviewable git history. Separately, a ticket whose subject is the AI dev workflow itself has no category; it gets mis-filed under a product area label. ## Solution -Move the research flow onto a branch gated by PR review. A research ticket opens the work and names the branch. The grilling session commits its artifacts — CONTEXT.md edits, ADRs, and the PRD — to that branch. The branch is pushed and reviewed as a draft PR against develop. Only after merge are implementation issues broken out. A new ai-workflow label marks tickets about the workflow itself. +Move the planning flow onto a branch gated by PR review. A planning ticket opens the work and names the branch. The planning session commits its artifacts — CONTEXT.md edits, ADRs, and the PRD — to that branch. The branch is pushed and reviewed as a draft PR against develop. Only after merge are implementation issues broken out. A new ai-workflow label marks tickets about the workflow itself. ## User Stories -1. As a maintainer, I want a research ticket that states the open question, so that the branch and PR have a tracked entry point. -2. As a maintainer, I want the grilling session's CONTEXT.md and ADR edits committed to the research branch, so that the reasoning is durable git history instead of chat. -3. As a maintainer, I want the PRD written to docs/research// and committed, so that it is reviewable in the PR diff. +1. As a maintainer, I want a planning ticket that states the open question, so that the branch and PR have a tracked entry point. +2. As a maintainer, I want the planning session's CONTEXT.md and ADR edits committed to the branch, so that the reasoning is durable git history instead of chat. +3. As a maintainer, I want the PRD written to docs/planning// and committed, so that it is reviewable in the PR diff. 4. As a reviewer, I want the research, terminology, ADRs, and PRD in one draft PR, so that I can comment before any implementation issues exist. 5. As a maintainer, I want implementation issues broken out only after the PRD merges, so that issues never get ahead of the reviewed plan. 6. As a maintainer, I want an ai-workflow label, so that changes to the skills and docs/agents are a recognized category, not mis-filed under product areas. @@ -22,12 +22,13 @@ Move the research flow onto a branch gated by PR review. A research ticket opens ## Implementation Decisions -- Research artifacts (PRD + grilling notes) live in docs/research//. ADRs stay in docs/adr/; CONTEXT.md stays at the root. +- Planning artifacts (PRD + notes) live in docs/planning//. ADRs stay in docs/adr/; CONTEXT.md stays at the root. - Branch naming reuses the existing {issue}-{kebab-title} convention — no new namespace. - to-prd gains a pipeline mode (commit PRD to the branch) alongside its existing standalone mode (file an issue). - grill-with-docs documents that, in pipeline mode, its edits are committed to the branch and reviewed in the PR. - ai-workflow is a workflow-group label, orthogonal to area labels, created via gh label create. -- The decision is recorded in ADR 0003 (misc-research-pipeline); operative mechanics live in docs/agents/research-pipeline.md. +- The decision is recorded in ADR 0003 (misc-planning-pipeline); operative mechanics live in docs/agents/planning-pipeline.md. +- The flow is named "planning pipeline," not "research pipeline" — it spans terminology, ADRs, and PRD authoring, not just research. ## Testing Decisions @@ -40,4 +41,4 @@ This slice is documentation and skill guidance — no automated tests. Verificat ## Further Notes -The pipeline applies to research-heavy work generally; the ai-workflow label is an orthogonal marker for the subset whose subject is the workflow itself. +The pipeline applies to planning-heavy work generally; the ai-workflow label is an orthogonal marker for the subset whose subject is the workflow itself. diff --git a/docs/planning/README.md b/docs/planning/README.md new file mode 100644 index 00000000..a2d9eb30 --- /dev/null +++ b/docs/planning/README.md @@ -0,0 +1,13 @@ +# Planning artifacts + +One folder per planning ticket, named for its branch (`-`). Each holds the committed output of a planning-pipeline session — the PRD and any planning notes — reviewed as a draft PR before implementation issues are broken out. + +``` +docs/planning/ +└── 668-build-planning-pipeline/ + └── prd.md +``` + +ADRs do not live here — they go in docs/adr/. Glossary updates go in the root CONTEXT.md. See docs/agents/planning-pipeline.md for the full flow and ADR 0003 for the decision. + +prd.md follows the template in the to-prd skill (.claude/skills/to-prd/SKILL.md). diff --git a/docs/research/README.md b/docs/research/README.md deleted file mode 100644 index d7b750cf..00000000 --- a/docs/research/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Research artifacts - -One folder per research ticket, named for its branch (`-`). Each holds the committed output of a research-pipeline session — the PRD and any grilling notes — reviewed as a draft PR before implementation issues are broken out. - -``` -docs/research/ -└── 668-build-research-pipeline/ - └── prd.md -``` - -ADRs do not live here — they go in docs/adr/. Glossary updates go in the root CONTEXT.md. See docs/agents/research-pipeline.md for the full flow and ADR 0003 for the decision. - -prd.md follows the template in the to-prd skill (.claude/skills/to-prd/SKILL.md). From a010c4cc3092f6d5b9401073bd20d3996eae04b3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 25 Jun 2026 19:54:31 +0000 Subject: [PATCH 03/15] #668 - clarify the planning flow starts with grill-with-docs Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index a5e52e01..46dc6cc2 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`. Planning-heavy work runs through the branch-based planning pipeline — the grilling session's artifacts are committed to a branch and reviewed before issues spawn; see `docs/agents/planning-pipeline.md` (ADR 0003). 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 starts with `grill-with-docs` and proceeds `grill-with-docs → to-prd → to-issues → triage` — always open with the grilling session, don't jump straight to drafting issues. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. Planning-heavy work runs through the branch-based planning pipeline: open a planning ticket and run `grill-with-docs` on a branch first, so its artifacts are committed and reviewed before issues spawn; see `docs/agents/planning-pipeline.md` (ADR 0003). The `caveman` terse mode is on by default in this repo as a pilot — see the Communication section above. ### Issue tracker From 8eaa6e60869ded3513ccb0be6155d5487d54e54f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 25 Jun 2026 22:48:16 +0000 Subject: [PATCH 04/15] #668 - frame the planning pipeline as the default, not heavy-ticket-only It is the normal way to plan a feature with grill-with-docs/to-prd: do it on a branch off develop so the work is saved, recorded, and reviewed rather than lost to chat or committed straight to develop. Reframes the pipeline doc, issue-tracker, glossary, CLAUDE.md, and both skills; makes pipeline the default path in to-prd with standalone as the exception. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/grill-with-docs/SKILL.md | 2 +- .claude/skills/to-prd/SKILL.md | 4 ++-- CLAUDE.md | 2 +- docs/agents/glossary.md | 2 +- docs/agents/issue-tracker.md | 2 +- docs/agents/planning-pipeline.md | 4 ++-- docs/planning/668-build-planning-pipeline/prd.md | 2 +- 7 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.claude/skills/grill-with-docs/SKILL.md b/.claude/skills/grill-with-docs/SKILL.md index 36f87003..2f650b97 100644 --- a/.claude/skills/grill-with-docs/SKILL.md +++ b/.claude/skills/grill-with-docs/SKILL.md @@ -87,6 +87,6 @@ If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md]( ## Planning pipeline -When this session is part of Argos's planning pipeline (see docs/agents/planning-pipeline.md), it runs on a branch tied to a planning ticket. The CONTEXT.md edits and ADRs you create are committed to that branch and reviewed as a draft PR against develop before any implementation issues are broken out — not filed straight from chat. Keep capturing artifacts inline as decisions crystallise; the branch is where they durably land. +By default this session runs through Argos's planning pipeline (see docs/agents/planning-pipeline.md): on a branch off develop, not develop itself. The CONTEXT.md edits and ADRs you create are committed to that branch and reviewed as a draft PR before any implementation issues are broken out — so the work is saved and recorded, not lost to chat or committed straight to develop. Keep capturing artifacts inline as decisions crystallise; the branch is where they durably land. diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index f6f51d8e..8a065db2 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -19,9 +19,9 @@ Check with the user that these modules match their expectations. Check with the 3. Write the PRD using the template below. - **Pipeline mode** — when operating within the planning pipeline (docs/agents/planning-pipeline.md), you are on a branch tied to a planning ticket. Write the PRD to docs/planning//prd.md and commit it on the branch instead of filing it as an issue. It is reviewed in the branch's draft PR; implementation issues are broken out with `to-issues` after merge. is the kebab-case branch name. + By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, write the PRD to docs/planning//prd.md and commit it, so it is reviewed in a draft PR and implementation issues are broken out with `to-issues` after merge. is the kebab-case branch name. - **Standalone mode** — otherwise, publish the PRD to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. + Only for a quick one-off where you are explicitly not planning on a branch, publish the PRD straight to the issue tracker instead, applying the `ready-for-agent` triage label. diff --git a/CLAUDE.md b/CLAUDE.md index 46dc6cc2..5ba8a335 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 starts with `grill-with-docs` and proceeds `grill-with-docs → to-prd → to-issues → triage` — always open with the grilling session, don't jump straight to drafting issues. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. Planning-heavy work runs through the branch-based planning pipeline: open a planning ticket and run `grill-with-docs` on a branch first, so its artifacts are committed and reviewed before issues spawn; see `docs/agents/planning-pipeline.md` (ADR 0003). 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 starts with `grill-with-docs` and proceeds `grill-with-docs → to-prd → to-issues → triage` — always open with the grilling session, don't jump straight to drafting issues. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. By default, plan features through the branch-based planning pipeline: run `grill-with-docs`/`to-prd` on a branch off develop (not on develop itself), so their artifacts are saved, committed, and reviewed before issues spawn; see `docs/agents/planning-pipeline.md` (ADR 0003). 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/agents/glossary.md b/docs/agents/glossary.md index 3b90d3e8..11156023 100644 --- a/docs/agents/glossary.md +++ b/docs/agents/glossary.md @@ -14,7 +14,7 @@ Plain-language definitions of the workflow and agent-tooling terms used across t **PRD (Product Requirements Document).** A feature spec. The `to-prd` skill writes one; `to-issues` then breaks it into tracer-bullet tickets. -**Planning pipeline.** The branch-based flow that carries planning-heavy work from an open question to implementation issues as reviewable git history: a planning ticket opens the work, a grill-with-docs / to-prd session commits its artifacts (CONTEXT.md edits, ADRs, PRD) to a branch tied to that ticket, and the branch is reviewed as a draft PR before issues are broken out. Covers research, terminology, ADRs, and PRD authoring — not just research. See planning-pipeline.md; ADR 0003 records the decision. +**Planning pipeline.** The default flow for planning a feature with grill-with-docs or to-prd: the session runs on a branch off develop and commits its artifacts (CONTEXT.md edits, ADRs, PRD) there, so they are saved and reviewable as a draft PR before implementation issues are broken out — rather than lost to chat or committed straight to develop. See planning-pipeline.md; ADR 0003 records the decision. **Planning ticket.** The entry-point ticket of the planning pipeline. It describes what is being researched or triaged — the question, not the answer — and names the branch the session runs on. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index fbeee8d5..e9916a2b 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -34,7 +34,7 @@ The triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-hu ## Planning tickets -Planning-heavy tickets — anything that needs a grill-with-docs / to-prd session before implementation — flow through the branch-based planning pipeline: the session's artifacts are committed to a branch tied to the ticket and reviewed as a draft PR before implementation issues are broken out. See planning-pipeline.md. +Whenever you plan a feature with grill-with-docs or to-prd, do it through the branch-based planning pipeline: the session runs on a branch off develop, its artifacts are committed and reviewed as a draft PR, and implementation issues are broken out after merge — not filed straight from chat or committed to develop. This is the normal path, not a special case. See planning-pipeline.md. **Backticks:** at most three backtick usages in the entire issue body. Reference files, functions, and identifiers in plain text; reserve backticks for commands worth copy-pasting or short snippets. diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index 99423491..18dd6f98 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -1,10 +1,10 @@ # Planning pipeline -How AI-authored work moves from an open question to implementation issues as reviewable git history, instead of an ephemeral chat session. It covers the whole planning step — research, terminology, ADRs, and PRD authoring — not just research. Decision and rationale: ADR 0003. +The default way to plan a feature with grill-with-docs or to-prd. Instead of doing that work in an ephemeral chat — or committing it straight to develop — you do it on a branch, so the artifacts it produces (CONTEXT.md edits, ADRs, the PRD) are saved, recorded, reviewed, and testable before anything lands on develop. Decision and rationale: ADR 0003. ## When to use it -Reach for the pipeline when the work needs planning before implementation — research, terminology decisions, or an architecture call — the kind of session that runs grill-with-docs and to-prd. Small, well-understood tickets don't need it; file them and go. +Most of the time. Any session that runs grill-with-docs or to-prd to plan a feature goes through the pipeline — that is just what it means to plan on a branch rather than in chat. Skip it only for trivial, well-understood changes that need no planning session at all. ## Stages diff --git a/docs/planning/668-build-planning-pipeline/prd.md b/docs/planning/668-build-planning-pipeline/prd.md index acbca1a3..14c66112 100644 --- a/docs/planning/668-build-planning-pipeline/prd.md +++ b/docs/planning/668-build-planning-pipeline/prd.md @@ -41,4 +41,4 @@ This slice is documentation and skill guidance — no automated tests. Verificat ## Further Notes -The pipeline applies to planning-heavy work generally; the ai-workflow label is an orthogonal marker for the subset whose subject is the workflow itself. +The pipeline is the default for planning a feature with grill-with-docs or to-prd, not a special case for big tickets; the ai-workflow label is an orthogonal marker for the subset whose subject is the workflow itself. From 6e2fa39d0942435ab720ce74086c2e6f2c1d342a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 25 Jun 2026 23:16:51 +0000 Subject: [PATCH 05/15] #668 - tighten planning-pipeline docs and skill prose Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/grill-with-docs/SKILL.md | 2 +- .claude/skills/to-prd/SKILL.md | 4 ++-- docs/adr/0003-misc-planning-pipeline.md | 2 +- docs/agents/glossary.md | 4 ++-- docs/agents/issue-tracker.md | 4 ++-- docs/agents/planning-pipeline.md | 12 ++++++------ 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.claude/skills/grill-with-docs/SKILL.md b/.claude/skills/grill-with-docs/SKILL.md index 2f650b97..d0e698a9 100644 --- a/.claude/skills/grill-with-docs/SKILL.md +++ b/.claude/skills/grill-with-docs/SKILL.md @@ -87,6 +87,6 @@ If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md]( ## Planning pipeline -By default this session runs through Argos's planning pipeline (see docs/agents/planning-pipeline.md): on a branch off develop, not develop itself. The CONTEXT.md edits and ADRs you create are committed to that branch and reviewed as a draft PR before any implementation issues are broken out — so the work is saved and recorded, not lost to chat or committed straight to develop. Keep capturing artifacts inline as decisions crystallise; the branch is where they durably land. +By default this session runs through Argos's planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, not develop itself. Your CONTEXT.md edits and ADRs are committed to that branch and reviewed as a draft PR before any issues are broken out — saved and recorded, not lost to chat. Keep capturing artifacts inline as decisions crystallise; the branch is where they land. diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index 8a065db2..154070a7 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -19,9 +19,9 @@ Check with the user that these modules match their expectations. Check with the 3. Write the PRD using the template below. - By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, write the PRD to docs/planning//prd.md and commit it, so it is reviewed in a draft PR and implementation issues are broken out with `to-issues` after merge. is the kebab-case branch name. + By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, write the PRD to docs/planning//prd.md and commit it — reviewed in a draft PR, then broken into issues with `to-issues` after merge. is the kebab-case branch name. - Only for a quick one-off where you are explicitly not planning on a branch, publish the PRD straight to the issue tracker instead, applying the `ready-for-agent` triage label. + For a quick one-off not planned on a branch, publish the PRD straight to the issue tracker instead, applying the `ready-for-agent` triage label. diff --git a/docs/adr/0003-misc-planning-pipeline.md b/docs/adr/0003-misc-planning-pipeline.md index f3abd311..e85271dc 100644 --- a/docs/adr/0003-misc-planning-pipeline.md +++ b/docs/adr/0003-misc-planning-pipeline.md @@ -1,6 +1,6 @@ # Branch-based planning pipeline for AI-authored issues -The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produces its research, terminology decisions, ADRs, and PRD inside one ephemeral chat session, then files implementation issues directly from chat with no review gate. Argos moves that flow onto a branch: a planning ticket opens the work, the grilling session's artifacts (CONTEXT.md edits, ADRs, PRD) are committed to a branch tied to that ticket, and the branch is reviewed as a draft PR against develop before any implementation issues are spawned. Implementation issues are broken out after merge. A new ai-workflow label marks tickets whose subject is the AI dev workflow itself. +The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produced its research, terminology, ADRs, and PRD inside one ephemeral chat session, then filed implementation issues from chat with no review gate. Argos moves that flow onto a branch: a planning ticket opens the work, the session's artifacts (CONTEXT.md edits, ADRs, PRD) are committed to the branch, and it's reviewed as a draft PR against develop before any issues spawn. Issues are broken out after merge. A new ai-workflow label marks tickets whose subject is the AI dev workflow itself. ## Considered Options diff --git a/docs/agents/glossary.md b/docs/agents/glossary.md index 11156023..3f2650df 100644 --- a/docs/agents/glossary.md +++ b/docs/agents/glossary.md @@ -14,8 +14,8 @@ Plain-language definitions of the workflow and agent-tooling terms used across t **PRD (Product Requirements Document).** A feature spec. The `to-prd` skill writes one; `to-issues` then breaks it into tracer-bullet tickets. -**Planning pipeline.** The default flow for planning a feature with grill-with-docs or to-prd: the session runs on a branch off develop and commits its artifacts (CONTEXT.md edits, ADRs, PRD) there, so they are saved and reviewable as a draft PR before implementation issues are broken out — rather than lost to chat or committed straight to develop. See planning-pipeline.md; ADR 0003 records the decision. +**Planning pipeline.** The default flow for planning a feature with grill-with-docs or to-prd: the session runs on a branch off develop and commits its artifacts (CONTEXT.md edits, ADRs, PRD) there, reviewed as a draft PR before issues are broken out — not lost to chat or committed straight to develop. See planning-pipeline.md; ADR 0003 records the decision. -**Planning ticket.** The entry-point ticket of the planning pipeline. It describes what is being researched or triaged — the question, not the answer — and names the branch the session runs on. +**Planning ticket.** Entry point of the planning pipeline: a ticket stating what's being researched or triaged — the question, not the answer — that names the branch. **ai-workflow label.** Marks tickets whose subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline), as opposed to product code. See issue-tracker.md. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index e9916a2b..5c1456ed 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -28,13 +28,13 @@ These apply when an AI skill files an issue with `gh issue create`. They govern | Difficulty | `straightforward`, `medium`, `difficult` | | Workflow | `ai-workflow` | -Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — the skills, docs/agents, or the issue pipeline — rather than product code. It is orthogonal to the area labels (a ticket is about the workflow or about a product component, not both). Created via `gh label create`, like the triage roles. +Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — the skills, docs/agents, or the issue pipeline — not product code. Orthogonal to the area labels (a ticket is about the workflow or a product component, not both). Created via `gh label create`, like the triage roles. The triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) are applied by `/triage`, not at creation time. See triage-labels.md. ## Planning tickets -Whenever you plan a feature with grill-with-docs or to-prd, do it through the branch-based planning pipeline: the session runs on a branch off develop, its artifacts are committed and reviewed as a draft PR, and implementation issues are broken out after merge — not filed straight from chat or committed to develop. This is the normal path, not a special case. See planning-pipeline.md. +Plan features with grill-with-docs or to-prd through the branch-based planning pipeline: the session runs on a branch off develop, its artifacts are committed and reviewed as a draft PR, and implementation issues are broken out after merge — not filed from chat or committed to develop. The normal path, not a special case. See planning-pipeline.md. **Backticks:** at most three backtick usages in the entire issue body. Reference files, functions, and identifiers in plain text; reserve backticks for commands worth copy-pasting or short snippets. diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index 18dd6f98..a3c1593e 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -1,23 +1,23 @@ # Planning pipeline -The default way to plan a feature with grill-with-docs or to-prd. Instead of doing that work in an ephemeral chat — or committing it straight to develop — you do it on a branch, so the artifacts it produces (CONTEXT.md edits, ADRs, the PRD) are saved, recorded, reviewed, and testable before anything lands on develop. Decision and rationale: ADR 0003. +The default way to plan a feature with grill-with-docs or to-prd: do it on a branch, not in chat or straight on develop, so its artifacts (CONTEXT.md edits, ADRs, the PRD) are saved, reviewed, and testable before anything lands on develop. Decision and rationale: ADR 0003. ## When to use it -Most of the time. Any session that runs grill-with-docs or to-prd to plan a feature goes through the pipeline — that is just what it means to plan on a branch rather than in chat. Skip it only for trivial, well-understood changes that need no planning session at all. +Most of the time — any grill-with-docs or to-prd session for planning a feature. Skip only for trivial changes that need no planning session. ## Stages -1. **Planning ticket.** A human files a lightweight ticket describing what is being researched or triaged — the question, not the answer. This is the entry point and the thing the branch is named for. If the ticket's subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline), apply the ai-workflow label; otherwise label it by the product area being planned. +1. **Planning ticket.** A lightweight ticket stating what's being researched or triaged — the question, not the answer. It's the entry point and names the branch. Apply the ai-workflow label if its subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline); otherwise label by product area. -2. **Planning session on a branch.** Branch from develop as {issue}-{kebab-title}. Run grill-with-docs (and to-prd) against the ticket. Every artifact the session produces is committed to that branch: +2. **Planning session on a branch.** Branch from develop as {issue}-{kebab-title}; run grill-with-docs (and to-prd) against the ticket. Commit every artifact to the branch: - CONTEXT.md edits at the repo root (glossary). - New ADRs in docs/adr/. - The PRD in docs/planning//prd.md, plus any planning notes in the same folder. -3. **Push + review.** Push the branch and open a draft PR against develop. Humans review the research, terminology, ADRs, and PRD in the diff before any implementation work is broken out. +3. **Push + review.** Push, open a draft PR against develop. Humans review the artifacts in the diff before any issues are broken out. -4. **Merge to implementation issues.** Once the PR merges, the PRD is broken into tracer-bullet issues with to-issues, linked back to the planning ticket. Today this is run manually after merge; auto-creating the issues on merge is a planned follow-up (keyed off the committed PRD path). +4. **Merge to implementation issues.** On merge, break the PRD into tracer-bullet issues with to-issues, linked back to the planning ticket. Manual after merge today; auto-creation on merge is a planned follow-up (keyed off the committed PRD path). ## Where artifacts live From 8f29477555b944d77f3db87ec58193823babbc0d Mon Sep 17 00:00:00 2001 From: wyattb Date: Sun, 28 Jun 2026 10:47:38 -0700 Subject: [PATCH 06/15] #668 - address PR review: parent link, ticket close, PRD retention, title shape, on-develop guard, drop stale label notes --- .claude/skills/to-issues/SKILL.md | 2 ++ .claude/skills/to-prd/SKILL.md | 2 +- CLAUDE.md | 2 +- docs/adr/0003-misc-planning-pipeline.md | 2 +- docs/agents/planning-pipeline.md | 10 ++++++---- docs/planning/668-build-planning-pipeline/prd.md | 1 - 6 files changed, 11 insertions(+), 8 deletions(-) diff --git a/.claude/skills/to-issues/SKILL.md b/.claude/skills/to-issues/SKILL.md index 3017446e..a7efb1c1 100644 --- a/.claude/skills/to-issues/SKILL.md +++ b/.claude/skills/to-issues/SKILL.md @@ -55,6 +55,8 @@ For each approved slice, publish a new issue to the issue tracker. Use the issue Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field. +When breaking out a planning-pipeline PRD (docs/planning//prd.md), set the Parent of every spawned issue to the planning ticket the branch is named for, even though the immediate source is the PRD file, so the issues link back to it. + ## Parent diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index 154070a7..a68b254a 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -19,7 +19,7 @@ Check with the user that these modules match their expectations. Check with the 3. Write the PRD using the template below. - By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, write the PRD to docs/planning//prd.md and commit it — reviewed in a draft PR, then broken into issues with `to-issues` after merge. is the kebab-case branch name. + By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, write the PRD to docs/planning//prd.md and commit it — reviewed in a draft PR, then broken into issues with `to-issues` after merge. is the planning ticket's number and kebab-title, the same as the branch name. For a quick one-off not planned on a branch, publish the PRD straight to the issue tracker instead, applying the `ready-for-agent` triage label. diff --git a/CLAUDE.md b/CLAUDE.md index 5ba8a335..d2090e37 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 starts with `grill-with-docs` and proceeds `grill-with-docs → to-prd → to-issues → triage` — always open with the grilling session, don't jump straight to drafting issues. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. By default, plan features through the branch-based planning pipeline: run `grill-with-docs`/`to-prd` on a branch off develop (not on develop itself), so their artifacts are saved, committed, and reviewed before issues spawn; see `docs/agents/planning-pipeline.md` (ADR 0003). 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 starts with `grill-with-docs` and proceeds `grill-with-docs → to-prd → to-issues → triage` — always open with the grilling session, don't jump straight to drafting issues. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. By default, plan features through the branch-based planning pipeline: run `grill-with-docs`/`to-prd` on a branch off develop, never on develop itself, so their artifacts are saved, committed, and reviewed before issues spawn. If a planning session starts while you are on develop, create the planning branch first. See `docs/agents/planning-pipeline.md` (ADR 0003). 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/0003-misc-planning-pipeline.md b/docs/adr/0003-misc-planning-pipeline.md index e85271dc..85c2cba5 100644 --- a/docs/adr/0003-misc-planning-pipeline.md +++ b/docs/adr/0003-misc-planning-pipeline.md @@ -21,6 +21,6 @@ The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produced i - to-prd gains a pipeline mode: write the PRD to docs/planning// and commit it on the branch, rather than only filing an issue from chat. Standalone mode (no planning branch) still publishes to the tracker. - grill-with-docs's CONTEXT.md and ADR edits are committed to the planning branch and reviewed in the draft PR. - Stage 4 (auto-create implementation issues on merge) is not built here — to-issues is still run manually after merge. Tracked as a follow-up. -- The ai-workflow label must exist in the tracker, created via gh label create; it is documented in docs/agents/issue-tracker.md. +- The ai-workflow label is created via gh label create and documented in docs/agents/issue-tracker.md. See docs/agents/planning-pipeline.md for the operative stages and conventions. diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index a3c1593e..f60291be 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -8,16 +8,16 @@ Most of the time — any grill-with-docs or to-prd session for planning a featur ## Stages -1. **Planning ticket.** A lightweight ticket stating what's being researched or triaged — the question, not the answer. It's the entry point and names the branch. Apply the ai-workflow label if its subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline); otherwise label by product area. +1. **Planning ticket.** A lightweight ticket stating what's being researched or triaged — the question, not the answer. It's the entry point and names the branch. Title it as a normal imperative with no special prefix (e.g. "Build grill-with-docs into a planning pipeline"), the same as any other ticket. Apply the ai-workflow label if its subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline); otherwise label by product area. 2. **Planning session on a branch.** Branch from develop as {issue}-{kebab-title}; run grill-with-docs (and to-prd) against the ticket. Commit every artifact to the branch: - CONTEXT.md edits at the repo root (glossary). - New ADRs in docs/adr/. - The PRD in docs/planning//prd.md, plus any planning notes in the same folder. -3. **Push + review.** Push, open a draft PR against develop. Humans review the artifacts in the diff before any issues are broken out. +3. **Push + review.** Push and open a draft PR against develop; reference the planning ticket in the PR body with "Closes #" so merging the reviewed plan closes it automatically. Humans review the artifacts in the diff before any issues are broken out. -4. **Merge to implementation issues.** On merge, break the PRD into tracer-bullet issues with to-issues, linked back to the planning ticket. Manual after merge today; auto-creation on merge is a planned follow-up (keyed off the committed PRD path). +4. **Merge to implementation issues.** On merge, break the PRD into tracer-bullet issues with to-issues, setting each issue's Parent to the planning ticket so they link back to it (the merge closes that ticket, but a closed issue is still a valid Parent reference). Manual after merge today; auto-creation on merge is a planned follow-up (keyed off the committed PRD path). ## Where artifacts live @@ -27,7 +27,9 @@ Most of the time — any grill-with-docs or to-prd session for planning a featur | ADRs | docs/adr/ (see domain.md for the naming convention) | | Glossary updates | CONTEXT.md (root) | - is the kebab-case branch name, e.g. docs/planning/668-build-planning-pipeline/. + is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/planning/668-build-planning-pipeline/. + +Planning artifacts are retained in-repo as durable history; they are not pruned after issues are created (stage-4 automation keys off the committed PRD path). ## Conventions diff --git a/docs/planning/668-build-planning-pipeline/prd.md b/docs/planning/668-build-planning-pipeline/prd.md index 14c66112..43243ab4 100644 --- a/docs/planning/668-build-planning-pipeline/prd.md +++ b/docs/planning/668-build-planning-pipeline/prd.md @@ -37,7 +37,6 @@ This slice is documentation and skill guidance — no automated tests. Verificat ## Out of Scope - Stage 4 automation: auto-creating implementation issues on merge (a GitHub Action or merge hook running to-issues, keyed off the PRD path). Tracked as a separate follow-up PR. Until then, to-issues is run manually after merge. -- Creating the ai-workflow label in the tracker (run via gh label create when access allows). ## Further Notes From 14f655f13fc739a59f58eefed811fe2f5e319858 Mon Sep 17 00:00:00 2001 From: wyattb Date: Sun, 28 Jun 2026 12:54:17 -0700 Subject: [PATCH 07/15] #668 - review nits: tighten agent-skills sentence, move Planning tickets section --- CLAUDE.md | 2 +- docs/agents/issue-tracker.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d2090e37..efa2299c 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 starts with `grill-with-docs` and proceeds `grill-with-docs → to-prd → to-issues → triage` — always open with the grilling session, don't jump straight to drafting issues. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. By default, plan features through the branch-based planning pipeline: run `grill-with-docs`/`to-prd` on a branch off develop, never on develop itself, so their artifacts are saved, committed, and reviewed before issues spawn. If a planning session starts while you are on develop, create the planning branch first. See `docs/agents/planning-pipeline.md` (ADR 0003). 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-prd → to-issues → triage`; always open with the grilling session, never jump straight to drafting issues. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`. By default, plan features through the branch-based planning pipeline: run `grill-with-docs`/`to-prd` on a branch off develop, never on develop itself, so their artifacts are saved, committed, and reviewed before issues spawn. If a planning session starts while you are on develop, create the planning branch first. See `docs/agents/planning-pipeline.md` (ADR 0003). 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/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 5c1456ed..89a25710 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -32,14 +32,14 @@ Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — The triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) are applied by `/triage`, not at creation time. See triage-labels.md. -## Planning tickets - -Plan features with grill-with-docs or to-prd through the branch-based planning pipeline: the session runs on a branch off develop, its artifacts are committed and reviewed as a draft PR, and implementation issues are broken out after merge — not filed from chat or committed to develop. The normal path, not a special case. See planning-pipeline.md. - **Backticks:** at most three backtick usages in the entire issue body. Reference files, functions, and identifiers in plain text; reserve backticks for commands worth copy-pasting or short snippets. **Assignment:** pass `--assignee @me` by default. This repo self-assigns issues. +## Planning tickets + +Plan features with grill-with-docs or to-prd through the branch-based planning pipeline: the session runs on a branch off develop, its artifacts are committed and reviewed as a draft PR, and implementation issues are broken out after merge — not filed from chat or committed to develop. The normal path, not a special case. See planning-pipeline.md. + ## When a skill says "publish to the issue tracker" Create a GitHub issue. From 7dcaba8ef290918898b58a4837dbbcc90c64184d Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 3 Jul 2026 20:20:34 +0000 Subject: [PATCH 08/15] #668 - address review: fix pipeline contradictions - issue-tracker: PRDs live under docs/planning by default, not as issues - ai-workflow tickets still take type/difficulty labels - to-prd description mentions the branch/pipeline default so skill selection picks it - to-issues reads the merged PRD from docs/planning// (branch is deleted on merge); define as the folder name, not branch Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/to-issues/SKILL.md | 2 ++ .claude/skills/to-prd/SKILL.md | 2 +- docs/agents/issue-tracker.md | 4 ++-- docs/agents/planning-pipeline.md | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.claude/skills/to-issues/SKILL.md b/.claude/skills/to-issues/SKILL.md index a7efb1c1..2b40ef7c 100644 --- a/.claude/skills/to-issues/SKILL.md +++ b/.claude/skills/to-issues/SKILL.md @@ -15,6 +15,8 @@ Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage lab 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. +In the planning pipeline (docs/agents/planning-pipeline.md) you run after the PRD merges, so read the merged PRD at docs/planning//prd.md — reference that folder, not the planning branch, which is deleted on merge. + ### 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. diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index a68b254a..ff73a3c5 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -1,6 +1,6 @@ --- 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. +description: Turn the current conversation context into a PRD. By default commits it to a branch under docs/planning/ via the planning pipeline; can also publish straight to the issue tracker for a quick one-off. Use when user wants to create a PRD from the current context. --- 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. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 89a25710..74c769dd 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,6 +1,6 @@ # Issue tracker: GitHub -Issues and PRDs for this repo live as GitHub issues in `Northeastern-Electric-Racing/Argos`. Use the `gh` CLI for all operations. +Issues for this repo live as GitHub issues in `Northeastern-Electric-Racing/Argos`; use the `gh` CLI for all operations. PRDs live on a branch under docs/planning/ by default (see planning-pipeline.md) — only quick one-off PRDs are filed as issues. ## Conventions @@ -28,7 +28,7 @@ These apply when an AI skill files an issue with `gh issue create`. They govern | Difficulty | `straightforward`, `medium`, `difficult` | | Workflow | `ai-workflow` | -Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — the skills, docs/agents, or the issue pipeline — not product code. Orthogonal to the area labels (a ticket is about the workflow or a product component, not both). Created via `gh label create`, like the triage roles. +Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — the skills, docs/agents, or the issue pipeline — not product code. It replaces the area label (a ticket is about the workflow or a product component, not both) but still takes a type and difficulty label where they fit. Created via `gh label create`, like the triage roles. The triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) are applied by `/triage`, not at creation time. See triage-labels.md. diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index f60291be..d5e38da7 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -27,7 +27,7 @@ Most of the time — any grill-with-docs or to-prd session for planning a featur | ADRs | docs/adr/ (see domain.md for the naming convention) | | Glossary updates | CONTEXT.md (root) | - is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/planning/668-build-planning-pipeline/. + is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/planning/668-build-planning-pipeline/. The branch is deleted on merge, but the folder persists. Planning artifacts are retained in-repo as durable history; they are not pruned after issues are created (stage-4 automation keys off the committed PRD path). From e3399d21d8edfaeadb0383383c32e1d95f5014b5 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 3 Jul 2026 21:42:30 +0000 Subject: [PATCH 09/15] #668 - PRD home is a GitHub issue; docs/planning is temporary staging Correct the model: a PRD's durable home is the tracker, not docs. The pipeline only stages it as a temporary file on the branch for PR review; on merge it graduates (published as an issue, broken into implementation tickets) and the file is deleted. ADRs and CONTEXT.md edits still persist. Drops the earlier "retained as durable history" framing. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/to-prd/SKILL.md | 6 +++--- docs/adr/0003-misc-planning-pipeline.md | 6 +++--- docs/agents/glossary.md | 2 +- docs/agents/issue-tracker.md | 2 +- docs/agents/planning-pipeline.md | 16 ++++++++-------- docs/planning/668-build-planning-pipeline/prd.md | 8 ++++---- docs/planning/README.md | 4 ++-- 7 files changed, 22 insertions(+), 22 deletions(-) diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index ff73a3c5..f35a54b5 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -1,6 +1,6 @@ --- name: to-prd -description: Turn the current conversation context into a PRD. By default commits it to a branch under docs/planning/ via the planning pipeline; can also publish straight to the issue tracker for a quick one-off. Use when user wants to create a PRD from the current context. +description: Turn the current conversation context into a PRD. A PRD's home is a GitHub issue; in the planning pipeline it's first staged as a temporary file on a branch for review, then graduates to an issue. Use when user wants to create a PRD from the current context. --- 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. @@ -19,9 +19,9 @@ Check with the user that these modules match their expectations. Check with the 3. Write the PRD using the template below. - By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, write the PRD to docs/planning//prd.md and commit it — reviewed in a draft PR, then broken into issues with `to-issues` after merge. is the planning ticket's number and kebab-title, the same as the branch name. + A PRD's home is a GitHub issue. By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, stage the PRD as docs/planning//prd.md and commit it so it's reviewed in a draft PR. After merge it graduates — published as an issue and broken into implementation tickets with `to-issues`, then the temporary file is deleted. is the planning ticket's number and kebab-title, the same as the branch name. - For a quick one-off not planned on a branch, publish the PRD straight to the issue tracker instead, applying the `ready-for-agent` triage label. + For a quick one-off not planned on a branch, skip the file and publish the PRD straight to the issue tracker, applying the `ready-for-agent` triage label. diff --git a/docs/adr/0003-misc-planning-pipeline.md b/docs/adr/0003-misc-planning-pipeline.md index 85c2cba5..067bda64 100644 --- a/docs/adr/0003-misc-planning-pipeline.md +++ b/docs/adr/0003-misc-planning-pipeline.md @@ -17,10 +17,10 @@ The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produced i ## Consequences -- PRDs and planning notes live in docs/planning//; ADRs still go in docs/adr/, and CONTEXT.md stays at the repo root. -- to-prd gains a pipeline mode: write the PRD to docs/planning// and commit it on the branch, rather than only filing an issue from chat. Standalone mode (no planning branch) still publishes to the tracker. +- A PRD's home stays a GitHub issue. The pipeline only stages it as a temporary file in docs/planning// so the plan is reviewable in the PR diff; on graduation it is published as an issue, broken into implementation tickets, and the file is deleted. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. +- to-prd gains a pipeline mode: stage the PRD as docs/planning//prd.md on the branch for review. Standalone mode (no planning branch) publishes straight to the tracker. - grill-with-docs's CONTEXT.md and ADR edits are committed to the planning branch and reviewed in the draft PR. -- Stage 4 (auto-create implementation issues on merge) is not built here — to-issues is still run manually after merge. Tracked as a follow-up. +- Stage 4 (graduate on merge: publish the PRD issue, create implementation tickets, delete the file) is not built here — done manually after merge. Tracked as a follow-up. - The ai-workflow label is created via gh label create and documented in docs/agents/issue-tracker.md. See docs/agents/planning-pipeline.md for the operative stages and conventions. diff --git a/docs/agents/glossary.md b/docs/agents/glossary.md index 3f2650df..e5e69fc7 100644 --- a/docs/agents/glossary.md +++ b/docs/agents/glossary.md @@ -14,7 +14,7 @@ Plain-language definitions of the workflow and agent-tooling terms used across t **PRD (Product Requirements Document).** A feature spec. The `to-prd` skill writes one; `to-issues` then breaks it into tracer-bullet tickets. -**Planning pipeline.** The default flow for planning a feature with grill-with-docs or to-prd: the session runs on a branch off develop and commits its artifacts (CONTEXT.md edits, ADRs, PRD) there, reviewed as a draft PR before issues are broken out — not lost to chat or committed straight to develop. See planning-pipeline.md; ADR 0003 records the decision. +**Planning pipeline.** The default flow for planning a feature with grill-with-docs or to-prd: the session runs on a branch off develop, committing its ADRs and glossary edits (which persist) and staging the PRD as a temporary file, all reviewed as a draft PR — not lost to chat or committed straight to develop. After merge the PRD graduates to a GitHub issue plus implementation tickets, and the file is deleted. See planning-pipeline.md; ADR 0003 records the decision. **Planning ticket.** Entry point of the planning pipeline: a ticket stating what's being researched or triaged — the question, not the answer — that names the branch. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 74c769dd..bb2e60aa 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,6 +1,6 @@ # Issue tracker: GitHub -Issues for this repo live as GitHub issues in `Northeastern-Electric-Racing/Argos`; use the `gh` CLI for all operations. PRDs live on a branch under docs/planning/ by default (see planning-pipeline.md) — only quick one-off PRDs are filed as issues. +Issues and PRDs for this repo live as GitHub issues in `Northeastern-Electric-Racing/Argos`; use the `gh` CLI for all operations. The planning pipeline stages a PRD as a temporary file on a branch for review before it graduates to an issue; see planning-pipeline.md. ## Conventions diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index d5e38da7..cb56ddf3 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -17,19 +17,19 @@ Most of the time — any grill-with-docs or to-prd session for planning a featur 3. **Push + review.** Push and open a draft PR against develop; reference the planning ticket in the PR body with "Closes #" so merging the reviewed plan closes it automatically. Humans review the artifacts in the diff before any issues are broken out. -4. **Merge to implementation issues.** On merge, break the PRD into tracer-bullet issues with to-issues, setting each issue's Parent to the planning ticket so they link back to it (the merge closes that ticket, but a closed issue is still a valid Parent reference). Manual after merge today; auto-creation on merge is a planned follow-up (keyed off the committed PRD path). +4. **Merge, then graduate.** On merge the PRD file lands in develop. Graduating it publishes the PRD as a GitHub issue and breaks it into tracer-bullet implementation tickets with to-issues, each issue's Parent set to the planning ticket so they link back (the merge closes that ticket, but a closed issue is still a valid Parent). Then delete docs/planning//prd.md — the PRD's home is the tracker, not docs. Manual after merge today; auto-graduation on merge is a planned follow-up (keyed off the committed PRD path). ## Where artifacts live -| Artifact | Location | -| --- | --- | -| PRD + planning notes | docs/planning// | -| ADRs | docs/adr/ (see domain.md for the naming convention) | -| Glossary updates | CONTEXT.md (root) | +| Artifact | Location | Lifetime | +| --- | --- | --- | +| PRD + planning notes | docs/planning// | temporary | +| ADRs | docs/adr/ (see domain.md for the naming convention) | persist | +| Glossary updates | CONTEXT.md (root) | persist | - is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/planning/668-build-planning-pipeline/. The branch is deleted on merge, but the folder persists. + is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/planning/668-build-planning-pipeline/. -Planning artifacts are retained in-repo as durable history; they are not pruned after issues are created (stage-4 automation keys off the committed PRD path). +The PRD file is a temporary home. It merges into develop as the record of what was reviewed, then graduation (stage 4) publishes the PRD as a GitHub issue, breaks it into implementation tickets, and deletes the file — the PRD's durable home is the tracker, not docs. The ADRs and CONTEXT.md edits are real docs and persist as normal. ## Conventions diff --git a/docs/planning/668-build-planning-pipeline/prd.md b/docs/planning/668-build-planning-pipeline/prd.md index 43243ab4..18b91a3c 100644 --- a/docs/planning/668-build-planning-pipeline/prd.md +++ b/docs/planning/668-build-planning-pipeline/prd.md @@ -8,7 +8,7 @@ As a maintainer running the AI issue-authoring flow (grill-with-docs to-prd to-i ## Solution -Move the planning flow onto a branch gated by PR review. A planning ticket opens the work and names the branch. The planning session commits its artifacts — CONTEXT.md edits, ADRs, and the PRD — to that branch. The branch is pushed and reviewed as a draft PR against develop. Only after merge are implementation issues broken out. A new ai-workflow label marks tickets about the workflow itself. +Move the planning flow onto a branch gated by PR review. A planning ticket opens the work and names the branch. The planning session commits its persistent artifacts — CONTEXT.md edits and ADRs — to that branch, and stages the PRD there as a temporary file. The branch is pushed and reviewed as a draft PR against develop. After merge the PRD graduates: published as a GitHub issue, broken into implementation tickets, and the file deleted. A new ai-workflow label marks tickets about the workflow itself. ## User Stories @@ -22,9 +22,9 @@ Move the planning flow onto a branch gated by PR review. A planning ticket opens ## Implementation Decisions -- Planning artifacts (PRD + notes) live in docs/planning//. ADRs stay in docs/adr/; CONTEXT.md stays at the root. +- A PRD's home is a GitHub issue. It's staged as a temporary file in docs/planning// only for PR review, then graduates to an issue on merge and the file is deleted. ADRs (docs/adr/) and CONTEXT.md edits persist. - Branch naming reuses the existing {issue}-{kebab-title} convention — no new namespace. -- to-prd gains a pipeline mode (commit PRD to the branch) alongside its existing standalone mode (file an issue). +- to-prd gains a pipeline mode (stage the PRD file for review) alongside its standalone mode (publish straight to the tracker). - grill-with-docs documents that, in pipeline mode, its edits are committed to the branch and reviewed in the PR. - ai-workflow is a workflow-group label, orthogonal to area labels, created via gh label create. - The decision is recorded in ADR 0003 (misc-planning-pipeline); operative mechanics live in docs/agents/planning-pipeline.md. @@ -36,7 +36,7 @@ This slice is documentation and skill guidance — no automated tests. Verificat ## Out of Scope -- Stage 4 automation: auto-creating implementation issues on merge (a GitHub Action or merge hook running to-issues, keyed off the PRD path). Tracked as a separate follow-up PR. Until then, to-issues is run manually after merge. +- Stage 4 automation: graduating on merge (publish the PRD issue, create implementation tickets, delete the file) via a GitHub Action or merge hook keyed off the PRD path. Tracked as a separate follow-up PR. Until then, graduation is done manually after merge. ## Further Notes diff --git a/docs/planning/README.md b/docs/planning/README.md index a2d9eb30..6bd6b91e 100644 --- a/docs/planning/README.md +++ b/docs/planning/README.md @@ -1,6 +1,6 @@ -# Planning artifacts +# Planning artifacts (temporary) -One folder per planning ticket, named for its branch (`-`). Each holds the committed output of a planning-pipeline session — the PRD and any planning notes — reviewed as a draft PR before implementation issues are broken out. +One folder per planning ticket, named for its branch (`-`). It temporarily holds a planning-pipeline session's PRD (and any notes) so the plan is reviewable in the draft PR. After merge the PRD graduates to a GitHub issue plus implementation tickets, and the folder is deleted — the PRD's durable home is the tracker, not docs. ``` docs/planning/ From e9bd3c0dfb019312a7783b5ccca31b51c4029364 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 3 Jul 2026 22:16:55 +0000 Subject: [PATCH 10/15] #668 - finalize model: PRD epic parents sub-tickets, 3 phased PRs, manual - Hierarchy: planning ticket -> PRD (epic issue, links to planning ticket) -> implementation tickets (Parent = the PRD). Only the PRD links to the planning ticket. - Three phased PRs: PRD under the planning ticket, issue drafts under the PRD, cleanup under the PRD. Branch reused off develop per phase. - Issue creation is a manual skill step; no merge automation, no reopening the planning ticket (automation deliberately rejected). - Updates planning-pipeline.md, ADR 0003, to-prd, to-issues, glossary, issue-tracker, README, and the #668 PRD. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/to-issues/SKILL.md | 4 +-- .claude/skills/to-prd/SKILL.md | 4 +-- docs/adr/0003-misc-planning-pipeline.md | 11 ++++--- docs/agents/glossary.md | 2 +- docs/agents/issue-tracker.md | 2 +- docs/agents/planning-pipeline.md | 31 ++++++++++++------- .../668-build-planning-pipeline/prd.md | 17 +++++----- docs/planning/README.md | 2 +- 8 files changed, 42 insertions(+), 31 deletions(-) diff --git a/.claude/skills/to-issues/SKILL.md b/.claude/skills/to-issues/SKILL.md index 2b40ef7c..2d147670 100644 --- a/.claude/skills/to-issues/SKILL.md +++ b/.claude/skills/to-issues/SKILL.md @@ -15,7 +15,7 @@ Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage lab 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. -In the planning pipeline (docs/agents/planning-pipeline.md) you run after the PRD merges, so read the merged PRD at docs/planning//prd.md — reference that folder, not the planning branch, which is deleted on merge. +In the planning pipeline (docs/agents/planning-pipeline.md) the source is the PRD at docs/planning//prd.md, and the PRD is published as an epic issue that parents these tickets. You draft the tickets as local files under that folder for review in a phase-2 PR (under the PRD), then create them on the tracker after it merges — reference the folder, not the branch, which is recreated per phase. ### 2. Explore the codebase (optional) @@ -57,7 +57,7 @@ For each approved slice, publish a new issue to the issue tracker. Use the issue Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field. -When breaking out a planning-pipeline PRD (docs/planning//prd.md), set the Parent of every spawned issue to the planning ticket the branch is named for, even though the immediate source is the PRD file, so the issues link back to it. +When breaking out a planning-pipeline PRD (docs/planning//prd.md), set the Parent of every spawned issue to the PRD's epic issue — not the planning ticket. The epic is what links back to the planning ticket; the sub-tickets hang off the epic. ## Parent diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index f35a54b5..c34b51fe 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -1,6 +1,6 @@ --- name: to-prd -description: Turn the current conversation context into a PRD. A PRD's home is a GitHub issue; in the planning pipeline it's first staged as a temporary file on a branch for review, then graduates to an issue. Use when user wants to create a PRD from the current context. +description: Turn the current conversation context into a PRD. A PRD's home is a GitHub epic issue that parents the implementation tickets; in the planning pipeline it's first staged as a temporary file on a branch for review, then published as that epic. Use when user wants to create a PRD from the current context. --- 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. @@ -19,7 +19,7 @@ Check with the user that these modules match their expectations. Check with the 3. Write the PRD using the template below. - A PRD's home is a GitHub issue. By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, stage the PRD as docs/planning//prd.md and commit it so it's reviewed in a draft PR. After merge it graduates — published as an issue and broken into implementation tickets with `to-issues`, then the temporary file is deleted. is the planning ticket's number and kebab-title, the same as the branch name. + A PRD's home is a GitHub epic issue that parents the implementation tickets. By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, stage the PRD as docs/planning//prd.md and commit it (phase 1, PR under the planning ticket) so it's reviewed in a draft PR. Once that PR is approved and merged, publish the PRD as the epic issue and link it to the planning ticket; to-issues then handles the child tickets (phase 2). is the planning ticket's number and kebab-title, the same as the branch name. For a quick one-off not planned on a branch, skip the file and publish the PRD straight to the issue tracker, applying the `ready-for-agent` triage label. diff --git a/docs/adr/0003-misc-planning-pipeline.md b/docs/adr/0003-misc-planning-pipeline.md index 067bda64..84f1b307 100644 --- a/docs/adr/0003-misc-planning-pipeline.md +++ b/docs/adr/0003-misc-planning-pipeline.md @@ -12,15 +12,16 @@ The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produced i - Planning artifacts become reviewable git history. The PRD and any ADRs land in a PR diff teammates can comment on before the work fans out into issues. - A planning ticket gives the branch a tracked entry point, consistent with the existing {issue}-{kebab-title} branch convention — no new branch namespace to learn. -- Decoupling issue creation from the chat session is what makes stage-4 automation possible later: implementation issues can be generated from the merged PRD, keyed off its committed file path. +- Reviewing the plan before it fans out means the tickets that get created reflect an approved PRD, not a chat draft nobody signed off on. - The ai-workflow label gives meta-work (changes to the skills and docs/agents themselves) a first-class category, instead of mis-filing it under a product area label. ## Consequences -- A PRD's home stays a GitHub issue. The pipeline only stages it as a temporary file in docs/planning// so the plan is reviewable in the PR diff; on graduation it is published as an issue, broken into implementation tickets, and the file is deleted. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. -- to-prd gains a pipeline mode: stage the PRD as docs/planning//prd.md on the branch for review. Standalone mode (no planning branch) publishes straight to the tracker. -- grill-with-docs's CONTEXT.md and ADR edits are committed to the planning branch and reviewed in the draft PR. -- Stage 4 (graduate on merge: publish the PRD issue, create implementation tickets, delete the file) is not built here — done manually after merge. Tracked as a follow-up. +- Hierarchy: planning ticket → PRD (published as an epic issue that links to the planning ticket) → implementation tickets (Parent = the PRD). Only the PRD links to the planning ticket; the sub-tickets hang off the PRD. +- Three phases, each its own PR on a branch reused off develop: (1) PRD file, PR under the planning ticket; (2) implementation tickets drafted as local files, PR under the PRD; (3) delete the temporary files, PR under the PRD. +- Planning files (PRD + issue drafts) in docs/planning// are temporary — they exist for PR review and are deleted in phase 3, once the epic and child issues exist. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. +- to-prd gains a pipeline mode: stage the PRD as docs/planning//prd.md for review. to-issues drafts the sub-tickets as local files with Parent = the PRD. Standalone mode still publishes straight to the tracker. +- Issue creation is a manual skill step at each phase (to-prd publishes the epic, to-issues the children). No merge automation, and the planning ticket is not reopened — phase 1 runs under the planning ticket, phases 2 and 3 under the PRD. - The ai-workflow label is created via gh label create and documented in docs/agents/issue-tracker.md. See docs/agents/planning-pipeline.md for the operative stages and conventions. diff --git a/docs/agents/glossary.md b/docs/agents/glossary.md index e5e69fc7..f0b29d5e 100644 --- a/docs/agents/glossary.md +++ b/docs/agents/glossary.md @@ -14,7 +14,7 @@ Plain-language definitions of the workflow and agent-tooling terms used across t **PRD (Product Requirements Document).** A feature spec. The `to-prd` skill writes one; `to-issues` then breaks it into tracer-bullet tickets. -**Planning pipeline.** The default flow for planning a feature with grill-with-docs or to-prd: the session runs on a branch off develop, committing its ADRs and glossary edits (which persist) and staging the PRD as a temporary file, all reviewed as a draft PR — not lost to chat or committed straight to develop. After merge the PRD graduates to a GitHub issue plus implementation tickets, and the file is deleted. See planning-pipeline.md; ADR 0003 records the decision. +**Planning pipeline.** The default flow for planning a feature: on a branch, grill-with-docs commits its ADRs and glossary edits (which persist) and to-prd stages the PRD as a temporary file, all reviewed as a draft PR. The PRD is then published as an epic issue (linked to the planning ticket), and to-issues creates the implementation tickets as its children; the temporary files are deleted. Runs as three phased PRs — PRD, then issues, then cleanup — with issue creation done manually. See planning-pipeline.md; ADR 0003 records the decision. **Planning ticket.** Entry point of the planning pipeline: a ticket stating what's being researched or triaged — the question, not the answer — that names the branch. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index bb2e60aa..543c3f23 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,6 +1,6 @@ # Issue tracker: GitHub -Issues and PRDs for this repo live as GitHub issues in `Northeastern-Electric-Racing/Argos`; use the `gh` CLI for all operations. The planning pipeline stages a PRD as a temporary file on a branch for review before it graduates to an issue; see planning-pipeline.md. +Issues and PRDs for this repo live as GitHub issues in `Northeastern-Electric-Racing/Argos`; use the `gh` CLI for all operations. The planning pipeline stages a PRD as a temporary file on a branch for review before it's published as an epic issue; see planning-pipeline.md. ## Conventions diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index cb56ddf3..856c4db4 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -1,39 +1,46 @@ # Planning pipeline -The default way to plan a feature with grill-with-docs or to-prd: do it on a branch, not in chat or straight on develop, so its artifacts (CONTEXT.md edits, ADRs, the PRD) are saved, reviewed, and testable before anything lands on develop. Decision and rationale: ADR 0003. +The default way to plan a feature: grill on a branch, review the plan, then create the tickets — as reviewable git history and GitHub issues, not an ephemeral chat session. Decision and rationale: ADR 0003. ## When to use it Most of the time — any grill-with-docs or to-prd session for planning a feature. Skip only for trivial changes that need no planning session. -## Stages +## Hierarchy -1. **Planning ticket.** A lightweight ticket stating what's being researched or triaged — the question, not the answer. It's the entry point and names the branch. Title it as a normal imperative with no special prefix (e.g. "Build grill-with-docs into a planning pipeline"), the same as any other ticket. Apply the ai-workflow label if its subject is the AI dev workflow itself (the skills, docs/agents, the issue pipeline); otherwise label by product area. +- **Planning ticket** — the idea/question. Entry point; names the branch. +- **PRD** — the plan, published as an epic issue that links up to the planning ticket. Parent of the implementation tickets. +- **Implementation tickets** — tracer-bullet slices; each has Parent = the PRD, not the planning ticket. -2. **Planning session on a branch.** Branch from develop as {issue}-{kebab-title}; run grill-with-docs (and to-prd) against the ticket. Commit every artifact to the branch: - - CONTEXT.md edits at the repo root (glossary). - - New ADRs in docs/adr/. - - The PRD in docs/planning//prd.md, plus any planning notes in the same folder. +Only the PRD links to the planning ticket; everything else hangs off the PRD. -3. **Push + review.** Push and open a draft PR against develop; reference the planning ticket in the PR body with "Closes #" so merging the reviewed plan closes it automatically. Humans review the artifacts in the diff before any issues are broken out. +## Phases -4. **Merge, then graduate.** On merge the PRD file lands in develop. Graduating it publishes the PRD as a GitHub issue and breaks it into tracer-bullet implementation tickets with to-issues, each issue's Parent set to the planning ticket so they link back (the merge closes that ticket, but a closed issue is still a valid Parent). Then delete docs/planning//prd.md — the PRD's home is the tracker, not docs. Manual after merge today; auto-graduation on merge is a planned follow-up (keyed off the committed PRD path). +Each phase is its own PR against develop, on a branch reused per phase (recreate {issue}-{kebab-title} off develop after each merge). "Under X" means the PR references issue X. + +1. **PRD — PR under the planning ticket.** Run grill-with-docs (CONTEXT.md + ADR edits) and to-prd (PRD saved to docs/planning//prd.md). Review the plan in the draft PR. Once it's approved and merged, publish the PRD as an epic issue (to-prd) linked to the planning ticket. + +2. **Issues — PR under the PRD.** Draft the implementation tickets as local files under docs/planning// with to-issues. Review them in the draft PR. Once merged, create the child issues (to-issues) with Parent = the PRD. + +3. **Cleanup — PR under the PRD.** Delete the temporary planning files (PRD + issue drafts); the epic and its child issues are now the durable home. + +Creating the issues is a manual skill step at each phase (to-prd for the epic, to-issues for the children) — there is no merge automation, and the planning ticket is not reopened. ## Where artifacts live | Artifact | Location | Lifetime | | --- | --- | --- | -| PRD + planning notes | docs/planning// | temporary | +| PRD + issue drafts + notes | docs/planning// | temporary (deleted in phase 3) | | ADRs | docs/adr/ (see domain.md for the naming convention) | persist | | Glossary updates | CONTEXT.md (root) | persist | is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/planning/668-build-planning-pipeline/. -The PRD file is a temporary home. It merges into develop as the record of what was reviewed, then graduation (stage 4) publishes the PRD as a GitHub issue, breaks it into implementation tickets, and deletes the file — the PRD's durable home is the tracker, not docs. The ADRs and CONTEXT.md edits are real docs and persist as normal. +The planning files are temporary — they exist so the plan and the drafted tickets are reviewable in the diff, and are deleted in phase 3 once the epic and child issues exist on the tracker. The ADRs and CONTEXT.md edits are real docs and persist. ## Conventions -- **Branch:** {issue}-{kebab-title}, same as feature branches — no separate namespace. +- **Branch:** {issue}-{kebab-title}, recreated off develop for each phase — no separate namespace. - **PR:** draft, against develop, per the repo PR convention. - **ai-workflow label:** marks tickets whose subject is the AI dev workflow itself, distinct from the product area labels. See issue-tracker.md for the palette. diff --git a/docs/planning/668-build-planning-pipeline/prd.md b/docs/planning/668-build-planning-pipeline/prd.md index 18b91a3c..8e88d9e4 100644 --- a/docs/planning/668-build-planning-pipeline/prd.md +++ b/docs/planning/668-build-planning-pipeline/prd.md @@ -8,7 +8,7 @@ As a maintainer running the AI issue-authoring flow (grill-with-docs to-prd to-i ## Solution -Move the planning flow onto a branch gated by PR review. A planning ticket opens the work and names the branch. The planning session commits its persistent artifacts — CONTEXT.md edits and ADRs — to that branch, and stages the PRD there as a temporary file. The branch is pushed and reviewed as a draft PR against develop. After merge the PRD graduates: published as a GitHub issue, broken into implementation tickets, and the file deleted. A new ai-workflow label marks tickets about the workflow itself. +Move the planning flow onto a branch gated by PR review, in three phased PRs. A planning ticket opens the work and names the branch. Phase 1 (PR under the planning ticket): grill-with-docs commits its persistent artifacts — CONTEXT.md edits and ADRs — and to-prd stages the PRD as a temporary file; after review and merge the PRD is published as an epic issue linked to the planning ticket. Phase 2 (PR under the PRD): to-issues drafts the implementation tickets as local files; after merge they're created as children of the epic. Phase 3 (PR under the PRD): delete the temporary files. Issue creation is manual at each phase — no merge automation, no reopening the planning ticket. A new ai-workflow label marks tickets about the workflow itself. ## User Stories @@ -17,15 +17,18 @@ Move the planning flow onto a branch gated by PR review. A planning ticket opens 3. As a maintainer, I want the PRD written to docs/planning// and committed, so that it is reviewable in the PR diff. 4. As a reviewer, I want the research, terminology, ADRs, and PRD in one draft PR, so that I can comment before any implementation issues exist. 5. As a maintainer, I want implementation issues broken out only after the PRD merges, so that issues never get ahead of the reviewed plan. -6. As a maintainer, I want an ai-workflow label, so that changes to the skills and docs/agents are a recognized category, not mis-filed under product areas. -7. As a contributor, I want the pipeline documented in docs/agents, so that I can follow it without reverse-engineering it from skills. +6. As a maintainer, I want the PRD published as an epic that parents the implementation tickets, and only the epic linking to the planning ticket, so that the hierarchy is one clean tree. +7. As a maintainer, I want an ai-workflow label, so that changes to the skills and docs/agents are a recognized category, not mis-filed under product areas. +8. As a contributor, I want the pipeline documented in docs/agents, so that I can follow it without reverse-engineering it from skills. ## Implementation Decisions -- A PRD's home is a GitHub issue. It's staged as a temporary file in docs/planning// only for PR review, then graduates to an issue on merge and the file is deleted. ADRs (docs/adr/) and CONTEXT.md edits persist. +- Hierarchy: planning ticket → PRD (an epic issue that links to the planning ticket) → implementation tickets (Parent = the PRD). Only the PRD links to the planning ticket. +- The PRD's home is a GitHub epic issue. It's staged as a temporary file in docs/planning// only for PR review, then published as the epic and the files deleted in phase 3. ADRs (docs/adr/) and CONTEXT.md edits persist. +- Three phases, each its own PR on a branch reused off develop: PRD (under the planning ticket), issue drafts (under the PRD), cleanup (under the PRD). +- Issue creation is manual at each phase (to-prd publishes the epic, to-issues the children). No merge automation, no reopening the planning ticket. - Branch naming reuses the existing {issue}-{kebab-title} convention — no new namespace. -- to-prd gains a pipeline mode (stage the PRD file for review) alongside its standalone mode (publish straight to the tracker). -- grill-with-docs documents that, in pipeline mode, its edits are committed to the branch and reviewed in the PR. +- to-prd gains a pipeline mode (stage the PRD file for review); to-issues drafts the sub-tickets as local files with Parent = the PRD. grill-with-docs's edits are committed to the branch and reviewed in the PR. - ai-workflow is a workflow-group label, orthogonal to area labels, created via gh label create. - The decision is recorded in ADR 0003 (misc-planning-pipeline); operative mechanics live in docs/agents/planning-pipeline.md. - The flow is named "planning pipeline," not "research pipeline" — it spans terminology, ADRs, and PRD authoring, not just research. @@ -36,7 +39,7 @@ This slice is documentation and skill guidance — no automated tests. Verificat ## Out of Scope -- Stage 4 automation: graduating on merge (publish the PRD issue, create implementation tickets, delete the file) via a GitHub Action or merge hook keyed off the PRD path. Tracked as a separate follow-up PR. Until then, graduation is done manually after merge. +- Merge automation. Issue creation stays a manual skill step at each phase; no GitHub Action or merge hook creates issues, and the planning ticket is never reopened. This was considered and deliberately rejected, not deferred. ## Further Notes diff --git a/docs/planning/README.md b/docs/planning/README.md index 6bd6b91e..77c8a299 100644 --- a/docs/planning/README.md +++ b/docs/planning/README.md @@ -1,6 +1,6 @@ # Planning artifacts (temporary) -One folder per planning ticket, named for its branch (`-`). It temporarily holds a planning-pipeline session's PRD (and any notes) so the plan is reviewable in the draft PR. After merge the PRD graduates to a GitHub issue plus implementation tickets, and the folder is deleted — the PRD's durable home is the tracker, not docs. +One folder per planning ticket, named for its branch (`-`). It temporarily holds a planning-pipeline session's PRD and the drafted implementation tickets so they're reviewable in a draft PR. Once the PRD is published as an epic issue and its child tickets are created, the folder is deleted (phase 3) — their durable home is the tracker, not docs. ``` docs/planning/ From 9effb2e5f6459622ce8c3ce407f67aa451b6dd3c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 3 Jul 2026 23:41:54 +0000 Subject: [PATCH 11/15] #668 - remove dogfood PRD; PRD files are temporary, not committed to develop The example prd.md contradicted the model (PRD files are temporary staging, deleted in phase 3). Drop it; README documents the folder convention with a generic layout instead. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .../668-build-planning-pipeline/prd.md | 46 ------------------- docs/planning/README.md | 5 +- 2 files changed, 3 insertions(+), 48 deletions(-) delete mode 100644 docs/planning/668-build-planning-pipeline/prd.md diff --git a/docs/planning/668-build-planning-pipeline/prd.md b/docs/planning/668-build-planning-pipeline/prd.md deleted file mode 100644 index 8e88d9e4..00000000 --- a/docs/planning/668-build-planning-pipeline/prd.md +++ /dev/null @@ -1,46 +0,0 @@ -# PRD: Branch-based planning pipeline - -Planning ticket: #668. This PRD is the prototype instance of the pipeline it describes — it was committed to this branch and reviewed before any implementation issues were broken out. - -## Problem Statement - -As a maintainer running the AI issue-authoring flow (grill-with-docs to-prd to-issues triage), I do all the research, terminology work, and PRD drafting inside one chat session and then file implementation issues straight from that chat. Nobody reviews the plan or the decisions before issues spawn, and the reasoning evaporates with the conversation — it never becomes durable, reviewable git history. Separately, a ticket whose subject is the AI dev workflow itself has no category; it gets mis-filed under a product area label. - -## Solution - -Move the planning flow onto a branch gated by PR review, in three phased PRs. A planning ticket opens the work and names the branch. Phase 1 (PR under the planning ticket): grill-with-docs commits its persistent artifacts — CONTEXT.md edits and ADRs — and to-prd stages the PRD as a temporary file; after review and merge the PRD is published as an epic issue linked to the planning ticket. Phase 2 (PR under the PRD): to-issues drafts the implementation tickets as local files; after merge they're created as children of the epic. Phase 3 (PR under the PRD): delete the temporary files. Issue creation is manual at each phase — no merge automation, no reopening the planning ticket. A new ai-workflow label marks tickets about the workflow itself. - -## User Stories - -1. As a maintainer, I want a planning ticket that states the open question, so that the branch and PR have a tracked entry point. -2. As a maintainer, I want the planning session's CONTEXT.md and ADR edits committed to the branch, so that the reasoning is durable git history instead of chat. -3. As a maintainer, I want the PRD written to docs/planning// and committed, so that it is reviewable in the PR diff. -4. As a reviewer, I want the research, terminology, ADRs, and PRD in one draft PR, so that I can comment before any implementation issues exist. -5. As a maintainer, I want implementation issues broken out only after the PRD merges, so that issues never get ahead of the reviewed plan. -6. As a maintainer, I want the PRD published as an epic that parents the implementation tickets, and only the epic linking to the planning ticket, so that the hierarchy is one clean tree. -7. As a maintainer, I want an ai-workflow label, so that changes to the skills and docs/agents are a recognized category, not mis-filed under product areas. -8. As a contributor, I want the pipeline documented in docs/agents, so that I can follow it without reverse-engineering it from skills. - -## Implementation Decisions - -- Hierarchy: planning ticket → PRD (an epic issue that links to the planning ticket) → implementation tickets (Parent = the PRD). Only the PRD links to the planning ticket. -- The PRD's home is a GitHub epic issue. It's staged as a temporary file in docs/planning// only for PR review, then published as the epic and the files deleted in phase 3. ADRs (docs/adr/) and CONTEXT.md edits persist. -- Three phases, each its own PR on a branch reused off develop: PRD (under the planning ticket), issue drafts (under the PRD), cleanup (under the PRD). -- Issue creation is manual at each phase (to-prd publishes the epic, to-issues the children). No merge automation, no reopening the planning ticket. -- Branch naming reuses the existing {issue}-{kebab-title} convention — no new namespace. -- to-prd gains a pipeline mode (stage the PRD file for review); to-issues drafts the sub-tickets as local files with Parent = the PRD. grill-with-docs's edits are committed to the branch and reviewed in the PR. -- ai-workflow is a workflow-group label, orthogonal to area labels, created via gh label create. -- The decision is recorded in ADR 0003 (misc-planning-pipeline); operative mechanics live in docs/agents/planning-pipeline.md. -- The flow is named "planning pipeline," not "research pipeline" — it spans terminology, ADRs, and PRD authoring, not just research. - -## Testing Decisions - -This slice is documentation and skill guidance — no automated tests. Verification is by review: the pipeline page, ADR, label-palette entry, and skill edits are read in the PR, and this PRD's own presence on the branch demonstrates the structure end-to-end. - -## Out of Scope - -- Merge automation. Issue creation stays a manual skill step at each phase; no GitHub Action or merge hook creates issues, and the planning ticket is never reopened. This was considered and deliberately rejected, not deferred. - -## Further Notes - -The pipeline is the default for planning a feature with grill-with-docs or to-prd, not a special case for big tickets; the ai-workflow label is an orthogonal marker for the subset whose subject is the workflow itself. diff --git a/docs/planning/README.md b/docs/planning/README.md index 77c8a299..64b9e5e4 100644 --- a/docs/planning/README.md +++ b/docs/planning/README.md @@ -4,8 +4,9 @@ One folder per planning ticket, named for its branch (`-`). ``` docs/planning/ -└── 668-build-planning-pipeline/ - └── prd.md +└── -/ # created during a planning session, deleted in phase 3 + ├── prd.md + └── issues/ # drafted implementation tickets (phase 2) ``` ADRs do not live here — they go in docs/adr/. Glossary updates go in the root CONTEXT.md. See docs/agents/planning-pipeline.md for the full flow and ADR 0003 for the decision. From 8e65c6a06fae7330c966b752074503f797b2ad91 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 4 Jul 2026 19:18:17 +0000 Subject: [PATCH 12/15] #668 - ai-workflow is a single label; drop the type/difficulty clause Keep difficulty/type label scope unchanged in this PR. ai-workflow is the one label for the new issue type, used in place of an area label. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- docs/agents/issue-tracker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 543c3f23..958e3649 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -28,7 +28,7 @@ These apply when an AI skill files an issue with `gh issue create`. They govern | Difficulty | `straightforward`, `medium`, `difficult` | | Workflow | `ai-workflow` | -Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — the skills, docs/agents, or the issue pipeline — not product code. It replaces the area label (a ticket is about the workflow or a product component, not both) but still takes a type and difficulty label where they fit. Created via `gh label create`, like the triage roles. +Apply `ai-workflow` when the ticket's subject is the AI dev workflow itself — the skills, docs/agents, or the issue pipeline — not product code. It's the single label for that type, used in place of an area label. Created via `gh label create`, like the triage roles. The triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) are applied by `/triage`, not at creation time. See triage-labels.md. From afcb9365468a714403b3b71455cf5743308e06c9 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 5 Jul 2026 16:34:20 +0000 Subject: [PATCH 13/15] #668 - PRD stays a PRD issue, not relabeled to an epic The PRD is published as a plain issue that parents the implementation tickets; drop the "epic" framing across planning-pipeline.md, ADR 0003, to-prd, to-issues, glossary, issue-tracker, and README. The pre-existing epic Type label is untouched. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/to-issues/SKILL.md | 4 ++-- .claude/skills/to-prd/SKILL.md | 4 ++-- docs/adr/0003-misc-planning-pipeline.md | 6 +++--- docs/agents/glossary.md | 2 +- docs/agents/issue-tracker.md | 2 +- docs/agents/planning-pipeline.md | 10 +++++----- docs/planning/README.md | 2 +- 7 files changed, 15 insertions(+), 15 deletions(-) diff --git a/.claude/skills/to-issues/SKILL.md b/.claude/skills/to-issues/SKILL.md index 2d147670..522a393f 100644 --- a/.claude/skills/to-issues/SKILL.md +++ b/.claude/skills/to-issues/SKILL.md @@ -15,7 +15,7 @@ Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage lab 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. -In the planning pipeline (docs/agents/planning-pipeline.md) the source is the PRD at docs/planning//prd.md, and the PRD is published as an epic issue that parents these tickets. You draft the tickets as local files under that folder for review in a phase-2 PR (under the PRD), then create them on the tracker after it merges — reference the folder, not the branch, which is recreated per phase. +In the planning pipeline (docs/agents/planning-pipeline.md) the source is the PRD at docs/planning//prd.md, and the PRD is published as an issue that parents these tickets. You draft the tickets as local files under that folder for review in a phase-2 PR (under the PRD), then create them on the tracker after it merges — reference the folder, not the branch, which is recreated per phase. ### 2. Explore the codebase (optional) @@ -57,7 +57,7 @@ For each approved slice, publish a new issue to the issue tracker. Use the issue Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field. -When breaking out a planning-pipeline PRD (docs/planning//prd.md), set the Parent of every spawned issue to the PRD's epic issue — not the planning ticket. The epic is what links back to the planning ticket; the sub-tickets hang off the epic. +When breaking out a planning-pipeline PRD (docs/planning//prd.md), set the Parent of every spawned issue to the PRD issue — not the planning ticket. The PRD is what links back to the planning ticket; the sub-tickets hang off the PRD. ## Parent diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index c34b51fe..b5c515c6 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -1,6 +1,6 @@ --- name: to-prd -description: Turn the current conversation context into a PRD. A PRD's home is a GitHub epic issue that parents the implementation tickets; in the planning pipeline it's first staged as a temporary file on a branch for review, then published as that epic. Use when user wants to create a PRD from the current context. +description: Turn the current conversation context into a PRD. A PRD's home is a GitHub issue that parents the implementation tickets; in the planning pipeline it's first staged as a temporary file on a branch for review, then published as that issue. Use when user wants to create a PRD from the current context. --- 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. @@ -19,7 +19,7 @@ Check with the user that these modules match their expectations. Check with the 3. Write the PRD using the template below. - A PRD's home is a GitHub epic issue that parents the implementation tickets. By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, stage the PRD as docs/planning//prd.md and commit it (phase 1, PR under the planning ticket) so it's reviewed in a draft PR. Once that PR is approved and merged, publish the PRD as the epic issue and link it to the planning ticket; to-issues then handles the child tickets (phase 2). is the planning ticket's number and kebab-title, the same as the branch name. + A PRD's home is a GitHub issue that parents the implementation tickets. By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, stage the PRD as docs/planning//prd.md and commit it (phase 1, PR under the planning ticket) so it's reviewed in a draft PR. Once that PR is approved and merged, publish the PRD as the issue and link it to the planning ticket; to-issues then handles the child tickets (phase 2). is the planning ticket's number and kebab-title, the same as the branch name. For a quick one-off not planned on a branch, skip the file and publish the PRD straight to the issue tracker, applying the `ready-for-agent` triage label. diff --git a/docs/adr/0003-misc-planning-pipeline.md b/docs/adr/0003-misc-planning-pipeline.md index 84f1b307..afde502a 100644 --- a/docs/adr/0003-misc-planning-pipeline.md +++ b/docs/adr/0003-misc-planning-pipeline.md @@ -17,11 +17,11 @@ The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produced i ## Consequences -- Hierarchy: planning ticket → PRD (published as an epic issue that links to the planning ticket) → implementation tickets (Parent = the PRD). Only the PRD links to the planning ticket; the sub-tickets hang off the PRD. +- Hierarchy: planning ticket → PRD (published as an issue that links to the planning ticket) → implementation tickets (Parent = the PRD). Only the PRD links to the planning ticket; the sub-tickets hang off the PRD. - Three phases, each its own PR on a branch reused off develop: (1) PRD file, PR under the planning ticket; (2) implementation tickets drafted as local files, PR under the PRD; (3) delete the temporary files, PR under the PRD. -- Planning files (PRD + issue drafts) in docs/planning// are temporary — they exist for PR review and are deleted in phase 3, once the epic and child issues exist. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. +- Planning files (PRD + issue drafts) in docs/planning// are temporary — they exist for PR review and are deleted in phase 3, once the PRD issue and child issues exist. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. - to-prd gains a pipeline mode: stage the PRD as docs/planning//prd.md for review. to-issues drafts the sub-tickets as local files with Parent = the PRD. Standalone mode still publishes straight to the tracker. -- Issue creation is a manual skill step at each phase (to-prd publishes the epic, to-issues the children). No merge automation, and the planning ticket is not reopened — phase 1 runs under the planning ticket, phases 2 and 3 under the PRD. +- Issue creation is a manual skill step at each phase (to-prd publishes the PRD issue, to-issues the children). No merge automation, and the planning ticket is not reopened — phase 1 runs under the planning ticket, phases 2 and 3 under the PRD. - The ai-workflow label is created via gh label create and documented in docs/agents/issue-tracker.md. See docs/agents/planning-pipeline.md for the operative stages and conventions. diff --git a/docs/agents/glossary.md b/docs/agents/glossary.md index f0b29d5e..ec7ea462 100644 --- a/docs/agents/glossary.md +++ b/docs/agents/glossary.md @@ -14,7 +14,7 @@ Plain-language definitions of the workflow and agent-tooling terms used across t **PRD (Product Requirements Document).** A feature spec. The `to-prd` skill writes one; `to-issues` then breaks it into tracer-bullet tickets. -**Planning pipeline.** The default flow for planning a feature: on a branch, grill-with-docs commits its ADRs and glossary edits (which persist) and to-prd stages the PRD as a temporary file, all reviewed as a draft PR. The PRD is then published as an epic issue (linked to the planning ticket), and to-issues creates the implementation tickets as its children; the temporary files are deleted. Runs as three phased PRs — PRD, then issues, then cleanup — with issue creation done manually. See planning-pipeline.md; ADR 0003 records the decision. +**Planning pipeline.** The default flow for planning a feature: on a branch, grill-with-docs commits its ADRs and glossary edits (which persist) and to-prd stages the PRD as a temporary file, all reviewed as a draft PR. The PRD is then published as an issue (linked to the planning ticket) that parents the implementation tickets, which to-issues creates as its children; the temporary files are deleted. Runs as three phased PRs — PRD, then issues, then cleanup — with issue creation done manually. See planning-pipeline.md; ADR 0003 records the decision. **Planning ticket.** Entry point of the planning pipeline: a ticket stating what's being researched or triaged — the question, not the answer — that names the branch. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 958e3649..f3c6c000 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,6 +1,6 @@ # Issue tracker: GitHub -Issues and PRDs for this repo live as GitHub issues in `Northeastern-Electric-Racing/Argos`; use the `gh` CLI for all operations. The planning pipeline stages a PRD as a temporary file on a branch for review before it's published as an epic issue; see planning-pipeline.md. +Issues and PRDs for this repo live as GitHub issues in `Northeastern-Electric-Racing/Argos`; use the `gh` CLI for all operations. The planning pipeline stages a PRD as a temporary file on a branch for review before it's published as an issue; see planning-pipeline.md. ## Conventions diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index 856c4db4..dba45faf 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -9,7 +9,7 @@ Most of the time — any grill-with-docs or to-prd session for planning a featur ## Hierarchy - **Planning ticket** — the idea/question. Entry point; names the branch. -- **PRD** — the plan, published as an epic issue that links up to the planning ticket. Parent of the implementation tickets. +- **PRD** — the plan, published as an issue that links up to the planning ticket. Parent of the implementation tickets. - **Implementation tickets** — tracer-bullet slices; each has Parent = the PRD, not the planning ticket. Only the PRD links to the planning ticket; everything else hangs off the PRD. @@ -18,13 +18,13 @@ Only the PRD links to the planning ticket; everything else hangs off the PRD. Each phase is its own PR against develop, on a branch reused per phase (recreate {issue}-{kebab-title} off develop after each merge). "Under X" means the PR references issue X. -1. **PRD — PR under the planning ticket.** Run grill-with-docs (CONTEXT.md + ADR edits) and to-prd (PRD saved to docs/planning//prd.md). Review the plan in the draft PR. Once it's approved and merged, publish the PRD as an epic issue (to-prd) linked to the planning ticket. +1. **PRD — PR under the planning ticket.** Run grill-with-docs (CONTEXT.md + ADR edits) and to-prd (PRD saved to docs/planning//prd.md). Review the plan in the draft PR. Once it's approved and merged, publish the PRD as an issue (to-prd) linked to the planning ticket. 2. **Issues — PR under the PRD.** Draft the implementation tickets as local files under docs/planning// with to-issues. Review them in the draft PR. Once merged, create the child issues (to-issues) with Parent = the PRD. -3. **Cleanup — PR under the PRD.** Delete the temporary planning files (PRD + issue drafts); the epic and its child issues are now the durable home. +3. **Cleanup — PR under the PRD.** Delete the temporary planning files (PRD + issue drafts); the PRD issue and its child issues are now the durable home. -Creating the issues is a manual skill step at each phase (to-prd for the epic, to-issues for the children) — there is no merge automation, and the planning ticket is not reopened. +Creating the issues is a manual skill step at each phase (to-prd for the PRD issue, to-issues for the children) — there is no merge automation, and the planning ticket is not reopened. ## Where artifacts live @@ -36,7 +36,7 @@ Creating the issues is a manual skill step at each phase (to-prd for the epic, t is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/planning/668-build-planning-pipeline/. -The planning files are temporary — they exist so the plan and the drafted tickets are reviewable in the diff, and are deleted in phase 3 once the epic and child issues exist on the tracker. The ADRs and CONTEXT.md edits are real docs and persist. +The planning files are temporary — they exist so the plan and the drafted tickets are reviewable in the diff, and are deleted in phase 3 once the PRD issue and child issues exist on the tracker. The ADRs and CONTEXT.md edits are real docs and persist. ## Conventions diff --git a/docs/planning/README.md b/docs/planning/README.md index 64b9e5e4..68557688 100644 --- a/docs/planning/README.md +++ b/docs/planning/README.md @@ -1,6 +1,6 @@ # Planning artifacts (temporary) -One folder per planning ticket, named for its branch (`-`). It temporarily holds a planning-pipeline session's PRD and the drafted implementation tickets so they're reviewable in a draft PR. Once the PRD is published as an epic issue and its child tickets are created, the folder is deleted (phase 3) — their durable home is the tracker, not docs. +One folder per planning ticket, named for its branch (`-`). It temporarily holds a planning-pipeline session's PRD and the drafted implementation tickets so they're reviewable in a draft PR. Once the PRD is published as an issue and its child tickets are created, the folder is deleted (phase 3) — their durable home is the tracker, not docs. ``` docs/planning/ From 6df300686c4e4d84c58ab0df48fed5b1f542eabe Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 5 Jul 2026 18:09:25 +0000 Subject: [PATCH 14/15] #668 - ticket drafts live under a tickets/ subfolder of the PRD folder Rename the old issues/ subfolder to tickets/ and make explicit it sits under the folder named for the PRD. Updates README, planning-pipeline.md, to-issues, and ADR 0003. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/to-issues/SKILL.md | 2 +- docs/adr/0003-misc-planning-pipeline.md | 2 +- docs/agents/planning-pipeline.md | 4 ++-- docs/planning/README.md | 9 +++++---- 4 files changed, 9 insertions(+), 8 deletions(-) diff --git a/.claude/skills/to-issues/SKILL.md b/.claude/skills/to-issues/SKILL.md index 522a393f..31c34c0c 100644 --- a/.claude/skills/to-issues/SKILL.md +++ b/.claude/skills/to-issues/SKILL.md @@ -15,7 +15,7 @@ Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage lab 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. -In the planning pipeline (docs/agents/planning-pipeline.md) the source is the PRD at docs/planning//prd.md, and the PRD is published as an issue that parents these tickets. You draft the tickets as local files under that folder for review in a phase-2 PR (under the PRD), then create them on the tracker after it merges — reference the folder, not the branch, which is recreated per phase. +In the planning pipeline (docs/agents/planning-pipeline.md) the source is the PRD at docs/planning//prd.md, and the PRD is published as an issue that parents these tickets. You draft the tickets as local files under docs/planning//tickets/ for review in a phase-2 PR (under the PRD), then create them on the tracker after it merges — reference the folder, not the branch, which is recreated per phase. ### 2. Explore the codebase (optional) diff --git a/docs/adr/0003-misc-planning-pipeline.md b/docs/adr/0003-misc-planning-pipeline.md index afde502a..b1ca387b 100644 --- a/docs/adr/0003-misc-planning-pipeline.md +++ b/docs/adr/0003-misc-planning-pipeline.md @@ -19,7 +19,7 @@ The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produced i - Hierarchy: planning ticket → PRD (published as an issue that links to the planning ticket) → implementation tickets (Parent = the PRD). Only the PRD links to the planning ticket; the sub-tickets hang off the PRD. - Three phases, each its own PR on a branch reused off develop: (1) PRD file, PR under the planning ticket; (2) implementation tickets drafted as local files, PR under the PRD; (3) delete the temporary files, PR under the PRD. -- Planning files (PRD + issue drafts) in docs/planning// are temporary — they exist for PR review and are deleted in phase 3, once the PRD issue and child issues exist. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. +- Planning files (prd.md plus the ticket drafts under tickets/) in docs/planning// are temporary — they exist for PR review and are deleted in phase 3, once the PRD issue and child issues exist. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. - to-prd gains a pipeline mode: stage the PRD as docs/planning//prd.md for review. to-issues drafts the sub-tickets as local files with Parent = the PRD. Standalone mode still publishes straight to the tracker. - Issue creation is a manual skill step at each phase (to-prd publishes the PRD issue, to-issues the children). No merge automation, and the planning ticket is not reopened — phase 1 runs under the planning ticket, phases 2 and 3 under the PRD. - The ai-workflow label is created via gh label create and documented in docs/agents/issue-tracker.md. diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index dba45faf..c72cb1eb 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -20,7 +20,7 @@ Each phase is its own PR against develop, on a branch reused per phase (recreate 1. **PRD — PR under the planning ticket.** Run grill-with-docs (CONTEXT.md + ADR edits) and to-prd (PRD saved to docs/planning//prd.md). Review the plan in the draft PR. Once it's approved and merged, publish the PRD as an issue (to-prd) linked to the planning ticket. -2. **Issues — PR under the PRD.** Draft the implementation tickets as local files under docs/planning// with to-issues. Review them in the draft PR. Once merged, create the child issues (to-issues) with Parent = the PRD. +2. **Issues — PR under the PRD.** Draft the implementation tickets as local files under docs/planning//tickets/ with to-issues. Review them in the draft PR. Once merged, create the child issues (to-issues) with Parent = the PRD. 3. **Cleanup — PR under the PRD.** Delete the temporary planning files (PRD + issue drafts); the PRD issue and its child issues are now the durable home. @@ -30,7 +30,7 @@ Creating the issues is a manual skill step at each phase (to-prd for the PRD iss | Artifact | Location | Lifetime | | --- | --- | --- | -| PRD + issue drafts + notes | docs/planning// | temporary (deleted in phase 3) | +| PRD + ticket drafts | docs/planning// (prd.md + tickets/) | temporary (deleted in phase 3) | | ADRs | docs/adr/ (see domain.md for the naming convention) | persist | | Glossary updates | CONTEXT.md (root) | persist | diff --git a/docs/planning/README.md b/docs/planning/README.md index 68557688..831e3304 100644 --- a/docs/planning/README.md +++ b/docs/planning/README.md @@ -1,14 +1,15 @@ # Planning artifacts (temporary) -One folder per planning ticket, named for its branch (`-`). It temporarily holds a planning-pipeline session's PRD and the drafted implementation tickets so they're reviewable in a draft PR. Once the PRD is published as an issue and its child tickets are created, the folder is deleted (phase 3) — their durable home is the tracker, not docs. +One folder per PRD, named for it (`-`, the same slug as the planning ticket and branch). It temporarily holds the PRD and, under a `tickets/` subfolder, the drafted implementation tickets, so they're reviewable in a draft PR. Once the PRD is published as an issue and its child tickets are created, the folder is deleted (phase 3) — their durable home is the tracker, not docs. ``` docs/planning/ -└── -/ # created during a planning session, deleted in phase 3 +└── -/ # named for the PRD; created during a planning session, deleted in phase 3 ├── prd.md - └── issues/ # drafted implementation tickets (phase 2) + └── tickets/ # drafted implementation tickets (phase 2) + └── .md ``` ADRs do not live here — they go in docs/adr/. Glossary updates go in the root CONTEXT.md. See docs/agents/planning-pipeline.md for the full flow and ADR 0003 for the decision. -prd.md follows the template in the to-prd skill (.claude/skills/to-prd/SKILL.md). +prd.md follows the template in the to-prd skill (.claude/skills/to-prd/SKILL.md); the files under tickets/ follow the issue template in the to-issues skill. From 7eae9137944184b0eea96a2b629c7d51131bc39e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 5 Jul 2026 18:57:15 +0000 Subject: [PATCH 15/15] #668 - move planning artifacts to docs/prd//, tickets as flat files Rename docs/planning -> docs/prd. Proposed implementation tickets are one kebab-named file each directly in the PRD folder (no tickets/ subfolder), alongside prd.md. Updates README, planning-pipeline.md, ADR 0003, to-prd, and to-issues. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT --- .claude/skills/to-issues/SKILL.md | 4 ++-- .claude/skills/to-prd/SKILL.md | 2 +- docs/adr/0003-misc-planning-pipeline.md | 4 ++-- docs/agents/planning-pipeline.md | 8 ++++---- docs/planning/README.md | 15 --------------- docs/prd/README.md | 14 ++++++++++++++ 6 files changed, 23 insertions(+), 24 deletions(-) delete mode 100644 docs/planning/README.md create mode 100644 docs/prd/README.md diff --git a/.claude/skills/to-issues/SKILL.md b/.claude/skills/to-issues/SKILL.md index 31c34c0c..5c71f20e 100644 --- a/.claude/skills/to-issues/SKILL.md +++ b/.claude/skills/to-issues/SKILL.md @@ -15,7 +15,7 @@ Issue tracker conventions live in `docs/agents/issue-tracker.md`; the triage lab 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. -In the planning pipeline (docs/agents/planning-pipeline.md) the source is the PRD at docs/planning//prd.md, and the PRD is published as an issue that parents these tickets. You draft the tickets as local files under docs/planning//tickets/ for review in a phase-2 PR (under the PRD), then create them on the tracker after it merges — reference the folder, not the branch, which is recreated per phase. +In the planning pipeline (docs/agents/planning-pipeline.md) the source is the PRD at docs/prd//prd.md, and the PRD is published as an issue that parents these tickets. You draft the tickets as local files in docs/prd// — one kebab-named file per proposed ticket — for review in a phase-2 PR (under the PRD), then create them on the tracker after it merges. Reference the folder, not the branch, which is recreated per phase. ### 2. Explore the codebase (optional) @@ -57,7 +57,7 @@ For each approved slice, publish a new issue to the issue tracker. Use the issue Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field. -When breaking out a planning-pipeline PRD (docs/planning//prd.md), set the Parent of every spawned issue to the PRD issue — not the planning ticket. The PRD is what links back to the planning ticket; the sub-tickets hang off the PRD. +When breaking out a planning-pipeline PRD (docs/prd//prd.md), set the Parent of every spawned issue to the PRD issue — not the planning ticket. The PRD is what links back to the planning ticket; the sub-tickets hang off the PRD. ## Parent diff --git a/.claude/skills/to-prd/SKILL.md b/.claude/skills/to-prd/SKILL.md index b5c515c6..37c96109 100644 --- a/.claude/skills/to-prd/SKILL.md +++ b/.claude/skills/to-prd/SKILL.md @@ -19,7 +19,7 @@ Check with the user that these modules match their expectations. Check with the 3. Write the PRD using the template below. - A PRD's home is a GitHub issue that parents the implementation tickets. By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, stage the PRD as docs/planning//prd.md and commit it (phase 1, PR under the planning ticket) so it's reviewed in a draft PR. Once that PR is approved and merged, publish the PRD as the issue and link it to the planning ticket; to-issues then handles the child tickets (phase 2). is the planning ticket's number and kebab-title, the same as the branch name. + A PRD's home is a GitHub issue that parents the implementation tickets. By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, stage the PRD as docs/prd//prd.md and commit it (phase 1, PR under the planning ticket) so it's reviewed in a draft PR. Once that PR is approved and merged, publish the PRD as the issue and link it to the planning ticket; to-issues then handles the child tickets (phase 2). is the planning ticket's number and kebab-title, the same as the branch name. For a quick one-off not planned on a branch, skip the file and publish the PRD straight to the issue tracker, applying the `ready-for-agent` triage label. diff --git a/docs/adr/0003-misc-planning-pipeline.md b/docs/adr/0003-misc-planning-pipeline.md index b1ca387b..57d08ede 100644 --- a/docs/adr/0003-misc-planning-pipeline.md +++ b/docs/adr/0003-misc-planning-pipeline.md @@ -19,8 +19,8 @@ The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) produced i - Hierarchy: planning ticket → PRD (published as an issue that links to the planning ticket) → implementation tickets (Parent = the PRD). Only the PRD links to the planning ticket; the sub-tickets hang off the PRD. - Three phases, each its own PR on a branch reused off develop: (1) PRD file, PR under the planning ticket; (2) implementation tickets drafted as local files, PR under the PRD; (3) delete the temporary files, PR under the PRD. -- Planning files (prd.md plus the ticket drafts under tickets/) in docs/planning// are temporary — they exist for PR review and are deleted in phase 3, once the PRD issue and child issues exist. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. -- to-prd gains a pipeline mode: stage the PRD as docs/planning//prd.md for review. to-issues drafts the sub-tickets as local files with Parent = the PRD. Standalone mode still publishes straight to the tracker. +- Planning files (prd.md plus one kebab-named file per proposed ticket) in docs/prd// are temporary — they exist for PR review and are deleted in phase 3, once the PRD issue and child issues exist. ADRs (docs/adr/) and CONTEXT.md edits are real docs and persist. +- to-prd gains a pipeline mode: stage the PRD as docs/prd//prd.md for review. to-issues drafts the sub-tickets as local files in the same folder with Parent = the PRD. Standalone mode still publishes straight to the tracker. - Issue creation is a manual skill step at each phase (to-prd publishes the PRD issue, to-issues the children). No merge automation, and the planning ticket is not reopened — phase 1 runs under the planning ticket, phases 2 and 3 under the PRD. - The ai-workflow label is created via gh label create and documented in docs/agents/issue-tracker.md. diff --git a/docs/agents/planning-pipeline.md b/docs/agents/planning-pipeline.md index c72cb1eb..b4880f22 100644 --- a/docs/agents/planning-pipeline.md +++ b/docs/agents/planning-pipeline.md @@ -18,9 +18,9 @@ Only the PRD links to the planning ticket; everything else hangs off the PRD. Each phase is its own PR against develop, on a branch reused per phase (recreate {issue}-{kebab-title} off develop after each merge). "Under X" means the PR references issue X. -1. **PRD — PR under the planning ticket.** Run grill-with-docs (CONTEXT.md + ADR edits) and to-prd (PRD saved to docs/planning//prd.md). Review the plan in the draft PR. Once it's approved and merged, publish the PRD as an issue (to-prd) linked to the planning ticket. +1. **PRD — PR under the planning ticket.** Run grill-with-docs (CONTEXT.md + ADR edits) and to-prd (PRD saved to docs/prd//prd.md). Review the plan in the draft PR. Once it's approved and merged, publish the PRD as an issue (to-prd) linked to the planning ticket. -2. **Issues — PR under the PRD.** Draft the implementation tickets as local files under docs/planning//tickets/ with to-issues. Review them in the draft PR. Once merged, create the child issues (to-issues) with Parent = the PRD. +2. **Issues — PR under the PRD.** Draft the implementation tickets as local files in docs/prd// — one kebab-named file per proposed ticket — with to-issues. Review them in the draft PR. Once merged, create the child issues (to-issues) with Parent = the PRD. 3. **Cleanup — PR under the PRD.** Delete the temporary planning files (PRD + issue drafts); the PRD issue and its child issues are now the durable home. @@ -30,11 +30,11 @@ Creating the issues is a manual skill step at each phase (to-prd for the PRD iss | Artifact | Location | Lifetime | | --- | --- | --- | -| PRD + ticket drafts | docs/planning// (prd.md + tickets/) | temporary (deleted in phase 3) | +| PRD + ticket drafts | docs/prd// (prd.md + one file per proposed ticket) | temporary (deleted in phase 3) | | ADRs | docs/adr/ (see domain.md for the naming convention) | persist | | Glossary updates | CONTEXT.md (root) | persist | - is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/planning/668-build-planning-pipeline/. + is the planning ticket's number and kebab-title (the same string as the branch name), e.g. docs/prd/668-build-planning-pipeline/. The planning files are temporary — they exist so the plan and the drafted tickets are reviewable in the diff, and are deleted in phase 3 once the PRD issue and child issues exist on the tracker. The ADRs and CONTEXT.md edits are real docs and persist. diff --git a/docs/planning/README.md b/docs/planning/README.md deleted file mode 100644 index 831e3304..00000000 --- a/docs/planning/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Planning artifacts (temporary) - -One folder per PRD, named for it (`-`, the same slug as the planning ticket and branch). It temporarily holds the PRD and, under a `tickets/` subfolder, the drafted implementation tickets, so they're reviewable in a draft PR. Once the PRD is published as an issue and its child tickets are created, the folder is deleted (phase 3) — their durable home is the tracker, not docs. - -``` -docs/planning/ -└── -/ # named for the PRD; created during a planning session, deleted in phase 3 - ├── prd.md - └── tickets/ # drafted implementation tickets (phase 2) - └── .md -``` - -ADRs do not live here — they go in docs/adr/. Glossary updates go in the root CONTEXT.md. See docs/agents/planning-pipeline.md for the full flow and ADR 0003 for the decision. - -prd.md follows the template in the to-prd skill (.claude/skills/to-prd/SKILL.md); the files under tickets/ follow the issue template in the to-issues skill. diff --git a/docs/prd/README.md b/docs/prd/README.md new file mode 100644 index 00000000..891ab2d2 --- /dev/null +++ b/docs/prd/README.md @@ -0,0 +1,14 @@ +# Planning artifacts (temporary) + +One folder per PRD, named for it (`-`, the same slug as the planning ticket and branch). It temporarily holds the PRD plus the drafted implementation tickets — one kebab-named file per proposed ticket — so they're reviewable in a draft PR. Once the PRD is published as an issue and its child tickets are created, the folder is deleted (phase 3) — their durable home is the tracker, not docs. + +``` +docs/prd/ +└── -/ # named for the PRD; created during a planning session, deleted in phase 3 + ├── prd.md + └── .md # one file per proposed implementation ticket (phase 2) +``` + +ADRs do not live here — they go in docs/adr/. Glossary updates go in the root CONTEXT.md. See docs/agents/planning-pipeline.md for the full flow and ADR 0003 for the decision. + +prd.md follows the template in the to-prd skill (.claude/skills/to-prd/SKILL.md); each proposed-ticket file follows the issue template in the to-issues skill.