vinta-ai-workflows 0.1.7 → 0.2.0-alpha2

package/CHANGELOG.md

@@ -5,6 +5,195 @@ All notable changes to `vinta-ai-workflows` are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — YYYY-MM-DD
+
+<!-- pre-release: 0.2.0-alpha2 on 2026-06-13 -->
+
+### Changed
+
+- **Fixed bug on setup-ai-tools.mjs**: Sub agents were being generated 
+with an invalid description and were not being loaded by claude-code and 
+possibly other AI tools.
+
+- **`implement-plan` template — stray main-checkout-write guard (only
+  when `run_options.use_worktree = true`).** A subagent told to work
+  inside the worktree can resolve an absolute path back to the **main
+  checkout** and silently edit files there; because worktrees have
+  independent working trees those edits never reach the phase commit —
+  they sit as uncommitted thrash in the main checkout and read as a
+  silent implementer/fixer failure. Layer 1 mechanical checks gain a new
+  item: 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 — recover intent
+  via `git -C <main-checkout-path> diff`, re-dispatch the agent with an
+  explicit worktree-path instruction if the change belongs there, then
+  `git -C <main-checkout-path> restore` so the main checkout returns
+  clean between phases. `<main-checkout-path>` is the repo root the skill
+  was invoked from, never `run_options.worktree_path`. Skipped entirely
+  when `use_worktree = false`. Mirrored in the per-phase Quick checklist
+  Layer 1 line and a new **Important rules** bullet.
+
+<!-- pre-release: 0.2.0-alpha1 on 2026-06-12 -->
+
+### Added
+
+- **Third-party dependency license policy captured at bootstrap, surfaced
+  to AI agents at implementation time.** `vinta-bootstrap-ai-tools` Step 0
+  group **C. Project conventions** gains question 7 — enforcement
+  (`block` (default) / `warn` / `off`), a confirm-and-edit prompt for the
+  forbidden SPDX list (seed: `GPL-2.0-only`, `GPL-3.0-only`,
+  `AGPL-3.0-only`, `SSPL-1.0`), per-package overrides, and free-form
+  notes. Captured in a new `policies.dependency_licenses` block of
+  `vinta-ai-workflows-config.v1.schema.json`. Consumers:
+  - `vinta-write-agents-md` renders a new **Dependency licenses** section
+    in `ai-tools/AGENTS.md` (enforcement mode + forbidden list + approved
+    overrides table + notes + pre-install check pointers like
+    `npm view <pkg> license`, PyPI metadata, etc.).
+  - `vinta-derive-skills` substitutes three new placeholders into the
+    `implement-plan` + `amend-plan` templates: `{{DEPENDENCY_LICENSE_BLOCK}}`
+    (top-level "Adding new third-party dependencies" section directly
+    before Working instructions — canonical body at
+    [vinta-derive-skills/resources/dependency-license-block.md](skills/vinta-derive-skills/resources/dependency-license-block.md)),
+    `{{DEPENDENCY_LICENSE_LAYER1_CHECK}}` (reviewer Layer 1 mechanical
+    check that greps the manifest diff for forbidden licenses), and
+    `{{DEPENDENCY_LICENSE_RULE_LINE}}` (an Important-rules bullet).
+  All three placeholders render the empty string when
+  `enforcement: off` or the config block is absent — projects that opt
+  out get no extra prose in their rendered skills. `enforcement: block`
+  refuses the install + asks the user to acknowledge before recording an
+  `allowed_overrides[]` entry and re-running; `warn` proceeds but flags
+  in the phase report. **Missing / `UNKNOWN` / undeclared license is
+  always handled as a stop-and-ask, regardless of enforcement mode** —
+  unknown ≠ permissive, so the subagent surfaces the gap (registry
+  lookup output, upstream URL) and asks the user to pick `skip the dep`
+  / `treat as forbidden` / `record an `allowed_overrides` entry with an
+  off-channel-confirmed SPDX`. Same behaviour reinforced in the Layer 1
+  reviewer check: undeclared license = BLOCKER, no enforcement-mode
+  downgrade.
+  
+- **New `policies.commit_strategy` field in `.vinta-ai-workflows.yaml`**
+  (`stacked-branches` | `modular-commits` | `ask`, default
+  `stacked-branches`). Drives how the rendered `implement-plan` skill
+  structures branches and commits across phases:
+  - `stacked-branches` — current behavior. One branch + one PR per
+    phase, stacked on top of each other.
+  - `modular-commits` — one branch + one PR for the whole plan; each
+    phase contributes multiple atomic commits (one per logical unit:
+    service, use-case wire-up, init/exports, serializer field,
+    refactor, fix). Tests travel in the same commit as the code they
+    test. The commit list becomes a table of contents for reviewers.
+  - `ask` — `implement-plan` prompts the user at Step 0 (alongside
+    `pause_between_phases` / `generate_inline_comments`) and caches the
+    resolved value in `TRACKING_{plan-id}.md` under
+    `run_options.commit_strategy_resolved`.
+  Additive on schema v1 — existing configs without the field default
+  to `stacked-branches` at read time (backward-compatible). Bootstrap
+  interview captures the answer in **C. Project conventions**.
+
+- **New optional foundation skill: `prepare-worktree`** (copied verbatim
+  to `ai-tools/skills/prepare-worktree/SKILL.md` per project, opt-in via
+  the bootstrap **Optional foundation skills** interview, new
+  `prepare-worktree` question). Source:
+  [skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md).
+  Provisions a fully-runnable git worktree for parallel feature work so a
+  long-running plan (or experiment) can build, test, lint, migrate, and
+  hit databases without disturbing the main checkout — or other parallel
+  worktrees on the same machine. Walks the project's `.gitignore` +
+  package manifests + env templates + docker config and decides per
+  ignored path whether to **symlink** (read-only-ish reuse), **copy**
+  (defensive, when the feature mutates the path), or **fork** (state
+  that would corrupt main if shared — dev DB, test DB, docker-compose
+  project name). Reads the active plan to bias decisions: dep churn
+  flips dep dirs to copy/reinstall; migrations flip the dev DB to fork
+  and run them once; new env vars flip `.env` from symlink to copy +
+  mutate; compose changes flip the network strategy. Drops a per-worktree
+  summary YAML at `.vinta-ai-workflows/worktrees/<name>.yaml` + a
+  `WORKTREE.md` at the worktree root so teardown is mechanical (no
+  decision lives only in conversation memory). Bucket A (copy verbatim) —
+  body is project-agnostic; per-project variability lives in
+  `skills.prepare-worktree.*` config (worktree root, deps strategy,
+  compose-network strategy, test-DB strategy, summary dir).
+
+- **`implement-plan` Step 0 question (c) — "Run phases in a worktree?"**.
+  New opt-in: when the user picks `Yes`, the orchestrator runs
+  `prepare-worktree` **once** at the start of the plan (new
+  **Provision worktree** step between Step 0 and Step 1), records
+  `worktree_path` / `worktree_branch` / `worktree_summary` in the
+  tracking file, and threads them into every phase's subagent prompt +
+  every `git` call in the **Branch + push** step. **One worktree per
+  plan run** — every phase branch stacks inside the same worktree; the
+  skill never provisions a second one mid-plan. Mid-plan resumes detect
+  the worktree from tracking and reuse it (asking only when the worktree
+  is missing). When `foundation_skills.prepare-worktree` is `disabled`,
+  the question is skipped and `run_options.use_worktree` is forced to
+  `false` with a one-line note pointing at `vinta-sync-ai-tools` to
+  enable later. Failure modes are explicit — prepare-worktree errors
+  never fall back silently to the main checkout; the user picks `Retry`
+  / `Run in main` / `Stop`.
+
+- **`.vinta-ai-workflows.yaml` config additions for `prepare-worktree`**:
+  - `foundation_skills.prepare-worktree: enabled | disabled` — sticky
+    opt-in like every other foundation skill.
+  - `skills.prepare-worktree.worktree_root: string` (default
+    `.claude/worktrees` for claude-code-primary projects;
+    `../<repo>-wt-` sibling-dir layout otherwise) — where new worktrees
+    land. The skill resolves `<root>/<name>` per provisioning call.
+  - `skills.prepare-worktree.deps_strategy: symlink | copy | reinstall`
+    (default `symlink`) — default for dep dirs (`node_modules/`,
+    `vendor/`, `venv/`) when the active plan does NOT install new deps.
+    The skill auto-flips to `reinstall` when it detects dep churn in the
+    plan body.
+  - `skills.prepare-worktree.compose_network: per-worktree | shared-external | host`
+    (default `per-worktree`) — docker-compose networking strategy.
+    `shared-external` joins an externally-declared network so the
+    worktree can reach main's compose services (queues, caches, search
+    indexes that are expensive to spin twice).
+  - `skills.prepare-worktree.test_db_strategy: fork-on-schema-change | always-fork | share`
+    (default `fork-on-schema-change`) — when to fork the test DB per
+    worktree. `share` is only safe for solo work (parallel runs flake).
+  - `skills.prepare-worktree.summary_dir: string` (default
+    `.vinta-ai-workflows/worktrees`) — where per-worktree summary YAMLs
+    land. Covered by the umbrella `.vinta-ai-workflows/` gitignore.
+  - `run_options.implement-plan.use_worktree: boolean` (default
+    `false`) — suggested default shown for the Step 0 question (c)
+    above; per-run prompt always asks. Flipped to `true` at bootstrap
+    when the user opts in via the `prepare-worktree` follow-up.
+
+- **Bootstrap interview — new `prepare-worktree` question** under
+  **Optional foundation skills**, plus four short follow-ups (worktree
+  root, default deps strategy, default test-DB strategy, and the
+  `implement-plan` default for question (c)). The **Optional foundation
+  skills** opener switched from "four skills" to "five skills"
+  accordingly. Outputs tree updated to list
+  `ai-tools/skills/prepare-worktree/SKILL.md` as an opt-in foundation
+  skill. The **Existing AI artifacts** disposition flow's
+  `foundation-shape` name list (which gates the
+  `Replace with Vinta foundation version` option) gained
+  `prepare-worktree`.
+
+- **`vinta-derive-skills` — Always copy bucket** gains a row for
+  `prepare-worktree` (verbatim copy). The **Optional — ask the user**
+  bucket also gets a row covering the opt-in interview + the four
+  follow-ups; this is the same compose pattern as `add-one-off-script`
+  (verbatim copy, gated by ask-first). Foundation-shape lists in both
+  "Reconcile against existing skills" + Rules sections extended with
+  `prepare-worktree`.
+
+### Changed
+
+- **`implement-plan` template**: the Step 0 opt-in questions block grew
+  from two questions to three (added (c) for worktree opt-in); a new
+  **Provision worktree** step sits between Step 0 and Step 1; the
+  per-phase prompt (`Prepare agent prompt` step) carries a worktree
+  block when `use_worktree = true`; the `Branch + push` step's branch
+  and push commands now prefix with `git -C <worktree_path>` when
+  applicable; tracking schema (`Update tracking file` step) gains
+  `run_options.worktree_path` / `worktree_branch` / `worktree_summary`;
+  Re-running mid-plan flow learned to detect + reuse the worktree;
+  Step 2 final report surfaces the teardown command (never auto-runs
+  it). Three new entries in the **Important rules** section codify the
+  one-worktree-per-plan-run invariant + the no-silent-fallback rule.
+
 ## [0.1.7] — 2026-06-01
 
 ### Added
