vinta-ai-workflows 0.6.1 → 0.7.0-alpha2

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md

@@ -19,8 +19,9 @@ The output is a worktree that is the **same shape as the main checkout** from th
 
 - A plan / spec that takes hours-to-days where parallel work in the main checkout would be disruptive (a long migration, a refactor, a feature you want to experiment on while still serving customer support out of `main`).
 - Two-or-more concurrent plans where each needs its own running app + own DB state.
+- **A lane pool for one plan** — [implement-plan](../implement-plan/SKILL.md) implements independent phases concurrently and calls this skill once per lane (plus once for an integration worktree). See **Provisioning a pool** below.
 - A risky migration where the user wants the migration to run against a forked DB, then walk the diff before promoting.
-- [implement-plan](../implement-plan/SKILL.md) Step 0 (c) — when the user opts in, that orchestrator runs this skill once before phase 1, captures the resulting path, and threads it through every subagent's prompt.
+- [implement-plan](../implement-plan/SKILL.md) Step 0 (c) — when the user opts in, that orchestrator runs this skill before the first phase (once for a sequential run, once per lane plus one integration worktree for a parallel run), captures the resulting paths, and threads each lane's through its own subagent prompts.
 
 ## When NOT to use
 
@@ -28,6 +29,19 @@ The output is a worktree that is the **same shape as the main checkout** from th
 - The project has no ignored runnable state (rare — usually means the project is so simple a worktree adds friction with no upside).
 - The user is on a filesystem that doesn't support symlinks (Windows non-NTFS volumes, some corporate fileshares). Fall back to copy-only and warn the user up front.
 
+## Provisioning a pool (several worktrees for one plan)
+
+A caller that needs N isolated lanes invokes this skill N times — once per lane, with distinct names (`plan-<id>-lane-1`, `plan-<id>-lane-2`, …, plus `plan-<id>-integ` for merges). Nothing about the flow changes per invocation, but four things must hold across them:
+
+1. **Names are the isolation key.** Every forked DB name, compose project name, redis index, and S3 prefix already derives from `<worktree-name>` — distinct names give distinct everything. Never provision two lanes with the same name.
+2. **Answer the interview once, reuse the answers.** The caller passes the same plan and the same strategy answers to every lane. Don't re-interview per lane.
+3. **Provision lanes concurrently when the caller asks for it** — the expensive part of a lane (dependency install or link, DB clone, summary write) shares nothing between lanes and should overlap. But **two steps must be serialized**, and skipping either corrupts something:
+   - **`git worktree add` itself.** Git rewrites `.git/worktrees/` metadata on every add, and concurrent adds against one repository clobber each other's entries. Add the worktrees one at a time, then do the per-lane work in parallel. This is forced by git, not a choice.
+   - **The DB template.** Create or refresh the template DB once, then let each lane clone from it — that clone is what makes N lanes cost N cheap copies instead of N full provisions.
+4. **Record a `reset_cmd`** for each forked DB (see the summary schema). A pooled lane gets reused for a later phase on a different base, and the caller must be able to return its DB to a fresh state without re-provisioning. A lane whose DBs have no `reset_cmd` is single-use — say so in the report so the caller re-provisions instead of reusing it.
+
+Disk is the real constraint: N lanes means N dep trees and N DB copies. Run the **Sanity checks** disk probe against `N ×` the estimate, not `1 ×`, and warn the caller before the first lane if the pool won't fit.
+
 ## Inputs (Step 0 — interview)
 
 Use `AskUserQuestion` for every finite-choice question. Open prose only when the answer is genuinely free-form.
@@ -344,11 +358,17 @@ state:
     strategy: fork | share | stub
     forked_name: <forked db name>   # null when share / stub
     connection_url_var: DATABASE_URL
+    reset_cmd: <shell command that returns this DB to the state of a fresh checkout>
+    # e.g. dropdb <forked> && createdb -T <template> <forked>
+    #      rm -f <path>/db.sqlite3 && <migrate cmd>
+    # null when the engine / setup has no safe reset — callers must then re-provision
+    # instead of reusing this worktree across a migration boundary.
   test_db:
     engine: ...
     strategy: fork | share
     forked_name: ...
     connection_url_var: TEST_DATABASE_URL
+    reset_cmd: <same idea, for the test DB>   # null when not resettable
   compose:
     project_name: <repo>_<worktree-name>
     network_strategy: per-worktree | shared-external | host
@@ -371,7 +391,9 @@ state:
     # claude-hook                 → in-process (claude-code) Layer A hook only (file tools)
     # claude-native-sandbox       → in-process (claude-code) Layer A hook + Layer B OS sandbox
     # null                        → tier=none (no guard wired)
