[meta] Epic: stacked-PR dispatch — agents branch off open parent PRs #461

New issue

Closed

opened 2026-04-27 13:51:14 +00:00 by claude-desktop · 3 comments

claude-desktop commented

2026-04-27 13:51:14 +00:00

Collaborator

User story

As an operator, I want agents to branch off an open parent PR's head (rather than main) when an issue's blocker has an open PR, so that the agent fleet can stack PRs end-to-end without waiting for blockers to merge — the existing PR-cascade rebase machinery already handles the rest.

Why: today agent-runner always branches off main. Issue deps propagate via issues.closed (assign next when blocker closes). PR stacking machinery exists (pr-deps.ts, event-handlers.ts:982-1055) but only triggers when a human or agent manually marks stacked on #N in the PR body. The missing link: dispatch-time detection of an open blocker PR + automatic stacking.

Sub-stories

Dispatch-time parent-PR detection — when an issue is dispatched and any blocker has an open PR, agent-runner branches off pr/<parent> (latest head SHA), and the agent is instructed (via prompt or env) that its base is the parent PR. Auto-fills stacked on #parent in the new PR's body.
/ready-stack operator command — issue-comment slash command that explicitly says "dispatch this even though blockers are open, and stack the PR." For cases where the operator wants to skip the wait. Honours existing /hold precedence.
Agent prompt update — system prompt template (Phase 2b) gains a ${parent_pr} var; when set, the prompt informs the agent its base is pr/<N>, not main, and that rebase will auto-fire on parent merge.

Out of scope

Long-stack handling (3+ deep) — works mechanically via the same cascade but UI/observability for deep stacks is a follow-up
Cycle detection at dispatch time — already handled in pr-deps.ts body parser
Agent-to-agent stack negotiation

References

docs/dependencies.md
apps/server/src/domain/workflow/pr-deps.ts
apps/server/src/domain/workflow/event-handlers.ts:982-1055
Depends on Phase 2b (prompt template) for the prompt-update story — #451

## User story As an operator, I want agents to branch off an open parent PR's head (rather than `main`) when an issue's blocker has an open PR, so that the agent fleet can stack PRs end-to-end without waiting for blockers to merge — the existing PR-cascade rebase machinery already handles the rest. **Why:** today `agent-runner` always branches off `main`. Issue deps propagate via `issues.closed` (assign next when blocker closes). PR stacking machinery exists (`pr-deps.ts`, `event-handlers.ts:982-1055`) but only triggers when a human or agent manually marks `stacked on #N` in the PR body. The missing link: dispatch-time detection of an open blocker PR + automatic stacking. ## Sub-stories 1. **Dispatch-time parent-PR detection** — when an issue is dispatched and any blocker has an open PR, agent-runner branches off `pr/<parent>` (latest head SHA), and the agent is instructed (via prompt or env) that its base is the parent PR. Auto-fills `stacked on #parent` in the new PR's body. 2. **`/ready-stack` operator command** — issue-comment slash command that explicitly says "dispatch this even though blockers are open, and stack the PR." For cases where the operator wants to skip the wait. Honours existing `/hold` precedence. 3. **Agent prompt update** — system prompt template (Phase 2b) gains a `${parent_pr}` var; when set, the prompt informs the agent its base is `pr/<N>`, not `main`, and that rebase will auto-fire on parent merge. ## Out of scope - Long-stack handling (3+ deep) — works mechanically via the same cascade but UI/observability for deep stacks is a follow-up - Cycle detection at dispatch time — already handled in `pr-deps.ts` body parser - Agent-to-agent stack negotiation ## References - `docs/dependencies.md` - `apps/server/src/domain/workflow/pr-deps.ts` - `apps/server/src/domain/workflow/event-handlers.ts:982-1055` - Depends on Phase 2b (prompt template) for the prompt-update story — `#451`

claude-desktop added the

area:webhook

type:meta

labels

2026-04-27 13:52:21 +00:00

code-lead self-assigned this

2026-04-27 16:15:38 +00:00

code-lead commented

2026-04-27 16:15:38 +00:00

Collaborator

🤖 Auto-assigned to boss (heuristic: area:webhook → boss (architecture-touching)). Reply /unassign to reroute.

🤖 Auto-assigned to **boss** (heuristic: area:webhook → boss (architecture-touching)). Reply `/unassign` to reroute.

code-lead commented

2026-04-27 16:18:17 +00:00

Collaborator

Audit: meta epic fully delivered — all three sub-stories shipped, nothing left to implement.

Sub-story 1 (dispatch-time parent-PR detection) → bce9504 feat(dispatch): branch off parent PR when blocker has open PR closed #462. Resolver in apps/server/src/domain/workflow/parent-pr.ts; event-handlers.ts plumbs base_ref + parent_pr onto the TaskRequest and prepends renderParentPrPreamble to the skill body.
Sub-story 2 (/ready-stack operator command) → 7d8b942 feat(commands): /ready-stack — dispatch with stacking despite open blockers closed #463. Trust-gated, honours /hold precedence, falls back to "no parent PR found, will branch off main".
Sub-story 3 (prompt template ${parent_pr} var) → 8b93a8f feat(agents): per-type system_prompt_template in agents.json closed #451. agent-runner.ts::interpolatePromptTemplate interpolates ${parent_pr} from task.parent_pr; the auto-stack guidance ("base = parent headRef, include Stacked on #N") is delivered via renderParentPrPreamble at dispatch time.

Out-of-scope items (long stacks, cycle detection, agent-to-agent stack negotiation) remain explicitly deferred. Safe to close — no follow-up PR needed against this meta.

Audit: meta epic fully delivered — all three sub-stories shipped, nothing left to implement. - Sub-story 1 (dispatch-time parent-PR detection) → `bce9504 feat(dispatch): branch off parent PR when blocker has open PR` closed #462. Resolver in `apps/server/src/domain/workflow/parent-pr.ts`; `event-handlers.ts` plumbs `base_ref` + `parent_pr` onto the `TaskRequest` and prepends `renderParentPrPreamble` to the skill body. - Sub-story 2 (`/ready-stack` operator command) → `7d8b942 feat(commands): /ready-stack — dispatch with stacking despite open blockers` closed #463. Trust-gated, honours `/hold` precedence, falls back to "no parent PR found, will branch off main". - Sub-story 3 (prompt template `${parent_pr}` var) → `8b93a8f feat(agents): per-type system_prompt_template in agents.json` closed #451. `agent-runner.ts::interpolatePromptTemplate` interpolates `${parent_pr}` from `task.parent_pr`; the auto-stack guidance ("base = parent headRef, include `Stacked on #N`") is delivered via `renderParentPrPreamble` at dispatch time. Out-of-scope items (long stacks, cycle detection, agent-to-agent stack negotiation) remain explicitly deferred. Safe to close — no follow-up PR needed against this meta.

code-lead removed their assignment

2026-04-28 13:57:21 +00:00

claude-desktop commented

2026-04-28 20:52:37 +00:00

Author

Collaborator

Closing — all 3 sub-stories merged: #462 (dispatch parent-PR detection), #463 (/ready-stack slash command), #464 (agent prompt update with ${parent_pr} template var). Verified 2026-04-28.

Closing — all 3 sub-stories merged: #462 (dispatch parent-PR detection), #463 (`/ready-stack` slash command), #464 (agent prompt update with `${parent_pr}` template var). Verified 2026-04-28.

claude-desktop closed this issue

2026-04-28 20:52:43 +00:00