vinta-ai-workflows 0.2.0-alpha2 → 0.2.0-alpha4

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

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

@@ -1,416 +0,0 @@
----
-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: spawn one subagent per phase (whichever model plan recommends + runtime can run), run lint / typecheck / unit / e2e (where applicable), push one stacked {{CODE_HOST}} branch per phase, keep a progress tracking file as context handoff between phases. 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` — orchestrator does NOT auto-execute these.
-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).
-
-   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 [Open PR via context file](#1f-open-pr-via-context-file) step always opens the PR via [open-pr.sh](../foundation-skills/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`{{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`.{{COMMIT_STRATEGY_STEP0_TRAILER}}
-
-## Step 0.5 — Provision worktree (when `run_options.use_worktree = true`)
-
-Skip when `run_options.use_worktree = false`; jump to Step 1.
-
-When true, invoke [prepare-worktree](../prepare-worktree/SKILL.md) **once**, before any phase runs:
-
-1. **Inputs.** Plan path (so prepare-worktree can read it for deps / migrations / env / compose churn — see prepare-worktree's **Plan inspection** step), suggested worktree name = `plan-{plan-id-kebab}`, plan-driven mode.
-2. **Pre-run sanity.** Confirm no existing worktree at the target path (`git worktree list | grep <name>` — refuse if collision). Confirm `git -C <main> status` of the main checkout (warn if dirty; defer to prepare-worktree's **Sanity checks** step for the call).
-3. **Run prepare-worktree.** Pass the plan file + worktree name. The skill returns:
-   - `worktree_path` — absolute path the phase subagents will `cd` into.
-   - `worktree_branch` — the base branch prepare-worktree created; phase branches stack off this.
-   - `worktree_summary` — `.vinta-ai-workflows/worktrees/<name>.yaml` (read by teardown).
-4. **Persist to tracking.** Write `run_options.worktree_path`, `run_options.worktree_branch`, `run_options.worktree_summary` into `{{PLAN_DIR}}/TRACKING_{plan-id}.md` (Step 1g schema gains these three fields). All later phases read them — never re-provision mid-plan.
-5. **Report to user.** Quote the prepare-worktree summary back: which dirs symlinked vs copied vs forked; which DB(s) forked + their names; compose project name; teardown command. Hold here until the user confirms (`AskUserQuestion`: `Looks good — start phase 1`, `Stop — let me adjust`).
-
-**Worktree topology rule.** When `use_worktree = true`, every phase branches off the previous phase **inside the worktree**, not off `{{DEFAULT_BRANCH}}` in the main checkout. The first phase branches off `<worktree_branch>` (which prepare-worktree based on `origin/{{DEFAULT_BRANCH}}`); subsequent phases stack as usual. All `git` calls in the **{{BRANCH_PUSH_HEADING}}** step use `git -C <worktree_path>` (or `cd` into the worktree first). All inner / outer test commands in the [Prepare agent prompt](#1a-prepare-agent-prompt-token-efficient) step's working-instructions block run inside the worktree so they hit the forked DB / env / compose stack.
-
-Failure modes:
-- **prepare-worktree returns an error** (disk full, branch exists, DB clone failed) → surface to the user; do NOT fall back to "just run in the main checkout" silently — that defeats the opt-in. Ask: `Retry`, `Run in main checkout instead (flip use_worktree to false)`, `Stop`.
-- **User cancels at the confirmation gate** → tear the worktree down (run the teardown command from prepare-worktree's report) before exiting, so the next run starts clean.
-
-## Step 1 — Per-phase loop
-
-For each phase that's `not is_cross_repo and not is_flag_removal`, in plan order:
-
-### 1a. Prepare agent prompt (token-efficient)
-
-Compose with **only what the agent needs**:
-
-```
-You are implementing {phase.id}: {phase.title} of plan {plan.id}.
-
-## Repo
-{{PROJECT_NAME}} ({{STACK_SUMMARY}}).
-
-{If run_options.use_worktree = true:}
-  ## Worktree
-  Work entirely inside this worktree: `<run_options.worktree_path>`.
-  `cd` into it before any command. Every `git`, every lint / test / build / migrate
-  call runs there. Do NOT touch the main checkout — its DB, env, and compose stack
-  are intentionally separated. See `<run_options.worktree_path>/WORKTREE.md` for
-  what's forked vs shared (deps, dev DB, test DB, compose project name, env file).
-  Branch base for this phase: `<phase-specific base>` — orchestrator already
-  created your phase branch there; commit straight to it.
-
-## Read first
-1. AGENTS.md — repo conventions.
-2. {{PLAN_DIR}}/{plan-filename}, the **Goals + Non-goals**, **Guiding Decisions**, **Data Model Changes** sections and YOUR phase body inside **Phased Rollout**.
-{If run_options.use_worktree = true:} 3. `WORKTREE.md` at the worktree root — fork map (which dirs symlink to main vs are independent copies).
-
-## Plan-level decisions (from Goals + Non-goals + Guiding Decisions)
-{Goals + Non-goals verbatim}
-{Guiding Decisions table verbatim}
-{If feature flag declared:}
-  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."}
-
-## Your tasks (Phase {id} only)
-{phase.body verbatim, including Goal / Spec use-case / Feature flag / Changes / Tests / Acceptance lines}
-
-## Reusable skills you SHOULD invoke
-{phase.reusable_skills — for each, instruct the agent to first read ai-tools/skills/{name}/SKILL.md, then follow that pattern.}
-
-Project skills available: {{PROJECT_SKILLS_LIST}}
-
-{{DEPENDENCY_LICENSE_BLOCK}}
-
-## Working instructions
-1. Read existing code paths your changes touch — do not write before reading.
-2. Implement using Read/Edit/Write. Match existing patterns.
-3. **Inner loop — fast iteration.** Scoped to files/apps you touched:
-   a. `{{LINT_CMD}}` until clean.
-   b. {{NEW_TEST_CMD_PATTERN}} for new tests individually.
-   c. Scoped suite: {{SCOPED_TEST_PATTERN}}.
-4. Iterate 2–3 until **new tests pass individually** and the scoped suite is green. Do **not** advance to step 5 with red scoped tests.
-5. **Outer gate — full local verification, only after step 4 is green.** All MUST pass before staging:
-   a. **Type / build:** `{{BUILD_CMD}}`.
-   b. **Full test suite:** `{{TEST_CMD}}`.
-   {{E2E_OUTER_GATE_LINE}}
-6. Outer gate fails → return step 2 (fix regression), re-run inner loop, then 5a/5b/5c. **Never** commit, push, or proceed while any gate is red.
-{{PER_PHASE_COMMIT_BLOCK}}
-
-## Required output (single final report)
-- Status: SUCCESS or FAILURE (and why).
-- Files created/modified (paths only).
-- 5–15 line summary of what you implemented and key decisions.
-{{E2E_REPORT_FIELD}}
-- Deviations from the plan body and reasoning.
-- 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.
-
-### 1b. Pick model from plan's per-phase suggestion
-
-**Plan owns model selection — this skill does not re-derive tiers, doesn't assume vendor.** Each phase carries `**Suggested AI model**:` listing one model per vendor.
-
-Pick:
-
-1. Read line, parse out **all** vendor suggestions.
-2. **Filter to what's actually available in the runtime.** Different harnesses expose different sets.
-3. From 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.
-
-**Retry escalation (no user prompt):** picked model fails on a clear capability gap → step **one tier up** + 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.
-
-### 1c. Spawn subagent
-
-Use whatever agent-spawning primitive the runtime exposes. Pass:
-
-- Descriptive label (e.g. `"{plan.id} {phase.id}: {phase.title}"`).
-- Model from the [Pick model from plan's per-phase suggestion](#1b-pick-model-from-plans-per-phase-suggestion) step, translated.
-- Phase prompt from the [Prepare agent prompt](#1a-prepare-agent-prompt-token-efficient) step.
-- The right **agent type**.
-
-**Agent type per phase.** Project agents in [`ai-tools/agents/`](ai-tools/agents/) (exposed to claude-code via `.claude/agents` symlink):
-
-{{AGENT_DISPATCH_TABLE}}
-
-Phase combines shapes → agent type stays `implementer`, prompt lists every relevant SKILL.md. 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.
-
-### 1d. Thorough review
-
-Three layers, all required, in order. The orchestrator never edits — every issue surfaces as a fix-up subagent task.
-
-#### Layer 1 — Mechanical checks
-
-1. `git status` + `git diff --stat`: confirm file list matches the agent's report.
-2. **Read the full diff** for every changed file using `git diff`. Spot-checking is not enough.
-3. **Verify the outer gate** ran + green. Look in the report for explicit confirmation that `{{BUILD_CMD}}` AND `{{TEST_CMD}}` were executed + passed{{E2E_LAYER1_NOTE}}. Vague confirmation → **re-run yourself**.
-4. **Scope creep**: file touched outside expected surface area? Unrelated formatting churn? Surface it.
-5. **No-secrets scan**: `git diff` for `password|secret|token|api_key|AKIA|BEGIN [A-Z]+ KEY`.
-6. **Stray main-checkout writes (only when `run_options.use_worktree = true`)**: a subagent is told to work inside the worktree, but a buggy agent (often a smaller model) can resolve an absolute path back to the **main checkout** and silently edit files there (worktrees have independent working trees, so those edits never reach the phase commit — they sit as uncommitted thrash in the main checkout, and the "missing" edits read as a silent fixer/implementer failure). After **every** implementer **and** fixer subagent returns, run `git -C <main-checkout-path> status --short | grep -vE '^\?\?'` (tracked modifications only). Any output is a BLOCKER for this phase:
-   - Diff the stray files (`git -C <main-checkout-path> diff -- <path>`) to recover intent.
-   - If the edit belongs in the worktree, re-dispatch the fixer/implementer with an explicit instruction to write to the worktree path (the change is missing from the phase commit until it does).
-   - Once recovered (or confirmed superseded by the correctly-committed worktree version), discard the stray edits with `git -C <main-checkout-path> restore -- <path>` so the main checkout returns clean. Never leave the main checkout dirty between phases — a later phase's Layer 1 can't tell new thrash from old.
-   `<main-checkout-path>` is the repo root the skill was invoked from (NOT `run_options.worktree_path`). Skip this check entirely when `run_options.use_worktree = false`.
-{{DEPENDENCY_LICENSE_LAYER1_CHECK}}
-{{COAUTHOR_LAYER1_CHECK}}
-
-#### Layer 2 — Plan compliance walkthrough
-
-Open phase body alongside diff and walk:
-
-1. **Every numbered "Changes" item implemented.**
-2. **Every "Tests" entry materialized**, with assertions actually exercising the called-out behavior.
-3. **Acceptance line satisfiable** by the diff.
-4. **Repo conventions** from AGENTS.md.
-5. **Reusable-skill compliance.**
-{{E2E_LAYER2_CHECK}}
-6. **Feature-flag wiring** if the plan's **Guiding Decisions** declared a flag — flag-OFF byte-for-byte pre-feature behavior, ≥1 test asserts.
-7. **Cross-phase consistency** with prior tracking summaries.
-
-#### Layer 3 — Independent reviewer subagent
-
-After Layers 1–2 pass, spawn a **separate** subagent (different session, no implementation context) using the project's `reviewer` agent type ([ai-tools/agents/reviewer.md](ai-tools/agents/reviewer.md)). Read-only by design.
-
-Reviewer prompt template — see the reviewer agent's body for the standard form. Triage findings:
-- **BLOCKER**: must fix before the **{{BRANCH_PUSH_HEADING}}** step below.
-- **SHOULD-FIX**: fix in-phase if cheap; else follow-up issue + tracking note.
-- **NIT**: ignore unless trivially cheap.
-
-Reviewer finds nothing on a >300-LoC multi-file phase → suspicious. Read once more.
-
-#### Fix loop
-
-1. Spawn a **new** subagent — project's `fixer` agent type ([ai-tools/agents/fixer.md](ai-tools/agents/fixer.md)). Fix prompt quotes the finding verbatim.
-2. The `fixer`'s system prompt mandates re-running the inner loop + outer gate.
-3. After fixer returns, redo Layer 1 in full + the affected portion of Layer 2.
-4. Loop until Layers 1, 2, 3 are clean.
-
-### 1e. {{BRANCH_PUSH_HEADING}}
-
-**Worktree path rule (applies to whichever commit strategy `{{BRANCH_NAMING_BLOCK}}` renders below).** When `run_options.use_worktree = false`, every `git` command runs in the main checkout exactly as written. When `true`, run every `git` command below inside the worktree — prefix with `git -C <run_options.worktree_path>` (or `cd` into it first), and the first executed phase branches off `<run_options.worktree_branch>` instead of `{{DEFAULT_BRANCH}}`. Branches / commits stack inside the worktree; nothing touches the main checkout's working tree.
-
-{{BRANCH_NAMING_BLOCK}}
-
-PR opening lives in the [Open PR via context file](#1f-open-pr-via-context-file) step below (single flow — context file + `open-pr.sh`). Subagents never open PRs themselves; the orchestrator does, after review passes.
-
-### 1f. Open PR via context file
-
-This is the **only** PR-creation path. PRs always go through {{PRS_CONTEXT_FILE_PATH_DESCRIPTION}} + the bundled [open-pr.sh](../foundation-skills/open-pr-from-context/scripts/open-pr.sh) script — even when inline comments are not requested. The file is the durable record; the script is the publisher.
-
-{{PR_OPEN_TIMING_BLOCK}}
-
-Two project-level signals decide the actual behavior:
-
-| `{{PR_POLICY_BLOCK}}` policy | `run_options.generate_inline_comments` | What this **Open PR via context file** step does |
-|---|---|---|
-| agents create PRs | false | Write minimal context file (`# Title`, `# Description`, empty `# Comments`). Run `open-pr.sh` → PR opened, no inline comments. |
-| agents create PRs | true  | Write full context file (title + description + 3–10 inline comments). Run `open-pr.sh` → PR opened, all comments posted. |
-| branches only     | false | **Skip this step entirely.** Human will open PR manually from the pushed branch. |
-| branches only     | true  | Write full context file (durable record). **Don't run `open-pr.sh`.** Human can publish later from a CLI-equipped session via [open-pr-from-context](../foundation-skills/open-pr-from-context/SKILL.md). Surface this in the [Send brief update](#1h-send-brief-update-to-user) step. |
-
-#### Steps
-
-1. **Skip if neither column applies** (policy = branches only AND `generate_inline_comments = false`). Jump to the [Update tracking file](#1g-update-tracking-file) step.
-
-2. **Honor existing PR / MR templates.** Read `project.pr_template_paths` from `.vinta-ai-workflows.yaml`. For each entry:
-   - **One template** → load it; the prs-context `# Description` body must follow that template's section structure verbatim. Fill each section with phase-specific content drawn from the plan's **Goals + Non-goals**, **Guiding Decisions**, and the phase body. Preserve any `<!-- HTML comments -->` placeholders; do not strip the template's checklists. Sections you can't fill from phase data → leave the template's placeholder/prompt untouched (don't fabricate).
-   - **Multiple templates** (`PULL_REQUEST_TEMPLATE/` directory) → ask once via `AskUserQuestion`: list each template + its filename, ask which to use for this run. Cache the choice in tracking under `run_options.pr_template_used` so subsequent phases of the same plan use the same one without re-asking.
-   - **Empty array** → free-form description. Default sections: `## Summary` (1–3 sentences), `## Plan reference` (link / phase id), `## Test plan` (commands the reviewer can run).
-
-   When the project's PR template includes a checkbox checklist (e.g. `- [ ] Tests added`, `- [ ] Docs updated`), tick the boxes the phase's diff actually satisfies and leave unsatisfied ones unticked — never auto-tick everything.
-
-   GitHub also honors `?template=<name>` in the PR-create URL when the project has a multi-template directory. `gh pr create --body-file` writes the body directly so the URL trick isn't needed; the body must match the chosen template's structure regardless.
-
-3. **Pick comment targets** (only when `generate_inline_comments = true`). Read the phase diff via `git diff {{DEFAULT_BRANCH}}...HEAD` (or the previous phase branch for stacked phases). Select 3–10 spots that benefit from a one-paragraph context note — typically:
-   - A subtle invariant the diff relies on (cite the plan's **Goals + Non-goals** / **Guiding Decisions** entries — by name, never use `§` shorthand).
-   - A workaround for a known framework / library limitation.
-   - A naming choice driven by an upstream contract.
-   - The off-flag short-circuit when a feature flag is in **Guiding Decisions**.
-   - Why a seemingly-cleaner refactor wasn't made (out of scope per **Goals + Non-goals**).
-   - Cross-phase coupling (this hook is consumed by phase N+k).
-
-   Skip lint/format churn, boilerplate matching nearby files, standard patterns from AGENTS.md, and self-explanatory test names. **A clean phase produces few comments — that's fine. Don't pad.**
-
-   When `generate_inline_comments = false`: skip this step. The file's `# Comments` block stays empty.
-
-4. **Write `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md`** following [resources/prs-context-template.md](../prs-context-template.md). Frontmatter: `plan_id`, `feature_name`, `phase_id`, `phase_title`, `branch`, `base`, `created_at`, `status: pending`, empty `pr_url`. Body sections: `# Title` (single-line PR title), `# Description` (Markdown body — uses the project's PR template structure from step 2 when one exists), `# Comments` (YAML list of `{file, start_line, end_line?, side, body}` — empty list when comments are off).
-
-5. **Confirm `.vinta-ai-workflows/prs-context/` is in `.gitignore`.** [vinta-install-ai-tools-setup](../../../vinta-install-ai-tools-setup/SKILL.md) runs the multi-vendor setup script which appends `.vinta-ai-workflows/prs-context/` on its first invocation. If an older bootstrap missed it, append it now.
-
-6. **Run `open-pr.sh`** (only when policy = agents create PRs). Detect a usable CLI (`gh` for GitHub, `glab` for GitLab) plus the script's other deps (`yq`, `jq`):
-
-   ```bash
-   bash ai-tools/skills/open-pr-from-context/scripts/open-pr.sh .vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md
-   ```
-
-   Script opens the PR (or detects an existing one), posts each inline comment, rewrites the file's frontmatter to `status: published` + populated `pr_url`, appends a publish log. Exit codes:
-
-   - `0` — PR up, all comments (if any) posted. Capture `pr_url` for the [Send brief update](#1h-send-brief-update-to-user) step.
-   - `1` — PR up, ≥1 comment failed. Surface the failed `(file:line)` list to the user; continue to the [Update tracking file](#1g-update-tracking-file) step.
-   - `2` — Hard failure (deps missing, branch not pushed, CLI unauthed, file invalid). Surface the script's stderr; treat the phase as having no PR. The file stays `status: pending` so the user can re-run after fixing the gap.
-
-   When policy = "branches only": **don't run the script.** File stays `status: pending`.
-
-7. **Skill wrapper** — [open-pr-from-context](../foundation-skills/open-pr-from-context/SKILL.md) is available for ad-hoc invocation (after the run, on a different machine, etc.). The orchestrator can call the script directly here; the skill is for humans.
-
-### 1g. Update tracking file
-
-Tracking lives at `{{PLAN_DIR}}/TRACKING_{plan-id}.md`. Commit on the **current** phase's branch — deletion in Step 3.
-
-Schema: feature-name, plan path, started/last-updated dates, optional feature-flag info, **run options** (`pause_between_phases`, `generate_inline_comments`, `use_worktree`, `worktree_path`, `worktree_branch`, `worktree_summary` — last three 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 orchestrator writes this from the git diff + the agent's summary — not from the agent's narration.
-
-### 1h. Send brief update to user
-
-One short paragraph: phase N done, branch pushed{{PR_LINK_NOTE}}, what got built, and — when the [Open PR via context file](#1f-open-pr-via-context-file) 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 — tracking file is the durable record.
-
-### 1i. Per-phase pause gate (opt-in)
-
-`run_options.pause_between_phases = false` (default) → **immediately spawn 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` (orchestrator exits cleanly; tracking file already records progress so the next invocation resumes mid-plan per the "Re-running mid-plan" section).
-- `Stop — abort the plan run` (orchestrator 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 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.
-   - All resumed phases use the existing worktree — do not provision a second one.
-3. `git -C <path> branch -a | grep plan/{plan-id-kebab}` to detect already-pushed phase branches (`<path>` = main checkout or worktree per `run_options.use_worktree`).
-4. Cross-reference with the plan's phase list.
-5. Confirm 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.
-- **Orchestrator owns git topology.** Subagents commit but never branch, push, {{PR_RULE_TAIL}}.
-{{COAUTHOR_RULE_LINE}}
-- **Trust the plan's per-phase model suggestion.**
-- **Don't re-implement what a project skill encodes.**
-{{UI_E2E_RULE_LINE}}
-- **Two-tier verification, in order, every phase.** Inner scoped, outer full repo.
-- **Three-layer review, every phase, no exceptions.**
-- **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](#1i-per-phase-pause-gate-opt-in); `run_options.generate_inline_comments` controls whether the [Open PR via context file](#1f-open-pr-via-context-file) step drafts inline comments (always writes the file when that step runs at all — empty comments when off); `run_options.use_worktree` controls whether the [Provision worktree](#step-05--provision-worktree-when-run_optionsuse_worktree--true) step runs and whether every later `git` / lint / test / build / migrate call uses the worktree path.
-- **One worktree per plan run.** When `use_worktree = true`, provision once in the [Provision worktree](#step-05--provision-worktree-when-run_optionsuse_worktree--true) step 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 they're ready (after reviewer feedback is addressed, after the PR merges, etc.).
-- **Catch stray main-checkout writes when `use_worktree = true`.** A subagent can resolve a path back to the main checkout and silently edit there, leaving the change out of the phase commit. Layer 1 runs `git -C <main-checkout-path> status --short` after every implementer and fixer; any tracked modification is a BLOCKER — recover the intent, re-dispatch to the worktree, then restore the main checkout clean. `<main-checkout-path>` is the repo root the skill was invoked from, never `run_options.worktree_path`.
-- **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. The file is durable; the script is the publisher.
-{{DEPENDENCY_LICENSE_RULE_LINE}}
-- **[Open PR via context file](#1f-open-pr-via-context-file) gating** = combination of project PR policy ({{PR_POLICY_BLOCK}}) and `generate_inline_comments`. See the matrix in that step. Skip it entirely only when policy = branches only AND comments = off.
-- **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. `§N` references are hard to read for humans and brittle when section numbering shifts.
-
-## Quick checklist (orchestrator, per phase)
-
-- [ ] Plan parsed; structured fields cached.
-- [ ] Cross-repo + flag-removal phases identified + deferred.
-- [ ] `run_options.use_worktree` resolved; [Provision worktree](#step-05--provision-worktree-when-run_optionsuse_worktree--true) ran when `true` (worktree provisioned + summary captured + user confirmed); skipped when `false`.
-- [ ] Current phase: prompt composed with **Goals + Non-goals** + **Guiding Decisions** + relevant **Data Model Changes** subsection + tracking summaries + this phase's body (plus the worktree block when `use_worktree = true`).
-- [ ] Model picked from `**Suggested AI model**:` line (cheapest available); plan tier recorded.
-- [ ] Subagent spawned, report received.
-- [ ] Inner loop green: scoped lint + new tests individually + scoped suite.
-- [ ] **Outer gate green:** `{{BUILD_CMD}}` AND `{{TEST_CMD}}`{{E2E_OUTER_GATE_CHECKLIST}} both passed.
-- [ ] Layer 1 review: full diff read; no scope creep; no secrets; outer gate confirmed{{COAUTHOR_CHECKLIST_NOTE}}; when `use_worktree = true`, `git -C <main-checkout-path> status --short` clean (no stray main-checkout writes) after the implementer and after every fixer.
-- [ ] Layer 2 review: every "Changes" ticked; every "Tests" materialized; acceptance line satisfiable; conventions, reusable skills, e2e + screenshot compliance (if applicable), flag wiring all checked.
-- [ ] Layer 3 review: adversarial review run; BLOCKERs fixed; SHOULD-FIX either fixed or noted.
-- [ ] After any fix-up: Layers 1 + 2 + outer gate re-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`):
-  - [ ] PR-context 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) surfaced with `(file:line)` list.
-  - [ ] Hard failure (exit 2) surfaced; file left `status: pending`.
-- [ ] `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.
-- [ ] If `run_options.pause_between_phases = false`: 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.