-    deny: [<main-checkout-root>]   # subtree(s) made read-only inside the cage
+    deny: [<main-checkout-root>, <worktree-root>]   # subtree(s) made read-only inside the cage
+    # <worktree-root> is the dir that holds the worktrees — denying it blocks writes into
+    # SIBLING lanes when a pool is provisioned; the allow entry below re-opens only this one.
     allow: [<worktree-path>, <main-checkout-root>/.git, <.vinta-ai-workflows-dir>]  # writable exceptions
 notes: |
   <freeform — anything the user / agent should know>

package/skills/vinta-derive-skills/resources/plan-execution/README.md

@@ -3,7 +3,7 @@
 Source-of-truth fragments for the **plan-execution skill family** that
 `vinta-derive-skills` renders into a target project's `ai-tools/skills/`:
 
-- `implement-plan` (conductor) — parse → classify → resolve `WORKROOT` → per-phase loop → track → report.
+- `implement-plan` (conductor) — parse → classify → build the dependency graph → resolve a `WORKROOT` per lane → scheduler loop (several phases at a time) → wave integration → track → report.
 - `implement-phase` — compose prompt + pick model + spawn implementer (one phase).
 - `review-phase` — three-layer review + fix loop (shared by all three conductors).
 - `integrate-phase` — push + open PR via context file (commit-strategy-resolved).
@@ -31,12 +31,29 @@ Partials and shells are **not** `SKILL.md` files, so they legitimately keep `{{.
 
 ## The `WORKROOT` seam (why worktree branching is gone)
 
-The conductor resolves three values **once** (see `partials/worktree-seam.md#WORKROOT_RESOLUTION`) and passes them to every sub-skill as data:
+The conductor resolves three values **once per lane** (see `partials/worktree-seam.md#WORKROOT_RESOLUTION`) and passes them to every sub-skill as data:
 
 | Value | `use_worktree = false` | `use_worktree = true` |
 |---|---|---|
-| `WORKROOT` | `<main_checkout>` | `<worktree_path>` |
+| `WORKROOT` | `<main_checkout>` | `<worktree_path>` — this lane's, when a pool is provisioned |
 | `BASE_BRANCH` | `{{DEFAULT_BRANCH}}` | `<worktree_branch>` |
-| `SANDBOX_TIER` | `none` | `enforced` \| `none` (probed by prepare-worktree) |
+| `SANDBOX_TIER` | `none` | `enforced` \| `none` (probed by prepare-worktree, per lane) |
 
 Every `git` / lint / test / build call in every sub-skill uses `git -C <WORKROOT>` **uniformly** — no `if use_worktree` inside them. Only two genuine conditionals remain, each local and data-driven: the `SANDBOX_TIER`-gated spawn wrap in `implement-phase`, and the `WORKROOT != main_checkout`-gated stray-write check in `review-phase`.
+
+## The parallel-lanes seam (`partials/parallel-lanes.md`)
+
+The plan gives every phase a `**Depends on**:` line. The conductor turns those into a DAG and dispatches a phase the moment its dependencies are green and a lane is free. Six blocks:
+
+| Block | Consumed by | What it owns |
+|---|---|---|
+| `DAG_PARSE` | `implement-plan` Step 0 | graph build, wave derivation, cycle / unknown-id / file-overlap validation |
+| `LANE_WORKTREE_POOL` | `implement-plan` Step 0.5 | pool sizing + provisioning, lane reuse + DB reset, teardown; the hard refusal when worktrees are unavailable |
+| `LANE_TOPOLOGY` | `implement-plan` (linked, not included, from `integrate-phase`) | per-phase base branch from `depends_on`, `integ-{id}` merge bases, `wave-{N}` integration branches, merge-conflict handling |
+| `LANE_SCHEDULER` | `implement-plan` Step 1 | the dispatch loop, tie-breaking, failure containment, the pause gate under concurrency |
+| `TRACKING_DIR` | `implement-plan` | the `TRACKING_{plan-id}/` directory + its ownership rules |
+| `SIBLING_LANE_ISOLATION` | `worktree-seam.md#STRAY_WRITE_CHECK` → `review-phase` | the stray-write guard extended across sibling lanes |
+
+**Sequential execution is `max_parallel_lanes = 1`**, running the same blocks — there is no separate sequential code path to keep in sync.
+
+**Why tracking is a directory.** Lanes commit on branches that later merge. One shared file would conflict at every wave merge for no reason. `run.md` is conductor-owned, `phase-{id}.md` is written only by the lane that ran that phase, on that phase's own branch — so no two branches ever touch the same path and the merges are clean by construction.

