vinta-ai-workflows 0.7.0-alpha8 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/CHANGELOG.md +472 -595
  2. package/README.md +33 -19
  3. package/package.json +4 -1
  4. package/schemas/README.md +11 -3
  5. package/schemas/ai-models.v1.schema.json +5 -0
  6. package/schemas/interview-answers.v1.schema.json +122 -0
  7. package/schemas/interview-round.v1.schema.json +346 -0
  8. package/schemas/plan-review.v1.schema.json +342 -0
  9. package/schemas/postmortem.v1.schema.json +848 -3
  10. package/schemas/prs-context-comments.v1.schema.json +1 -1
  11. package/schemas/prs-context-frontmatter.v1.schema.json +18 -7
  12. package/schemas/vinta-ai-workflows-config.v1.schema.json +677 -18
  13. package/schemas/workflow.v1.schema.json +751 -26
  14. package/skills/vinta-analyze-codebase/SKILL.md +5 -0
  15. package/skills/vinta-bootstrap-ai-tools/SKILL.md +154 -31
  16. package/skills/vinta-bootstrap-ai-tools/resources/stacks/README.md +1 -1
  17. package/skills/vinta-bootstrap-ai-tools/resources/stacks/django/notes.md +36 -1
  18. package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/README.md +85 -0
  19. package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/lib-template.sh +160 -0
  20. package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/prepare-template.sh +250 -0
  21. package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/teardown-template.sh +96 -0
  22. package/skills/vinta-derive-skills/SKILL.md +23 -15
  23. package/skills/vinta-derive-skills/resources/dependency-license-block.md +8 -9
  24. package/skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md +1 -1
  25. package/skills/vinta-derive-skills/resources/foundation-skills/create-qa-use-cases/SKILL.md +3 -3
  26. package/skills/vinta-derive-skills/resources/foundation-skills/create-spec/SKILL.md +21 -2
  27. package/skills/vinta-derive-skills/resources/foundation-skills/handoff/SKILL.md +3 -3
  28. package/skills/vinta-derive-skills/resources/foundation-skills/interview-ui/SKILL.md +121 -0
  29. package/skills/vinta-derive-skills/resources/foundation-skills/interview-ui/resources/examples/docs/D4-concurrency.md +28 -0
  30. package/skills/vinta-derive-skills/resources/foundation-skills/interview-ui/resources/examples/round-01.json +60 -0
  31. package/skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/SKILL.md +1 -1
  32. package/skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh +34 -7
  33. package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md +363 -142
  34. package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/resources/ai-models.yaml +19 -13
  35. package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md +39 -21
  36. package/skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md +8 -6
  37. package/skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-review-loop/SKILL.md +181 -0
  38. package/skills/vinta-derive-skills/resources/plan-execution/README.md +40 -7
  39. package/skills/vinta-derive-skills/resources/plan-execution/partials/agent-models.md +14 -35
  40. package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/stacked.md +21 -0
  41. package/skills/vinta-derive-skills/resources/plan-execution/partials/dispatched-agent.md +31 -0
  42. package/skills/vinta-derive-skills/resources/plan-execution/partials/implementer-prompt.md +67 -6
  43. package/skills/vinta-derive-skills/resources/plan-execution/partials/maestro-live-run.md +44 -0
  44. package/skills/vinta-derive-skills/resources/plan-execution/partials/model-pick.md +9 -3
  45. package/skills/vinta-derive-skills/resources/plan-execution/partials/parallel-lanes.md +95 -50
  46. package/skills/vinta-derive-skills/resources/plan-execution/partials/pr-context.md +4 -2
  47. package/skills/vinta-derive-skills/resources/plan-execution/partials/relay-questions.md +13 -0
  48. package/skills/vinta-derive-skills/resources/plan-execution/partials/review-loop.md +81 -0
  49. package/skills/vinta-derive-skills/resources/plan-execution/partials/worktree-seam.md +86 -17
  50. package/skills/vinta-derive-skills/resources/plan-execution/shell/amend-plan-template.md +35 -16
  51. package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-phase-template.md +12 -1
  52. package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-plan-template.md +49 -33
  53. package/skills/vinta-derive-skills/resources/plan-execution/shell/integrate-phase-template.md +2 -1
  54. package/skills/vinta-derive-skills/resources/plan-execution/shell/review-phase-template.md +19 -27
  55. package/skills/vinta-derive-skills/resources/prs-context-template.md +5 -4
  56. package/skills/vinta-derive-skills/resources/systematic-debugging-mcp-tools.md +1 -1
  57. package/skills/vinta-derive-skills/resources/systematic-debugging-template.md +8 -8
  58. package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/django.md +4 -1
  59. package/skills/vinta-derive-skills/resources/write-unit-test-template.md +3 -0
  60. package/skills/vinta-derive-subagents/SKILL.md +25 -9
  61. package/skills/vinta-install-ai-tools-setup/SKILL.md +29 -2
  62. package/skills/vinta-migrate-plans-specs/SKILL.md +7 -7
  63. package/skills/vinta-sync-ai-tools/SKILL.md +19 -2
  64. package/skills/vinta-update-project-skills/SKILL.md +1 -0
  65. package/skills/vinta-write-agents-md/SKILL.md +10 -6
  66. package/skills/vinta-write-agents-md/resources/asking-the-human.md +56 -0
  67. package/skills/vinta-derive-skills/resources/plan-execution/partials/review-layers.md +0 -101
