vinta-ai-workflows 0.2.0-alpha3 → 0.2.0-alpha5

package/skills/vinta-derive-skills/resources/{amend-plan-template.md → plan-execution/shell/amend-plan-template.md}

@@ -5,7 +5,7 @@ description: Adjust an existing implementation plan in `{{PLAN_DIR}}/` after imp
 
 # Amend Plan
 
-Revise a plan in [`{{PLAN_DIR}}/`]({{PLAN_DIR}}/) after work has begun. Companion to [implement-plan](../implement-plan/SKILL.md): same agents, same review gates, same PR-context flow — but the orchestrator's job here is **history rewriting** instead of forward execution.
+Revise a plan in [`{{PLAN_DIR}}/`]({{PLAN_DIR}}/) after work has begun. Companion conductor to [implement-plan](../implement-plan/SKILL.md): it reuses the same sub-skills ([implement-phase](../implement-phase/SKILL.md) for the body change, [review-phase](../review-phase/SKILL.md) for the gates) — but the orchestrator's job here is **history rewriting** instead of forward execution.
 
 The flow is destructive (force-push). Every modification is gated on user confirmation. Default disposition for any ambiguous case is "stop and ask" — never force-push without an explicit per-branch `Confirm` from the user.{{COMMIT_STRATEGY_REFUSAL_BLOCK}}
 
@@ -22,6 +22,7 @@ The flow is destructive (force-push). Every modification is gated on user confir
 - {{COAUTHOR_POLICY_BLOCK}}
 - Default branch: `{{DEFAULT_BRANCH}}`.
 - Branch naming convention (set by [implement-plan](../implement-plan/SKILL.md)): `plan/{plan-id-kebab}/phase-{phase.id}`.