package/skills/vinta-derive-skills/resources/plan-execution/partials/agent-models.md

@@ -1,16 +1,43 @@
-<!-- Partial: agent-models — resolves the `.vinta-ai-workflows.yaml` `agent_models` section (tier per role/task) to a concrete spawn model, and the mechanical-step delegation pattern. Blocks: TIER_RESOLVE (review-phase reviewer/fixer + implement-plan mechanical steps), MECHANICAL_DELEGATION (implement-plan worktree/integrate steps). The implementer model is NOT here — that stays plan-owned via model-pick. -->
+<!-- Partial: agent-models — resolves the `.vinta-ai-workflows.yaml` `agent_models` section (tier per role/task) to a concrete spawn model, the reviewer's tier-above-the-author derivation, and the mechanical-step delegation pattern. Blocks: TIER_RESOLVE (review-phase reviewer/fixer + implement-plan mechanical steps), MECHANICAL_DELEGATION (implement-plan worktree/integrate steps). The implementer model is NOT here — that stays plan-owned via model-pick. -->
 
 <!-- block-begin: TIER_RESOLVE -->
 ## Resolve an `agent_models` tier to a spawn model
 
 `.vinta-ai-workflows.yaml` may carry an `agent_models` section mapping a role/task (`reviewer`, `fixer`, `worktree_prep`, `integrate`) to a **tier** (1–4) into the same table the per-phase implementer suggestion uses — [`ai-tools/skills/plan-feature/resources/ai-models.yaml`](../plan-feature/resources/ai-models.yaml). `agent_models` is the **project default** for these roles; for `reviewer` / `fixer`, a plan phase's optional `**Review models**:` line may override the tier for that one phase (the caller resolves that precedence and hands this block the effective tier). The mechanical steps (`worktree_prep`, `integrate`) are never plan-named. To turn a tier into the model a spawn actually uses:
 