@@ -1,4 +1,4 @@
1
- <!-- Partial: worktree-seam — the WORKROOT abstraction. Collapses the former scattered `if use_worktree` conditionals into one resolution (conductor) + two local, data-driven checks (implement-phase spawn wrap, review-phase stray-write). Blocks: WORKROOT_RESOLUTION (conductors), WORKROOT_TOPOLOGY_RULE (conductors + integrate-phase), SANDBOX_WRAP (implement-phase), STRAY_WRITE_CHECK (review-phase). Under parallel execution `WORKROOT` becomes per-lane — the pool lives in parallel-lanes.md#LANE_WORKTREE_POOL and every downstream step still reads exactly one `WORKROOT`, the one for its own lane. -->
1
+ <!-- Partial: worktree-seam — the WORKROOT abstraction. Collapses the former scattered `if use_worktree` conditionals into one resolution (conductor) + two local, data-driven checks (implement-phase spawn wrap, implement-phase stray-write, which review-phase re-runs after each fix round). Blocks: WORKROOT_RESOLUTION (conductors), WORKROOT_TOPOLOGY_RULE (conductors + integrate-phase), SANDBOX_WRAP (implement-phase), STRAY_WRITE_CHECK (implement-phase). Under parallel execution `WORKROOT` becomes per-lane — the pool lives in parallel-lanes.md#LANE_WORKTREE_POOL and every downstream step still reads exactly one `WORKROOT`, the one for its own lane. -->
2
2
 
3
3
  <!-- block-begin: WORKROOT_RESOLUTION -->
4
4
  ## Step 0.5 — Resolve `WORKROOT`
@@ -7,29 +7,98 @@ Resolve three values **once per lane**, before any phase runs, and record them i
7
7
 
8
8
  | Value | `run_options.use_worktree = false` | `run_options.use_worktree = true` |
9
9
  |---|---|---|
