#668 - Branch-based planning pipeline and ai-workflow label by bracyw · Pull Request #669 · Northeastern-Electric-Racing/Argos

bracyw · 2026-06-25T17:51:08Z

Closes #668 (stages 1-3).

Moves the AI issue-authoring flow onto a branch gated by PR review: a planning ticket opens the work, the grilling session commits its artifacts (CONTEXT.md edits, ADRs, PRD) to the branch, and the branch is reviewed before implementation issues are broken out. Named "planning pipeline" since it spans research, terminology, ADRs, and PRD authoring — not just research.

Changes

ADR 0003 (misc-planning-pipeline) records the decision and rationale.
docs/agents/planning-pipeline.md documents stages 1-3, artifact locations, and conventions.
docs/planning/ home + README; the Build grill-with-docs into a branch-based planning-to-issues pipeline #668 PRD lives there as the prototype instance (dogfood).
ai-workflow label added to the palette in issue-tracker.md as a workflow-group label, orthogonal to area labels; glossary terms added.
Pipeline-mode guidance added to grill-with-docs and to-prd; pointer in CLAUDE.md.

Out of scope

Stage 4 automation (auto-create issues on merge) — separate follow-up PR; to-issues is run manually after merge for now.

🤖 Generated with Claude Code

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

…itle shape, on-develop guard, drop stale label notes

…ets section

TheJeffreyKuo · 2026-07-03T20:17:24Z

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


Instead of just one area label, maybe also a type and difficulty label

Talked this through and decided to keep ai-workflow as a single label for this issue type (used in place of an area label), and not attach type/difficulty to it.

It also surfaced a broader question we don't want to settle inside this PR: whether preset difficulty labels (straightforward/medium/difficult) earn their keep at all, vs. having the assignee estimate effort when they pick up a ticket. That's out of scope here — parked as its own planning ticket rather than expanding this one. So no label changes beyond adding ai-workflow.

Generated by Claude Code

TheJeffreyKuo · 2026-07-03T20:17:34Z

-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.
+
+   By default, work through the planning pipeline (docs/agents/planning-pipeline.md): on a branch off develop, write the PRD to docs/planning/<ticket>/prd.md and commit it — reviewed in a draft PR, then broken into issues with `to-issues` after merge. <ticket> is the planning ticket's number and kebab-title, the same as the branch name.


Description up top still says publish to the issue tracker, skill selection only reads the description so it might skip this skill

Fixed. The frontmatter description now leads with the pipeline — a PRD's home is a GitHub issue that parents the implementation tickets, staged as a temporary file on a branch for review then published as that issue. So skill selection reads the pipeline default, not just "publish to the tracker."

Generated by Claude Code

TheJeffreyKuo · 2026-07-03T20:17:44Z


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


Line 3 still says PRDs live as GitHub issues, contradicts the planning-pipeline default

Resolved — we went back and forth on this one. Landing point: PRDs do live as GitHub issues — a PRD issue that parents the implementation tickets (it stays a PRD, not relabeled to an epic). docs/prd// is only temporary staging so the PRD is reviewable in the diff before it's published, then deleted. Line 3 now says that, so the contradiction's gone.

Generated by Claude Code

TheJeffreyKuo · 2026-07-03T20:17:54Z


 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/<ticket>/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.


Branch is deleted after merge, maybe say the folder name instead

Fixed — to-issues points at the docs/prd// folder as the source instead of the branch, since the branch is recreated per phase. Sub-tickets are drafted there as one kebab-named file each, and their Parent is set to the PRD issue (the PRD is what links back to the planning ticket).

Generated by Claude Code

- 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/<ticket>/ (branch is deleted on merge); define <ticket> as the folder name, not branch Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

bracyw · 2026-07-03T20:22:48Z

Addressed all four review comments in 7dcaba8:

issue-tracker line 3: PRDs live under docs/planning by default now, only quick one-offs are filed as issues.
issue-tracker ai-workflow: workflow tickets still take a type and difficulty label.
to-prd frontmatter description: mentions the branch/pipeline default so skill selection won't skip it.
to-issues: reads the merged PRD from docs/planning//, and is defined as the folder name since the branch is deleted on merge.

Generated by Claude Code

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

…nual - 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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

…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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

… 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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

bracyw · 2026-07-05T19:02:04Z

Superseding my earlier summary — the design moved a lot since then, so that comment is stale. Final state:

Hierarchy: planning ticket → PRD (a plain issue that parents the implementation tickets — stays a PRD, not relabeled to an epic) → sub-tickets whose Parent is the PRD. Only the PRD links to the planning ticket.
Three phased PRs on a branch reused off develop: PRD (under the planning ticket), then ticket drafts (under the PRD), then cleanup (under the PRD).
Artifacts live temporarily in docs/prd// — prd.md plus one kebab-named file per proposed ticket — reviewed in the diff, deleted in phase 3. ADRs and CONTEXT.md edits persist.
Issue creation is a manual skill step at each phase; no merge automation, no reopening the planning ticket.
ai-workflow is the single label for the new issue type. The broader difficulty-label rethink is parked as its own planning ticket, out of scope here.

All four review threads addressed and replied to individually.

Generated by Claude Code

claude added 2 commits June 25, 2026 17:50

bracyw changed the title ~~#668 - Branch-based research pipeline and ai-workflow label~~ #668 - Branch-based planning pipeline and ai-workflow label Jun 25, 2026

#668 - clarify the planning flow starts with grill-with-docs

a010c4c

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

bracyw marked this pull request as ready for review June 25, 2026 20:14

bracyw requested a review from TheJeffreyKuo June 25, 2026 20:14

claude and others added 4 commits June 25, 2026 22:48

#668 - tighten planning-pipeline docs and skill prose

6e2fa39

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4jsfko5DsXeEQh6erhHrT

#668 - address PR review: parent link, ticket close, PRD retention, t…

8f29477

…itle shape, on-develop guard, drop stale label notes

#668 - review nits: tighten agent-skills sentence, move Planning tick…

14f655f

…ets section

TheJeffreyKuo reviewed Jul 3, 2026

View reviewed changes

claude added 7 commits July 3, 2026 21:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

#668 - Branch-based planning pipeline and ai-workflow label#669
bracyw wants to merge 15 commits into
developfrom
claude/grill-docs-build-pipeline-75qv28

bracyw commented Jun 25, 2026 •

edited

Loading

Uh oh!

TheJeffreyKuo Jul 3, 2026

Uh oh!

bracyw Jul 4, 2026

Uh oh!

TheJeffreyKuo Jul 3, 2026

Uh oh!

bracyw Jul 5, 2026

Uh oh!

TheJeffreyKuo Jul 3, 2026

Uh oh!

bracyw Jul 5, 2026

Uh oh!

TheJeffreyKuo Jul 3, 2026

Uh oh!

bracyw Jul 5, 2026

Uh oh!

bracyw commented Jul 3, 2026

Uh oh!

bracyw commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## 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.


		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/<ticket>/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.

Uh oh!

Conversation

bracyw commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Out of scope

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bracyw commented Jul 3, 2026

Uh oh!

bracyw commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bracyw commented Jun 25, 2026 •

edited

Loading