-1. Determine the **effective tier** for the role: for `reviewer` / `fixer`, a per-phase override the conductor passed wins over `agent_models.<role>`; for the mechanical steps, it's simply `agent_models.<role>`.
+1. Determine the **effective tier** for the role. For the mechanical steps it is simply `agent_models.<role>`. For `reviewer` / `fixer` there are now three sources, in this order:
+   1. a per-phase `**Review models**:` override the conductor passed;
+   2. **the cheapest reviewer on the plan's Crew table at or above the phase's tier** (see [Who reviews](#who-reviews-a-member-not-a-tier) below);
+   3. `agent_models.<role>`.
 2. **No effective tier (override absent AND key unset, or the whole `agent_models` section absent) → do not force a model.** Spawn with the runtime's default model (today's behavior). Skip the rest.
 3. Open [`ai-tools/skills/plan-feature/resources/ai-models.yaml`](../plan-feature/resources/ai-models.yaml), take that tier's `models`, **filter to the vendors the runtime actually exposes**, pick the cheapest/fastest survivor, and translate it to the runner's spawn form — the same resolution [implement-phase](../implement-phase/SKILL.md) runs for the implementer, only keyed by a config tier instead of a plan line.
 4. `ai-models.yaml` missing, or the tier has no runtime-available vendor → fall back to the runtime default and surface the fallback once. Never hard-fail a phase over a model-selection miss.
 
-Record the **model actually used** in tracking: for `reviewer` / `fixer`, alongside the review note; for the mechanical steps, in the phase's tracking row next to the branch/PR fields.
+### Who reviews: a member, not a tier
+
+**Reviewers are their own members on the plan's Crew table**, with `role: reviewer`, and they never take phases. That is what makes an agent reviewing its own work impossible rather than merely unlikely — and it replaces an earlier rule that resolved a reviewer *model* one tier above the author, which was a proxy for independence and failed in both directions: a phase covered by the top-tier implementer had nobody above it and fell back to being read at its own tier, and a tier says nothing about *who* once a member is a durable agent rather than a model id.
+
+Resolve it from the roster: the **cheapest reviewer at or above the phase's tier**. A reviewer's tier is a floor in the same way an implementer's is — it reads work at or below its own capability, never above it.
+
+Three consequences worth knowing:
+
+- **A reviewer is claimed, not borrowed.** It has one session ledger, so two reviews running as the same reviewer would collide over it; a phase whose reviewer is busy waits. That cannot deadlock — reviewers never take phases, so the wait is always on a review already running.
+- **A reviewer reads the lane it is reviewing**, uncommitted changes and all, so findings are fixed before the commit. It has no worktree of its own, and therefore keeps a session only when consecutive reviews land in the same lane.
+- **No reviewer on the roster → fall through to `agent_models.reviewer`**, cold, one session per phase. That is what every plan did before, and the one thing a roster-less plan leaves on the table.
+
+A plan with no **Crew** table skips this step entirely and resolves `agent_models.<role>` as it always did.
+
+### What `fixer` still governs
+
+`fixer` governs fewer rounds than it used to. A finding goes back to the phase's
+own implementer — the same agent, in the same session — which fixes at the tier
+of the crew member that took the phase
+because it *is* that member; `agent_models.fixer` applies to the cold cases
+only — a runtime that cannot continue a sub-agent, and the last round before
+giving up, which is deliberately handed to an agent that has not seen the work.
+See the fix loop in [review-phase](../review-phase/SKILL.md).
+
+Record the **model actually used** in tracking, **and which of the three sources it came from** — a review that quietly fell through to the project default because the roster had nobody above the author is a fact worth being able to read later. For `reviewer` / `fixer`, alongside the review note; for the mechanical steps, in the phase's tracking row next to the branch/PR fields.
 <!-- block-end: TIER_RESOLVE -->
 
 <!-- block-begin: MECHANICAL_DELEGATION -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/modular.md

@@ -1,26 +1,36 @@
-<!-- Partial: commit-strategy / modular-commits. Folds in the former implement-plan-template-modular-substitutions.md. Blocks consumed by implement-phase (PER_PHASE_COMMIT) + integrate-phase (BRANCH_NAMING, PR_OPEN_TIMING) + conductor (CHECKLIST). All git calls use `git -C <WORKROOT>`; the first executed phase branches off `<BASE_BRANCH>` — both resolved once by the conductor (see worktree-seam.md#WORKROOT_RESOLUTION). The rendering-guidance appendix at the bottom is read by derive-skills to resolve the {{MODULAR_*}} placeholders; it is NOT part of any shipped block. -->
+<!-- Partial: commit-strategy / modular-commits. Folds in the former implement-plan-template-modular-substitutions.md. Blocks consumed by implement-phase (PER_PHASE_COMMIT) + integrate-phase (BRANCH_NAMING, PR_OPEN_TIMING) + conductor (CHECKLIST). All git calls use `git -C <WORKROOT>`; each phase branches off its own dependency-derived `<phase.base_branch>` — all resolved by the conductor (see worktree-seam.md#WORKROOT_RESOLUTION + parallel-lanes.md#LANE_TOPOLOGY). The rendering-guidance appendix at the bottom is read by derive-skills to resolve the {{MODULAR_*}} placeholders; it is NOT part of any shipped block. -->
 
 <!-- block-begin: BRANCH_NAMING -->
 Branch naming: `plan/{plan-id-kebab}` (one branch for the whole plan — no per-phase suffix).
 
-**First executed phase** (branches from `<BASE_BRANCH>`, already made current by the conductor):
+**Sequential run** (`max_parallel_lanes = 1`) — every phase commits straight onto the plan branch:
 
 ```bash
-git -C <WORKROOT> checkout <BASE_BRANCH>
-git -C <WORKROOT> checkout -b plan/{plan-id-kebab}
+git -C <WORKROOT> checkout plan/{plan-id-kebab}     # created from <BASE_BRANCH> on the first phase
 # subagent's atomic unit commits land on this branch
 git -C <WORKROOT> push -u origin plan/{plan-id-kebab}
 ```
 
-**Subsequent phases** (stay on the same plan branch — no new branch):
+**Parallel run** — one branch cannot take concurrent writers, so each lane commits its atomic units on a **lane branch** and the conductor merges those into the plan branch at each wave boundary:
 
 ```bash
-git -C <WORKROOT> checkout plan/{plan-id-kebab}
-# subagent's atomic unit commits land on this branch
-git -C <WORKROOT> push origin plan/{plan-id-kebab}
+git -C <WORKROOT> checkout <phase.base_branch>
+git -C <WORKROOT> checkout -b plan/{plan-id-kebab}/lane-{phase.id}
+# subagent's atomic unit commits land on this lane branch
+git -C <WORKROOT> push -u origin plan/{plan-id-kebab}/lane-{phase.id}
 ```
 
-The branch carries every phase's commits in plan order. Reviewers read the commit log top-to-bottom as a table of contents of the implementation.
+then, once every phase at that wave is green, in the integration worktree:
+
+```bash
+git -C <integ.workroot> checkout plan/{plan-id-kebab}
+git -C <integ.workroot> merge --no-ff plan/{plan-id-kebab}/lane-{phase.id}   # once per lane, in plan order
+git -C <integ.workroot> push origin plan/{plan-id-kebab}
+```
+
+`--no-ff` is what preserves the atomic units: the plan branch keeps every individual unit commit, grouped by the merge commit that names its phase. `plan/{plan-id-kebab}` **is** the wave integration branch under this strategy — there is no separate `wave-{N}` branch. Reviewers still read the commit log top-to-bottom as a table of contents; parallel phases appear as adjacent groups rather than one flat sequence.
+
+**Never squash a lane merge.** Squashing collapses the unit commits this whole strategy exists to preserve.
 <!-- block-end: BRANCH_NAMING -->
 
 <!-- block-begin: PER_PHASE_COMMIT -->
@@ -72,24 +82,27 @@ Tests for a unit belong **in the same commit** as that unit. Never commit tests
 <!-- block-end: PER_PHASE_COMMIT -->
 
 <!-- block-begin: PR_OPEN_TIMING -->
-**PR opens once — after Phase 1 passes review.** Subsequent phases push their atomic unit commits to the same plan branch (`plan/{plan-id-kebab}`); the orchestrator re-runs [open-pr.sh](../open-pr-from-context/scripts/open-pr.sh) against the same plan-level prs-context file at `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md`. The script is idempotent for already-open PRs — it updates the body, appends new inline comments, and posts a `Phase {N} complete — pushed M commits` PR comment.
+**PR opens once — after the first phase passes review.** Subsequent phases land their atomic unit commits on the same plan branch (`plan/{plan-id-kebab}`) — directly when sequential, through a wave merge when parallel; the orchestrator re-runs [open-pr.sh](../open-pr-from-context/scripts/open-pr.sh) against the same plan-level prs-context file at `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md`. The script is idempotent for already-open PRs — it updates the body, appends new inline comments, and posts a `Phase {N} complete — pushed M commits` PR comment.
+
+Under a parallel run, the PR comment goes up **after the wave merge**, not when the lane branch is pushed — before the merge those commits are not on the branch the PR tracks.
 <!-- block-end: PR_OPEN_TIMING -->
 
 <!-- block-begin: CHECKLIST -->
 - [ ] Commit units listed upfront before any staging.
 - [ ] Each commit covers exactly one logical unit (no "and" in commit messages).
 - [ ] Tests landed in the same commit as the code they cover (never a separate test-only commit).
-- [ ] All unit commits pushed to `plan/{plan-id-kebab}` at end of phase.
+- [ ] All unit commits pushed at end of phase — to `plan/{plan-id-kebab}` when sequential, to `plan/{plan-id-kebab}/lane-{phase.id}` when parallel.
+- [ ] Parallel runs only: lane branch merged into `plan/{plan-id-kebab}` with `--no-ff` at the wave boundary; never squashed.
 <!-- block-end: CHECKLIST -->
 
 <!-- Single-line values (derive-skills substitutes these into the shells directly):
      BRANCH_PUSH_HEADING            = Push to plan branch
-     BRANCH_NAMING_PATTERN_SUMMARY  = plan branch (one branch for whole plan: `plan/{plan-id-kebab}`)
+     BRANCH_NAMING_PATTERN_SUMMARY  = plan branch (one branch for whole plan: `plan/{plan-id-kebab}`; parallel runs add per-lane branches `plan/{plan-id-kebab}/lane-{phase-id}` merged in at each wave boundary)
      PRS_CONTEXT_FILE_PATH          = a single `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md` file (one PR per plan, not per phase)
      TRACKING_BRANCH_FIELD          = top-level `plan_branch:` field
      TRACKING_PHASE_BRANCH_FIELD    = (empty — no per-phase branch under modular)
-     FINAL_REPORT_BRANCH_SUMMARY    = single plan branch `plan/{plan-id-kebab}` with commit log organized by phase
-     BRANCH_CHECKLIST_LINE          = Plan branch updated with phase commits; pushed. -->
+     FINAL_REPORT_BRANCH_SUMMARY    = single plan branch `plan/{plan-id-kebab}` with commit log organized by phase (parallel runs: plus the lane branches merged into it, per wave)
+     BRANCH_CHECKLIST_LINE          = Plan branch updated with phase commits (directly, or via the lane branch's wave merge); pushed. -->
 
 <!-- ===================================================================== -->
 <!-- rendering-guidance (read by derive-skills; NOT shipped in any block)  -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/stacked.md

@@ -1,29 +1,22 @@
-<!-- Partial: commit-strategy / stacked-branches. Blocks consumed by implement-phase (PER_PHASE_COMMIT) + integrate-phase (BRANCH_NAMING, PR_OPEN_TIMING) + conductor (CHECKLIST). All git calls use `git -C <WORKROOT>`; the first executed phase branches off `<BASE_BRANCH>` — both resolved once by the conductor (see worktree-seam.md#WORKROOT_RESOLUTION). -->
+<!-- Partial: commit-strategy / stacked-branches. Blocks consumed by implement-phase (PER_PHASE_COMMIT) + integrate-phase (BRANCH_NAMING, PR_OPEN_TIMING) + conductor (CHECKLIST). All git calls use `git -C <WORKROOT>`; each phase branches off its own dependency-derived `<phase.base_branch>` — all resolved by the conductor (see worktree-seam.md#WORKROOT_RESOLUTION + parallel-lanes.md#LANE_TOPOLOGY). -->
 
 <!-- block-begin: BRANCH_NAMING -->
-Branch naming: `plan/{plan-id-kebab}/phase-{phase.id}` (one branch + one PR per phase, stacked).
+Branch naming: `plan/{plan-id-kebab}/phase-{phase.id}` (one branch + one PR per phase, stacked on its **dependencies** rather than on plan order).
 
-**First executed phase** (branches from `<BASE_BRANCH>`, already made current by the conductor):
+Each phase branches from `<phase.base_branch>` — the branch the conductor computed from that phase's `**Depends on**:` set (see [Lane branch topology](../implement-plan/SKILL.md#lane-branch-topology)): `<BASE_BRANCH>` for a phase with no dependencies, the single dependency's phase branch for one, `plan/{plan-id-kebab}/integ-{phase.id}` for several. The conductor creates the branch when it assigns the phase to a lane:
 
 ```bash
-git -C <WORKROOT> checkout <BASE_BRANCH>
+git -C <WORKROOT> checkout <phase.base_branch>
 git -C <WORKROOT> checkout -b plan/{plan-id-kebab}/phase-{phase.id}
 # subagent's commits land on this branch
 git -C <WORKROOT> push -u origin plan/{plan-id-kebab}/phase-{phase.id}
 ```
 
-**Subsequent phases** (stacked on the previous phase's branch):
+A chain-shaped plan reproduces the classic stack exactly — each phase depends on the one before it, so `<phase.base_branch>` *is* the previous phase's branch. A plan with independent phases produces several stacks rooted at `<BASE_BRANCH>`, reunited by the wave integration branches.
 
-```bash
-git -C <WORKROOT> checkout plan/{plan-id-kebab}/phase-{prev.id}
-git -C <WORKROOT> checkout -b plan/{plan-id-kebab}/phase-{phase.id}
-git -C <WORKROOT> push -u origin plan/{plan-id-kebab}/phase-{phase.id}
-```
-
-**PR base per phase** (the `base` field written into the prs-context frontmatter — this is what `gh pr create --base` / `glab mr create --target-branch` opens the PR against; getting it wrong makes every stacked PR target `<BASE_BRANCH>` instead of its parent phase):
+**PR base per phase** (the `base` field written into the prs-context frontmatter — this is what `gh pr create --base` / `glab mr create --target-branch` opens the PR against; getting it wrong makes the PR diff include every upstream phase and the review unusable):
 
-- **First executed phase** → `base = <BASE_BRANCH>`.
-- **Subsequent phases** → `base = plan/{plan-id-kebab}/phase-{prev.id}` (the previous phase's branch, **not** `<BASE_BRANCH>`). The PR must open against its parent phase so the diff shows only this phase's changes and the stack reviews cleanly.
+- `base = <phase.base_branch>`, always. Never `<BASE_BRANCH>` for a phase that has dependencies.
 <!-- block-end: BRANCH_NAMING -->
 
 <!-- block-begin: PER_PHASE_COMMIT -->
@@ -38,14 +31,15 @@ One PR per phase — the [Open PR via context file](#open-pr-via-context-file) s
 <!-- block-end: PR_OPEN_TIMING -->
 
 <!-- block-begin: CHECKLIST -->
-<!-- stacked adds no extra commit-discipline checklist items beyond the branch line -->
+- [ ] Phase branch created from `<phase.base_branch>` (dependency-derived), not from plan order.
+- [ ] PR `base` in the prs-context frontmatter equals `<phase.base_branch>`.
 <!-- block-end: CHECKLIST -->
 
 <!-- Single-line values (derive-skills substitutes these into the shells directly):
      BRANCH_PUSH_HEADING            = Push stacked branch
-     BRANCH_NAMING_PATTERN_SUMMARY  = branch naming pattern (default: `plan/{plan-id-kebab}/phase-{phase-id}`)
+     BRANCH_NAMING_PATTERN_SUMMARY  = branch naming pattern (default: `plan/{plan-id-kebab}/phase-{phase-id}`, each based on its dependencies; wave integration branches `plan/{plan-id-kebab}/wave-{N}`)
      PRS_CONTEXT_FILE_PATH          = `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md`
      TRACKING_BRANCH_FIELD          = (empty — per-phase branch lives inline under TRACKING_PHASE_BRANCH_FIELD)
      TRACKING_PHASE_BRANCH_FIELD    = , branch, base
-     FINAL_REPORT_BRANCH_SUMMARY    = branches pushed (with bases, in stack order)
-     BRANCH_CHECKLIST_LINE          = Stacked branch created; pushed. -->
+     FINAL_REPORT_BRANCH_SUMMARY    = branches pushed (with bases, grouped by wave)
+     BRANCH_CHECKLIST_LINE          = Phase branch created from its dependency-derived base; pushed. -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/implementer-prompt.md

@@ -1,4 +1,4 @@
-<!-- Partial: implementer-prompt — the token-efficient per-phase prompt. FULL = the forward-implementation prompt used by implement-phase. INNER_OUTER_LOOP = the read→edit→inner→outer verification steps (1–6), reused verbatim by amend-plan's 4b (which appends its own amend-specific commit / no-push tail instead of the commit-strategy block). The {If run_options.use_worktree = true:} markers are runtime gates the agent reads at execution time; derive-skills strips them entirely when foundation_skills.prepare-worktree is disabled (use_worktree can only ever be false). -->
+<!-- Partial: implementer-prompt — the token-efficient per-phase prompt. FULL = the forward-implementation prompt used by implement-phase. INNER_OUTER_LOOP = the read→edit→inner→outer verification steps (1–6), reused verbatim by amend-plan's 4b (which appends its own amend-specific commit / no-push tail instead of the commit-strategy block). The {If run_options.use_worktree = true:} and {If run_options.parallel_phases = true:} markers are runtime gates the agent reads at execution time; derive-skills strips both entirely when foundation_skills.prepare-worktree is disabled (use_worktree can only ever be false, and parallel execution requires a worktree). -->
 
 <!-- block-begin: FULL -->
 ```
@@ -14,11 +14,18 @@ every lint / test / build / migrate call runs there.
   `<WORKROOT>` is an isolated git worktree — do NOT touch the main checkout; its DB,
   env, and compose stack are intentionally separated. See `<WORKROOT>/WORKTREE.md` for
   what's forked vs shared (deps, dev DB, test DB, compose project name, env file).
-  {If run_options.sandbox_tier = enforced:} Writes to the main checkout are OS-blocked —
-  if you see `Operation not permitted` / `EROFS` on a write, you used a main-checkout
-  path by mistake; redo it against this worktree path.
-Branch base for this phase: `<phase-specific base>` — the orchestrator already created
-your phase branch there; commit straight to it.
+  {If run_options.sandbox_tier = enforced:} Writes outside this worktree are OS-blocked —
+  if you see `Operation not permitted` / `EROFS` on a write, you used a path outside
+  `<WORKROOT>` by mistake; redo it against this worktree path.
+{If run_options.parallel_phases = true:}
+  Other phases of this plan are being implemented **right now**, in sibling worktrees
+  next to yours. Never read or write any path outside `<WORKROOT>` — a sibling's tree is
+  mid-edit and mid-test, and a write there corrupts someone else's phase. Anything you
+  need from another phase is either already in your base branch or is a dependency the
+  plan failed to declare — say so in your report rather than reaching for it.
+Branch base for this phase: `<phase.base_branch>` — derived from this phase's
+**Depends on** set, not from plan order. The orchestrator already created your phase
+branch there; commit straight to it.
 
 ## Read first
 1. AGENTS.md — repo conventions.
@@ -32,8 +39,11 @@ your phase branch there; commit straight to it.
   Feature flag: `{flag-key}` — scope `{per-tenant|per-request}`, default `{false|true}`.
   Wire reads + writes per the plan's **Guiding Decisions** entry. Off-flag path = byte-for-byte pre-feature behavior.
 
-## What was already implemented in prior phases
-{Tracking file "Completed Phases" section. First executed phase: "Nothing yet — this is the first phase."}
+## What your phase builds on
+{The `phase-{id}.md` tracking summaries for this phase's transitive dependencies, in
+wave order. No dependencies: "Nothing yet — this phase starts from `<BASE_BRANCH>`."
+Sibling phases running in parallel are deliberately NOT listed: their work is not in
+your base branch and you must not code against it.}
 
 ## Your tasks (Phase {id} only)
 {phase.body verbatim, including Goal / Spec use-case / Feature flag / Changes / Tests / Acceptance lines}
@@ -57,7 +67,7 @@ Project skills available: {{PROJECT_SKILLS_LIST}}
 - Anything you couldn't do (with explanation).
 ```
 
-**Don't** dump the full plan into every prompt. Tracking summaries replace prior phases as context. Always include the **Goals + Non-goals** and **Guiding Decisions** sections plus the relevant **Data Model Changes** subsection — load-bearing decisions; phases reach back frequently.
+**Don't** dump the full plan into every prompt. Dependency-closure tracking summaries replace prior phases as context. Always include the **Goals + Non-goals** and **Guiding Decisions** sections plus the relevant **Data Model Changes** subsection — load-bearing decisions; phases reach back frequently.
 <!-- block-end: FULL -->
 
 <!-- block-begin: INNER_OUTER_LOOP -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/model-pick.md

@@ -1,19 +1,35 @@
 <!-- Partial: model-pick — the plan-owns-model-selection rules. Included by implement-phase; referenced (linked, not included) by amend-plan's Tier-4 rule. -->
 <!-- block-begin: MODEL_PICK -->
-## Pick the model from the plan's per-phase suggestion
+## Pick the model from the phase's crew assignment
 
-**The plan owns the *implementer* model — this skill does not re-derive tiers and doesn't assume a vendor.** Each phase carries a `**Suggested AI model**:` line listing one model per vendor. (The reviewer / fixer models default to `.vinta-ai-workflows.yaml`'s `agent_models` section, though a phase's optional `**Review models**:` line can override them for that phase; the mechanical-step models are `agent_models`-only. All of that is handled by `review-phase` / the conductor, not this implementer step.)
+**The plan owns the *implementer* model — this skill does not re-derive tiers and doesn't assume a vendor.** It owns it as a **roster**: the plan's **Crew** table names the agents it is staffed with and the tier each is staffed at, and every phase carries an `**Assigned to**:` line naming one of them.
 
 Pick:
 
-1. Read the line, parse out **all** vendor suggestions.
-2. **Filter to what's actually available in the runtime.** Different harnesses expose different sets.
-3. From the surviving suggestions, **pick the cheapest / fastest** the runner can use.
-4. Translate the chosen model to whatever form the runner's spawning tool expects.
-5. Phase suggestion straddles tiers → pick the higher-tier suggestion.
-6. Line missing / malformed → **ask the user**. Don't silently re-derive tier.
+1. Read the phase's `**Assigned to**:` line for the crew id, then that id's row in the plan's **Crew** table for the tier.
+2. Open the tier in [`ai-tools/skills/plan-feature/resources/ai-models.yaml`](../plan-feature/resources/ai-models.yaml) and take its models.
+3. **Filter to what's actually available in the runtime.** Different harnesses expose different sets.
+4. From the survivors, **pick the cheapest / fastest** the runner can use, and translate it to whatever form the runner's spawning tool expects.
+5. Tier with no runtime-available vendor → step one tier up and say so once. Never hard-fail a phase over a model-selection miss.
+6. `**Assigned to**:` missing or naming an agent the **Crew** table does not list → **ask the user**. Don't silently re-derive a tier from the phase body; the roster is the plan's arithmetic about how many agents this feature needs, and inventing a member changes it.
+
+**A legacy plan carries `**Suggested AI model**:` and no Crew table.** Read the tier straight off that line and continue — same resolution, one less indirection. Don't invent a roster for it.
+
+### Reuse the agent the plan staffed
+
+**A crew member is an agent, and it is still alive.** If this member has already taken a phase on this run, continue that sub-agent rather than spawning a new one: it is standing in the same worktree — a member keeps one for the whole run — and it already knows where this codebase keeps things, how its suite is run and what its conventions are. Rediscovering that is most of what a cold agent's first turn costs.
+
+Because it is new work, the continuation gets the phase's **full brief**, not a delta. Precede it with the re-orientation described in [Re-orienting a member after the reset](../implement-plan/SKILL.md#re-orienting-a-member-after-the-reset): same agent and same directory, whether the previous phase's work is in this tree, and which files differ from what it last saw.
+
+Start cold instead when any of these hold:
+
+- the member has taken no phase yet on this run;
+- **their previous phase failed** — that session is the context that failed with it;
+- the runtime cannot continue a finished sub-agent at all.
+
+Record which of those applied, so a phase that was unexpectedly slow can be read later without guessing.
 
 **Retry escalation (no user prompt):** the picked model fails on a clear capability gap → step **one tier up** and retry once. After Tier 4 fails, STOP. Update tracking with `❌`, post the agent's report to the user, ask how to proceed.
 
-Record the **model actually used** + the **plan's suggested tier** in tracking.
+Record the **model actually used**, the **crew member** it came from, and **whether that member is the one the plan assigned** — a phase run by a covering peer is the difference between a run that cost what the plan said and one that did not.
 <!-- block-end: MODEL_PICK -->