vinta-ai-workflows 0.1.7 → 0.2.0-alpha2

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

@@ -0,0 +1,198 @@
+# Modular-commits substitutions for `implement-plan-template.md`
+
+This file holds the substitution bodies for the `{{COMMIT_STRATEGY_*}}` placeholder family when `policies.commit_strategy = modular-commits`. The `stacked-branches` substitutions are inline in the parent placeholder table in [SKILL.md](../SKILL.md). The `ask` variant emits **both** the stacked and the modular bodies gated by inline runtime markers — see [Phase 4 ask-mode substitutions](#ask-mode-substitutions) at the bottom.
+
+Each section below is delimited by `<!-- substitution: {{PLACEHOLDER}} -->` markers so derive-skills can extract the block by name. The block's content is everything between the open and close markers, **excluding** the markers themselves.
+
+## `{{BRANCH_NAMING_BLOCK}}` (modular)
+
+<!-- substitution-begin: BRANCH_NAMING_BLOCK -->
+Branch naming: `plan/{plan-id-kebab}` (one branch for the whole plan — no per-phase suffix).
+
+**First executed phase** (branches from `{{DEFAULT_BRANCH}}`):
+```bash
+git checkout {{DEFAULT_BRANCH}}
+git pull --ff-only
+git checkout -b plan/{plan-id-kebab}
+# subagent's atomic unit commits land on this branch
+git push -u origin plan/{plan-id-kebab}
+```
+
+**Subsequent phases** (stay on the same plan branch — no new branch):
+```bash
+git checkout plan/{plan-id-kebab}
+# subagent's atomic unit commits land on this branch
+git push origin plan/{plan-id-kebab}
+```
+
+The branch carries every phase's commits in plan order. Reviewers read the commit log top-to-bottom as a table of contents of the implementation.
+<!-- substitution-end: BRANCH_NAMING_BLOCK -->
+
+## `{{PER_PHASE_COMMIT_BLOCK}}` (modular)
+
+<!-- substitution-begin: PER_PHASE_COMMIT_BLOCK -->
+7. **Plan commit units before staging.** List the logical units this phase produces (e.g. `3 services + 1 use case update + 1 init export`). Each unit = **one** commit. Tests for that unit travel **in the same commit** as the code they test — never a separate commit.
+8. For each unit, in order:
+   a. Stage exactly that unit's files: `git add <explicit paths>` (NEVER `git add -A` — {{ANTI_GIT_ADD_ALL_REASON}}). Tests for the unit go in the same `git add`.
+   b. Commit with the repo's commit_style — see the **Commit Boundaries** + **Commit Message Format** tables below.
+   c. Don't bundle two units in one commit. If the commit message needs the word "and" to cover the diff, **split** — see **Red Flags** below.
+9. {{COAUTHOR_INSTRUCTION_LINE}}
+10. {{PUSH_INSTRUCTION_LINE}} — push all unit commits at once at end of phase.
+
+### Modular-commits discipline (load-bearing — re-read every phase)
+
+Commit each logical unit independently as you complete it. One service = one commit. One use-case update = one commit. Tests travel with the code they test.
+
+The commit list becomes a **table of contents** for reviewers — they can read the commit titles before touching any code and already understand the shape and sequence of the implementation.
+
+#### Commit Boundaries
+
+| Unit | When to commit | Example commit message |
+|------|---------------|------------------------|
+| New service | Service + its unit tests complete | {{MODULAR_EXAMPLE_NEW_SERVICE}} |
+| Use case update | Use case wires in new services, with integration tests | {{MODULAR_EXAMPLE_USE_CASE}} |
+| Init / exports | After exposing new symbols | {{MODULAR_EXAMPLE_INIT}} |
+| Serializer field | Field + validation + tests | {{MODULAR_EXAMPLE_SERIALIZER}} |
+| Refactor / cleanup | Standalone cleanup pass only | {{MODULAR_EXAMPLE_REFACTOR}} |
+| Bug fix | Fix + regression test | {{MODULAR_EXAMPLE_BUGFIX}} |
+
+Tests for a unit belong **in the same commit** as that unit. Never commit tests separately.
+
+#### Commit Message Format
+
+{{MODULAR_COMMIT_MESSAGE_FORMAT_BLOCK}}
+
+#### Red Flags — Split the Commit
+
+- Commit message needs "and" to cover everything in it.
+- You are staging files from two different units.
+- A reviewer cannot understand the diff without seeing the other commits first.
+
+#### Common Rationalizations
+
+| Rationalization | Reality |
+|----------------|---------|
+| "I'll commit everything at the end" | Reviewers read commit-by-commit; one giant diff hides intent. |
+| "The user can squash later" | Squashing destroys the logical history this discipline exists to preserve. |
+| "It's faster to do one commit" | Planning units takes 2 minutes; reviewing a 2000-line blob takes much longer. |
+| "The changes are all related" | Related ≠ same unit. Services that depend on each other still get separate commits. |
+<!-- substitution-end: PER_PHASE_COMMIT_BLOCK -->
+
+### Conditional example messages (driven by `policies.commit_style`)
+
+derive-skills resolves the six `{{MODULAR_EXAMPLE_*}}` placeholders + the `{{MODULAR_COMMIT_MESSAGE_FORMAT_BLOCK}}` from this table when rendering `{{PER_PHASE_COMMIT_BLOCK}}`:
+
+| Placeholder | `commit_style = conventional` | `commit_style = imperative` | `commit_style = other` |
+|---|---|---|---|
+| `{{MODULAR_EXAMPLE_NEW_SERVICE}}` | `` `feat(record-copy): add service to copy files between records` `` | `Created service to copy files between records` | both — `` `feat(record-copy): add service to copy files between records` `` (Conventional) or `Created service to copy files between records` (imperative) |
+| `{{MODULAR_EXAMPLE_USE_CASE}}` | `` `feat(record-copy): wire optional fields into record copy use case` `` | `Updated record copy use case to call optional fields services` | both |
+| `{{MODULAR_EXAMPLE_INIT}}` | `` `chore(record-copy): expose new services in init file` `` | `Updated init file to expose new copy services` | both |
+| `{{MODULAR_EXAMPLE_SERIALIZER}}` | `` `feat(record-copy): add copy flag for tags to serializer` `` | `Added copy flag for tags to serializer` | both |
+| `{{MODULAR_EXAMPLE_REFACTOR}}` | `` `refactor(record-copy): apply shared batch size to copy services` `` | `Applied batch size constant to all copy services` | both |
+| `{{MODULAR_EXAMPLE_BUGFIX}}` | `` `fix(reports): include archived rows in summary section` `` | `Fixed missing archived rows in summary section` | both |
+| `{{MODULAR_COMMIT_MESSAGE_FORMAT_BLOCK}}` | the **Conventional Commits** block below | the **Verb-first imperative** block below | both blocks under `### Option A` / `### Option B` headings + a `Pick one style and use it consistently within the plan branch` lead-in |
+
+#### Conventional Commits block (used when `commit_style = conventional` or `other`)
+
+Spec: [conventionalcommits.org](https://www.conventionalcommits.org/en/v1.0.0/)
+
+```
+<type>(<scope>): <description>
+
+[optional body: non-obvious why, constraints, or side effects — omit if obvious]
+```
+
+| Type | Use for |
+|------|---------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring without behavior change |
+| `chore` | Maintenance — init files, exports, config |
+| `docs` | Documentation only |
+
+**Scope:** the feature area or module (e.g. `reports`, `record-copy`). Optional but recommended.
+
+**Breaking changes:** append `!` before the colon — `feat(auth)!: replace session tokens`.
+
+```
+feat(record-copy): add service to copy files between records
+feat(record-copy): add service to copy tags between records
+feat(record-copy): wire optional fields into record copy use case
+chore(record-copy): expose new services in init file
+refactor(record-copy): apply shared batch size to copy services
+```
+
+#### Verb-first imperative block (used when `commit_style = imperative` or `other`)
+
+```
+<Verb> <what was done> [for/to/between <context>]
+
+[optional body: non-obvious why, constraints, or side effects — omit if obvious]
+```
+
+**Preferred verbs:** Created, Updated, Added, Removed, Fixed, Refactored.
+
+```
+Created service to copy files between records
+Created service to copy tags between records
+Updated record copy use case to call optional fields services
+Updated init file to expose new copy services
+Applied batch size constant to all copy services
+```
+
+#### Bad (both styles)
+
+```
+WIP
+add stuff
+Implement full record copy feature   ← too broad, should be split
+```
+
+## `{{PR_OPEN_TIMING_BLOCK}}` (modular)
+
+<!-- substitution-begin: PR_OPEN_TIMING_BLOCK -->
+**PR opens once — after Phase 1 passes review.** Subsequent phases push their atomic unit commits to the same plan branch (`plan/{plan-id-kebab}`); the orchestrator re-runs [open-pr.sh](../foundation-skills/open-pr-from-context/scripts/open-pr.sh) against the same plan-level prs-context file at `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md`. The script is idempotent for already-open PRs — it updates the body, appends new inline comments, and posts an `Phase {N} complete — pushed M commits` PR comment.
+
+<!-- substitution-end: PR_OPEN_TIMING_BLOCK -->
+
+## `{{COMMIT_STRATEGY_CHECKLIST_BLOCK}}` (modular)
+
+<!-- substitution-begin: COMMIT_STRATEGY_CHECKLIST_BLOCK -->
+- [ ] Commit units listed upfront before any staging.
+- [ ] Each commit covers exactly one logical unit (no "and" in commit messages).
+- [ ] Tests landed in the same commit as the code they cover (never a separate test-only commit).
+- [ ] All unit commits pushed to `plan/{plan-id-kebab}` at end of phase.
+<!-- substitution-end: COMMIT_STRATEGY_CHECKLIST_BLOCK -->
+
+## Other modular substitutions (single-line — listed for completeness)
+
+| Placeholder | Modular substitution |
+|---|---|
+| `{{BRANCH_PUSH_HEADING}}` | `Push to plan branch` |
+| `{{BRANCH_NAMING_PATTERN_SUMMARY}}` | ``plan branch (one branch for whole plan: `plan/{plan-id-kebab}`)`` |
+| `{{PRS_CONTEXT_FILE_PATH_DESCRIPTION}}` | `` a single `.vinta-ai-workflows/prs-context/{feature-kebab}/plan.md` file (one PR per plan, not per phase) `` |
+| `{{TRACKING_BRANCH_FIELD}}` | `top-level \`plan_branch:\` field` |
+| `{{TRACKING_PHASE_BRANCH_FIELD}}` | empty string (no per-phase branch under modular) |
+| `{{FINAL_REPORT_BRANCH_SUMMARY}}` | ``single plan branch `plan/{plan-id-kebab}` with commit log organized by phase`` |
+| `{{BRANCH_CHECKLIST_LINE}}` | `Plan branch updated with phase commits; pushed.` |
+| `{{COMMIT_STRATEGY_STEP0_QUESTION}}` | empty string (modular is set as the project default; nothing to ask) |
+| `{{COMMIT_STRATEGY_STEP0_TRAILER}}` | empty string |
+| `{{COMMIT_STRATEGY_CONFIRM_NOTE}}` | empty string |
+
+## Ask-mode substitutions
+
+When `policies.commit_strategy = ask`, derive-skills renders **both** the stacked-branches and the modular-commits bodies for each multi-line placeholder, gated by inline runtime markers the agent reads at execution time:
+
+```markdown
+**If `run_options.commit_strategy_resolved = "modular-commits"`:**
+
+<modular substitution body here>
+
+**Else (`run_options.commit_strategy_resolved = "stacked-branches"`):**
+
+<stacked substitution body here>
+```
+
+Single-line placeholders under ask use the same gating pattern but inline (`If modular: <a> · Else (stacked): <b>`).
+
+For the Step 0 question itself (`{{COMMIT_STRATEGY_STEP0_QUESTION}}`), the ask substitution is the AskUserQuestion block documented in the parent placeholder table in [SKILL.md](../SKILL.md) — same content used to populate the resolved value.

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

@@ -34,17 +34,44 @@ Parse once, reuse for every phase:
    - **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 two opt-in questions** via `AskUserQuestion`. Both default to off; record both answers in tracking under `run_options`:
+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`.
 
-   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.
+   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).
 
-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 (default: `plan/{plan-id-kebab}/phase-{phase-id}`), captured `run_options.pause_between_phases` + `run_options.generate_inline_comments`{{PR_REMINDER_LINE}}.
+      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).
 
-   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`.
+      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
 
@@ -60,9 +87,20 @@ 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}
@@ -82,6 +120,8 @@ You are implementing {phase.id}: {phase.title} of plan {plan.id}.
 
 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.
@@ -95,10 +135,7 @@ Project skills available: {{PROJECT_SKILLS_LIST}}
    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.
-7. Stage right files (NEVER `git add -A` — {{ANTI_GIT_ADD_ALL_REASON}}). Stage explicitly: `git add {{STAGE_PATTERN}}`.
-8. Commit with the repo's style — look at `git log -10 --oneline` first. {{COMMIT_STYLE_LINE}}.
-9. {{COAUTHOR_INSTRUCTION_LINE}}
-10. {{PUSH_INSTRUCTION_LINE}}
+{{PER_PHASE_COMMIT_BLOCK}}
 
 ## Required output (single final report)
 - Status: SUCCESS or FAILURE (and why).
@@ -156,6 +193,12 @@ Three layers, all required, in order. The orchestrator never edits — every iss
 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
@@ -191,29 +234,17 @@ Reviewer finds nothing on a >300-LoC multi-file phase → suspicious. Read once
 
 ### 1e. {{BRANCH_PUSH_HEADING}}
 
-Branch naming: `plan/{plan-id-kebab}/phase-{phase.id}`.
+**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.
 
-**First executed phase** (branches from `{{DEFAULT_BRANCH}}`):
-```bash
-git checkout {{DEFAULT_BRANCH}}
-git pull --ff-only
-git checkout -b plan/{plan-id-kebab}/phase-{phase.id}
-# subagent's commits land on this branch
-git push -u origin plan/{plan-id-kebab}/phase-{phase.id}
-```
-
-**Subsequent phases** (stacked on the previous phase's branch):
-```bash
-git checkout plan/{plan-id-kebab}/phase-{prev.id}
-git checkout -b plan/{plan-id-kebab}/phase-{phase.id}
-git push -u origin plan/{plan-id-kebab}/phase-{phase.id}
-```
+{{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 a `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md` file + 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.
+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:
 
@@ -273,7 +304,7 @@ Two project-level signals decide the actual behavior:
 
 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, completed-phases (with status, model, branch, base, e2e+screenshots if any, 5–15 line summary), current phase, remaining phases, deferred phases.
+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.
 
@@ -314,17 +345,21 @@ What this skill does instead:
 
 User invokes the skill against a partially-done plan:
 
-1. Read `{{PLAN_DIR}}/TRACKING_{plan-id}.md` if present.
-2. `git branch -a | grep plan/{plan-id-kebab}` to detect already-pushed phase branches.
-3. Cross-reference with the plan's phase list.
-4. Confirm resumption point with the user.
+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: branches pushed (with bases, in stack order); for UI-flow phases — list of `pr-screenshots/` files (if applicable); deferred phases (cross-repo + flag-removal); next steps for the human.
+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.
 
@@ -344,8 +379,12 @@ After all executable phases complete:
 - **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).
+- **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.
 
@@ -353,16 +392,18 @@ After all executable phases complete:
 
 - [ ] Plan parsed; structured fields cached.
 - [ ] Cross-repo + flag-removal phases identified + deferred.
-- [ ] Current phase: prompt composed with **Goals + Non-goals** + **Guiding Decisions** + relevant **Data Model Changes** subsection + tracking summaries + this phase's body.
+- [ ] `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}}.
+- [ ] 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.
-- [ ] Stacked branch created; pushed.{{PR_CHECKLIST_NOTE}}
+- [ ] {{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.

package/skills/vinta-install-ai-tools-setup/resources/setup-ai-tools.mjs

@@ -204,13 +204,23 @@ function autoGenHeader(srcPath, comment = '#') {
 
 // ── Vendor emitters ──────────────────────────────────────────────────────
 
+// Fold a (possibly multi-line) value into a YAML-safe single-line scalar.
+// The agent `description` in the source YAML is authored as multi-line prose;
+// interpolated raw into markdown frontmatter it produces invalid YAML
+// (unindented continuation lines + embedded colons), so the harness silently
+// skips the agent. A JSON string is also a valid YAML double-quoted flow
+// scalar, so JSON.stringify gives correct escaping for free.
+function yamlInlineScalar(value) {
+  return JSON.stringify(String(value).replace(/\s+/g, ' ').trim());
+}
+
 function emitClaude(name, doc, body) {
   const cfg = resolveVendorConfig(doc, 'claude');
   const lines = [
     '---',
     autoGenHeader(`ai-tools/agents/${name}.yaml`),
     `name: ${doc.name}`,
-    `description: ${doc.description}`,
+    `description: ${yamlInlineScalar(doc.description)}`,
   ];
   if (cfg.tools) lines.push(`tools: ${cfg.tools}`);
   if (cfg.model) lines.push(`model: ${cfg.model}`);
@@ -224,7 +234,7 @@ function emitCursor(name, doc, body) {
     '---',
     autoGenHeader(`ai-tools/agents/${name}.yaml`),
     `name: ${doc.name}`,
-    `description: ${doc.description}`,
+    `description: ${yamlInlineScalar(doc.description)}`,
   ];
   if (cfg.model) lines.push(`model: ${cfg.model}`);
   if (cfg.readonly !== undefined) lines.push(`readonly: ${cfg.readonly}`);
@@ -238,7 +248,7 @@ function emitCopilot(name, doc, body) {
   const lines = [
     '---',
     autoGenHeader(`ai-tools/agents/${name}.yaml`),
-    `description: ${doc.description}`,
+    `description: ${yamlInlineScalar(doc.description)}`,
   ];
   if (cfg.tools) lines.push(`tools: ${JSON.stringify(cfg.tools)}`);
   if (cfg.model) lines.push(`model: ${cfg.model}`);

package/skills/vinta-write-agents-md/SKILL.md

@@ -19,6 +19,7 @@ The canonical project-conventions document. Read by every AI tool. Single source
    - **Keep as-is, link from AGENTS.md** — leave the file untouched; add a `## See also` reference to it from the new AGENTS.md and copy only the high-level pointer (one sentence + link).
    - **Replace from scratch** — discard the old content; draft fresh from inventory + interview. Note the discarded files in the run summary so the user can verify nothing important was lost.
 3. Interview answers (Step 0 below).
+4. `.vinta-ai-workflows.yaml` (`policies.dependency_licenses`) — drives the **Dependency licenses** section. The bootstrap interview captures enforcement + forbidden SPDX list + per-package overrides + free-form notes; this skill only reads and renders. Don't re-interview the user about license policy — if the config block is missing, route the user back to [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md) Step 0 (Project conventions → license policy).
 
 ## Step 0 — Interview before drafting
 
@@ -134,6 +135,30 @@ VAR_TWO
 ...
 ```
 
+## Dependency licenses
+
+{Rendered from `policies.dependency_licenses` in `.vinta-ai-workflows.yaml`. Skip when the block is absent. When `enforcement: off`, render a single line: "No license check enforced." When `enforcement: block` or `warn`, render:}
+
+**Enforcement:** {`block` — refuse install + ask user before override / `warn` — proceed but flag in phase report}.
+
+**Forbidden SPDX licenses** (any new third-party dep matching these must be checked before install):
+
+{Bullet list of `forbidden_spdx` entries as inline SPDX IDs.}
+
+**Pre-install check.** Before running `npm add` / `pnpm add` / `pip install` / `poetry add` / `uv add` / `cargo add` / `go get` (or equivalent) for any new dep, look up the package's declared license (`npm view <pkg> license`, PyPI metadata, `cargo metadata`, the package's repo `LICENSE`) and compare to the list above. If the license is in the list and the `(package, license)` pair is not in **Approved overrides**, stop and surface the conflict to the user.
+
+**Unknown / undeclared license.** When the lookup returns no license, an empty value, `UNKNOWN`, `SEE LICENSE IN <file>`, or only an unstructured `LICENSE` file with no SPDX identifier, **stop and ask the user** regardless of the enforcement mode above. Don't guess, don't fall back to "assume MIT" — the package may be all-rights-reserved by default. The user picks one of: skip the dep, treat as forbidden, or record an `allowed_overrides` entry with the SPDX they independently confirmed off-channel.
+
+{When `allowed_overrides` is non-empty:}
+
+**Approved overrides** (these forbidden-license deps are explicitly accepted):
+
+| Package | License | Reason |
+|---|---|---|
+| {package} | {SPDX} | {reason} |
+
+{When `notes` is non-empty, render verbatim under a `**Notes.**` paragraph.}
+
 ## Error / Exception Tracking
 
 {If Sentry / Bugsnag / Datadog detected: one section with init pattern + tracing examples. Else: omit.}