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.
- package/CHANGELOG.md +472 -595
- package/README.md +33 -19
- package/package.json +4 -1
- package/schemas/README.md +11 -3
- package/schemas/ai-models.v1.schema.json +5 -0
- package/schemas/interview-answers.v1.schema.json +122 -0
- package/schemas/interview-round.v1.schema.json +346 -0
- package/schemas/plan-review.v1.schema.json +342 -0
- package/schemas/postmortem.v1.schema.json +848 -3
- package/schemas/prs-context-comments.v1.schema.json +1 -1
- package/schemas/prs-context-frontmatter.v1.schema.json +18 -7
- package/schemas/vinta-ai-workflows-config.v1.schema.json +677 -18
- package/schemas/workflow.v1.schema.json +751 -26
- package/skills/vinta-analyze-codebase/SKILL.md +5 -0
- package/skills/vinta-bootstrap-ai-tools/SKILL.md +154 -31
- package/skills/vinta-bootstrap-ai-tools/resources/stacks/README.md +1 -1
- package/skills/vinta-bootstrap-ai-tools/resources/stacks/django/notes.md +36 -1
- package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/README.md +85 -0
- package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/lib-template.sh +160 -0
- package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/prepare-template.sh +250 -0
- package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/teardown-template.sh +96 -0
- package/skills/vinta-derive-skills/SKILL.md +23 -15
- package/skills/vinta-derive-skills/resources/dependency-license-block.md +8 -9
- package/skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md +1 -1
- package/skills/vinta-derive-skills/resources/foundation-skills/create-qa-use-cases/SKILL.md +3 -3
- package/skills/vinta-derive-skills/resources/foundation-skills/create-spec/SKILL.md +21 -2
- package/skills/vinta-derive-skills/resources/foundation-skills/handoff/SKILL.md +3 -3
- package/skills/vinta-derive-skills/resources/foundation-skills/interview-ui/SKILL.md +121 -0
- package/skills/vinta-derive-skills/resources/foundation-skills/interview-ui/resources/examples/docs/D4-concurrency.md +28 -0
- package/skills/vinta-derive-skills/resources/foundation-skills/interview-ui/resources/examples/round-01.json +60 -0
- package/skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/SKILL.md +1 -1
- package/skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh +34 -7
- package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md +363 -142
- package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/resources/ai-models.yaml +19 -13
- package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md +39 -21
- package/skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md +8 -6
- package/skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-review-loop/SKILL.md +181 -0
- package/skills/vinta-derive-skills/resources/plan-execution/README.md +40 -7
- package/skills/vinta-derive-skills/resources/plan-execution/partials/agent-models.md +14 -35
- package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/stacked.md +21 -0
- package/skills/vinta-derive-skills/resources/plan-execution/partials/dispatched-agent.md +31 -0
- package/skills/vinta-derive-skills/resources/plan-execution/partials/implementer-prompt.md +67 -6
- package/skills/vinta-derive-skills/resources/plan-execution/partials/maestro-live-run.md +44 -0
- package/skills/vinta-derive-skills/resources/plan-execution/partials/model-pick.md +9 -3
- package/skills/vinta-derive-skills/resources/plan-execution/partials/parallel-lanes.md +95 -50
- package/skills/vinta-derive-skills/resources/plan-execution/partials/pr-context.md +4 -2
- package/skills/vinta-derive-skills/resources/plan-execution/partials/relay-questions.md +13 -0
- package/skills/vinta-derive-skills/resources/plan-execution/partials/review-loop.md +81 -0
- package/skills/vinta-derive-skills/resources/plan-execution/partials/worktree-seam.md +86 -17
- package/skills/vinta-derive-skills/resources/plan-execution/shell/amend-plan-template.md +35 -16
- package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-phase-template.md +12 -1
- package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-plan-template.md +49 -33
- package/skills/vinta-derive-skills/resources/plan-execution/shell/integrate-phase-template.md +2 -1
- package/skills/vinta-derive-skills/resources/plan-execution/shell/review-phase-template.md +19 -27
- package/skills/vinta-derive-skills/resources/prs-context-template.md +5 -4
- package/skills/vinta-derive-skills/resources/systematic-debugging-mcp-tools.md +1 -1
- package/skills/vinta-derive-skills/resources/systematic-debugging-template.md +8 -8
- package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/django.md +4 -1
- package/skills/vinta-derive-skills/resources/write-unit-test-template.md +3 -0
- package/skills/vinta-derive-subagents/SKILL.md +25 -9
- package/skills/vinta-install-ai-tools-setup/SKILL.md +29 -2
- package/skills/vinta-migrate-plans-specs/SKILL.md +7 -7
- package/skills/vinta-sync-ai-tools/SKILL.md +19 -2
- package/skills/vinta-update-project-skills/SKILL.md +1 -0
- package/skills/vinta-write-agents-md/SKILL.md +10 -6
- package/skills/vinta-write-agents-md/resources/asking-the-human.md +56 -0
- 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,
|
|
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
|
|
11
|
-
| `BASE_BRANCH` | `{{DEFAULT_BRANCH}}` | `<worktree_branch>`
|
|
12
|
-
| `SANDBOX_TIER` | `none` | `enforced` or `none` (probed
|
|
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`:**
|
|
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
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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` (
|
|
25
|
-
- `worktree_summary` —
|
|
26
|
-
- `sandbox_tier` → `SANDBOX_TIER`: `enforced` (the [Filesystem sandbox](../prepare-worktree/SKILL.md#step-55--filesystem-sandbox-os-level-write-guard)
|
|
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.**
|
|
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
|
-
- **
|
|
32
|
-
- **User cancels at the confirmation gate** → tear the worktree down (
|
|
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
|
|
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
|
|
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):
|
|
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
|
|
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**,
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
- **
|
|
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
|
|
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).
|
package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-phase-template.md
CHANGED
|
@@ -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
|
-
|
|
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.
|