@@ -35,6 +224,21 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **`implement-plan` template rendered with new
+  `{{COMMIT_STRATEGY_*}}` placeholder family.** Branch naming, per-phase
+  push, subagent commit instructions, PR-open timing, tracking-file
+  branch field, and final-report branch summary now swap based on
+  `policies.commit_strategy`. Under `ask`, both code paths render in
+  the same body gated by `run_options.commit_strategy_resolved` —
+  mirrors the existing `pause_between_phases` /
+  `generate_inline_comments` opt-in pattern.
+- **`amend-plan` refuses to run when
+  `policies.commit_strategy != stacked-branches`** and points users at
+  appending a new phase via `implement-plan` (or hand-crafting the
+  rebase). Modular-commits amendment support is tracked as a follow-up
+  — rewriting an arbitrary number of inline commits on a shared branch
+  is out of scope for this release.
+
 - **Replaced all `§N` shorthand cross-references with named section
   links across the repo.** `§1`, `§4.3`, `§1f`, `§A.3`, etc. were
   unreadable for humans (forced readers to flip back to the source doc

package/README.md

@@ -124,6 +124,8 @@ git push -u origin plan/<feature-kebab>/phase-2
 
 Each phase's PR (or branch, depending on the project's PR policy captured at bootstrap) targets the previous phase's branch, not `main`. This keeps the diff per PR scoped to a single phase, makes review manageable, and lets the team merge phases sequentially as approvals land — earlier phases ship to production while later ones are still in review.
 
