Per-plan PR model — each plan ships as its own stacked/parallel PR

[andrewemark]

Why this change: slowing down to speed up

We're introducing a deliberately more broken-out PR process — one PR per plan, each gated by /drvr:assess → /drvr:docs-artifacts → /drvr:open-pr — so we can review each plan's actual output in isolation and see where the agent's implementation or our planning falls short. A feature-level PR makes those gaps easy to miss; a per-plan PR forces them to the surface.

The eventual goal is to NOT need this much process. Once we trust the agent's planning + implementation cycle enough that per-plan review stops catching meaningful gaps, we can collapse this back toward fewer, larger PRs. Until then, slowing down here lets us:

• See where the agent under-specifies plans or over-builds implementations
• Revise the SDLC process itself based on real friction, not speculation
• Get features across the line in the architectural form we actually want, not the form that emerges from accumulated drift across one large PR

TL;DR: slowing down to speed up.

---

What this PR does

Restructures the SDLC post-implementation flow so each plan in a feature ships as its own pull request with self-contained PR-body documentation, instead of one feature-level PR at the end.

Mental model: DAG of bases (not a linear stack)

Each plan's PR Base Branch is derived from its depends_on:

• depends_on: [] → Base = feature parent (e.g. main). Independent plans get parallel PRs.
• depends_on: [N] → Base = upstream plan N's Feature Branch. Dependent plans get stacked PRs.
• depends_on: [N, M] → user picks one as the branch parent; others satisfied by interface contracts.

Plans can be implemented in any dependency-respecting order. Plan 8 before Plan 2 is fine if they're independent — both PRs target the feature parent in parallel.

Per-plan PR gate (REQUIRED before next plan)

Plan <name> bookkeeping complete
  → /drvr:assess <plan>           writes assessment/<plan>-test-curation.md
  → [/drvr:review <plan>]         only if assess found FAIL violations
  → /drvr:docs-artifacts <plan>   writes driver-docs/<plan>/* (PR body content)
  → /drvr:open-pr <plan>          push branch, gh pr create --base <plan's Base Branch>
  → THEN next unblocked plan

Each step is surfaced explicitly in sdlc-orchestration and implementation-guidance so the agent doesn't collapse the chain or skip ahead.

Per-plan handoff doc structure

driver-docs/
├── 00-feature-overview.md      # cross-plan rollup, updated as plans ship
├── 01-foo/
│   ├── feature-overview.md     # PR body — self-contained with Stack Position section
│   ├── architecture.md
│   ├── testing-guide.md
│   └── risk-assessment.md
└── 02-bar/
    └── ...

Each per-plan feature-overview.md has a mandatory Stack Position section (base/feature branch, upstream/downstream plans, link to cross-plan rollup) so a reviewer who hasn't seen the rest of the DAG can still evaluate the PR.

Edge cases handled

• Upstream merged before downstream PR opens — recorded Base Branch may be gone. /drvr:open-pr checks git ls-remote and asks the user which branch to target instead (usually the feature parent). The plan's recorded Base Branch is updated to match.
• Plans in different states simultaneously — phase detection scans per-plan via FEATURE_LOG.md events (pr_created_<plan>, pr_merged_<plan>, etc.). Plan 01 merged, Plan 02 in review, Plan 03 mid-implementation is a valid simultaneous state.

---

Files changed

File	What changed
CLAUDE.md	Lifecycle diagram, folder layout, DAG-of-bases mental model, per-plan principles
commands/feature.md	Collects feature parent branch + branch prefix at scaffold time (not a single feature branch)
skills/planning-guidance/SKILL.md	Per-plan Environment (Base/Feature branch from depends_on); PR Stack table in overview; branch confirmation in Step 4.5
skills/implementation-guidance/SKILL.md	Per-plan branch validation in pre-flight 2.3; Step 5.5 surfaces the per-plan gate (assess→docs→open-pr) explicitly
skills/sdlc-orchestration/SKILL.md	Per-plan gate transitions; per-plan FEATURE_LOG events; DAG-aware "next plan" hints (parallel vs stacked); per-plan post-PR phase detection
commands/assess.md	Scoped to one plan; output is assessment/<plan>-test-curation.md; gates /drvr:docs-artifacts <plan>
commands/docs-artifacts.md	Writes driver-docs/<plan>/* with mandatory Stack Position section; updates cross-plan rollup; gates /drvr:open-pr <plan>
commands/open-pr.md	Per-plan; base from plan Environment; prompts user for replacement base if recorded one was deleted by upstream merge

Stats: 8 files changed, +605 / −291

Test plan

This plugin can't be unit-tested end-to-end without running through a real feature, so the verification here is documentation review:

• The lifecycle diagram in CLAUDE.md matches the per-plan gate described in sdlc-orchestration
• planning-guidance Step 4.5 and Step 5 prescribe the same Base Branch derivation rule (from depends_on)
• implementation-guidance Step 5.5 names the same three gate commands (assess, docs-artifacts, open-pr) in the same order as sdlc-orchestration Bookkeeping → Per-Plan PR Gate
• commands/open-pr.md Step 5 correctly handles the merged-upstream case (asks user, updates plan Environment)
• PR body template in commands/docs-artifacts.md includes the Stack Position section as a required section
• After merge: run a small dogfood feature (2-3 plans, mix of independent + dependent) and confirm the agent surfaces each gate step without prompting

Out of scope (follow-ups if needed)

• Branch creation automation: implementation-guidance pre-flight 2.3 detects missing Feature Branch and suggests git checkout -b <branch> <base>, but doesn't run it. Could be automated later if we trust the convention.
• Rebase-on-upstream-merge automation: when an upstream merges while a downstream is in revision, the user handles the rebase. Could be helped by a future /drvr:rebase-on-upstream command.
• Cascade-check integration with stacked PRs: if Plan N's PR is revised in a way that changes its interface, downstream plans may need rebasing. The Loop Handling table flags this; the agent doesn't yet automate it.

🤖 Generated with Claude Code