vinta-ai-workflows 0.6.0 → 0.7.0-alpha1

package/CHANGELOG.md

@@ -5,6 +5,264 @@ 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.7.0] — YYYY-MM-DD
+
+<!-- pre-release: 0.7.0-alpha1 on 2026-09-11 -->
+
+### Added
+
+- **A plan staffs a team, instead of picking a model per phase.** Choosing a tier
+  phase by phase answers "what runs this one" ten times and never adds it up, so the
+  two questions that decide what a feature costs go unasked: how many agents does
+  this need at once, and is any of them too junior for what it was handed.
+  - `plan-feature` opens **Phased Rollout** with a **Crew** table — one row per
+    agent, carrying its tier and the phases it takes — and every phase carries an
+    **`**Assigned to**:`** line naming one of them. It replaces
+    `**Suggested AI model**:`; a plan that still has the old line keeps working, and
+    the executor reads the tier straight off it.
+  - The **Execution graph** table gains an **Agent** column and an **Idle** note.
+    Reading across a row says who is working that wave; reading down a column says
+    who is not. A wave that will serialize because the roster cannot staff it is now
+    stated in the plan rather than discovered as a slow run.
+  - **Every member has to earn their place**, by concurrency (a wave genuinely needs
+    that many hands *at or above* those phases' tiers) or by cheapness (they take
+    work a dearer member would otherwise do). The roster is therefore **not** capped
+    at the widest wave — a junior who runs the migration and the flag deletion is
+    worth having in a graph that never runs two phases at once — but the lane pool
+    still is, because lanes are bought with concurrency and crew are not.
+  - **Reviewers are a role on the crew, and implementers and reviewers are
+    disjoint.** A member has `role: implementer` or `role: reviewer`; a phase cannot
+    be assigned to a reviewer and a reviewer never writes code, so an agent reading
+    its own diff is not something a plan can express. A phase is read by the
+    cheapest reviewer at or above its tier. A roster with no reviewer still runs and
+    falls back to `agent_models.reviewer`, cold, one session per phase.
+    - **A reviewer reads the lane it is reviewing**, with the phase's changes still
+      uncommitted in it, and has no worktree of its own. That is what puts review
+      before the commit: a finding is fixed in the working tree rather than
+      recorded as a mistake on the branch plus a correction after it. The cost is
+      that a reviewer's directory follows the work, so its session carries only
+      between reviews that land in the same lane.
+  - **A crew member is an agent that lives for the whole run.** Each one keeps its
+    own worktree and its own session across every phase it takes, so the agent that
+    takes Phase 4 still knows what it learned about the codebase in Phase 1 —
+    which is most of what a cold agent's first turn of a phase is spent
+    rediscovering.
+    - This works because the *directory* stops moving. Lanes used to be anonymous
+      slots handed out by a free list, so a member landed somewhere different each
+      phase and its context described paths it was not standing in. Pinning each
+      member to one worktree leaves a far smaller question — which files changed —
+      and `git diff --name-only` answers it exactly.
+    - A cross-phase continuation therefore gets the new phase's **full brief** (it
+      is new work, not a delta) behind a re-orientation: same agent, same directory,
+      everything you learned still holds; the tree is on a different branch; these
+      files differ; and — the sentence that matters most — whether the previous
+      phase's own work is in this tree at all.
+    - A delta that cannot be computed is reported as **unknown**, never as empty.
+      "Nothing changed" is the one wording that would stop an agent re-reading.
+    - Two things still start cold: a member whose previous phase **failed**, because
+      its session is the context that failed with it, and the final fix round.
+    - The cost, stated plainly: **one worktree and one set of forked databases per
+      implementer**, so `resources.lane.capacity` is now the implementer count
+      rather than the widest wave, and adding a cheaper implementer is a trade of
+      disk against money rather than free.
+  - The workflow document gained a top-level **`crew`** block and **`nodes[].crew`**.
+    A staffed node carries no `model` — the member has one — and a document that is
+    half-staffed, names a member nobody declared, assigns a phase to a reviewer,
+    declares an implementer nobody is assigned to, or staffs a reviewer below every
+    phase on the plan is refused before the run starts.
+  - `vinta-ai-maestro` claims an agent **before** the lane, prefers the member the plan
+    named, covers with the **cheapest** qualified free peer when they are busy, and
+    **waits rather than handing a phase below its tier** — even with a lane free. A
+    lane is disk; a phase run by too junior an agent does not fail cleanly, it fails
+    review two rounds later with nothing pointing back at the staffing. A reviewer is
+    claimed per review turn rather than per phase — it has one session ledger and
+    two concurrent reviews would collide over it — so one reviewer on a three-lane
+    plan is a queue at the review step and not a serialised run.
+  - The run view reports who actually worked against who the plan said would.
+    `substituted` is the figure to read beside a cost that overran: every
+    substitution ran at or above the budgeted tier, so a run can be entirely green
+    and still have been staffed dearer than planned.
+
+- **`implement-plan` runs independent phases in parallel.** The plan now carries a
+  dependency graph and the conductor schedules against it: a phase starts as soon as
+  every phase it depends on is green and a worktree lane is free, instead of waiting
+  for its turn in plan order. A chain-shaped plan behaves exactly as before —
+  sequential execution is the one-lane case of the same scheduler.
+  - `plan-feature` gives every phase a **`**Depends on**:`** line naming the artifact
+    it needs from each upstream phase, and opens **Phased Rollout** with an
+    **Execution graph** table derived from those lines. It also checks same-wave
+    phases against the **Touch List** for file overlap and tells you to add an edge
+    when two phases would fight over the same file.
+  - New shared partial `plan-execution/partials/parallel-lanes.md` carries the graph
+    parse, the worktree lane pool, the dependency-derived branch topology, the
+    dispatch loop, the tracking-directory schema, and the sibling-lane write guard.
+  - `prepare-worktree` documents provisioning a **pool** of lanes for one plan and
+    records a `reset_cmd` per forked DB so a lane can be reused across phases without
+    carrying the previous phase's migrations into the next one's test run.
+  - Two new config fields: `run_options.implement-plan.parallel_phases` (default
+    `true`) and `run_options.implement-plan.max_parallel_lanes` (default `3`), asked
+    at bootstrap alongside the existing `prepare-worktree` follow-ups.
+
+- **`plan-feature` emits an executable `ai-plans/<feature-kebab>.workflow.json`
+  beside every plan.** The markdown stays the document humans review; the JSON is
+  the same phase graph in the form an orchestrator runs — one node per phase, one
+  `depends_on` entry per `**Depends on**:` clause carrying both the upstream phase
+  and the artifact it provides, plus the phase's Touch List, gates, capacity pools
+  and model tier. Validated by
+  [`schemas/workflow.v1.schema.json`](schemas/workflow.v1.schema.json), which the
+  emitted file references from its `$schema` key so editors validate it as it is
+  written. **Unconditional** — no config field, no bootstrap question, no opt-in:
+  a project with no orchestrator carries a file nothing reads, and a project that
+  adopts one later finds its plans already executable.
+
+- **Review findings go back to the phase's own implementer, not to a fresh fixer.**
+  The agent that wrote the code still holds the phase brief, the plan's bounds, the
+  dependency context and its own reasoning; a fresh fixer held a quoted finding and
+  had to rediscover the rest — slower, dearer, and likelier to "fix" a symptom by
+  undoing something the phase chose deliberately. The fix message is now a delta —
+  the findings, nothing else — because re-sending the brief invites a
+  re-implementation rather than a fix.
+
+  Three rules keep that from costing what it buys. **The reviewer is never the
+  implementer**: continuing the reviewer across rounds is fine, but the review must
+  come from an agent that did not write the code. **The last round before giving up
+  goes to a fresh fixer, always** — reuse means the agent that wrote the bug is
+  fixing it, which is usually the point and occasionally exactly wrong, because that
+  assumption *was* the bug. And where a runtime cannot continue a finished
+  sub-agent, the old cold hand-off still happens and is recorded as one, so a slow
+  phase can be read later without guessing.
+
+  One consequence worth knowing: a continued implementer fixes at its own crew
+  member's tier, so `agent_models.fixer` now governs only the cold cases. A project
+  that set `fixer` cheap to save money is saving it on fewer rounds.
+
+- **The workflow schema gained `defaults.max_session_turns`.** Optional, default
+  12. An orchestrator that reuses one agent session across a phase's implement
+  and fix turns needs a ceiling on how long that session may grow before the next
+  turn starts cold; without one a long phase eventually dies on a context-window
+  error that reads as a broken harness. `plan-feature` omits the field — it is a
+  safety limit, not something a plan tunes — and its field table says so.
+
+- **`plan-feature` asks about the project's databases and emits the workflow's
+  `project` block.** The block records what a phase lane must **fork** to be a
+  working checkout — the `dev` and `test` databases, and the project's own
+  migrate command, which runs once per template database rather than once per
+  lane. Without it every lane got a git worktree and nothing else, so two phases
+  running concurrently pointed their test gate at the same rows. Asked at
+  emission time with one `AskUserQuestion` call ("what does a phase lane need its
+  own copy of", "how is that database delivered"); the rest — the migrate
+  command, the database names, the env var names — is read out of the project's
+  settings and task runner rather than asked.
+
+  Two rules the skill is explicit about, because both are easy to get wrong:
+  **sharing is the absence of a declaration** (there is no `share` value, and a
+  lane that reads the main checkout's database has nothing to describe), and
+  **each role names its own database** (a lane's fork is named from `name` and
+  the lane, not the role, so `dev` and `test` sharing one `name` collapse to one
+  forked database). Everything `prepare-worktree` discovers per worktree —
+  `reset_cmd`, compose project names, volume forks, seed commands, env-file
+  strategy — stays out of the block by design.
+
+- **New schema
+  [`postmortem.v1.schema.json`](schemas/postmortem.v1.schema.json)** — the
+  structured plan post-mortem an orchestrator writes at
+  `.vinta-ai-maestro/runs/<run-id>/postmortem.json` once a run has ended: dependencies
+  that were declared but never used, dependencies discovered at gate time,
+  same-wave phases that actually conflicted, and phases whose real duration
+  diverged from their wave placement. `plan-feature` reads it before drawing the
+  next feature's Execution graph, which is what stops a plan from repeating a
+  defect the last run already paid for. Like
+  [`workflow.v1.schema.json`](schemas/workflow.v1.schema.json) it is
+  **generated** from a zod source rather than hand-written — see
+  [`schemas/README.md`](schemas/README.md).
+
+### Changed
+
+- **Phase branches base on their dependencies, not on the previous phase.** A phase
+  with no dependencies cuts from the default branch; one with a single dependency
+  cuts from that phase's branch; one with several cuts from a
+  `plan/{plan-id}/integ-{phase-id}` branch that merges them. Each wave is then merged
+  into a `plan/{plan-id}/wave-{N}` integration branch, which is what a resume anchors
+  on and what the final report points at. The PR `base` follows the same value —
+  a stacked plan produces exactly the stack it did before.
+- **Tracking is a directory, not a file.** `{{PLAN_DIR}}/TRACKING_{plan-id}/` holds
+  `run.md` (conductor-owned), one `phase-{id}.md` per phase (written only by the lane
+  that ran it, committed on that phase's own branch), and `waves/wave-{N}.md`. No two
+  branches write the same path, so wave merges no longer conflict on tracking. A run
+  started under the old single-file layout is migrated on resume.
+- **An implementer is told about its dependencies only.** Prior-phase context passed
+  into a phase prompt is now that phase's transitive dependency closure rather than
+  "everything finished so far" — a sibling lane's work is not in the phase's base
+  branch, and describing it as done made the implementer code against files it could
+  not see.
+- **The stray-write guard covers sibling lanes.** The sandbox denies the whole
+  worktree pool root and allows back only the running lane; the review-phase backstop
+  checks the main checkout and every sibling workroot after each implementer and
+  fixer. A write into a lane that is mid-implementation is worse than a stray
+  main-checkout write.
+- **`amend-plan` cascades along the dependency graph.** A rewrite touches the
+  amended phase's dependent closure instead of "every phase with a higher number",
+  rebases in topological order, rebuilds `integ-` bases before rebasing a
+  multi-dependency phase onto them, and refuses to run while any phase is still in
+  flight. It gained a `dependency-change` amendment kind for edits to a
+  `**Depends on**:` line.
+- **`implement-plan` refuses rather than degrading** when parallel execution is asked
+  for but worktrees are unavailable — several agents cannot share one working tree,
+  and silently falling back to sequential would discard the schedule the user
+  approved.
+- **`modular-commits` supports parallel runs**: lanes commit their atomic units on
+  `plan/{plan-id}/lane-{phase-id}` branches, merged `--no-ff` into the single plan
+  branch at each wave boundary, so the unit commits survive.
+
+### Fixed
+
+- **Lane provisioning serializes `git worktree add`, not only the database
+  template.** `prepare-worktree` previously named one serialization point; there
+  are two. Git rewrites `.git/worktrees/` metadata on every add, and concurrent
+  adds against one repository clobber each other's entries — a reproducible
+  corruption, not a theoretical race. Worktrees are added one at a time; the
+  expensive per-lane work (dependency linking, database cloning, summary
+  writing) still overlaps around it.
+
+- **The conflict-fixer round budget is an integration-level setting, not a
+  phase's `max_fix_rounds`.** `parallel-lanes.md` now says so, and defaults it to
+  two. A merge conflict belongs to a *pair* of phases, so deriving the budget
+  from one of them made the answer depend on which phase happened to merge
+  second.
+
+- **A resolved merge conflict is confirmed by scanning the files, never by asking
+  git.** `git add` clears a path's unmerged flag whether or not `<<<<<<<` is
+  still sitting in it, so git's index cannot answer "did the fixer actually fix
+  it". `parallel-lanes.md` now requires scanning the conflicted paths for
+  conflict markers before the merge is committed. Without it, a fixer that did
+  nothing produces a merge commit full of markers that passes into the wave
+  branch unnoticed.
+
+> The repository also gained `packages/vinta-ai-maestro/`, a **private workspace
+> package** that executes these workflows. It is not published and is not part of
+> the `vinta-ai-workflows` package — the root `files` whitelist excludes
+> `packages/`, so nothing in it is installed by `npx vinta-ai-workflows install`.
+> What ships from that work is the two generated schemas above and the skill
+> changes that produce and consume them.
+>
+> Its browser UI is now built on `packages/design-system/` (`vinta-design-system`),
+> a second private workspace package: oklch tokens in three layers mirroring
+> `vinta-schedule-design-system`, six run-status **tones** (`idle`, `active`,
+> `wait`, `attention`, `ok`, `error` — waiting is amber and failure is red, never
+> the same hue), shadcn/ui components on Tailwind CSS v4, a small layout kit, and
+> a light/dark/system theme. The run graph and the pipeline editor are re-skinned
+> through their own custom properties, so the canvas and the badges beside it
+> share one palette. Equally unpublished: nothing in it reaches `npx
+> vinta-ai-workflows install`.
+
+## [0.6.1] — 2026-08-17
+
+### Fixed
+
+- **Codex sub-agent descriptions are emitted as valid TOML basic strings.**
+  Newlines and other control characters are escaped when
+  `setup-ai-tools.mjs` generates `.codex/agents/*.toml` files.
+
 ## [0.6.0] — 2026-08-17
 
 ### Changed

package/README.md

@@ -48,9 +48,9 @@ After bootstrap, the project ships with **three foundation skills** that take a
    └─────────────────┘      Phased Rollout, Touch List, Risks)
             │
             ▼
-   ┌─────────────────┐    one stacked branch per phase + tracking file
-   │  implement-plan │───►  plan/<feature>/phase-1, phase-2, ...
-   └─────────────────┘      pushed to GitHub / GitLab / etc.
+   ┌─────────────────┐    one branch per phase (independent phases run in
+   │  implement-plan │───►  parallel lanes) + a tracking dir
+   └─────────────────┘      plan/<feature>/phase-1, phase-2, wave-1, ...
 ```
 
 You also get: an `AGENTS.md` tuned to the codebase — a regular file at the repo root, with per-vendor aliases (`CLAUDE.md`, `.github/copilot-instructions.md`) symlinked to it — project-specific sub-agents and skills derived from the actual stack, and per-vendor wiring so Claude Code / Codex / Cursor / Copilot all see the same artifacts.
@@ -80,7 +80,7 @@ The bootstrap skills are **one-shot**. They scaffold the project once and are re
 - **Goals + Non-goals** — what's in / out of scope.
 - **Guiding Decisions** — feature flag (key, scope, default, flip-on criterion if any), storage shape, tenant scoping, API contract, schema rules. Load-bearing — every phase reaches back here.
 - **Data Model Changes** — migrations + rollout order.
-- **Phased Rollout** — each phase declares: `id`, `title`, `goal`, `Suggested AI model` (per vendor — implement-plan picks the cheapest available), `reusable_skills` (other project skills the implementer should invoke), `Changes`, `Tests`, `Acceptance`, plus flags for `is_cross_repo` and `is_flag_removal` (both deferred).
+- **Phased Rollout** — opens with a **Crew** table (the agents this plan is staffed with, each with a role — `implementer` or `reviewer` — and a tier; every implementer keeps one worktree and one session for the whole run, while reviewers read the lane they are reviewing before it is committed), then each phase declares: `id`, `title`, `goal`, `Assigned to` (which crew member takes it — implement-plan resolves their tier to the cheapest available model), `reusable_skills` (other project skills the implementer should invoke), `Changes`, `Tests`, `Acceptance`, plus flags for `is_cross_repo` and `is_flag_removal` (both deferred).
 - **Risk & Rollout Notes**, **Open Questions**, **Touch List**.
 
 Phases are sized so the slowest path (e.g. cross-repo producer wiring, external integration approval) starts in Phase 1 and fast in-repo work fills in behind. Large mutation phases get split (`4a / 4b / 4c`) rather than monolithic.
@@ -105,28 +105,34 @@ Phases are sized so the slowest path (e.g. cross-repo producer wiring, external
    - **Layer 3 — independent reviewer**: spawn a fresh `reviewer` agent with no implementation context. Findings triaged BLOCKER / SHOULD-FIX / NIT.
 6. **Fix loop**: each finding → spawn a `fixer` agent (separate session) that re-runs inner + outer loops; orchestrator never edits directly. Repeat until all three layers are clean.
 
-**Branch model — one branch per phase, stacked:**
+**Branch model — one branch per phase, based on that phase's dependencies:**
+
+Every phase in the plan declares what it needs (`**Depends on**: Phase 1 (the `BookmarkFolder` model), …`). That line — not the phase's number — decides both when it runs and what it branches from.
 
 ```bash
-# First executed phase — branches from the default branch.
+# A phase with no dependencies — branches from the default branch.
 git checkout main && git pull --ff-only
 git checkout -b plan/<feature-kebab>/phase-1
-# implementer's commits land here
 git push -u origin plan/<feature-kebab>/phase-1
 
-# Phase 2 stacks on phase 1 — never branches back to main.
+# A phase depending on exactly one phase — branches from it.
 git checkout plan/<feature-kebab>/phase-1
 git checkout -b plan/<feature-kebab>/phase-2
 git push -u origin plan/<feature-kebab>/phase-2
 
-# Phase 3 stacks on phase 2, etc.
+# A phase depending on several — branches from a merge of them.
+git checkout -B plan/<feature-kebab>/integ-4 plan/<feature-kebab>/phase-2
+git merge --no-ff plan/<feature-kebab>/phase-3
+git checkout -b plan/<feature-kebab>/phase-4
 ```
 
-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.
+Each phase's PR (or branch, depending on the project's PR policy captured at bootstrap) targets its own base, not `main`. This keeps the diff per PR scoped to a single phase, makes review manageable, and lets the team merge as approvals land. A plan whose phases form a chain produces exactly the classic stack; a plan with independent phases produces several short stacks, reunited by per-wave integration branches (`plan/<feature-kebab>/wave-<N>`).
+
+**Parallel phases.** Because the plan carries a dependency graph, `implement-plan` implements independent phases **at the same time** — one worktree lane per phase in flight, each with its own dev + test database and compose stack, so concurrent test runs don't collide. A phase starts the moment every phase it depends on is green and a lane frees up; a failed phase blocks only its dependents while the rest of the plan keeps going. On by default (`run_options.implement-plan.parallel_phases`, capped by `max_parallel_lanes`, default 3), it requires `prepare-worktree` and refuses to run rather than silently falling back to sequential when worktrees aren't available. A chain-shaped plan runs one phase at a time — same scheduler, one lane.
 
 **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.
+**Tracking directory** — `ai-plans/TRACKING_<feature-kebab>/`. The orchestrator writes it from `git diff` + the agent's report (not the agent's narration): `run.md` for run options, the resolved dependency graph, and the lane pool; one `phase-<id>.md` per phase (status, model used, branch, base, wave, e2e+screenshots when applicable, 5–15 line summary); `waves/wave-<N>.md` for each integration merge. It is a directory rather than one file so concurrent lanes never write the same path — each phase's entry is committed on that phase's own branch, which keeps wave merges clean. Acts as the durable context handoff between phase prompts, scoped per phase to its own dependencies. Deleted on plan completion.
 
 **Phases the orchestrator never auto-executes:**
 
@@ -218,7 +224,7 @@ The 0.2.0 alpha line adds five foundation skills and restructures plan execution
 
 - **`handoff` (always)** — writes a session-continuation doc to `.vinta-ai-workflows/handoffs/` so a fresh session, a different agent, or a teammate can resume in-flight work without re-deriving context. Write mode gathers the goal, what's verified vs. still assumed, decisions and the alternatives rejected, landmines, and the single concrete next step **from the repo, never from memory**. Resume mode reads a handoff and re-checks its claims against the repo before trusting them.
 - **`deslop-comments` (always)** — rewrites the comments and doc blocks a task touched into Simple English, stripping AI-slop vocabulary and negative framing. Comment-only: no renames, no behavior change. It's wired into the review flow — `review-phase` Layer 2 gained a comment-hygiene check and dispatches a `fixer` to run this skill on any comment-slop finding — and is also invokable standalone ("deslop these comments").
-- **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and decides per ignored path whether to symlink, copy, or fork (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it.
+- **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and decides per ignored path whether to symlink, copy, or fork (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase.
 - **`thermo-nuclear-code-quality-review` (opt-in)** — a deliberately harsh, on-demand structural-maintainability audit of a diff (abstraction quality, giant files, spaghetti-condition growth) that hunts for "code-judo" reframes collapsing whole branches / helpers / modes / layers rather than polishing them. Read-only — it reports findings and hands each fix to a `fixer`. `review-phase` Layer 3 now applies a condensed version of this lens on every phase and escalates to the full audit only when a phase touches core architecture, crosses ~1,000 lines, or surfaces a structural smell too big to fix inline.
 - **`handoff-to-client` (opt-in, API-only repos)** — generates a self-contained markdown document for the client teams consuming the repo's API: every endpoint / operation added, changed, deprecated, or removed on the current branch vs. the default branch, with request/response shapes derived from the code, auth + error changes, breaking-change flags judged from the strictest plausible client, one realistic example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (required `client_platforms`, plus `api_style` / `api_spec_path` / `output_dir`).
 
@@ -246,7 +252,7 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
 | `add-e2e-test` | **opt-in** | Add an e2e test. Body covers e2e framework, page-object pattern, auth/storage-state, seed helpers, tenant scoping, screenshot conventions. |
 | `add-env-var` | **opt-in** | Propagate a new env var through every layer (`.env.example`, build tool envPrefix, build cache hash, app config, AGENTS.md, CI, deploy injection). |
 | [`add-one-off-script`](skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md) | **opt-in** | Author one-off operational scripts (backfills, cleanups, ad-hoc fixes). Ships a `BaseOneOffScript` class (Python + TS) enforcing dry-run default, idempotency, batched DB ops, segmented CSV backups, signal-safe interruption, multi-sink logging. |
-| [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it. |
+| [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase. |
 | [`thermo-nuclear-code-quality-review`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | **opt-in** | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to `fixer`. `review-phase` Layer 3 runs a condensed lens every phase and escalates to this full audit on core-architecture / ~1000-line / structurally-smelly phases. |
 | `handoff-to-client` | **opt-in** | (API-only repos) Generate a self-contained API-change handoff doc for the client teams consuming the repo's API — every endpoint / operation added / changed / deprecated / removed vs the default branch, with request/response shapes, auth + error changes, breaking-change flags, one example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (client platforms, API style, spec path). |
 
@@ -572,6 +578,8 @@ vinta-ai-workflows/
 
 `vinta-bootstrap-ai-tools` is the entry point — walks a fresh repo, runs the others in order. The rest can also be invoked individually to refresh a single artifact.
 
+The repository is also a pnpm workspace. `packages/` holds **private, unpublished** packages that are not part of what `install` puts in your project — the `files` whitelist excludes the directory. The one worth knowing about is [`packages/vinta-ai-maestro`](packages/vinta-ai-maestro/README.md): an opt-in daemon that executes the `ai-plans/<feature>.workflow.json` files `plan-feature` emits, scheduling independent phases across worktree lanes. Nothing requires it; the skills path runs the same plans with no daemon installed.
+
 ### Why the `vinta-` prefix?
 
 Once installed, these skills sit alongside the user's own project skills in the same `.<vendor>/skills/` directory. The prefix makes ownership obvious in slash menus and on disk: anything under `vinta-*` is managed by this package and gets removed by `uninstall`; anything else belongs to the project.

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.6.0",
+  "version": "0.7.0-alpha1",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
+  "packageManager": "pnpm@10.33.0",
   "bin": {
     "vinta-ai-workflows": "./vinta-ai-workflows.mjs"
   },
   "scripts": {
-    "check-ai-models": "node scripts/check-ai-models.mjs"
+    "check-ai-models": "node scripts/check-ai-models.mjs",
+    "test": "node --test tests/*.test.mjs"
   },
   "devDependencies": {
     "yaml": "^2.4.0"

package/schemas/README.md

@@ -1,6 +1,6 @@
 # Schemas
 
-JSON Schema (Draft 2020-12) contracts for every YAML file the vinta-ai-workflows toolchain produces or consumes. Every YAML file carries a `schema_version` integer at its top level; that integer matches the suffix on the schema filename.
+JSON Schema (Draft 2020-12) contracts for every YAML or JSON payload the vinta-ai-workflows toolchain produces or consumes. Every payload carries a `schema_version` integer at its top level; that integer matches the suffix on the schema filename.
 
 ## Inventory
 
@@ -12,6 +12,10 @@ JSON Schema (Draft 2020-12) contracts for every YAML file the vinta-ai-workflows
 | PR-context inline comments | YAML inside the ` ```yaml ... ``` ` fence under `# Comments` of the same file | [`prs-context-comments.v1.schema.json`](prs-context-comments.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
 | MCP preflight cache | `.vinta-ai-workflows/cache.yaml` (gitignored — per-developer-machine state) | [`mcp-preflight-cache.v1.schema.json`](mcp-preflight-cache.v1.schema.json) | rendered `systematic-debugging` SKILL.md (writes during Phase 0) | rendered `systematic-debugging` SKILL.md (reads at Phase 0 start) |
 | AI model tier table | `ai-tools/skills/plan-feature/resources/ai-models.yaml` (shipped verbatim with the `plan-feature` foundation skill; source: `skills/vinta-derive-skills/resources/foundation-skills/plan-feature/resources/ai-models.yaml`) | [`ai-models.v1.schema.json`](ai-models.v1.schema.json) | nightly `check-ai-models` job ([`scripts/check-ai-models.mjs`](../scripts/check-ai-models.mjs)) → auto-PR | `plan-feature` (per-phase model suggestion) |
+| Workflow (executable plan) | `ai-plans/<feature-kebab>.workflow.json` — **JSON, not YAML** | [`workflow.v1.schema.json`](workflow.v1.schema.json) | `plan-feature` (emitted alongside the human-readable plan) | `vinta-ai-maestro` (the orchestrator daemon) |
+| Plan post-mortem | `.vinta-ai-maestro/runs/<run-id>/postmortem.json` — **JSON, not YAML**; per-run state beside the frozen workflow, copied to `ai-plans/<feature-kebab>.postmortem.json` when a team wants it committed | [`postmortem.v1.schema.json`](postmortem.v1.schema.json) | `vinta-ai-maestro` (once a run has ended) | `plan-feature` (when planning the next feature in the same repo) |
+
+> `workflow.v1.schema.json` and `postmortem.v1.schema.json` are the two schemas here that are **generated, not hand-written**. The workflow's source of truth is `packages/vinta-ai-maestro/src/types.ts`; regenerate with `pnpm --filter vinta-ai-maestro schema:gen` and verify with `schema:check`. The post-mortem's is `packages/vinta-ai-maestro/src/postmortem/postmortem.ts`; regenerate with `node --experimental-strip-types src/postmortem/generate.ts` from `packages/vinta-ai-maestro`, verify with the same command plus `--check` — `tests/postmortem.test.ts` runs that byte comparison too. Edit the zod schemas, never the JSON.
 
 ## Versioning rules