+**Alternative: modular commits.** Teams that prefer one branch + one PR per plan can set `policies.commit_strategy: modular-commits` in `.vinta-ai-workflows.yaml`. Under that mode, every phase pushes its **atomic unit commits** (one per service, use-case wire-up, init export, serializer field, refactor, or bug fix — tests in the same commit as code) to a single `plan/<feature-kebab>` branch; the PR opens once after Phase 1 review and gets updated as later phases push. The third option, `commit_strategy: ask`, prompts `implement-plan` at Step 0 (alongside the existing `pause_between_phases` / `generate_inline_comments` opt-ins) and caches the answer in the tracking file. Default is `stacked-branches` — the model documented above. See [`schemas/vinta-ai-workflows-config.v1.schema.json`](schemas/vinta-ai-workflows-config.v1.schema.json) for the field definition.
+
 **Tracking file** — `ai-plans/TRACKING_<feature-kebab>.md`. The orchestrator writes it from `git diff` + the agent's report (not the agent's narration). Records: completed phases (status, model used, branch, base, e2e+screenshots when applicable, 5–15 line summary), current phase, remaining phases, deferred phases. Acts as the durable context handoff between phase prompts. Deleted on plan completion.
 
 **Phases the orchestrator never auto-executes:**
@@ -257,7 +259,7 @@ That's it. The sync skill walks every release between the project's recorded ver
 
 ### How it stays safe
 
-The single source of truth is `.vinta-ai-workflows.yaml` at the repo root (written at bootstrap, schema: [`schemas/vinta-ai-workflows-config.v1.schema.json`](schemas/vinta-ai-workflows-config.v1.schema.json)). It records every opt-in the project made — which foundation skills are `enabled`, which stacks are applied, which vendors are wired, which policies (PR creation, AI co-author, commit style) hold. `vinta-sync-ai-tools` reads this file and uses it to classify every upstream change into one of:
+The single source of truth is `.vinta-ai-workflows.yaml` at the repo root (written at bootstrap, schema: [`schemas/vinta-ai-workflows-config.v1.schema.json`](schemas/vinta-ai-workflows-config.v1.schema.json)). It records every opt-in the project made — which foundation skills are `enabled`, which stacks are applied, which vendors are wired, which policies (PR creation, commit strategy, AI co-author, commit style) hold. `vinta-sync-ai-tools` reads this file and uses it to classify every upstream change into one of:
 
 | Bucket | Meaning | Default |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.1.7",
+  "version": "0.2.0-alpha2",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
   "bin": {

package/schemas/vinta-ai-workflows-config.v1.schema.json

@@ -105,6 +105,12 @@
           "type": "string",
           "enum": ["conventional", "imperative", "other"]
         },