+- **`WORKROOT`.** Resolve once, same as the [implement-plan Resolve WORKROOT step](../implement-plan/SKILL.md#step-05--resolve-workroot): the main checkout by default, or the plan's worktree when `run_options.use_worktree = true` in the tracking file. Every `git` call below runs with `git -C <WORKROOT>`; when no worktree is in play, `WORKROOT` is the main checkout and the commands read exactly as in-place git.
 
 ## When to use
 
@@ -48,7 +49,7 @@ The flow is destructive (force-push). Every modification is gated on user confir
 
 3. **Parse the plan.** Same structured fields as [implement-plan's "Extract structured fields" step](../implement-plan/SKILL.md#step-0--locate--parse-plan): plan id, **Goals + Non-goals** / **Guiding Decisions** / **Data Model Changes** / phase records from **Phased Rollout** / **Risk & Rollout Notes** through **Touch List**.
 
-4. **Read the tracking file** `{{PLAN_DIR}}/TRACKING_{plan-id}.md` if present. Its `Completed Phases` section tells you which phase branches were pushed and which model + base were used. If absent → `git branch -a | grep plan/{plan-id-kebab}` to enumerate pushed phase branches.
+4. **Read the tracking file** `{{PLAN_DIR}}/TRACKING_{plan-id}.md` if present. Its `Completed Phases` section tells you which phase branches were pushed, which model + base were used, and the `run_options` (including worktree state → `WORKROOT`). If absent → `git -C <WORKROOT> branch -a | grep plan/{plan-id-kebab}` to enumerate pushed phase branches.
 
 5. **Build a per-phase state map.** For every phase in the plan, record:
 
@@ -57,9 +58,9 @@ The flow is destructive (force-push). Every modification is gated on user confir
    | `phase.id`, `phase.title` | plan's **Phased Rollout** section |
    | `state` | one of `not-started` / `in-progress` / `implemented-not-merged` / `merged-to-default` |
    | `branch` | tracking file or git, pattern `plan/{plan-id-kebab}/phase-{id}` |
-   | `base` | tracking file or `git merge-base origin/<branch> <prev-branch>`; root phase bases on `{{DEFAULT_BRANCH}}` |
+   | `base` | tracking file or `git -C <WORKROOT> merge-base origin/<branch> <prev-branch>`; root phase bases on `{{DEFAULT_BRANCH}}` |
    | `pr_status` | `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{id}.md` frontmatter (`pending` / `published`) when the file exists |
-   | `merged_to_default` | `git branch --merged origin/{{DEFAULT_BRANCH}} | grep` against the branch |
+   | `merged_to_default` | `git -C <WORKROOT> branch --merged origin/{{DEFAULT_BRANCH}} | grep` against the branch |
 
    `merged-to-default = true` blocks any commit rewrite for that phase — see [Step 3 — Refuse force-pushes that can't work](#step-3--refuse-force-pushes-that-cant-work) below.
 
@@ -78,7 +79,7 @@ The flow is destructive (force-push). Every modification is gated on user confir
    | `guiding-decisions-change` cascading into | ≥ 50% of implemented phases |
    | Phases in `merged-to-default` (immutable, must be `append-new`) | ≥ 2, AND remaining work also rewrites earlier phases |
    | New body materially changes the data-model contract from **Data Model Changes** | rewrite of >2 phases hinges on it |
-   | Estimated touched LoC across rewrites | ≥ 70% of original implementation diff size (rough estimate via `git diff --stat <base>..<branch>` summed across affected branches) |
+   | Estimated touched LoC across rewrites | ≥ 70% of original implementation diff size (rough estimate via `git -C <WORKROOT> diff --stat <base>..<branch>` summed across affected branches) |
    | Multi-author phase branches in the rewrite queue | ≥ 1 (force-push erases collaborator local state) |
    | Approved PRs in the rewrite queue | ≥ 2 (re-review burden becomes non-trivial) |
 
@@ -141,13 +142,13 @@ Always the first write. Plan file is durable; commits get rewritten next.
 
 ## Step 2 — Build the rewrite queue
 
-For each phase classified as needing commit rewrites (`body-rewrite` for already-implemented phases, downstream phases for `insert-new` / `body-rewrite` / `section-2-decision-change`), build a queue ordered by branch stack depth: parent first, children after.
+For each phase classified as needing commit rewrites (`body-rewrite` for already-implemented phases, downstream phases for `insert-new` / `body-rewrite` / `guiding-decisions-change`), build a queue ordered by branch stack depth: parent first, children after.
 
 For each entry record:
 
 - `branch`, `base` (parent in the stack — may be `{{DEFAULT_BRANCH}}` or another phase branch).
 - `change_kind`: `amend-existing` (modify the phase body's effect on the diff) or `rebase-only` (parent moved, no body change for this phase).
-- `commits_to_amend`: list of SHAs the orchestrator may rewrite (look at `git log <base>..<branch>`).
+- `commits_to_amend`: list of SHAs the orchestrator may rewrite (look at `git -C <WORKROOT> log <base>..<branch>`).
 
 Phases in `not-started` state are deferred to [implement-plan](../implement-plan/SKILL.md) — not rewritten here.
 
@@ -163,7 +164,7 @@ Before any write to remote, **block on these conditions**:
 
 3. **Branch protection rules block force-push.** `gh api repos/{owner}/{repo}/branches/{branch}/protection` (or `glab` equivalent). If the branch is protected, force-push will fail noisily — surface the rule, stop.
 
-4. **Multiple authors on the branch.** `git log --pretty=format:%ae <base>..<branch> | sort -u | wc -l` > 1 → other developers committed too. Force-push erases their local state. Surface, require explicit `Yes, I've coordinated with <names>` confirmation.
+4. **Multiple authors on the branch.** `git -C <WORKROOT> log --pretty=format:%ae <base>..<branch> | sort -u | wc -l` > 1 → other developers committed too. Force-push erases their local state. Surface, require explicit `Yes, I've coordinated with <names>` confirmation.
 
 If any block triggers and the user can't dismiss it: stop. Don't proceed further. Tell the user the rewrite path is unavailable; suggest an `append-new` phase as the fallback.
 
@@ -174,14 +175,14 @@ For each entry in the rewrite queue, in stack order:
 ### 4a. Check out the branch
 
 ```bash
-git fetch origin
-git checkout {branch}
-git reset --hard origin/{branch}
+git -C <WORKROOT> fetch origin
+git -C <WORKROOT> checkout {branch}
+git -C <WORKROOT> reset --hard origin/{branch}
 ```
 
 ### 4b. For `change_kind = amend-existing` only — apply the body change
 
-Spawn an implementer subagent. Prompt shape (token-efficient, mirrors the [implement-plan "Prepare agent prompt" step](../implement-plan/SKILL.md#1a-prepare-agent-prompt-token-efficient)):
+Spawn an implementer subagent. The prompt mirrors [implement-phase](../implement-phase/SKILL.md#1-compose-the-agent-prompt-token-efficient) but records the change differently (new commit on top by default, never a push). Compose:
 
 ```
 You are amending {phase.id}: {phase.title} of plan {plan.id}.
@@ -189,10 +190,13 @@ You are amending {phase.id}: {phase.title} of plan {plan.id}.
 ## Repo
 {{PROJECT_NAME}} ({{STACK_SUMMARY}}).
 
+## Working location
+Work inside `<WORKROOT>`. `cd` into it before any command.
+
 ## Read first
 1. AGENTS.md — repo conventions.
 2. {{PLAN_DIR}}/{plan-filename}, the **Goals + Non-goals**, **Guiding Decisions**, and **Data Model Changes** sections, plus the rewritten phase body inside **Phased Rollout**.
-3. The current diff: `git diff {base}...HEAD` — what's already on this branch.
+3. The current diff: `git -C <WORKROOT> diff {base}...HEAD` — what's already on this branch.
 
 ## What changed in the plan (verbatim)
 {Diff between old phase body and new — produce via `diff <(old-body) <(new-body)`. Or, if the plan was rewritten in place, the new body verbatim with a note "this replaces what was here before".}
@@ -212,17 +216,19 @@ Use `git commit --amend` ONLY when:
 - The user explicitly authorized amend in Step 0.
 
 {{DEPENDENCY_LICENSE_BLOCK}}
+```
+
+Then splice in the shared inner/outer verification loop verbatim:
 
-## Working instructions (same loops as implement-plan)
-1. Read existing code paths your changes touch.
-2. Edit. Match existing patterns.
-3. Inner loop: `{{LINT_CMD}}` → {{NEW_TEST_CMD_PATTERN}} → scoped suite ({{SCOPED_TEST_PATTERN}}).
-4. Iterate 2–3 until green.
-5. Outer gate: `{{BUILD_CMD}}` AND `{{TEST_CMD}}`{{E2E_OUTER_GATE_LINE}}.
-6. Stage explicitly: `git add {{STAGE_PATTERN}}`.
-7. Commit. {{COMMIT_STYLE_LINE}}.
-8. {{COAUTHOR_INSTRUCTION_LINE}}
-9. **Do NOT push. Do NOT force-push.** Orchestrator owns the remote.
+<!-- include: partials/implementer-prompt.md#INNER_OUTER_LOOP -->
+
+…and close the prompt with the amend-specific staging tail:
+
+```
+7. Stage explicitly: `git add {{STAGE_PATTERN}}`.
+8. Commit. {{COMMIT_STYLE_LINE}}.
+9. {{COAUTHOR_INSTRUCTION_LINE}}
+10. **Do NOT push. Do NOT force-push.** The orchestrator owns the remote.
 
 ## Required output
 - Status: SUCCESS or FAILURE.
@@ -233,26 +239,26 @@ Use `git commit --amend` ONLY when:
 
 For `change_kind = rebase-only` (downstream phase whose parent moved): skip the agent. The work is purely git topology.
 
-### 4c. Run the three-layer review (same as implement-plan)
+### 4c. Run the three-layer review
 
-Same Layer 1 / 2 / 3 / fix-loop as the [implement-plan "Thorough review" step](../implement-plan/SKILL.md#1d-thorough-review). The reviewer agent gets the **new** phase body to walk against. Layer 2 walks: every "Changes" item in the new body, every "Tests" entry, the new acceptance line.
+Invoke [review-phase](../review-phase/SKILL.md) against the rewritten branch, passing the **new** phase body to walk against and `WORKROOT`. Layer 2 walks: every "Changes" item in the new body, every "Tests" entry, the new acceptance line.
 
-Skip Layer 3 only when `change_kind = rebase-only` (no body change → no compliance walk). Layers 1 + 2 still apply (verify the rebase didn't lose unrelated work).
+Skip this step only when `change_kind = rebase-only` (no body change → no compliance walk). Even then, spot-run review-phase's Layer 1 mechanical checks to verify the rebase didn't lose unrelated work.
 
 ### 4d. Rebase onto the (possibly-rewritten) parent
 
 ```bash
 # parent's tip may have moved if it was rewritten earlier in the queue.
-git fetch origin
-PARENT_TIP=$(git rev-parse origin/{base})
-git rebase $PARENT_TIP
+git -C <WORKROOT> fetch origin
+PARENT_TIP=$(git -C <WORKROOT> rev-parse origin/{base})
+git -C <WORKROOT> rebase $PARENT_TIP
 ```
 
 Conflicts:
 
-1. **Spawn a fixer subagent** with the conflict body + new phase body + parent's tip diff. Same agent type as the [implement-plan "Fix loop" subsection](../implement-plan/SKILL.md#fix-loop).
-2. Fixer resolves, runs inner + outer gate.
-3. Orchestrator continues the rebase: `git rebase --continue`.
+1. **Spawn a fixer subagent** with the conflict body + new phase body + parent's tip diff. Same fixer agent type as [review-phase](../review-phase/SKILL.md#fix-loop).
+2. Fixer resolves, runs inner + outer gate (in `<WORKROOT>`).
+3. Orchestrator continues the rebase: `git -C <WORKROOT> rebase --continue`.
 
 Repeat until the rebase finishes clean. If the fixer can't resolve after one retry → stop. Surface to user; do not push a half-rebased branch.
 
@@ -266,7 +272,7 @@ Repeat until the rebase finishes clean. If the fixer can't resolve after one ret
 On confirm:
 
 ```bash
-git push --force-with-lease origin {branch}
+git -C <WORKROOT> push --force-with-lease origin {branch}
 ```
 
 **Use `--force-with-lease`, not `--force`.** It refuses to overwrite if the remote moved since the last fetch — protects against another developer's pushes the orchestrator didn't see.
@@ -278,12 +284,12 @@ If `--force-with-lease` rejects: another developer pushed. Stop. Re-fetch, re-ap
 For the rewritten branch, look for `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md`:
 
 - **File missing** — skip; nothing to refresh.
-- **File `status: pending`** — rewrite the file to reflect new title / description / comments per the [prs-context-template](prs-context-template.md). Status stays `pending`. The user will publish later via [open-pr-from-context](../foundation-skills/open-pr-from-context/SKILL.md).
+- **File `status: pending`** — rewrite the file to reflect new title / description / comments per the [prs-context-template](../../prs-context-template.md). Status stays `pending`. The user will publish later via [open-pr-from-context](../open-pr-from-context/SKILL.md).
 - **File `status: published`** — the existing PR is auto-updated by the force-push (GitHub/GitLab pick up the new tip). But:
   - Inline comments may now reference SHAs that no longer exist. They'll appear as "outdated" in the PR UI.
-  - If the new diff has materially different comment-worthy spots, regenerate the `# Comments` block, set `status: pending`, and re-run [open-pr.sh](../foundation-skills/open-pr-from-context/scripts/open-pr.sh) on the file. The script reuses the existing PR, posts new comments. Old "outdated" comments stay visible in the PR for audit; that's the platform's behavior.
+  - If the new diff has materially different comment-worthy spots, regenerate the `# Comments` block, set `status: pending`, and re-run [open-pr.sh](../open-pr-from-context/scripts/open-pr.sh) on the file. The script reuses the existing PR, posts new comments. Old "outdated" comments stay visible in the PR for audit; that's the platform's behavior.
 
-When rewriting the `# Description` body, **honor `project.pr_template_paths`** from `.vinta-ai-workflows.yaml` — same rule as step 2 of the [implement-plan "Open PR via context file" step](../implement-plan/SKILL.md#1f-open-pr-via-context-file): follow the project's PR template structure, fill new sections with phase-specific content from the rewritten body, leave un-fillable placeholders untouched. If the prior file used a different template than the project now declares (template was added or swapped between the original `implement-plan` run and this amend), prefer the current `pr_template_paths` choice — surface the change to the user when the body shape shifts visibly.
+When rewriting the `# Description` body, **honor `project.pr_template_paths`** from `.vinta-ai-workflows.yaml` — same rule as [integrate-phase]({{INTEGRATE_PHASE_LINK}})'s **Open PR via context file** step: follow the project's PR template structure, fill new sections with phase-specific content from the rewritten body, leave un-fillable placeholders untouched. If the prior file used a different template than the project now declares, prefer the current `pr_template_paths` choice — surface the change to the user when the body shape shifts visibly.
 
 Always include in the publish-log block at the bottom of the file:
 
@@ -319,29 +325,29 @@ After every queue entry processes:
 - **Never `--force`. Always `--force-with-lease`.** Protects against silent overwrites.
 - **Plan file edit is the first write.** Commit the new plan body before any branch rewrite. The plan is the contract; the branches are the artifact.
 - **Recommend restart when blast radius is high.** The blast-radius step inside Step 0 evaluates signals; ≥2 tripping signals → surface a restart option to the user before any force-push plan is shown. Don't quietly amend a half-rewrite of the whole plan.
-- **Never use `§N` shorthand to point at sections** — neither in this skill body, the rewritten plan body, the amendment log entry, nor any prs-context refresh. Always use the section's full name (and link when possible). `§N` references are hard for humans to follow and shift when section numbering moves.
+- **Never use `§N` shorthand to point at sections** — neither in this skill body, the rewritten plan body, the amendment log entry, nor any prs-context refresh. Always use the section's full name (and link when possible).
 - **Phases merged to `{{DEFAULT_BRANCH}}` are immutable.** Convert to `append-new` phases. Refuse to attempt rewrites.
 - **Confirm every force-push individually.** No batch "confirm all".
-- **Use `--force-with-lease`** (already stated; worth restating).
-- **Three-layer review on every rewritten branch.** Same standard as [implement-plan](../implement-plan/SKILL.md). The amendment isn't done until Layer 3 passes.
+- **`WORKROOT` is resolved once, used everywhere.** Every `git` call takes `git -C <WORKROOT>`; no per-step worktree branching.
+- **Three-layer review on every rewritten branch.** Same standard as [implement-plan](../implement-plan/SKILL.md) — via [review-phase](../review-phase/SKILL.md). The amendment isn't done until Layer 3 passes.
 - **PR-context file is a derived artifact.** Refresh it after the rewrite; never edit the file as a substitute for fixing the diff.
 - **Subagents commit but never push.** Orchestrator owns force-push. {{PR_RULE_TAIL}}.
 {{COAUTHOR_RULE_LINE}}
 {{DEPENDENCY_LICENSE_RULE_LINE}}
-- **Stop on Tier-4 failure** (model escalation, same rules as the [implement-plan "Pick model" step](../implement-plan/SKILL.md#1b-pick-model-from-plans-per-phase-suggestion)).
+- **Stop on Tier-4 failure** (model escalation, same rules as [implement-phase](../implement-phase/SKILL.md#pick-the-model-from-the-plans-per-phase-suggestion)).
 - **Stop on rebase failure** the fixer can't resolve in one retry. Don't ship half-rebased branches.
 
 ## Quick checklist (orchestrator, per amendment run)
 
 - [ ] User-requested change captured verbatim; classification determined (`body-rewrite` / `insert-new` / `append-new` / `guiding-decisions-change`).
-- [ ] Plan parsed; per-phase state map built (state, branch, base, pr_status, merged_to_default).
+- [ ] Plan parsed; per-phase state map built (state, branch, base, pr_status, merged_to_default); `WORKROOT` resolved from tracking `run_options`.
 - [ ] Blast-radius signals computed; `low` → straight to confirmation, `high-blast-radius` / `restart-recommended` → user offered `Restart` / `Amend in place` / `Stop` before the force-push plan is shown.
 - [ ] On `Restart` choice: new plan drafted (or hand-off to [plan-feature](../plan-feature/SKILL.md)); old plan annotated `Superseded`; tracking marked; this skill exits.
 - [ ] Step 3 refusals surfaced; force-push plan confirmed by user.
 - [ ] Plan file edited; amendment log entry appended; committed on `{{DEFAULT_BRANCH}}`.
 - [ ] Rewrite queue ordered by stack depth (parent first).
 - [ ] For each entry: body change applied (when `amend-existing`); inner + outer gate green.
-- [ ] Three-layer review on each rewritten branch; BLOCKERs fixed; SHOULD-FIX noted.
+- [ ] [review-phase](../review-phase/SKILL.md) run on each rewritten branch; BLOCKERs fixed; SHOULD-FIX noted.
 - [ ] Rebase onto rewritten parent; conflicts resolved via fixer; tests re-run.
 - [ ] `--force-with-lease` push confirmed and executed per branch.
 - [ ] PR-context file refreshed (pending or republished).

package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-phase-template.md

@@ -0,0 +1,47 @@
+---
+name: implement-phase
+description: Internal execution step of [implement-plan] / [amend-plan] — NOT a standalone entry point. Given one already-classified plan phase plus the resolved `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER`, it composes a token-efficient implementer prompt, picks the model from the phase's own suggestion, and spawns exactly one implementer subagent, returning that agent's report. Do not invoke directly for ad-hoc edits or in response to a user's raw feature request; the conductor invokes it once per executable phase in {{PROJECT_NAME}}.
+---
+
+# Implement one phase
+
+Execution unit invoked by [implement-plan](../implement-plan/SKILL.md) (and by [amend-plan](../amend-plan/SKILL.md) for `amend-existing` rewrites). One phase in → one implementer report out. This skill does **not** review, branch, push, or open PRs — those are [review-phase](../review-phase/SKILL.md) and [integrate-phase](../integrate-phase/SKILL.md). It also does **not** decide whether a phase runs — the conductor already filtered cross-repo / flag-removal phases.
+
+## Inputs (passed by the conductor as data — this skill re-derives none of them)
+
+- `phase` record: `{ id, title, goal, body, spec_use_case, suggested_model_tier, reusable_skills, has_e2e, acceptance }`.
+- Plan-level decisions: **Goals + Non-goals**, **Guiding Decisions**, the relevant **Data Model Changes** subsection.
+- Prior-phase summaries (the tracking file's "Completed Phases" section).
+- `WORKROOT`, `BASE_BRANCH`, `SANDBOX_TIER` — resolved once by the conductor ([Resolve WORKROOT step](../implement-plan/SKILL.md#step-05--resolve-workroot)).
+- `run_options.full_test_suite` — resolves the outer gate's test scope in the composed prompt's `{If run_options.full_test_suite = true:}` marker (false = scoped suite only; true = full repo suite).
+
+## 1. Compose the agent prompt (token-efficient)
+
+Compose with **only what the agent needs**:
+
+<!-- include: partials/implementer-prompt.md#FULL -->
+
+<!-- include: partials/model-pick.md#MODEL_PICK -->
+
+## 3. Spawn the subagent
+
+Use whatever agent-spawning primitive the runtime exposes. Pass:
+
+- A descriptive label (e.g. `"{plan.id} {phase.id}: {phase.title}"`).
+- The model from the [Pick the model](#pick-the-model-from-the-plans-per-phase-suggestion) step, translated to the runner's form.
+- The phase prompt from the [Compose the agent prompt](#1-compose-the-agent-prompt-token-efficient) step.
+- The right **agent type** (below).
+
+<!-- include: partials/worktree-seam.md#SANDBOX_WRAP -->
+
+**Agent type per phase.** Project agents in [`ai-tools/agents/`](ai-tools/agents/) (exposed to claude-code via `.claude/agents` symlink):
+
+{{AGENT_DISPATCH_TABLE}}
+
+A phase that combines shapes → the agent type stays `implementer`, and the prompt lists every relevant SKILL.md. The agent type changes only when a stack-specialist's risk is the primary one.
+
+**Avoid bouncing the same phase between multiple agents.** Wanting to "hand off" mid-phase → the plan should have split into sub-phases instead.
+
+## Output
+
+Return the implementer's single final report verbatim to the conductor (status, files, summary, deviations, blockers). The conductor — not this skill — writes tracking from the git diff + the report.

package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-plan-template.md

@@ -0,0 +1,186 @@
+---
+name: implement-plan
+description: Execute a phased implementation plan from `{{PLAN_DIR}}/` in {{PROJECT_NAME}} by orchestrating one subagent per phase (using whatever model the plan suggests and the runtime supports), pushing one stacked branch per phase to {{CODE_HOST}}, and tracking progress. Use when the user says "implement the plan", "execute plan X", "start implementation", "run phase N of plan Y", "implement {feature} plan", or asks to drive a `*_IMPLEMENTATION_PLAN.md` file phase-by-phase. NOT for one-off changes, single-file edits, or work that doesn't have an existing plan. {{PR_POLICY_DESCRIPTION}}
+---
+
+# Implement Plan
+
+Drive a phased plan in [`{{PLAN_DIR}}/`]({{PLAN_DIR}}/) to completion. This skill is a **thin conductor**: it parses the plan once, resolves one `WORKROOT`, then runs a fixed three-step pipeline per phase, delegating the real work to focused sub-skills:
+
+1. [implement-phase](../implement-phase/SKILL.md) — compose prompt, pick model, spawn the implementer.
+2. [review-phase](../review-phase/SKILL.md) — three-layer review + fix loop.
+3. {{INTEGRATE_PHASE_DISPATCH}} — push the branch + open the PR via context file.
+
+The conductor itself owns only: plan parsing, phase classification, `WORKROOT` resolution, the loop, the progress-tracking file, the pause gate, and the final report. Harness-agnostic — claude-code, OpenAI Codex, Google's runtime, or any framework with a "spawn subagent with model + prompt" primitive.
+
+Execution counterpart to [plan-feature](../plan-feature/SKILL.md). Plan = contract; this skill = build pipeline.
+
+## Working assumptions
+
+- Repo: {{PROJECT_NAME}} ({{STACK_SUMMARY}}). Conventions: [AGENTS.md](AGENTS.md).
+- Plan files: [`{{PLAN_DIR}}/YYYY-MM-DD-FEATURE_NAME_IMPLEMENTATION_PLAN.md`]({{PLAN_DIR}}/).
+- Lint: `{{LINT_CMD}}`. Format: `{{FORMAT_CMD}}`.
+- Type / build gate: `{{BUILD_CMD}}`{{TYPECHECK_NOTE}}.
+- Unit / integration tests: `{{TEST_CMD}}` (everything){{SCOPED_TEST_NOTE}}.
+{{E2E_BLOCK}}
+{{STACK_SPECIFIC_DEPLOY_BLOCK}}
+- Code host: **{{CODE_HOST}}**. {{PR_POLICY_BLOCK}}
+- {{COAUTHOR_POLICY_BLOCK}}
+
+## Step 0 — Locate + parse plan
+
+Parse once, reuse for every phase:
+
+1. **Identify plan file.** Ask user which plan (path or feature name). Feature name: `ls {{PLAN_DIR}}/` + grep; confirm before proceeding.
+2. **Extract structured fields**, in order:
+   - **Feature name** + **plan id** — derived from filename's `FEATURE_NAME` portion only: strip `YYYY-MM-DD-` prefix + `_IMPLEMENTATION_PLAN.md` suffix. Kebab variant for branch names.
+   - **Goals + Non-goals** section — verbatim, used in every phase prompt.
+   - **Guiding Decisions** section — verbatim. Pay attention to: feature flag (key, scope, default, flip-on criterion), storage shape, tenant scoping, API contract decisions.
+   - **Data Model Changes** section — keep full body; later phases reference earlier subsections.
+   - **Phased Rollout** section — parse into phase records: `{ id, title, goal, body, spec_use_case, suggested_model_tier, reusable_skills, has_e2e, acceptance, is_cross_repo, is_flag_removal }`.
+   - **Risk & Rollout Notes**, **Open Questions**, **Touch List** sections — keep available; include in phase prompts only when relevant.
+3. **Classify each phase**: `is_cross_repo`, `is_flag_removal` — the conductor does NOT auto-execute these (see [Cross-repo phases](#cross-repo-phases) + [Flag-removal phase](#flag-removal-phase-always-out-of-scope)).
+4. **Ask the user three opt-in questions** via `AskUserQuestion`. Defaults are project-specific (see below); record every answer in tracking under `run_options`:
+
+   a. **Pause between phases?** *"Do you want me to pause and wait for confirmation after each phase, before starting the next one? Lets you review the diff / branch / PR / tracking summary before moving on."* Options: `Auto-flow (default) — keep going phase to phase`, `Pause between phases — wait for go after each one`.
+
+   b. **Draft inline review comments per phase?** *"On top of the standard PR description, do you want me to scan each phase's diff and add 3–10 inline comments calling out non-obvious decisions (subtle invariants, feature-flag short-circuits, cross-phase coupling, upstream-contract naming)? Off by default — say yes when reviewers will appreciate annotated diffs."* Options: `Yes — include inline comments`, `No — PR description only`.
+
+   c. **Run phases in a worktree?** *"Do you want every phase's subagent to work inside an isolated git worktree (its own runnable copy of the app with its own dev + test DB, env files, docker-compose project name) instead of sharing your main checkout? Lets you keep using `{{DEFAULT_BRANCH}}` for unrelated work while this plan runs; survives parallel plans on the same repo without DB / port / docker collisions. Costs one extra checkout's worth of disk + the time it takes [prepare-worktree](../prepare-worktree/SKILL.md) to provision it."* Options: `No — run in current checkout`, `Yes — provision one shared worktree for the whole plan`. Default = value of `run_options.implement-plan.use_worktree` in `.vinta-ai-workflows.yaml` (`No` when unset).
+
+      When `Yes`: **the same worktree is used for every executable phase** — all phase branches stack inside it. The skill never provisions a second worktree mid-plan. If the user wants per-phase worktrees, that's a different workflow (split the plan into independent plans).
+
+      Skip this question entirely when `foundation_skills.prepare-worktree` is `disabled` in `.vinta-ai-workflows.yaml`: record `run_options.use_worktree = false`; surface a one-line note that worktree isolation is available if the team opts in via [vinta-sync-ai-tools](../../skills/vinta-sync-ai-tools/SKILL.md).
+
+   d. **Full test suite each phase?** *"Each phase's outer gate always runs the repo-wide type/build gate. For tests, do you want the quick path (run only the scoped suite covering the apps/files that phase touched — faster phases) or the full repo test suite every phase (slower, but guards against regressions in untouched code)? New tests still pass individually in the inner loop either way."* Options: `Quick — scoped tests only each phase (default)`, `Full — run the whole test suite each phase`. Default = value of `run_options.implement-plan.full_test_suite` in `.vinta-ai-workflows.yaml` (`Quick`/false when unset). Records `run_options.full_test_suite` (`true` only for the `Full` answer).
+
+   PR opening itself is **not** asked here — it's governed by the project's PR creation policy captured at bootstrap (see `{{PR_POLICY_BLOCK}}` above). When that policy = "agents create PRs", the {{INTEGRATE_PHASE_DISPATCH}} step always opens the PR via [open-pr.sh](../open-pr-from-context/scripts/open-pr.sh) regardless of the comment opt-in.{{COMMIT_STRATEGY_STEP0_QUESTION}}
+
+5. **Confirm with user before starting.** Show plan path, phase list (id + title + tier + cross-repo/flag-removal flags + e2e flag), phases this skill will execute vs defer, {{BRANCH_NAMING_PATTERN_SUMMARY}}, captured `run_options.pause_between_phases` + `run_options.generate_inline_comments` + `run_options.use_worktree` + `run_options.full_test_suite`{{COMMIT_STRATEGY_CONFIRM_NOTE}}{{PR_REMINDER_LINE}}.
+
+   Wait for "go". After that, the per-phase pause behavior follows `run_options.pause_between_phases`. Inline-comment drafting follows `run_options.generate_inline_comments`. Worktree isolation follows `run_options.use_worktree`. Outer-gate test scope follows `run_options.full_test_suite`.{{COMMIT_STRATEGY_STEP0_TRAILER}}
+
+<!-- include: partials/worktree-seam.md#WORKROOT_RESOLUTION -->
+
+<!-- include: partials/worktree-seam.md#WORKROOT_TOPOLOGY_RULE -->
+
+## Step 1 — Per-phase loop
+
+For each phase that's `not is_cross_repo and not is_flag_removal`, in plan order, run the pipeline:
+
+### 1a. Implement
+
+Invoke [implement-phase](../implement-phase/SKILL.md), passing the phase record, the plan-level decisions (**Goals + Non-goals**, **Guiding Decisions**, the relevant **Data Model Changes** subsection), the prior-phase tracking summaries, `run_options.full_test_suite`, and `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER`. It returns the implementer's report.
+
+**Model escalation.** implement-phase escalates one tier + retries once on a clear capability gap. After Tier 4 fails, it stops and hands back the failure — update tracking with `❌`, post the report to the user, ask how to proceed. Don't silently re-derive tier.
+
+### 1b. Review
+
+Invoke [review-phase](../review-phase/SKILL.md) against the phase diff, passing the phase body to walk, `WORKROOT`, `main_checkout`, `run_options.full_test_suite`, and the `reviewer` / `fixer` agent types. It loops its three layers + fix loop until clean, then returns `PASS` (or the surfaced findings). Do not proceed to integrate while any layer is red.
+
+### 1c. Integrate
+
+Invoke {{INTEGRATE_PHASE_DISPATCH}}, passing `WORKROOT` / `BASE_BRANCH`, the `{{PR_POLICY_BLOCK}}` policy, and `run_options.generate_inline_comments`. It pushes the branch and routes the PR through the context file, returning the branch + PR-context path + status.
+
+### 1d. Update tracking file
+
+Tracking lives at `{{PLAN_DIR}}/TRACKING_{plan-id}.md`. Commit on the **current** phase's branch — deletion in [Step 2](#step-2--final-report).
+
+Schema: feature-name, plan path, started/last-updated dates, optional feature-flag info, **run options** (`pause_between_phases`, `generate_inline_comments`, `full_test_suite`, `use_worktree`, `worktree_path`, `worktree_branch`, `worktree_summary`, `sandbox_tier` — last four only when `use_worktree = true`), {{TRACKING_BRANCH_FIELD}}, completed-phases (with status, model{{TRACKING_PHASE_BRANCH_FIELD}}, e2e+screenshots if any, 5–15 line summary), current phase, remaining phases, deferred phases.
+
+The conductor writes this from the git diff + the agent's summary — not from the agent's narration.
+
+### 1e. Send brief update to user
+
+One short paragraph: phase N done, branch pushed{{PR_LINK_NOTE}}, what got built, and — when the [Integrate](#1c-integrate) step ran — the PR-context file path with its `status` (`published` + URL when `open-pr.sh` opened the PR; `pending` when the script wasn't run because PR policy = branches only or deps were missing). When `status: pending`, mention how to publish later (`bash ai-tools/skills/open-pr-from-context/scripts/open-pr.sh <path>`). Moving to phase N+1. No long retrospective — the tracking file is the durable record.
+
+### 1f. Per-phase pause gate (opt-in)
+
+`run_options.pause_between_phases = false` (default) → **immediately start the next phase**. Do not wait.
+
+`run_options.pause_between_phases = true` → ask the user via `AskUserQuestion`:
+
+- `Continue — start phase N+1`
+- `Pause — stop here, I'll resume later by re-invoking the skill` (conductor exits cleanly; tracking file already records progress so the next invocation resumes mid-plan per [Re-running mid-plan](#re-running-mid-plan)).
+- `Stop — abort the plan run` (conductor stops; user decides next steps manually).
+
+Wait for the answer. Don't spawn anything in the meantime. The pause is the user's review window — they may inspect the diff, the branch, the PR-context file, or the tracking file before agreeing to continue.
+
+## Cross-repo phases
+
+Phase in another repo:
+1. **Do not implement.**
+2. Mark in tracking under "Deferred Phases".
+3. Continue to the next in-repo phase. Don't block on cross-repo work.
+
+## Flag-removal phase (always out of scope)
+
+Plan declared a flag → last phase is `Phase N — Remove the {flag-key} feature flag`. This skill **never** executes that phase. Flag removal is gated on real-world soak signal + is the exclusive responsibility of a dedicated flag-removal skill (separate skill).
+
+What this skill does instead:
+1. Identify the phase during Step 0; always exclude.
+2. Mark in tracking as deferred.
+3. End the run with a `/schedule` offer pointing at the dedicated flag-removal skill.
+4. Refuse + redirect if the user asks this skill to remove the flag.
+
+## Re-running mid-plan
+
+User invokes the skill against a partially-done plan:
+
+1. Read `{{PLAN_DIR}}/TRACKING_{plan-id}.md` if present. Extract `run_options.*` — including `worktree_path` / `worktree_branch` / `worktree_summary` when set. Never re-prompt the Step 0 opt-in questions on resume; the original answers stick.
+2. **Worktree resume.** When `run_options.use_worktree = true`:
+   - Confirm the worktree still exists (`git worktree list | grep <worktree_path>`). Missing → ask user: `Reprovision (run prepare-worktree again with the same name)`, `Switch to main checkout (flip use_worktree to false for the rest of the run)`, `Stop`.
+   - Confirm the worktree summary file still parses; if not, regenerate from the existing worktree state.
+   - **Re-probe `SANDBOX_TIER`** (`command -v sandbox-exec || command -v bwrap`) — a resume may run on a different machine than the original provisioning. Update `run_options.sandbox_tier` in tracking before spawning; the implement-phase spawn wrapping follows the re-probed value.
+   - All resumed phases use the existing worktree — do not provision a second one.
+3. `git -C <WORKROOT> branch -a | grep plan/{plan-id-kebab}` to detect already-pushed phase branches.
+4. Cross-reference with the plan's phase list.
+5. Confirm the resumption point with the user.
+
+## Step 2 — Final report
+
+After all executable phases complete:
+
+1. **Delete `TRACKING_{plan-id}.md`** on the last phase's branch. Commit. The plan file stays.
+2. Send the user a final summary: {{FINAL_REPORT_BRANCH_SUMMARY}}; for UI-flow phases — list of `pr-screenshots/` files (if applicable); deferred phases (cross-repo + flag-removal); next steps for the human. When `run_options.use_worktree = true`: include the worktree path + branch + summary file path + the teardown command (`git worktree remove <path>` + the per-engine drop-db / `docker compose -p <project> down -v` lines from `<worktree_summary>`). Do NOT auto-run teardown — the user may still want the worktree to debug review feedback or land follow-ups.
+{{FINAL_REPORT_PR_NOTE}}
+3. Flag-removal phase deferred → end with `/schedule` offer for the dedicated flag-removal skill.
+
+## Important rules
+
+- **Read AGENTS.md** in every phase prompt.
+- **Stage explicitly.** No `git add -A`.
+- **Subagents work in fresh sessions.** Each phase = a new subagent. Tracking + plan files = the context handoff.
+- **Conductor owns git topology.** Subagents commit but never branch, push, {{PR_RULE_TAIL}}.
+{{COAUTHOR_RULE_LINE}}
+- **Trust the plan's per-phase model suggestion.** Model selection lives in [implement-phase](../implement-phase/SKILL.md); the conductor never re-derives tiers.
+- **Don't re-implement what a project skill encodes.**
+{{UI_E2E_RULE_LINE}}
+- **Two-tier verification, in order, every phase.** Inner scoped, then the outer gate — enforced inside [implement-phase](../implement-phase/SKILL.md). The outer gate always runs the repo-wide type/build gate; its test scope follows `run_options.full_test_suite` (scoped suite by default, full repo suite when opted in).
+- **Three-layer review, every phase, no exceptions** — [review-phase](../review-phase/SKILL.md) is not optional and not inlined here.
+- **Orchestrator never edits code.**
+- **Feature flags = gates, not toggles for tests.**
+- **Never remove a feature flag from this skill.**
+- **Stop on Tier-4 failure.**
+- **Honor opt-in flags.** `run_options.pause_between_phases` controls the [Per-phase pause gate](#1f-per-phase-pause-gate-opt-in); `run_options.generate_inline_comments` controls whether {{INTEGRATE_PHASE_DISPATCH}} drafts inline comments (always writes the file when that step runs at all — empty comments when off); `run_options.use_worktree` controls whether the [Resolve WORKROOT step](#step-05--resolve-workroot) provisions a worktree and thus what `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER` resolve to; `run_options.full_test_suite` controls the outer-gate test scope ([Implement](#1a-implement) + [Review](#1b-review) Layer 1) — scoped suite by default, full repo suite when `true`.
+- **One worktree per plan run.** When `use_worktree = true`, provision once in the [Resolve WORKROOT step](#step-05--resolve-workroot) and reuse for every phase. Never spawn a second worktree mid-plan; never silently fall back to the main checkout on prepare-worktree failure (ask the user).
+- **Don't auto-tear-down the worktree.** Step 2 surfaces the teardown command; the user runs it when ready.
+- **`WORKROOT` is resolved once, used everywhere.** Every sub-skill takes `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER` as data — no step re-derives worktree state. OS-level prevention (sandbox wrap in implement-phase when `SANDBOX_TIER = enforced`) plus the review-phase stray-write backstop keep main-checkout writes out; see [worktree-seam](../implement-phase/SKILL.md#3-spawn-the-subagent).
+- **PR-context file + `open-pr.sh` is the only PR-creation path.** No raw `gh pr create` / `glab mr create` calls outside the bundled script.
+{{DEPENDENCY_LICENSE_RULE_LINE}}
+- **Never use `§N` shorthand to point at sections** — neither in this skill body nor in any rendered file (tracking, prs-context, branch description). Always use the section's full name with a markdown link when possible.
+
+## Quick checklist (conductor, per phase)
+
+- [ ] Plan parsed; structured fields cached.
+- [ ] Cross-repo + flag-removal phases identified + deferred.
+- [ ] `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER` resolved once ([Resolve WORKROOT step](#step-05--resolve-workroot)); worktree provisioned + summary captured + user confirmed when `use_worktree = true`.
+- [ ] [implement-phase](../implement-phase/SKILL.md) run: prompt composed with **Goals + Non-goals** + **Guiding Decisions** + relevant **Data Model Changes** subsection + tracking summaries + this phase's body; model picked from `**Suggested AI model**:` (cheapest available); implementer report received.
+- [ ] [review-phase](../review-phase/SKILL.md) run: Layers 1–3 clean; BLOCKERs fixed; SHOULD-FIX fixed or noted; outer gate re-run after any fix; when a worktree is in use, `git -C <main_checkout> status --short` clean after the implementer and after every fixer.
+- [ ] {{INTEGRATE_PHASE_DISPATCH}} run: {{BRANCH_CHECKLIST_LINE}}{{PR_CHECKLIST_NOTE}}
+{{COMMIT_STRATEGY_CHECKLIST_BLOCK}}
+  - [ ] **Open PR via context file** decision applied per matrix (PR policy + `generate_inline_comments`): file written when at least one of policy=create / comments=true holds; `open-pr.sh` run when policy=create AND deps available (PR URL captured); per-comment failures (exit 1) and hard failures (exit 2) surfaced.
+- [ ] `TRACKING_{plan-id}.md` updated.
+- [ ] One-paragraph user update sent (PR URL or pending-file path included).
+- [ ] If `run_options.pause_between_phases = true`: prompted user (`Continue` / `Pause` / `Stop`); honored answer. Else: next phase started immediately.
+- [ ] On final phase: tracking file deleted; final summary lists branches{{FINAL_CHECKLIST_PR_NOTE}}; any `status: pending` PR-context files listed with publish command; `/schedule` offer for flag-removal if applicable.

package/skills/vinta-derive-skills/resources/plan-execution/shell/integrate-phase-template.md

@@ -0,0 +1,30 @@
+---
+name: {{INTEGRATE_PHASE_NAME}}
+description: Internal integration step of [implement-plan] — NOT a standalone entry point. Pushes one reviewed phase along {{PROJECT_NAME}}'s commit strategy and opens (or updates) its PR through the prs-context file + bundled open-pr.sh — the only PR-creation path. The conductor passes the resolved `WORKROOT` / `BASE_BRANCH` and the PR / inline-comment policy; do not invoke directly to push arbitrary work.
+---
+
+# Integrate one phase
+
+Invoked by [implement-plan](../implement-plan/SKILL.md) after [review-phase](../review-phase/SKILL.md) returns clean. Pushes the phase and routes its PR through the context file. Subagents never push or open PRs — this orchestrator step does.
+
+<!-- derive-skills note: for projects with `policies.commit_strategy` = stacked-branches or modular-commits this template renders once to `ai-tools/skills/integrate-phase/`. For `ask`, it renders TWICE — to `integrate-phase-stacked` and `integrate-phase-modular` — each with `<RESOLVED>` bound to its strategy and `{{INTEGRATE_PHASE_NAME}}` set to match its dir; the conductor dispatches to one by name on `run_options.commit_strategy_resolved`. -->
+
+## Inputs (passed by the conductor)
+
+- `WORKROOT`, `BASE_BRANCH` — resolved once by the conductor.
+- `{{PR_POLICY_BLOCK}}` policy + `run_options.generate_inline_comments`.
+- The phase record + plan-level decisions (for the PR body).
+
+<!-- include: partials/worktree-seam.md#WORKROOT_TOPOLOGY_RULE -->
+
+## {{BRANCH_PUSH_HEADING}}
+
+<!-- include: partials/commit-strategy/<RESOLVED>.md#BRANCH_NAMING -->
+
+## Open PR via context file
+
+<!-- include: partials/pr-context.md#PR_CONTEXT -->
+
+## Output
+
+Return to the conductor: the branch pushed, and the PR-context file path with its `status` (`published` + `pr_url` when `open-pr.sh` ran; `pending` otherwise) plus the publish command when `pending`.

package/skills/vinta-derive-skills/resources/plan-execution/shell/review-phase-template.md

@@ -0,0 +1,25 @@
+---
+name: review-phase
+description: Internal review gate of [implement-plan] / [amend-plan] / [systematic-debugging] — NOT a standalone entry point. Runs the mandatory three-layer review (mechanical checks, plan-compliance walkthrough, independent reviewer subagent) plus the fix loop against one phase's diff in {{PROJECT_NAME}}, spawning reviewer + fixer subagents and looping until all three layers are clean. The invoking conductor passes the diff, the phase body to walk against, and the resolved `WORKROOT`; do not invoke directly to "review my code" — use the project's standard code-review path for that.
+---
+
+# Review one phase
+
+The single review implementation shared by every plan-execution conductor: [implement-plan](../implement-plan/SKILL.md) (after an implementer runs), [amend-plan](../amend-plan/SKILL.md) (after a rewrite), and [systematic-debugging](../systematic-debugging/SKILL.md) (against the fix diff). Read-only orchestration: this skill **never edits code** — every issue becomes a fix-up subagent task.
+
+## Inputs (passed by the conductor)
+
+- The phase diff (on the current branch inside `WORKROOT`).
+- The phase body to walk against (the **new** body when invoked by amend-plan).
+- `WORKROOT`, `SANDBOX_TIER` — resolved once by the conductor.
+- `main_checkout` — the repo root the run was invoked from (equals `WORKROOT` when no worktree).
+- `run_options.full_test_suite` — resolves which outer gate Layer 1 item 3 verifies ran (false = scoped suite; true = full repo suite).
+- The project's `reviewer` + `fixer` agent types.
+
+## Review
+
+<!-- include: partials/review-layers.md#LAYERS -->
+
+## Output
+
+Return to the conductor: `PASS` (all three layers clean) with a one-line note, or the list of BLOCKER / SHOULD-FIX findings and what the fix loop applied. The conductor owns branch / push / PR — this skill hands back a clean (or annotated) working tree in `WORKROOT`.

package/skills/vinta-derive-skills/resources/systematic-debugging-template.md

@@ -125,8 +125,9 @@ Goal: ship the fix at the right level of abstraction with the right safety net.
    - `{{BUILD_CMD}}`
    - `{{TEST_CMD}}`{{SCOPED_TEST_NOTE}}
    {{E2E_OUTER_GATE_LINE}}
-4. **Verify on the observability side after deploy.** The error fingerprint from Phase 0 should stop firing. If the platform supports it, mark the issue resolved in the source MCP tool so a regression re-opens it instead of creating a duplicate.
-5. **Document if the fix is non-obvious.** A comment is justified only when the *why* would surprise the next reader — a hidden invariant, a workaround for a known upstream bug, a constraint not visible from the call site. Don't narrate the change.
+4. **Route the fix diff through the shared review gate.** Invoke [review-phase](../review-phase/SKILL.md) — the same three-layer review (mechanical checks, plan/intent-compliance walkthrough, independent reviewer subagent) + fix loop that [implement-plan](../implement-plan/SKILL.md) and [amend-plan](../amend-plan/SKILL.md) use — passing the fix diff, the one-sentence root cause + the new failing-then-passing test as the "body" to walk against, and `WORKROOT` = the current checkout. A bug fix is not done until review-phase returns clean. (When this skill runs *inside* implement-plan's inner/outer loop, the enclosing phase's review-phase already covers this — don't double-review; the standalone invocation is for bugs debugged outside a plan.)
+5. **Verify on the observability side after deploy.** The error fingerprint from Phase 0 should stop firing. If the platform supports it, mark the issue resolved in the source MCP tool so a regression re-opens it instead of creating a duplicate.
+6. **Document if the fix is non-obvious.** A comment is justified only when the *why* would surprise the next reader — a hidden invariant, a workaround for a known upstream bug, a constraint not visible from the call site. Don't narrate the change.
 
 ## Stop conditions — count your attempts
 
@@ -156,6 +157,8 @@ These are not debugging — they are guessing with extra steps. Stop and re-ente
 
 When this skill runs inside [implement-plan](../implement-plan/SKILL.md) (the inner / outer test loop), the implementer agent invokes systematic-debugging on every red gate and reports the Phase-1 cause in its report. The orchestrator never overrides the Iron Law — a phase that can't name the cause is not allowed to land.
 
+For the review gate in Phase 4, this skill shares [review-phase](../review-phase/SKILL.md) with implement-plan and amend-plan — one review implementation across all three, so a bug fix meets the same three-layer bar as any planned phase.
+
 For new test scaffolding, defer to the project's test conventions captured in [AGENTS.md](../../AGENTS.md). For env / config issues uncovered in Phase 0, route to the project's `add-env-var` skill if shipped (`{{PROJECT_SKILLS_LIST}}`).
 
 ## Verification checklist (apply before claiming a bug fixed)
@@ -164,4 +167,5 @@ For new test scaffolding, defer to the project's test conventions captured in [A
 2. Root cause stated in one sentence in the PR description.
 3. New failing-then-passing test cited by file:line.
 4. Full local gate green: `{{LINT_CMD}}` + `{{BUILD_CMD}}` + `{{TEST_CMD}}`{{E2E_OUTER_GATE_CHECKLIST}}.
-5. Observability source updated post-deploy (issue resolved / alert acknowledged) so a recurrence pages instead of silently re-opening.
+5. [review-phase](../review-phase/SKILL.md) run on the fix diff and returned clean (unless the fix landed inside an implement-plan phase already covered by its review-phase).
+6. Observability source updated post-deploy (issue resolved / alert acknowledged) so a recurrence pages instead of silently re-opening.

package/skills/vinta-update-project-skills/SKILL.md

@@ -8,7 +8,7 @@ description: Refresh the user's project skills under `ai-tools/skills/` against
 [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md) (specifically [vinta-derive-skills](../vinta-derive-skills/SKILL.md)) seeds a project's `ai-tools/skills/` directory from sources that live in this repo:
 
 - **Verbatim foundation skills** — copied as-is from `vinta-derive-skills/resources/foundation-skills/<name>/SKILL.md`.
-- **Templated skills** — `implement-plan/SKILL.md` is rendered from `vinta-derive-skills/resources/implement-plan-template.md` with project-specific values interpolated.
+- **Templated skills** — the plan-execution unit (`implement-plan` + `implement-phase` + `review-phase` + `integrate-phase` + `amend-plan`) is rendered from the shells under `vinta-derive-skills/resources/plan-execution/shell/` (which `<!-- include -->` shared `partials/`) with project-specific values interpolated; `systematic-debugging` from `vinta-derive-skills/resources/systematic-debugging-template.md`.
 - **Stack-derived skills** — drafted from prompts under `vinta-bootstrap-ai-tools/resources/stacks/<stack>/notes.md`.
 - **User-authored skills** — anything else the team added later. **Never overwritten.**