#668 - Branch-based planning pipeline and ai-workflow label

.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).
 
+## Planning pipeline
+
+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.
+
 </supporting-info>

.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) the source is the PRD at docs/prd/<ticket>/prd.md, and the PRD is published as an issue that parents these tickets. You draft the tickets as local files in docs/prd/<ticket>/ — 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)
 
 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.
@@ -55,6 +57,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/prd/<ticket>/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.
+
 <issue-template>
 ## Parent
 

.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. 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.
@@ -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.
+
+   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/<ticket>/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). <ticket> 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.
 
 <prd-template>
 

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`; 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
 

docs/adr/0003-misc-planning-pipeline.md

@@ -0,0 +1,27 @@
+# Branch-based planning pipeline for AI-authored issues
+
+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
+
+- 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
+
+- 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.
+- 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
+
+- 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 one kebab-named file per proposed ticket) in docs/prd/<ticket>/ 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/<ticket>/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.
+
+See docs/agents/planning-pipeline.md for the operative stages and conventions.

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.
+
+**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.
+
+**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.

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 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
 
@@ -26,13 +26,20 @@ 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 — 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.
 
 **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.

docs/agents/planning-pipeline.md

@@ -0,0 +1,47 @@
+# Planning pipeline
+
+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.
+
+## Hierarchy
+
+- **Planning ticket** — the idea/question. Entry point; names the branch.
+- **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.
+
+## Phases
+
+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/prd/<ticket>/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 in docs/prd/<ticket>/ — 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.
+
+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
+
+| Artifact | Location | Lifetime |
+| --- | --- | --- |
+| PRD + ticket drafts | docs/prd/<ticket>/ (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 |
+
+<ticket> 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.
+
+## Conventions
+
+- **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.
+
+See glossary.md for planning ticket, planning pipeline, PRD, and the triage roles.

docs/prd/README.md

@@ -0,0 +1,14 @@
+# Planning artifacts (temporary)
+
+One folder per PRD, named for it (`<issue>-<kebab-title>`, 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/
+└── <issue>-<kebab-title>/           # named for the PRD; created during a planning session, deleted in phase 3
+    ├── prd.md
+    └── <ticket-proposed-kebab>.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.