+        "commit_strategy": {
+          "description": "How `implement-plan` structures branches and commits across phases. `stacked-branches` (default — current behavior): one branch + one PR per phase, stacked on top of each other. `modular-commits`: one branch + one PR for the whole plan; each phase contributes multiple atomic commits (one per logical unit — service, use-case wire-up, init/exports, serializer field, refactor, fix). Tests travel in the same commit as the code they test. `ask`: `implement-plan` prompts the user at Step 0 (alongside `pause_between_phases` / `generate_inline_comments`) and caches the resolved value in `TRACKING_{plan-id}.md` under `run_options.commit_strategy_resolved`. Omitting the field is equivalent to `stacked-branches` (backward-compatible for configs written before this field existed).",
+          "type": "string",
+          "enum": ["stacked-branches", "modular-commits", "ask"],
+          "default": "stacked-branches"
+        },
         "stage_pattern": {
           "description": "Default `git add` pattern shown to subagents (no `git add -A`).",
           "type": "string"
@@ -112,6 +118,59 @@
         "anti_git_add_all_reason": {
           "description": "One-line reason `git add -A` is forbidden in this repo (e.g. secrets, build artifacts in tree).",
           "type": "string"
+        },
+        "dependency_licenses": {
+          "description": "Third-party dependency license policy. Captured at bootstrap; rendered into `ai-tools/AGENTS.md` (`## Dependency licenses` section) and the `implement-plan` / `amend-plan` skill bodies so the implementer / reviewer agents check a new dep's SPDX license against `forbidden_spdx` before running any install command (`npm add`, `pnpm add`, `pip install`, `poetry add`, `uv add`, `cargo add`, `go get`, etc.). When `enforcement: block`, the agent must refuse the install and surface the violation to the user; `warn` records the violation in the phase report but proceeds; `off` skips the check entirely.",
+          "type": "object",
+          "required": ["enforcement", "forbidden_spdx"],
+          "additionalProperties": false,
+          "properties": {
+            "enforcement": {
+              "description": "How the implementer / reviewer agents react when a new dep's license is in `forbidden_spdx`. `block` (default) — refuse install, ask user to confirm override before proceeding. `warn` — proceed but flag in the phase report. `off` — skip the check.",
+              "type": "string",
+              "enum": ["block", "warn", "off"],
+              "default": "block"
+            },
+            "forbidden_spdx": {
+              "description": "SPDX license identifiers (https://spdx.org/licenses/) the project refuses to take on as a third-party dep. Bootstrap proposes a default list (GPL-2.0-only, GPL-3.0-only, AGPL-3.0-only, SSPL-1.0) targeting viral copyleft licenses; the user confirms / edits before write. Empty array disables the check even when `enforcement` is `block` or `warn` (use `enforcement: off` instead for clarity).",
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "uniqueItems": true,
+              "default": ["GPL-2.0-only", "GPL-3.0-only", "AGPL-3.0-only", "SSPL-1.0"]
+            },
+            "allowed_overrides": {
+              "description": "Explicit per-package exceptions to `forbidden_spdx`. Each entry whitelists one package + license pair the team has accepted (legal review, dual-license clause, in-house carve-out). The implementer agent skips the block when the candidate package + license matches an entry; the reviewer agent treats the entry as load-bearing context (don't silently drop).",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["package", "license", "reason"],
+                "additionalProperties": false,
+                "properties": {
+                  "package": {
+                    "description": "Package identifier as it appears in the manifest (npm name, PyPI distribution, Cargo crate, Go module path).",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "license": {
+                    "description": "SPDX identifier this override applies to. Must be present in `forbidden_spdx` for the override to mean anything.",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "reason": {
+                    "description": "One-line justification (e.g. 'legal review 2025-Q4', 'GPL exception clause covers our use', 'wraps a CLI invoked at build time only — not linked').",
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              },
+              "uniqueItems": true,
+              "default": []
+            },
+            "notes": {
+              "description": "Free-form prose surfaced verbatim in the AGENTS.md `## Dependency licenses` section. Use for nuance the structured fields can't capture (e.g. 'LGPL is fine for dynamic linking but not for static linking — check the consuming module before adding', 'all viral-license deps go through @counsel before merge').",
+              "type": "string"
+            }
+          }
         }
       }
     },
@@ -144,6 +203,11 @@
           "description": "Root-cause-first debugging skill rendered from `vinta-derive-skills/resources/systematic-debugging-template.md`. When `enabled`, the per-project MCP tool selection lives in `skills.systematic-debugging.observability_mcp_tools`.",
           "type": "string",
           "enum": ["enabled", "disabled"]
+        },
+        "prepare-worktree": {
+          "description": "Provision a fully-runnable git worktree for parallel feature work — symlinks dep dirs, copies env files, forks dev / test DBs, namespaces docker-compose project + network, drops a summary YAML for mechanical teardown. Copy-verbatim foundation skill (bucket A). When `enabled`, project-level defaults (worktree root, deps strategy, compose network strategy) live under `skills.prepare-worktree`. Consumed by `implement-plan` when its Step 0 question (c) opts in — the orchestrator runs `prepare-worktree` once at the start of a plan run and threads the worktree path through every subagent's prompt so phases all stack inside the same isolated checkout.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
         }
       }
     },