10
- | `WORKROOT` | the main checkout root (the repo the skill was invoked from) | `<worktree_path>` returned by prepare-worktree — **this lane's** path under parallel execution |
11
- | `BASE_BRANCH` | `{{DEFAULT_BRANCH}}` | `<worktree_branch>` prepare-worktree created |
12
- | `SANDBOX_TIER` | `none` | `enforced` or `none` (probed by prepare-worktree, per lane) |
10
+ | `WORKROOT` | the main checkout root (the repo the skill was invoked from) | `<worktree_path>` returned by the provisioner — **this lane's** path under parallel execution |
11
+ | `BASE_BRANCH` | `{{DEFAULT_BRANCH}}` | `<worktree_branch>` the provisioner created |
12
+ | `SANDBOX_TIER` | `none` | `enforced` or `none` (probed per lane) |
13
+
14
+ **Pick the provisioner once.** `.vinta-ai-workflows.yaml` decides how a worktree gets made:
15
+
16
+ | Config | Provisioner |
17
+ |---|---|
18
+ | `commands.worktree_prepare` set | **The project's own command** — see [Provisioning with the project's command](#provisioning-with-the-projects-command). It wins even when the skill is also enabled; the skill is then only offered as a fallback when the command fails. |
19
+ | `commands.worktree_prepare` unset, `foundation_skills.prepare-worktree: enabled` | **The [prepare-worktree](../prepare-worktree/SKILL.md) skill.** |
20
+ | neither | None — worktrees are unavailable, and Step 0 already recorded `use_worktree = false`. |
21
+
22
+ Record the choice as `run_options.worktree_provisioner: command | skill` in tracking. Both provisioners hand back the same four values (`worktree_path`, `worktree_branch`, `worktree_summary`, `sandbox_tier`), so no later step checks which one ran.
13
23
 
14
24
  **When `run_options.parallel_phases = true`:** skip the single-worktree path below entirely and provision the pool per [Provision the lane worktree pool](#provision-the-lane-worktree-pool). That step resolves one `WORKROOT` / `SANDBOX_TIER` per lane plus one integration worktree, and refuses the run outright when worktrees are unavailable. `BASE_BRANCH` stays plan-level (`{{DEFAULT_BRANCH}}`, or the worktree base when the whole plan hangs off one); each phase's *own* base is derived from its dependencies, not from `BASE_BRANCH` — see [Lane branch topology](#lane-branch-topology).
15
25
 
16
26
  **When `use_worktree = false`:** set `WORKROOT` = main checkout, `BASE_BRANCH = {{DEFAULT_BRANCH}}`, `SANDBOX_TIER = none`. Make `BASE_BRANCH` current + up to date: `git -C <WORKROOT> checkout {{DEFAULT_BRANCH}} && git -C <WORKROOT> pull --ff-only`. Jump to Step 1.
17
27
 
18
- **When `use_worktree = true`:** run [prepare-worktree](../prepare-worktree/SKILL.md) **once**. This is a mechanical step: when `agent_models.worktree_prep` is set, **delegate it to a subagent** per the [Delegate a mechanical step to a configured model](#delegate-a-mechanical-step-to-a-configured-model) pattern (hand the subagent prepare-worktree's SKILL.md + the inputs below; consume its returned `worktree_path` / `worktree_branch` / `worktree_summary` / `sandbox_tier` report). When the tier is unset, run it inline — the steps below read the same either way:
28
+ **When `use_worktree = true`:** provision **once**, with the provisioner picked above.
29
+
30
+ - **Skill.** This is a mechanical step: when `agent_models.worktree_prep` is set, **delegate it to a subagent** per the [Delegate a mechanical step to a configured model](#delegate-a-mechanical-step-to-a-configured-model) pattern (hand the subagent prepare-worktree's SKILL.md + the inputs below; consume its returned `worktree_path` / `worktree_branch` / `worktree_summary` / `sandbox_tier` report). When the tier is unset, run it inline.
31
+ - **Command.** Run it inline, always. It is a shell command, so there is nothing for a model to do, and `agent_models.worktree_prep` is ignored.
19
32
 
20
- 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.
21
- 2. **Pre-run sanity.** Confirm no existing worktree at the target path (`git worktree list | grep <name>` — refuse if collision). Confirm `git -C <main_checkout> status` of the main checkout (warn if dirty; defer to prepare-worktree's **Sanity checks** step for the call).
22
- 3. **Run prepare-worktree.** Pass the plan file + worktree name. It returns:
33
+ The steps below read the same either way:
34
+
35
+ 1. **Inputs.** Plan path (so the provisioner 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. The command receives these as `VINTA_*` environment variables.
36
+ 2. **Pre-run sanity.** Confirm no existing worktree at the target path (`git worktree list | grep <name>` — refuse if collision). Confirm `git -C <main_checkout> status` of the main checkout (warn if dirty; with the skill, defer to prepare-worktree's **Sanity checks** step for the call).
37
+ 3. **Run the provisioner.** The skill gets the plan file + worktree name; the command gets [its contract](#provisioning-with-the-projects-command). Either one yields:
23
38
  - `worktree_path` → `WORKROOT`.
24
- - `worktree_branch` → `BASE_BRANCH` (prepare-worktree based it on `origin/{{DEFAULT_BRANCH}}`, so it is already current).
25
- - `worktree_summary` — `.vinta-ai-workflows/worktrees/<name>.yaml` (read by teardown).
26
- - `sandbox_tier` → `SANDBOX_TIER`: `enforced` (the [Filesystem sandbox](../prepare-worktree/SKILL.md#step-55--filesystem-sandbox-os-level-write-guard) step found `sandbox-exec` / `bwrap` and will OS-block main-checkout writes) or `none` (no sandbox tool — prevention degrades to the review-phase stray-write backstop).
27
- 4. **Persist to tracking.** Write `run_options.worktree_path`, `run_options.worktree_branch`, `run_options.worktree_summary`, `run_options.sandbox_tier` into `{{PLAN_DIR}}/TRACKING_{plan-id}/run.md`. All later phases read them — never re-provision mid-plan.
28
- 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`).
39
+ - `worktree_branch` → `BASE_BRANCH` (based on `origin/{{DEFAULT_BRANCH}}`, so it is already current).
40
+ - `worktree_summary` — `<summary_dir>/<name>.yaml` (read by teardown and lane reset). `null` when the project's command wrote none.
41
+ - `sandbox_tier` → `SANDBOX_TIER`: `enforced` (`sandbox-exec` / `bwrap` was found and the [Filesystem sandbox](../prepare-worktree/SKILL.md#step-55--filesystem-sandbox-os-level-write-guard) wrapper will OS-block main-checkout writes) or `none` (no sandbox tool — prevention degrades to the review-phase stray-write backstop).
42
+ 4. **Persist to tracking.** Write `run_options.worktree_provisioner`, `run_options.worktree_path`, `run_options.worktree_branch`, `run_options.worktree_summary`, `run_options.sandbox_tier` into `{{PLAN_DIR}}/TRACKING_{plan-id}/run.md`. All later phases read them — never re-provision mid-plan.
43
+ 5. **Report to user.** With the skill, quote its summary back: which dirs copied vs reinstalled vs forked (dependency dirs are always copied or reinstalled, never symlinked); which DB(s) forked + their names; compose project name; teardown command. With the command, quote the last ~20 lines of its output, the summary YAML when it wrote one, and the teardown command. Hold here until the user confirms (`AskUserQuestion`: `Looks good — start phase 1 (Recommended)`, `Stop — let me adjust`).
29
44
 
30
45
  Failure modes:
31
- - **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`.
32
- - **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.
46
+ - **The provisioner fails** (disk full, branch exists, DB clone failed, the command exited non-zero or failed its post-checks) → surface to the user; do NOT fall back to "just run in the main checkout" silently — that defeats the opt-in. Ask via `AskUserQuestion` (header `Worktree`), quoting the error line: `Retry (Recommended)`, `Run in main checkout instead (flip use_worktree to false)`, `Stop`. When the failed provisioner was the command **and** `foundation_skills.prepare-worktree` is `enabled`, add `Provision with the prepare-worktree skill instead` as the second option. Before a retry or the skill fallback, tear down whatever the command left behind (see [Teardown with the project's command](#teardown-with-the-projects-command)).
47
+ - **User cancels at the confirmation gate** → tear the worktree down (the skill's reported teardown command, or [the command teardown](#teardown-with-the-projects-command)) before exiting, so the next run starts clean.
48
+
49
+ ### Provisioning with the project's command
50
+
51
+ `commands.worktree_prepare` is a shell command the team owns. The conductor runs it once per worktree, from `<main_checkout>`, with stdin closed, through `sh -c '<commands.worktree_prepare>'`, and with these variables set in its environment:
52
+
53
+ | Variable | Value |
54
+ |---|---|
55
+ | `VINTA_WORKTREE_NAME` | The worktree name: `plan-{plan-id-kebab}` for a single worktree, or the lane / integration name from the [pool step](#provision-the-lane-worktree-pool). Distinct per worktree, so the command should derive every DB name, compose project name, cache key and port from it. |
56
+ | `VINTA_WORKTREE_PATH` | Absolute path to create the worktree at: `skills.prepare-worktree.worktree_root` (default `.claude/worktrees`) resolved against `<main_checkout>`, then `/<name>`. A root that ends in `-` (the `../<repo>-wt-` sibling convention) takes `<name>` with no slash. |
57
+ | `VINTA_WORKTREE_BRANCH` | The new branch to create: `plan/{plan-id-kebab}/wt` for a single worktree, `plan/{plan-id-kebab}/wt-<name>` for a pool lane or the integration worktree. Phase branches are cut inside the worktree later. |
58
+ | `VINTA_WORKTREE_BASE_REF` | `origin/{{DEFAULT_BRANCH}}`. |
59
+ | `VINTA_WORKTREE_KIND` | `single`, `lane` or `integration`. |
60
+ | `VINTA_MAIN_CHECKOUT` | Absolute path of `<main_checkout>`. |
61
+ | `VINTA_PLAN_PATH` | Absolute path of the plan file. |
62
+ | `VINTA_WORKTREE_SUMMARY` | Absolute path `<main_checkout>/<summary_dir>/<name>.yaml` (`summary_dir` from `skills.prepare-worktree.summary_dir`, default `.vinta-ai-workflows/worktrees`). |
63
+
64
+ **The command must:**
65
+
66
+ - Create a git worktree at `VINTA_WORKTREE_PATH`, on a new branch `VINTA_WORKTREE_BRANCH` based on `VINTA_WORKTREE_BASE_REF`. Fetching first is its call.
67
+ - Leave it runnable. The project's lint, test, build and migrate commands must work inside it without sharing writable state with the main checkout or with another worktree: its own dependency dirs, env files, databases and compose project, whatever the project needs.
68
+ - Exit non-zero on any failure. Never report success for a half-made worktree.
69
+ - Never write to the main checkout's tracked files, and never prompt for input.
70
+ - Succeed when run again for the same name after its teardown ran. Re-provisioning a lane depends on this.
71
+
72
+ **The command may** write a summary YAML at `VINTA_WORKTREE_SUMMARY`. If it does, the file must follow the summary shape in prepare-worktree's [Write the summary file](../prepare-worktree/SKILL.md#step-6--write-the-summary-file) step in full: every key present, `null` for "none", and only the listed values for each closed set. Other tools parse this file, so a partial summary is worse than none. When the skill is not installed, the shape is documented in the [vinta-ai-workflows source](https://github.com/vintasoftware/vinta-ai-workflows/blob/main/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md#step-6--write-the-summary-file). The conductor reads `state.dev_db.reset_cmd` / `state.test_db.reset_cmd` from it for lane reuse. Without a summary, the lane has no reset command, and the [lane reset](#re-orienting-a-member-after-the-reset) re-provisions it instead of reusing it across a migration boundary.
73
+
74
+ **Check the result. Never trust the exit code alone.** Capture `git -C <main_checkout> status --short` before the command runs; after it exits 0, all three checks must hold:
75
+
76
+ ```bash
77
+ git -C "$VINTA_WORKTREE_PATH" rev-parse --abbrev-ref HEAD # prints $VINTA_WORKTREE_BRANCH
78
+ wt_real="$(cd "$VINTA_WORKTREE_PATH" && pwd -P)" # git lists resolved paths
79
+ git -C <main_checkout> worktree list --porcelain | grep -Fx "worktree $wt_real"
80
+ git -C <main_checkout> status --short # identical to the capture taken before the command
81
+ ```
82
+
83
+ If any check fails, the provisioning failed; handle it with the failure modes above. Fill the four values:
84
+
85
+ - `worktree_path` = `VINTA_WORKTREE_PATH`; `worktree_branch` = `VINTA_WORKTREE_BRANCH`.
86
+ - `worktree_summary` = `VINTA_WORKTREE_SUMMARY` when the file exists, else `null`.
87
+ - `sandbox_tier`: probe it yourself, because the sandbox governs how agents are spawned, not how the worktree was made. It is `enforced` when `ai-tools/skills/prepare-worktree/scripts/sandbox-run.sh` exists in the main checkout **and** `sandbox-exec` (macOS) or `bwrap` (Linux) is on `PATH`. Otherwise it is `none`. With the skill disabled, the sandbox scripts are not installed, so the tier is `none` and the review-phase stray-write check is the only guard. Say so once in the report.
88
+
89
+ **Pools run the command one lane at a time.** The command runs `git worktree add` itself, and concurrent adds against one repository corrupt `.git/worktrees/`. The skill path can overlap the expensive per-lane work. The command path cannot, because the add and the rest of the work happen inside one opaque command.
90
+
91
+ ### Teardown with the project's command
92
+
93
+ Run `commands.worktree_teardown` from `<main_checkout>` with the same `VINTA_*` environment the worktree was provisioned with. When it is unset, teardown is `git -C <main_checkout> worktree remove <worktree_path>`. That removes only the checkout, so say in the report that anything the prepare command created outside it (forked DBs, compose volumes) is left behind.
94
+
95
+ **Re-provisioning a lane** runs teardown, then the prepare command with the same `VINTA_WORKTREE_NAME` and `VINTA_WORKTREE_PATH` and a fresh `VINTA_WORKTREE_BRANCH` (`<branch>-r<n>`): the old branch outlives `git worktree remove`, and `git worktree add -b` refuses an existing branch.
96
+
97
+ The final report prints each worktree's teardown as one ready-to-run line, with the environment inline:
98
+
99
+ ```bash
100
+ VINTA_WORKTREE_NAME=<name> VINTA_WORKTREE_PATH=<path> VINTA_WORKTREE_BRANCH=<branch> VINTA_WORKTREE_KIND=<kind> VINTA_MAIN_CHECKOUT=<main_checkout> VINTA_PLAN_PATH=<plan> VINTA_WORKTREE_SUMMARY=<summary> sh -c '<commands.worktree_teardown>'
101
+ ```
33
102
  <!-- block-end: WORKROOT_RESOLUTION -->
34
103
 
35
104
  <!-- block-begin: WORKROOT_TOPOLOGY_RULE -->
@@ -37,7 +106,7 @@ Failure modes:
37
106
  <!-- block-end: WORKROOT_TOPOLOGY_RULE -->
38
107
 
39
108
  <!-- block-begin: SANDBOX_WRAP -->
40
- **Sandbox the spawn — only when `SANDBOX_TIER = enforced`.** The prompt tells the subagent to stay in `WORKROOT`, but that's cooperative — a smaller model can resolve a path back to the main checkout and silently write there (the review-phase stray-write check catches this reactively). When `SANDBOX_TIER = enforced` **and** the runtime spawns subagents as **subprocesses** (it shells out to an agent CLI — e.g. `codex exec …`, a `claude -p …` child, a custom runner), wrap that launch command in the worktree's bundled guard so the OS blocks main-checkout writes regardless of harness:
109
+ **Sandbox the spawn — only when `SANDBOX_TIER = enforced`.** The prompt tells the subagent to stay in `WORKROOT`, but that's cooperative — a smaller model can resolve a path back to the main checkout and silently write there (the implement-phase stray-write check catches this reactively). When `SANDBOX_TIER = enforced` **and** the runtime spawns subagents as **subprocesses** (it shells out to an agent CLI — e.g. `codex exec …`, a `claude -p …` child, a custom runner), wrap that launch command in the worktree's bundled guard so the OS blocks main-checkout writes regardless of harness:
41
110
 
42
111
  ```bash
43
112
  ai-tools/skills/prepare-worktree/scripts/sandbox-run.sh \
@@ -54,7 +123,7 @@ ai-tools/skills/prepare-worktree/scripts/sandbox-run.sh \
54
123
  `<pool_root>` is the directory that holds the lane worktrees (the worktree root prepare-worktree provisioned into). Denying it and allowing back only this lane's `WORKROOT` blocks writes into **sibling lanes** — under parallel execution the more dangerous stray write, because a sibling's tree is being edited and tested at that moment. Omit the `--deny <pool_root>` line only when the run has a single lane and no pool exists.
55
124
 
56
125
  - **In-process subagent runtimes** (orchestrator and subagent share one OS process — e.g. claude-code's Task tool) can't wrap a single spawn. Two options: (a) install a runtime pre-write guard hook scoped to `WORKROOT` (prepare-worktree ships `scripts/claude-worktree-write-guard.py` + `scripts/gen-claude-sandbox-settings.sh` for claude-code); or (b) run the **entire** invocation under `sandbox-run.sh` with the same `--deny` / `--allow` set. Pick whichever the runtime supports.
57
- - **`SANDBOX_TIER = none`** (no sandbox tool, or `use_worktree = false`) → skip wrapping; prevention falls back entirely to the review-phase stray-write check. Surface this once to the user when a worktree run is unsandboxed so the weaker guarantee is explicit.
126
+ - **`SANDBOX_TIER = none`** (no sandbox tool, or `use_worktree = false`) → skip wrapping; prevention falls back entirely to the implement-phase stray-write check. Surface this once to the user when a worktree run is unsandboxed so the weaker guarantee is explicit.
58
127
  <!-- block-end: SANDBOX_WRAP -->
59
128
 
60
129
  <!-- block-begin: STRAY_WRITE_CHECK -->
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: amend-plan
3
3
  description: Adjust an existing implementation plan in `{{PLAN_DIR}}/` after implementation has started or finished. Updates the plan file (revising existing phases or appending new ones), then for each affected phase that was already implemented adjusts its commits (`git commit --amend` or new commits) on the phase branch, force-pushes the rewritten branch, rebases every phase branch in the rewritten phase's dependency closure, force-pushes each, and refreshes the PR-context files. Use when the user says "amend the plan", "update phase N", "add a phase to plan X", "the spec changed, fix the plan", or "rewrite the implementation for phase N". NOT for one-off changes to a single file unrelated to a plan; use the regular implement skill for that. {{PR_POLICY_DESCRIPTION}}
4
+ disable-model-invocation: true
4
5
  ---
5
6
 
6
7
  # Amend Plan
@@ -9,6 +10,8 @@ Revise a plan in [`{{PLAN_DIR}}/`]({{PLAN_DIR}}/) after work has begun. Companio
9
10
 
10
11
  The flow is destructive (force-push). Every modification is gated on user confirmation. Default disposition for any ambiguous case is "stop and ask" — never force-push without an explicit per-branch `Confirm` from the user.{{COMMIT_STRATEGY_REFUSAL_BLOCK}}
11
12
 
13
+ <!-- include: partials/dispatched-agent.md#CONDUCTOR_ENTRY_GUARD -->
14
+
12
15
  ## Working assumptions
13
16
 
14
17
  - Repo: {{PROJECT_NAME}} ({{STACK_SUMMARY}}). Conventions: [AGENTS.md](../../../AGENTS.md).
@@ -23,7 +26,7 @@ The flow is destructive (force-push). Every modification is gated on user confir
23
26
  - Default branch: `{{DEFAULT_BRANCH}}`.
24
27
  - Branch naming convention (set by [implement-plan](../implement-plan/SKILL.md)): `plan/{plan-id-kebab}/phase-{phase.id}`.
25
28
  - **`WORKROOT`.** Resolve once, same as the [implement-plan Resolve WORKROOT step](../implement-plan/SKILL.md#step-05--resolve-workroot): the main checkout by default, or the plan's worktree when `run_options.use_worktree = true` in `run.md`. When the run used a **lane pool**, amend in the **integration worktree** — lanes are sized for forward implementation and may still hold state from their last phase. Every `git` call below runs with `git -C <WORKROOT>`; when no worktree is in play, `WORKROOT` is the main checkout and the commands read exactly as in-place git.
26
- - **Amend only when no implementation is in flight.** A rewrite force-pushes branches other lanes may be based on. If `run.md` shows any phase `running`, stop and tell the user to let the run finish (or stop it) first.
29
+ - **Amend only when no implementation is in flight.** A rewrite force-pushes branches other lanes may be based on. If `run.md` shows any phase `running`, stop and tell the user to let the run finish (or stop it) first. A plan run by `vinta-ai-maestro` is the exception: that run is amended through its own CLI, never by force-pushing its branches — see [Step 0.5](#step-05--a-live-maestro-run).
27
30
 
28
31
  ## When to use
29
32
 
@@ -40,7 +43,7 @@ The flow is destructive (force-push). Every modification is gated on user confir
40
43
 
41
44
  ## Step 0 — Understand the change + parse the plan
42
45
 
43
- 1. **Identify the plan file.** Same logic as the [implement-plan "Locate + parse plan" step](../implement-plan/SKILL.md#step-0--locate--parse-plan): ask the user (path or feature name); `ls {{PLAN_DIR}}/` + grep; confirm before proceeding.
46
+ 1. **Identify the plan file.** Same logic as the [implement-plan "Locate + parse plan" step](../implement-plan/SKILL.md#step-0--locate--parse-plan): an `AskUserQuestion` (header `Plan file`) offering the 2–4 best-matching plans from `ls -t {{PLAN_DIR}}/` (most recent first; the free-text field covers any other path).
44
47
 
45
48
  2. **Capture the requested change.** The user's prompt is the source. If vague, interview via `AskUserQuestion`:
46
49
  - *"Which phases are affected?"* — enumerate phase ids from the plan's **Phased Rollout** section.
@@ -118,6 +121,10 @@ The flow is destructive (force-push). Every modification is gated on user confir
118
121
 
119
122
  Anything in `merged-to-default` state shown explicitly with a warning. **Do not** include those in the force-push list — user must convert those to `append-new` phases instead.
120
123
 
124
+ ## Step 0.5 — A live maestro run
125
+
126
+ <!-- include: partials/maestro-live-run.md#AMEND_LIVE_RUN -->
127
+
121
128
  ## Step 1 — Edit the plan file
122
129
 
123
130
  Always the first write. Plan file is durable; commits get rewritten next.
@@ -127,9 +134,9 @@ Always the first write. Plan file is durable; commits get rewritten next.
127
134
  2. **Inserts** — choose a new id. Two conventions are common:
128
135
  - Decimal: `1.5` between `1` and `2` (matches existing patterns in some Vinta plans). Branch becomes `plan/{plan-id-kebab}/phase-1.5`.
129
136
  - Letter: `1b` between `1` (relabeled `1a`) and `2`. Requires renaming `1` → `1a` inside **Phased Rollout** + updating downstream references.
130
- Ask the user. Default: decimal — no rename of existing ids.
137
+ Ask via `AskUserQuestion` (header `Phase id`): `Decimal id (Recommended)` (no rename of existing ids), `Letter id` (relabels the neighbouring phase).
131
138
 
132
- 3. **Appends** — new `## Phase N+1` block at end of **Phased Rollout**. Same shape as siblings: Goal, **Assigned to**, optional Review models, reusable_skills, Changes, Tests, Acceptance. An appended phase is staffed off the existing **Crew** table; adding a member is a change to the plan's staffing arithmetic and needs the same `Takes`-column update as any other.
139
+ 3. **Appends** — new `## Phase N+1` block at end of **Phased Rollout**. Same shape as siblings: Goal, **Assigned to**, reusable_skills, Changes, Tests, Acceptance. An appended phase is staffed off the existing **Crew** table; adding a member is a change to the plan's staffing arithmetic and needs the same `Takes`-column update as any other.
133
140
 
134
141
  4. **Guiding Decisions changes** — rewrite the affected row. Add a one-line note at the top of **Guiding Decisions** ("**Amended YYYY-MM-DD**: replaced storage shape from X to Y; affects phases 2, 3, 4.") so reviewers see what shifted. Reference the changed row by its **Decision** column name, not by a `§N.M` shorthand.
135
142
 
@@ -161,7 +168,7 @@ Phases in `not-started` state are deferred to [implement-plan](../implement-plan
161
168
 
162
169
  Before any write to remote, **block on these conditions**:
163
170
 
164
- 1. **Phase merged to `{{DEFAULT_BRANCH}}`.** History on `{{DEFAULT_BRANCH}}` is immutable in practice. Tell the user: "Phase X already merged to `{{DEFAULT_BRANCH}}`. The amendment must be a new phase appended to the plan, not a rewrite. Re-run with classification `append-new` and execute via [implement-plan](../implement-plan/SKILL.md)."
171
+ 1. **Phase merged to `{{DEFAULT_BRANCH}}`.** History on `{{DEFAULT_BRANCH}}` is immutable in practice. Explain that the amendment must be a new phase appended to the plan, not a rewrite, then ask via `AskUserQuestion` (header `Merged`): `Re-classify as append-new (Recommended)` (continue this run with classification `append-new`; execute it later via [implement-plan](../implement-plan/SKILL.md)), `Stop`.
165
172
 
166
173
  2. **Branch's PR was reviewed and approved.** Force-pushing destroys reviewer context. Surface: list approved PRs by URL, ask `AskUserQuestion`:
167
174
  - `Proceed — I'll re-request review after force-push`
@@ -169,7 +176,7 @@ Before any write to remote, **block on these conditions**:
169
176
 
170
177
  3. **Branch protection rules block force-push.** `gh api repos/{owner}/{repo}/branches/{branch}/protection` (or `glab` equivalent). If the branch is protected, force-push will fail noisily — surface the rule, stop.
171
178
 
172
- 4. **Multiple authors on the branch.** `git -C <WORKROOT> log --pretty=format:%ae <base>..<branch> | sort -u | wc -l` > 1 → other developers committed too. Force-push erases their local state. Surface, require explicit `Yes, I've coordinated with <names>` confirmation.
179
+ 4. **Multiple authors on the branch.** `git -C <WORKROOT> log --pretty=format:%ae <base>..<branch> | sort -u | wc -l` > 1 → other developers committed too. Force-push erases their local state. Ask via `AskUserQuestion` (header `Co-authors`), naming the other authors: `Stop — convert to a forward phase (Recommended)`, `I've coordinated with <names>`.
173
180
 
174
181
  If any block triggers and the user can't dismiss it: stop. Don't proceed further. Tell the user the rewrite path is unavailable; suggest an `append-new` phase as the fallback.
175
182
 
@@ -223,7 +230,10 @@ Use `git commit --amend` ONLY when:
223
230
  {{DEPENDENCY_LICENSE_BLOCK}}
224
231
  ```
225
232
 
226
- Then splice in the shared inner/outer verification loop verbatim:
233
+ Then splice in the shared "return your questions" contract and the inner/outer verification loop verbatim:
234
+
235
+ <!-- include: partials/implementer-prompt.md#NEEDS_INPUT -->
236
+
227
237
 
228
238
  <!-- include: partials/implementer-prompt.md#INNER_OUTER_LOOP -->
229
239
 
@@ -236,19 +246,22 @@ Then splice in the shared inner/outer verification loop verbatim:
236
246
  10. **Do NOT push. Do NOT force-push.** The orchestrator owns the remote.
237
247
 
238
248
  ## Required output
239
- - Status: SUCCESS or FAILURE.
249
+ - Status: SUCCESS, FAILURE, or NEEDS_INPUT (with the `questions:` block). SUCCESS means every outer gate is green.
250
+ - Gates: every outer-gate command you ran, in order, and what it returned (green, or red with the failing lines). Name any you did not run, and why.
240
251
  - New commit SHA(s) added (or amended SHA).
241
252
  - 5–15 line summary.
242
253
  - Deviations from new body + reasoning.
243
254
  ```
244
255
 
256
+ When the amend implementer (or any fixer below) returns `NEEDS_INPUT`, relay it as a clickable prompt before continuing — see [Relay a sub-agent's questions](#relay-a-sub-agents-questions-needs_input).
257
+
245
258
  For `change_kind = rebase-only` (downstream phase whose parent moved): skip the agent. The work is purely git topology.
246
259
 
247
- ### 4c. Run the three-layer review
260
+ ### 4c. Run the review loop
248
261
 
249
- Invoke [review-phase](../review-phase/SKILL.md) against the rewritten branch, passing the **new** phase body to walk against, `WORKROOT`, and the `reviewer` / `fixer` agent types with their `agent_models` tiers plus this phase's `reviewer_model_tier` / `fixer_model_tier` overrides (parsed from the rewritten body's `**Review models**:` line, null when absent). Layer 2 walks: every "Changes" item in the new body, every "Tests" entry, the new acceptance line.
262
+ Invoke [review-phase](../review-phase/SKILL.md) against the rewritten branch, passing the **new** phase body as the stated requirement, the branch's base, `WORKROOT`, the amend implementer to continue, and the tier it ran at. The reviewer runs one tier above it and reads the new body's changes, tests and acceptance line as what the diff must do. Carry on with the branch on `PASS`, or on `ACCEPTED` (the human took it with blockers open: record them in the amendment log), and stop on `STOPPED`.
250
263
 
251
- Skip this step only when `change_kind = rebase-only` (no body change → no compliance walk). Even then, spot-run review-phase's Layer 1 mechanical checks to verify the rebase didn't lose unrelated work.
264
+ Skip this step only when `change_kind = rebase-only` (no body change, and no new code to review). Even then, read `git -C <WORKROOT> diff --stat` against the pre-rebase tip to confirm the rebase didn't lose unrelated work.
252
265
 
253
266
  ### 4d. Rebase onto the (possibly-rewritten) parent
254
267
 
@@ -261,17 +274,17 @@ git -C <WORKROOT> rebase $PARENT_TIP
261
274
 
262
275
  Conflicts:
263
276
 
264
- 1. **Spawn a fixer subagent** with the conflict body + new phase body + parent's tip diff. Same fixer agent type as [review-phase](../review-phase/SKILL.md#fix-loop).
277
+ 1. **Spawn a fixer subagent** with the conflict body + new phase body + parent's tip diff: the project's `fixer` agent type, at `agent_models.fixer`.
265
278
  2. Fixer resolves, runs inner + outer gate (in `<WORKROOT>`).
266
279
  3. Orchestrator continues the rebase: `git -C <WORKROOT> rebase --continue`.
267
280
 
268
- Repeat until the rebase finishes clean. If the fixer can't resolve after one retry → stop. Surface to user; do not push a half-rebased branch.
281
+ Repeat until the rebase finishes clean. If the fixer can't resolve after one retry → stop; do not push a half-rebased branch. Show the conflicting files and ask via `AskUserQuestion` (header `Rebase`): `Abort rebase, stop the run (Recommended)` (`git rebase --abort`; branch stays as it was), `Retry with guidance` (the free-text answer goes into a new fixer prompt), `I'll resolve it by hand` (leave the rebase in progress and exit).
269
282
 
270
283
  ### 4e. Force-push (with confirmation)
271
284
 
272
285
  `AskUserQuestion`:
273
286
 
274
- - `Force-push <branch> now (was authorized in Step 0)`
287
+ - `Force-push <branch> now (Recommended)` (was authorized in Step 0)
275
288
  - `Pause — let me look at the local state first`
276
289
 
277
290
  On confirm:
@@ -327,6 +340,10 @@ After every queue entry processes:
327
340
  3. List any phases blocked from rewrite (Step 3 refusals) with the recommended forward path.
328
341
  4. Reminder: reviewers on existing PRs need a re-review request — force-push erases context. Send a short comment on each affected PR (the orchestrator can do this via the PR CLI if the project's PR policy = "agents create PRs"; otherwise hand off to the human).
329
342
 
343
+ <!-- include: partials/relay-questions.md#RELAY -->
344
+
345
+ <!-- include: partials/maestro-live-run.md#OPERATOR_RECIPES -->
346
+
330
347
  ## Important rules
331
348
 
332
349
  - **Never `--force`. Always `--force-with-lease`.** Protects against silent overwrites.
@@ -335,8 +352,9 @@ After every queue entry processes:
335
352
  - **Never use `§N` shorthand to point at sections** — neither in this skill body, the rewritten plan body, the amendment log entry, nor any prs-context refresh. Always use the section's full name (and link when possible).
336
353
  - **Phases merged to `{{DEFAULT_BRANCH}}` are immutable.** Convert to `append-new` phases. Refuse to attempt rewrites.
337
354
  - **Confirm every force-push individually.** No batch "confirm all".
355
+ - **Every stop for human input is a structured question.** `AskUserQuestion` with 2–4 concrete options, the recommended (safest) one first — see **Asking the human** in [AGENTS.md](../../../AGENTS.md). Never end a turn with a prose question. Sub-agents return `NEEDS_INPUT`; the orchestrator relays it.
338
356
  - **`WORKROOT` is resolved once, used everywhere.** Every `git` call takes `git -C <WORKROOT>`; no per-step worktree branching.
339
- - **Three-layer review on every rewritten branch.** Same standard as [implement-plan](../implement-plan/SKILL.md) — via [review-phase](../review-phase/SKILL.md). The amendment isn't done until Layer 3 passes.
357
+ - **The review loop on every rewritten branch.** Same standard as [implement-plan](../implement-plan/SKILL.md) — via [review-phase](../review-phase/SKILL.md). The amendment isn't done until the reviewer explicitly approves.
340
358
  - **PR-context file is a derived artifact.** Refresh it after the rewrite; never edit the file as a substitute for fixing the diff.
341
359
  - **Subagents commit but never push.** Orchestrator owns force-push. {{PR_RULE_TAIL}}.
342
360
  {{COAUTHOR_RULE_LINE}}
@@ -347,6 +365,7 @@ After every queue entry processes:
347
365
  ## Quick checklist (orchestrator, per amendment run)
348
366
 
349
367
  - [ ] User-requested change captured verbatim; classification determined (`body-rewrite` / `insert-new` / `append-new` / `guiding-decisions-change`).
368
+ - [ ] Live maestro run checked: when one exists and the user chose to amend it, the plan and the workflow were edited, committed on `plan/<workflow-id>/base`, and applied with `vinta-ai-maestro amend`; Steps 2–5 skipped.
350
369
  - [ ] Plan parsed; per-phase state map built (state, branch, base, pr_status, merged_to_default); `WORKROOT` resolved from tracking `run_options`.
351
370
  - [ ] Blast-radius signals computed; `low` → straight to confirmation, `high-blast-radius` / `restart-recommended` → user offered `Restart` / `Amend in place` / `Stop` before the force-push plan is shown.
352
371
  - [ ] On `Restart` choice: new plan drafted (or hand-off to [plan-feature](../plan-feature/SKILL.md)); old plan annotated `Superseded`; tracking marked; this skill exits.
@@ -354,7 +373,7 @@ After every queue entry processes:
354
373
  - [ ] Plan file edited; amendment log entry appended; committed on `{{DEFAULT_BRANCH}}`.
355
374
  - [ ] Rewrite queue ordered by stack depth (parent first).
356
375
  - [ ] For each entry: body change applied (when `amend-existing`); inner + outer gate green.
357
- - [ ] [review-phase](../review-phase/SKILL.md) run on each rewritten branch; BLOCKERs fixed; SHOULD-FIX noted.
376
+ - [ ] [review-phase](../review-phase/SKILL.md) run on each rewritten branch, and returned `PASS` (or `ACCEPTED`, with its open blockers in the amendment log).
358
377
  - [ ] Rebase onto rewritten parent; conflicts resolved via fixer; tests re-run.
359
378
  - [ ] `--force-with-lease` push confirmed and executed per branch.
360
379
  - [ ] PR-context file refreshed (pending or republished).
@@ -1,12 +1,15 @@
1
1
  ---
2
2
  name: implement-phase
3
3
  description: Internal execution step of [implement-plan] / [amend-plan] — NOT a standalone entry point. Given one already-classified plan phase plus the resolved `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER`, it composes a token-efficient implementer prompt, picks the model from the phase's own suggestion, and spawns exactly one implementer subagent, returning that agent's report. Do not invoke directly for ad-hoc edits or in response to a user's raw feature request; the conductor invokes it once per executable phase in {{PROJECT_NAME}}.
4
+ disable-model-invocation: true
4
5
  ---
5
6
 
6
7
  # Implement one phase
7
8
 
8
9
  Execution unit invoked by [implement-plan](../implement-plan/SKILL.md) (and by [amend-plan](../amend-plan/SKILL.md) for `amend-existing` rewrites). One phase in → one implementer report out. This skill does **not** review, branch, push, or open PRs — those are [review-phase](../review-phase/SKILL.md) and [integrate-phase](../integrate-phase/SKILL.md). It also does **not** decide whether a phase runs — the conductor already filtered cross-repo / flag-removal phases.
9
10
 
11
+ <!-- include: partials/dispatched-agent.md#CONDUCTOR_ENTRY_GUARD -->
12
+
10
13
  ## Inputs (passed by the conductor as data — this skill re-derives none of them)
11
14
 
12
15
  - `phase` record: `{ id, title, goal, body, spec_use_case, depends_on, wave, base_branch, crew_member, crew_tier, suggested_model_tier, reusable_skills, has_e2e, acceptance }`. `crew_member` / `crew_tier` come from the phase's `**Assigned to**:` line and the plan's **Crew** table; `suggested_model_tier` is the legacy path and is set only on a plan with no roster. Exactly one of the two is populated.
@@ -44,6 +47,14 @@ A phase that combines shapes → the agent type stays `implementer`, and the pro
44
47
 
45
48
  **Concurrent invocations are expected.** The conductor may have several lanes in flight, each running its own copy of this skill against a different phase. Nothing here is shared: the prompt, the model pick, the spawn, and the returned report all belong to one phase in one `WORKROOT`. Never read another lane's worktree, branch, or tracking entry — if this phase needs something from another phase, that is a dependency edge the plan should have declared.
46
49
 
50
+ ## 4. Check for stray writes
51
+
52
+ <!-- include: partials/worktree-seam.md#STRAY_WRITE_CHECK -->
53
+
54
+ [review-phase](../review-phase/SKILL.md) runs the same check after each round of fixes.
55
+
56
+ <!-- include: partials/relay-questions.md#RELAY -->
57
+
47
58
  ## Output
48
59
 
49
- Return the implementer's single final report verbatim to the conductor (status, files, summary, deviations, blockers). The conductor — not this skill — writes tracking from the git diff + the report.
60
+ When the implementer returns `NEEDS_INPUT`, relay it (above) and resume until it returns `SUCCESS` or `FAILURE`. Then return the implementer's single final report verbatim to the conductor (status, files, summary, deviations, blockers), plus the relayed decisions so the conductor can record them in tracking. The conductor — not this skill — writes tracking from the git diff + the report.