@@ -181,7 +245,12 @@
           "additionalProperties": false,
           "properties": {
             "pause_between_phases": { "type": "boolean", "default": false },
-            "generate_inline_comments": { "type": "boolean", "default": false }
+            "generate_inline_comments": { "type": "boolean", "default": false },
+            "use_worktree": {
+              "description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision an isolated git worktree (via `prepare-worktree`) and run every phase's subagent inside it. False = run in the current checkout. True = create one shared worktree at the start of the plan run; all phase branches stack inside it. Per-run prompt still asks; this is the suggested default shown.",
+              "type": "boolean",
+              "default": false
+            }
           }
         },
         "amend-plan": {
@@ -230,6 +299,42 @@
             }
           }
         },
+        "prepare-worktree": {
+          "description": "Configuration for the `prepare-worktree` foundation skill. Optional when `foundation_skills.prepare-worktree` is `enabled` — every field has a sensible default. Consumed by the skill at runtime to bias the per-worktree symlink-vs-copy-vs-fork decisions.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "worktree_root": {
+              "description": "Where new worktrees land. Default `.claude/worktrees` when claude-code is the primary harness (matches the EnterWorktree convention); other harnesses default to `../<repo-name>-wt-` (sibling dirs of the main checkout). The skill resolves `<root>/<name>` per provisioning call.",
+              "type": "string",
+              "minLength": 1
+            },
+            "deps_strategy": {
+              "description": "Default strategy for dep dirs (`node_modules/`, `vendor/`, `venv/`) when the active plan does NOT install new deps. `symlink` reuses main's install (fast, safe for read-only); `copy` clones it (safe for pnpm-style relative-symlink stores, fails for yarn PnP); `reinstall` runs the package manager fresh in the worktree. The skill flips to `reinstall` automatically when it detects dep churn in the plan body.",
+              "type": "string",
+              "enum": ["symlink", "copy", "reinstall"],
+              "default": "symlink"
+            },
+            "compose_network": {
+              "description": "Default docker-compose networking strategy for the worktree. `per-worktree` spins a fresh isolated network (safest, doubles infra); `shared-external` joins an externally-declared network so the worktree can talk to main's compose services (queues, caches, search); `host` uses host networking when the project already does. Skill writes the chosen strategy into the worktree's `docker-compose.override.yml` (or equivalent) when `compose_change` is set.",
+              "type": "string",
+              "enum": ["per-worktree", "shared-external", "host"],
+              "default": "per-worktree"
+            },
+            "test_db_strategy": {
+              "description": "Default policy for the test DB. `always-fork` provisions a dedicated test DB per worktree (no flaky cross-worktree races at the cost of one extra DB per worktree); `fork-on-schema-change` only forks when the plan touches migrations; `share` keeps using the main checkout's test DB and accepts the race risk (only sensible for solo work).",
+              "type": "string",
+              "enum": ["always-fork", "fork-on-schema-change", "share"],
+              "default": "fork-on-schema-change"
+            },
+            "summary_dir": {
+              "description": "Where per-worktree summary YAMLs land. Default `.vinta-ai-workflows/worktrees` — covered by the umbrella gitignore added in 0.1.3. The skill writes `<summary_dir>/<name>.yaml` per provisioned worktree; teardown reads it.",
+              "type": "string",
+              "minLength": 1,
+              "default": ".vinta-ai-workflows/worktrees"
+            }
+          }
+        },
         "add-one-off-script": {
           "description": "Configuration for the `add-one-off-script` foundation skill. Optional when `foundation_skills.add-one-off-script` is `enabled` — sensible defaults apply when omitted.",
           "type": "object",

package/skills/vinta-bootstrap-ai-tools/SKILL.md

@@ -69,10 +69,21 @@ These bleed across sub-skills, so capture once now:
 4. **PR creation policy** — agents open PRs, or only push branches and humans open PRs?
 5. **Co-author trailer policy** — repo allows AI co-author trailers in commits, or strictly human-only?
 6. **Deploy targets** — Vercel, AWS, Kubernetes, Heroku, custom, none.
+7. **Third-party dependency license policy.** Should agents check the SPDX license of any new dep against a forbidden list before running `npm add` / `pnpm add` / `pip install` / `poetry add` / `uv add` / `cargo add` / `go get` (etc.)?
+   - **Enforcement.** `AskUserQuestion` options: `Block (recommended)` — refuse install + surface violation, ask user to confirm override before proceeding; `Warn` — proceed but flag in the phase report; `Off` — skip the check entirely.
+   - **Forbidden SPDX list.** Show the default seed (`GPL-2.0-only`, `GPL-3.0-only`, `AGPL-3.0-only`, `SSPL-1.0`) targeting viral copyleft licenses, then ask via open prose: *"Add or remove entries? Common additions: `LGPL-2.1-only`, `LGPL-3.0-only`, `BSL-1.1`, `EUPL-1.2`, `CC-BY-NC-*` (non-commercial)."* Skip when enforcement = `Off`.
+   - **Existing overrides (optional).** Open prose: *"Any packages already in the manifest with a forbidden license the team has accepted? Format: `<package> <SPDX-id> <one-line reason>`. Leave blank if none."* Each entry lands in `policies.dependency_licenses.allowed_overrides[]`. Skip when enforcement = `Off`.
+   - **Notes (optional).** Open prose: *"Any nuance the structured fields can't capture? (e.g. 'LGPL fine for dynamic linking only', 'viral-license deps go through @counsel before merge'.)"* Lands in `policies.dependency_licenses.notes`.
+8. **Commit strategy** — how `implement-plan` should structure branches + commits across phases. `AskUserQuestion` options:
+   - `Stacked branches (default) — one branch + one PR per phase, stacked on top of each other` — current behavior. Each phase ships one commit on its own branch; reviewers see one PR per phase.
+   - `Modular commits — one branch + one PR for the whole plan, atomic commit per logical unit` — each phase produces multiple commits (one per service / use-case wire-up / init / serializer field / refactor / fix). Tests travel in the same commit as the code they test. Reviewers read the commit list as a TOC.
+   - `Ask me each run` — `implement-plan` prompts at Step 0 (alongside `pause_between_phases` / `generate_inline_comments`) and caches the answer in `TRACKING_{plan-id}.md`.
+
+   Lands in `.vinta-ai-workflows.yaml` `policies.commit_strategy`. Drives the `implement-plan` template's branch / commit / PR-opening flow + the `amend-plan` skill's supported-strategies check.
 
 ### D. Optional foundation skills
 
-Four skills are part of the foundation set but aren't always needed. Ask explicitly:
+Five skills are part of the foundation set but aren't always needed. Ask explicitly:
 
 1. **`add-e2e-test`** — does the project have e2e tests (Playwright / Cypress / similar) or plan to add them? `AskUserQuestion` options: `Yes — already has them`, `Yes — planning to add`, `No — skip`. If yes, [vinta-derive-skills](../vinta-derive-skills/SKILL.md)'s **Optional — ask the user** bucket follows up to ask whether the user has a template or wants to draft from scratch.
 2. **`add-env-var`** — does the project have a non-trivial env-var propagation flow (multiple files / build configs / CI updates per new var) or a single `.env` file is enough? `AskUserQuestion` options: `Yes — non-trivial flow`, `No — single .env is enough`. Skip if `No`.
@@ -84,6 +95,15 @@ Four skills are part of the foundation set but aren't always needed. Ask explici
    - **Primary language.** `AskUserQuestion`: `Python`, `TypeScript`. Auto-pick from `inventory.frameworks` when one language clearly dominates; ask only when polyglot. Drives which `BaseOneOffScript` template gets staged at `<scripts_dir>/_base.{py,ts}`.
    - **S3 bucket + prefix.** Open prose. Empty bucket disables S3 upload (filesystem copy stays authoritative). The skill also reads the `ONE_OFF_S3_BUCKET` / `ONE_OFF_S3_PREFIX` env vars at runtime, so leaving the config blank is fine if the team prefers env-only.
 
+5. **`prepare-worktree`** — does the team want to run long-running plans / experiments 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 swapping branches in the main checkout? `AskUserQuestion` options: `Yes — enable`, `No — skip`. Recommend `Yes` for any project with long migrations, multi-day plans, or teams where parallel concurrent work in the same checkout is common (one dev shipping a feature while another runs a migration; an agent driving `implement-plan` for hours while the human keeps coding on `main`). Skip for solo projects where branch-switching in place is unproblematic.
+
+   **Follow-up only when `prepare-worktree` = Yes — worktree defaults.** Three short questions land under `skills.prepare-worktree.*`:
+   - **Worktree root.** `AskUserQuestion`: `.claude/worktrees` (claude-code convention; the runtime's `EnterWorktree` puts them there), `../<repo-name>-wt-` (sibling dirs of the main checkout — survives across runtimes; relative-path tooling that walks up still works). Auto-pick the first when claude-code is the only selected vendor; ask when multiple vendors are in the **Scope** group's vendor coverage answer.
+   - **Default deps strategy when the plan does NOT install new deps.** `AskUserQuestion`: `symlink` (fastest, reuses main's `node_modules` / `vendor/` / `venv/`), `copy` (defensive; safe for pnpm + npm + cargo + go; risky for yarn PnP + venv), `reinstall` (slowest, always correct). Recommend `symlink` for pnpm / npm / cargo / go projects; `reinstall` for poetry / yarn PnP.
+   - **Default test-DB strategy.** `AskUserQuestion`: `fork-on-schema-change` (default — only forks when the plan body shows migrations), `always-fork` (defensive — every worktree gets its own test DB regardless), `share` (only safe for solo work; flaky cross-worktree test runs are the cost).
+
+   **Follow-up — `implement-plan` default for worktree opt-in.** `AskUserQuestion`: should the `implement-plan` Step 0 question (c) — "run phases in a worktree?" — default to `Yes` or `No`? Lands in `run_options.implement-plan.use_worktree`. Recommend `No` for solo projects + short plans; `Yes` for teams that already use worktrees as part of their workflow.
+
    **Follow-up only when `systematic-debugging` = Yes — observability MCP server inventory.** Open prose, not multi-select. Ask the user to name every MCP server already wired up that exposes observability data, in whatever shorthand the team uses (`sentry`, `datadog`, `our-internal-traces`, `grafana-prod`, etc.). The intent is not to pick from a fixed catalogue — that goes stale fast — but to give the systematic-debugging agent a starter list of servers to introspect at Phase 0. Cross-check the answers against any MCP servers actually configured in the project's AI tooling (`.mcp.json`, `~/.claude/mcp_servers.json`, `.codex/mcp.json`, etc.) — if a server is configured but the user didn't mention it, ask whether it carries observability data. The selection lands in `skills.systematic-debugging.observability_mcp_servers` of `.vinta-ai-workflows.yaml` (free-form string array). Empty array is allowed but warn the user that Phase 0 collapses to "local logs only" and production-only bugs without telemetry become a guess factory. The agent will discover specific tool names + categories (error tracking, traces, logs, metrics, alerts, deploys, dashboards) from the live MCP tool list at runtime — see [vinta-derive-skills/resources/systematic-debugging-mcp-tools.md](../vinta-derive-skills/resources/systematic-debugging-mcp-tools.md) for the evidence categories baked into the rendered SKILL.md.
 
    **Cache scaffolding.** Preflight state lives at `.vinta-ai-workflows/cache.yaml` ([`mcp-preflight-cache.v1`](../../schemas/mcp-preflight-cache.v1.schema.json)). The bootstrap orchestrator must:
@@ -92,7 +112,7 @@ Four skills are part of the foundation set but aren't always needed. Ask explici
    - Do **not** seed the cache file at bootstrap. The first debug run preflights all configured servers and writes the file then. An empty / missing `.vinta-ai-workflows/cache.yaml` is a valid initial state.
    - Mention to the user how to refresh: delete the file to re-preflight everything, or edit one entry's `status` to `dirty` to refresh that one server. Token rotated → cache will catch the auth error on the next call and flip the entry to `dirty` automatically.
 
-If the user answers "No" to any of the four, that skill won't ship. If the user answers "Yes" to `add-e2e-test` / `add-env-var` but doesn't have a template, derive-skills drafts one via interview. `systematic-debugging` is always template-rendered — no per-project drafting interview, just the MCP-server inventory above. `add-one-off-script` is copied verbatim from [vinta-derive-skills/resources/foundation-skills/add-one-off-script/](../vinta-derive-skills/resources/foundation-skills/add-one-off-script/) — its body is project-agnostic; the per-project variability lives in the `skills.add-one-off-script.*` config block above and in env vars consumed at runtime.
+If the user answers "No" to any of the five, that skill won't ship. If the user answers "Yes" to `add-e2e-test` / `add-env-var` but doesn't have a template, derive-skills drafts one via interview. `systematic-debugging` is always template-rendered — no per-project drafting interview, just the MCP-server inventory above. `add-one-off-script` is copied verbatim from [vinta-derive-skills/resources/foundation-skills/add-one-off-script/](../vinta-derive-skills/resources/foundation-skills/add-one-off-script/) — its body is project-agnostic; the per-project variability lives in the `skills.add-one-off-script.*` config block above and in env vars consumed at runtime. `prepare-worktree` is also copied verbatim from [vinta-derive-skills/resources/foundation-skills/prepare-worktree/](../vinta-derive-skills/resources/foundation-skills/prepare-worktree/) — same pattern: project-agnostic body, per-project defaults under `skills.prepare-worktree.*`.
 
 ### E. Existing AI artifacts (per-artifact disposition)
 
@@ -112,7 +132,7 @@ For each artifact, read it (frontmatter + body), then ask the user via `AskUserQ
   - `Keep in current vendor path, don't touch` — leaves it where it is. AGENTS.md may reference it; downstream skill setup won't manage it.
   - `Drop` — delete (rare; usually the user wants to migrate).
 
-  Foundation-shape skills (name matches `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`) get an extra option: `Replace with Vinta foundation version` — overwrites with the canonical foundation content, preserving the user's name. Useful when the existing version is stale.
+  Foundation-shape skills (name matches `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`) get an extra option: `Replace with Vinta foundation version` — overwrites with the canonical foundation content, preserving the user's name. Useful when the existing version is stale.
 
 - **Sub-agents** (each under any vendor `agents/` dir):
   - `Migrate to ai-tools/agents/<name>.yaml` — converts vendor-specific format → canonical YAML; `setup-ai-tools.mjs` re-emits per-vendor copies.
@@ -199,10 +219,22 @@ commands:
 
 policies:
   pr_creation: <Project conventions → PR creation policy>
+  commit_strategy: <Project conventions → Commit strategy>  # stacked-branches | modular-commits | ask
   ai_coauthor: <Project conventions → Co-author trailer policy>
   commit_style: <conventional | imperative | other>
   stage_pattern: <derived>
   anti_git_add_all_reason: <derived>
+  # Only emit `dependency_licenses` when enforcement != Off (the `off` value is
+  # supported by the schema but the agent never needs the rest of the block
+  # when there is no check to run — keep the config slim).
+  dependency_licenses:
+    enforcement: <Project conventions → license policy enforcement → block | warn | off>
+    forbidden_spdx: <license policy forbidden list — array of SPDX IDs the user confirmed at bootstrap>
+    allowed_overrides:                       # empty array when the user listed no exceptions
+      - package: <name>
+        license: <SPDX ID — must appear in forbidden_spdx>
+        reason: <one-line justification>
+    notes: <free-form prose, omit when blank>
 
 vendors: <Scope → Vendor coverage list>
 
@@ -217,6 +249,7 @@ foundation_skills:
   add-env-var: <Optional foundation skills → add-env-var answer → enabled | disabled>
   systematic-debugging: <Optional foundation skills → systematic-debugging answer → enabled | disabled>
   add-one-off-script: <Optional foundation skills → add-one-off-script answer → enabled | disabled>
+  prepare-worktree: <Optional foundation skills → prepare-worktree answer → enabled | disabled>
 
 foundation_agents:
   implementer: enabled
@@ -230,6 +263,7 @@ run_options:
   implement-plan:
     pause_between_phases: false
     generate_inline_comments: false
+    use_worktree: <Optional foundation skills → prepare-worktree follow-up → default for Step 0 question (c); false unless team opted in>
   amend-plan:
     blast_radius_signal_threshold: 2
 
@@ -238,6 +272,14 @@ skills:
   systematic-debugging:
     observability_mcp_servers: <systematic-debugging follow-up — free-form array of MCP server identifiers, e.g. [sentry, datadog, our-internal-traces]>
 
+  # Only emit this block when foundation_skills.prepare-worktree = enabled.
+  prepare-worktree:
+    worktree_root: <prepare-worktree follow-up — `.claude/worktrees` | `../<repo>-wt-`>
+    deps_strategy: <prepare-worktree follow-up — symlink | copy | reinstall>
+    compose_network: per-worktree
+    test_db_strategy: <prepare-worktree follow-up — fork-on-schema-change | always-fork | share>
+    summary_dir: .vinta-ai-workflows/worktrees
+
   # Only emit this block when foundation_skills.add-one-off-script = enabled.
   add-one-off-script:
     scripts_dir: <add-one-off-script follow-up — default `scripts/one_off`>
@@ -308,6 +350,7 @@ ai-tools/
 │   │   └── resources/
 │   │       ├── one_off_script_base.py
 │   │       └── one_off_script_base.ts
+│   ├── prepare-worktree/SKILL.md       ← optional — only if user opts in (verbatim copy; project-agnostic body, defaults under skills.prepare-worktree.*)
 │   ├── run-one-off-script-django/       ← optional sister skill — only when stack matches + user supplies template (authors Jupyter notebook / mgmt command runner + JupyterRuntime / DjangoMgmtRuntime adapter in the per-script folder)
 │   ├── run-one-off-script-medplum/      ← optional sister skill — only when stack matches + user supplies template (authors Medplum bot + MedplumBotRuntime adapter in the per-script folder)
 │   └── <stack-specific skills>/SKILL.md ← only if user supplied templates
@@ -338,7 +381,7 @@ Foundation skills break into three buckets — see [vinta-derive-skills](../vint
 
 - **Always copy verbatim**: `plan-feature`, `create-spec`, `create-qa-use-cases`. Bundled with the bootstrap skill set; project-agnostic enough to ship as-is (with light path scrubs).
 - **Always generate**: `implement-plan`, `amend-plan`. Bodies have too much project-specific content (test commands, branch convention, PR + co-author policy, agent dispatch) — generated from parameterized templates using interview answers + inventory.
-- **Optional, ask first**: `add-e2e-test`, `add-env-var`, `systematic-debugging`, `add-one-off-script`. Skipped by default; orchestrator asks via `AskUserQuestion` whether the project has the relevant flow at all. `add-e2e-test` / `add-env-var`: if yes + user has a template → copy + adapt; if yes + no template → draft from scratch via interview; if no → don't ship. `systematic-debugging`: if yes → render the bundled template plus the per-tool MCP catalogue blocks for the observability tools selected in its follow-up; if no → don't ship. `add-one-off-script`: if yes → copy the bundled SKILL.md verbatim plus the language-specific `BaseOneOffScript` template (`one_off_script_base.py` / `one_off_script_base.ts`) chosen via its follow-up; if no → don't ship.
+- **Optional, ask first**: `add-e2e-test`, `add-env-var`, `systematic-debugging`, `add-one-off-script`, `prepare-worktree`. Skipped by default; orchestrator asks via `AskUserQuestion` whether the project has the relevant flow at all. `add-e2e-test` / `add-env-var`: if yes + user has a template → copy + adapt; if yes + no template → draft from scratch via interview; if no → don't ship. `systematic-debugging`: if yes → render the bundled template plus the per-tool MCP catalogue blocks for the observability tools selected in its follow-up; if no → don't ship. `add-one-off-script`: if yes → copy the bundled SKILL.md verbatim plus the language-specific `BaseOneOffScript` template (`one_off_script_base.py` / `one_off_script_base.ts`) chosen via its follow-up; if no → don't ship. `prepare-worktree`: if yes → copy the bundled SKILL.md verbatim, populate `skills.prepare-worktree.*` defaults from its follow-ups, and (when the user opted in via the worktree-default follow-up) flip `run_options.implement-plan.use_worktree` to `true` so `implement-plan`'s Step 0 question (c) defaults to yes; if no → don't ship.
 
 Stack-specific skills + agents land in the target only when the user provides templates for them. If they don't have templates yet, the orchestrator records the detected stacks + skill categories as a TODO list the user can address later via [vinta-derive-skills](../vinta-derive-skills/SKILL.md) / [vinta-derive-subagents](../vinta-derive-subagents/SKILL.md) standalone runs.