vinta-ai-workflows 0.2.0-alpha3 → 0.2.0-alpha5

package/CHANGELOG.md

@@ -7,6 +7,168 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.2.0] — YYYY-MM-DD
 
+### Added
+
+<!-- pre-release: 0.2.0-alpha5 on 2026-07-13 -->
+
+- **`handoff` foundation skill — session-continuation handoff docs between
+  agents.** Write mode captures the current task (goal, verified-vs-unverified
+  state, decisions + rejected alternatives, landmines, single concrete next
+  step) into `.vinta-ai-workflows/handoffs/{date}-{slug}.md`, gathering state
+  from the repo — never from memory; resume mode reads a handoff, verifies its
+  claims against the repo before trusting them, and continues from the doc's
+  next step. Ships at
+  [skills/vinta-derive-skills/resources/foundation-skills/handoff/SKILL.md](skills/vinta-derive-skills/resources/foundation-skills/handoff/SKILL.md).
+  Wired as an **always-ship** bucket-A skill: new
+  `foundation_skills.handoff` enum entry (schema), derive-skills bucket-A
+  table + always-ships note, bootstrap always-copy-verbatim list + outputs
+  tree + Step 0.5 YAML (`handoff: enabled`), and both foundation-shape
+  replace lists. No bootstrap interview question — it always ships.
+
+- **`handoff-to-client` foundation skill — API-change handoff docs for
+  API-only repos (opt-in, template-rendered).** Generates a self-contained
+  markdown document for the client teams consuming the repo's API: every
+  endpoint/operation added / changed / deprecated / removed on the current
+  branch vs the default branch, with request/response shapes derived from the
+  code (or a regenerated API spec), auth/error changes, breaking-change flags
+  judged from the strictest plausible client, one realistic example per
+  operation, and per-platform migration notes. Template at
+  [skills/vinta-derive-skills/resources/handoff-to-client-template.md](skills/vinta-derive-skills/resources/handoff-to-client-template.md)
+  (bucket B + C). New schema fields: `foundation_skills.handoff-to-client`
+  enum entry and the `skills.handoff-to-client` config block
+  (`client_platforms` — required non-empty array, `api_style`,
+  `api_spec_path`, `output_dir` — default
+  `.vinta-ai-workflows/client-handoffs`). New template placeholders
+  `{{API_STYLE}}`, `{{CLIENT_PLATFORMS_LIST}}`, `{{CLIENT_HANDOFF_DIR}}`,
+  `{{API_SPEC_BLOCK}}` documented in the derive-skills placeholder table.
+  Bootstrap gains **Optional foundation skills question 7** (asked only when
+  the inventory suggests an API-only repo) plus a four-part config follow-up;
+  Step 0.5 YAML, outputs tree, optional-bucket lists, and both
+  foundation-shape replace lists updated. **Consumers**: API-only projects
+  re-sync + answer the new interview question to enable it.
+
+<!-- pre-release: 0.2.0-alpha4 on 2026-07-08 -->
+
+- **`implement-plan` outer-gate test scope is now configurable — and defaults
+  to the quick path.** Each phase's outer gate still always runs the repo-wide
+  type/build gate, but for tests it now runs **only the scoped suite** covering
+  the apps/files that phase touched by default, instead of the whole repo suite
+  every phase (new tests still pass individually in the inner loop). This
+  **flips the previous default** (full suite every phase → scoped) to make
+  multi-phase plans materially faster. Opt back into the full suite per run via
+  the new Step 0 question (d), or set the default in
+  `.vinta-ai-workflows.yaml` under
+  `run_options.implement-plan.full_test_suite: true`. New config field
+  (`run_options.implement-plan.full_test_suite`, boolean, default `false`);
+  threaded from the conductor into `implement-phase` (outer-gate marker in the
+  implementer prompt) and `review-phase` (Layer 1 verifies whichever gate the
+  flag selects); recorded in `TRACKING_{plan-id}.md` `run_options`.
+
+- **`deslop-comments` foundation skill — Simple-English comment cleanup, now
+  part of the review flow.** Rewrites comments + doc blocks touched during a
+  task into Simple English (strips AI-slop vocabulary and negative framing;
+  comment-only — no renames, no behavior change). Ships at
+  [skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md](skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md).
+  Wired as an **always-ship** bucket-A skill (new
+  `foundation_skills.deslop-comments` enum, added to the derive-skills bucket-A
+  table + always-on note, the bootstrap always-copy-verbatim list + outputs
+  tree + Step 0.5 YAML, and both foundation-shape replace lists) because
+  `review-phase` now depends on it: **Layer 2 gains a comment-hygiene check**
+  and the **fix loop dispatches a `fixer` to run `deslop-comments`** on the
+  phase's touched files for any comment-slop finding. Also invokable
+  standalone ("deslop these comments"). **Consumers**: re-sync to pick up the
+  skill and the `review-phase` comment-hygiene step.
+
+- **`thermo-nuclear-code-quality-review` foundation skill — opt-in deep
+  structural-maintainability audit.** A deliberately harsh, on-demand review
+  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. Copy-verbatim foundation skill
+  (bucket A), read-only — it reports findings and hands each fix to the
+  `fixer` agent. Ships at
+  [skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md).
+  Wired as **opt-in / ask-first**: new `foundation_skills.thermo-nuclear-code-quality-review`
+  enum in `schemas/vinta-ai-workflows-config.v1.schema.json`, a new
+  question 6 in the bootstrap **Optional foundation skills** interview, and
+  the derive-skills bucket-A + foundation-shape lists. The `review-phase`
+  Layer 3 reviewer now applies a **condensed structural-simplification lens**
+  on every phase and escalates to this full audit only when a phase touches
+  core architecture, crosses ~1,000 lines, or surfaces a structural smell too
+  big to resolve inline — the deep pass never auto-runs on every diff.
+  **Consumers**: re-sync; the bootstrap now asks one more optional-skill
+  question, and `review-phase` gains the escalation hook.
+
+- **`prepare-worktree` — write-guard for *in-process* subagent runtimes
+  (claude-code's Task tool).** `sandbox-run.sh` confines a *process*, so it
+  only works when the harness spawns subagents as subprocesses (`codex exec`,
+  a `claude -p` child). Claude Code runs subagents in-process — same OS
+  process, same tool pipeline, no child command to wrap — so a new
+  harness-config guard covers it instead. Two bundled scripts:
+  `prepare-worktree/scripts/claude-worktree-write-guard.py` (a `PreToolUse`
+  hook that fires for the orchestrator **and** every in-process Task subagent,
+  blocking the file-editing tools — `Edit`/`Write`/`MultiEdit`/`NotebookEdit`
+  — from writing outside the worktree; filesystem-only, no network impact) and
+  `prepare-worktree/scripts/gen-claude-sandbox-settings.sh` (generates the
+  worktree's `.claude/settings.json` wiring that hook, and optionally
+  Claude Code's **native** OS sandbox via `sandbox.filesystem.denyWrite`/
+  `allowWrite` under `--os-sandbox` to also block Bash-issued writes — noting
+  the native sandbox forces network isolation, so registry + git-remote hosts
+  must be allow-listed via `--allow-domain`). Same deny-main/allow-rest model
+  as `sandbox-run.sh`. Step 5.5 of `prepare-worktree` gains an *In-process
+  runtimes (claude-code)* subsection; `implement-plan` §1c makes the
+  previously hand-wavy "in-process runtime" branch concrete. **Consumers**:
+  re-sync `prepare-worktree` + `implement-plan` — the two new scripts ship
+  with the foundation-skill dir.
+
+### Fixed
+
+- **`prepare-worktree/scripts/sandbox-run.sh` — two correctness bugs.**
+  (1) The macOS profile temp file used `mktemp -t vinta-sandbox`, which fails
+  with "too few X's in template" under GNU `mktemp` (present on any machine
+  with coreutils on `PATH`, including many macOS setups) — the whole sandbox
+  path errored out; now uses an explicit `…/vinta-sandbox.XXXXXX` template
+  portable across BSD + GNU `mktemp`. (2) Callers must now pass
+  `--allow <main>/.git`: git worktrees write every commit into the main repo's
+  `.git` (`.git/worktrees/<name>/index.lock`, shared objects/refs), so a
+  deny-main that omits it made the subagent's own `git commit` fail with
+  `Operation not permitted`. `implement-plan` §1c's documented invocation +
+  checklist + rules are updated to include `<main>/.git` in the allow-set.
+
+### Changed
+
+- **`implement-plan` / `amend-plan` decomposed into a modular "plan-execution
+  unit" of deterministic sub-skills.** The single ~440-line
+  `implement-plan-template.md` (and its `implement-plan-template-modular-substitutions.md`
+  sister file) are replaced by a thin **conductor** plus three co-shipped
+  single-purpose sub-skills, all rendered from
+  [skills/vinta-derive-skills/resources/plan-execution/](skills/vinta-derive-skills/resources/plan-execution/)
+  (`shell/` templates that `<!-- include -->` shared `partials/`):
+  - `implement-plan` — conductor: parse → classify → resolve one `WORKROOT`
+    → per-phase loop (dispatch) → track → report.
+  - `implement-phase` — compose prompt + pick model + spawn the implementer.
+  - `review-phase` — the three-layer review + fix loop, now shared by
+    `implement-plan`, `amend-plan`, **and** `systematic-debugging` (one review
+    implementation instead of three).
+  - `integrate-phase` — push + open PR via context file, rendered
+    commit-strategy-resolved.
+  The scattered runtime `if use_worktree` branches collapse into a single
+  `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER` seam the conductor resolves once
+  and passes to every sub-skill as data; only two local, data-driven checks
+  remain (the sandbox spawn-wrap in `implement-phase`, the stray-write
+  backstop in `review-phase`). Under `commit_strategy = ask`, the former
+  dual-rendered branch/commit/PR bodies become **two** rendered
+  `integrate-phase-stacked` / `integrate-phase-modular` skills the conductor
+  dispatches by name — no more both-paths-in-one-file. `amend-plan` reuses
+  `review-phase` verbatim + the shared inner/outer verification loop, and
+  picks up the same `WORKROOT` uniformity, while keeping its own
+  history-rewriting topology. **Consumers**: re-sync — the target now gets
+  five plan-execution SKILL.md files (`implement-plan`, `implement-phase`,
+  `review-phase`, `integrate-phase` [or the two `ask` variants], `amend-plan`)
+  instead of two. The three new sub-skills are a co-shipped unit: always
+  generated with `implement-plan`, not individually opt-in (no new
+  `foundation_skills` enum entry, no new interview question). Runtime
+  behavior is unchanged; the decomposition is for reviewability + determinism.
+
 <!-- pre-release: 0.2.0-alpha3 on 2026-06-23 -->
 
 ### Added

package/README.md

@@ -222,8 +222,11 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
 | [`plan-feature`](skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md) | always | Phased delivery plan from the matching spec → `ai-plans/YYYY-MM-DD-FEATURE_NAME_PLAN.md`. |
 | [`create-qa-use-cases`](skills/vinta-derive-skills/resources/foundation-skills/create-qa-use-cases/SKILL.md) | always | Bootstrap `QA_USE_CASES.md` from the active spec / plan. Called by `plan-feature` when missing. |
 | [`open-pr-from-context`](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/SKILL.md) | always | Publish a `.vinta-ai-workflows/prs-context/<feature>/<phase>.md` file as a real PR + inline comments via `gh` / `glab`. Bundles [`open-pr.sh`](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh). |
-| `implement-plan` | always (generated) | Phase-by-phase plan execution. Generated from a template with project commands + branch / PR / co-author policy. |
-| `amend-plan` | always (generated) | History-rewriting companion to `implement-plan` — revises in-flight plans, amends prior-phase commits, force-pushes, rebases stacked downstream branches. |
+| `implement-plan` | always (generated) | Phase-by-phase plan execution. Thin **conductor**: parses the plan, resolves one `WORKROOT`, and runs a fixed pipeline per phase (`implement-phase` → `review-phase` → `integrate-phase`), tracking + reporting. Generated from a template with project commands + branch / PR / co-author policy. |
+| `implement-phase` | always (unit) | Plan-execution sub-skill co-shipped with `implement-plan`: compose the implementer prompt, pick the model, spawn one implementer subagent for a single phase. |
+| `review-phase` | always (unit) | Plan-execution sub-skill: the three-layer review (mechanical / plan-compliance / independent reviewer) + fix loop. Shared by `implement-plan`, `amend-plan`, and `systematic-debugging`. |
+| `integrate-phase` | always (unit) | Plan-execution sub-skill: push the reviewed phase along the project's commit strategy + open the PR via context file. Under `commit_strategy = ask`, ships as `integrate-phase-stacked` + `integrate-phase-modular`. |
+| `amend-plan` | always (generated) | History-rewriting companion to `implement-plan` — revises in-flight plans, amends prior-phase commits, force-pushes, rebases stacked downstream branches. Reuses `review-phase` + `implement-phase`'s shared prompt loop. |
 | `systematic-debugging` | **opt-in** | Root-cause-first debugging with project-specific repro commands + MCP evidence-gathering (error tracking, traces, logs, metrics, alerts). Renders from a catalogue of observability MCP servers the user declares. |
 | `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). |

package/package.json

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

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

@@ -212,6 +212,26 @@
           "description": "Provision a fully-runnable git worktree for parallel feature work — symlinks dep dirs, copies env files, forks dev / test DBs, namespaces docker-compose project + network, drops a summary YAML for mechanical teardown. Copy-verbatim foundation skill (bucket A). When `enabled`, project-level defaults (worktree root, deps strategy, compose network strategy) live under `skills.prepare-worktree`. Consumed by `implement-plan` when its Step 0 question (c) opts in — the orchestrator runs `prepare-worktree` once at the start of a plan run and threads the worktree path through every subagent's prompt so phases all stack inside the same isolated checkout.",
           "type": "string",
           "enum": ["enabled", "disabled"]
+        },
+        "thermo-nuclear-code-quality-review": {
+          "description": "Opt-in deep structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — harsher than the standard per-phase review. Copy-verbatim foundation skill (bucket A). Read-only; hands each fix to the `fixer` agent. Invoked deliberately by the user, or escalated from the `review-phase` Layer 3 structural-simplification lens; never auto-run on every diff.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        },
+        "deslop-comments": {
+          "description": "Rewrite comments and doc blocks touched during the current task into Simple English — strip AI-slop vocabulary and negative framing, comment-only (no renames, no behavior change). Copy-verbatim foundation skill (bucket A), always shipped: the `review-phase` Layer 2 comment-hygiene check and fix loop depend on it. Set `disabled` only if a project deliberately opts out of the review flow's comment-hygiene step.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        },
+        "handoff": {
+          "description": "Write or consume a session-continuation handoff document under `.vinta-ai-workflows/handoffs/` so a fresh agent session (or a different agent / teammate) can resume in-flight work without re-deriving context. Copy-verbatim foundation skill (bucket A), always shipped — its body is fully project-agnostic. Set `disabled` only if a project deliberately opts out.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        },
+        "handoff-to-client": {
+          "description": "Generate a markdown API-change handoff document for client teams consuming an API-only repo — endpoints added/changed/deprecated/removed on the current branch vs the default branch, with request/response shapes, breaking-change flags, and per-platform migration notes. Template-rendered (bucket B) from `vinta-derive-skills/resources/handoff-to-client-template.md` and opt-in (bucket C) — only ships when the bootstrap interview confirms an API-only repo with separate client codebases. When `enabled`, project-level configuration lives under `skills.handoff-to-client` (client platforms, API style, spec path, output dir).",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
         }
       }
     },
@@ -250,6 +270,11 @@
           "properties": {
             "pause_between_phases": { "type": "boolean", "default": false },
             "generate_inline_comments": { "type": "boolean", "default": false },
+            "full_test_suite": {
+              "description": "Default answer to Step 0 question (d) — what each phase's outer gate runs for tests. False (default) = quick path: the outer gate runs only the scoped test suite covering the apps/files the phase touched (new tests still pass individually in the inner loop). True = run the full repo test suite in every phase's outer gate, guarding against regressions in untouched code at the cost of slower phases. The repo-wide type/build gate runs every phase either way. Per-run prompt still asks; this is the suggested default shown.",
+              "type": "boolean",
+              "default": false
+            },
             "use_worktree": {
               "description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision an isolated git worktree (via `prepare-worktree`) and run every phase's subagent inside it. False = run in the current checkout. True = create one shared worktree at the start of the plan run; all phase branches stack inside it. Per-run prompt still asks; this is the suggested default shown.",
               "type": "boolean",
@@ -303,6 +328,38 @@
             }
           }
         },
+        "handoff-to-client": {
+          "description": "Configuration for the `handoff-to-client` foundation skill. Required when `foundation_skills.handoff-to-client` is `enabled`; ignored otherwise. Rendered into the skill body at derive time.",
+          "type": "object",
+          "required": ["client_platforms"],
+          "additionalProperties": false,
+          "properties": {
+            "client_platforms": {
+              "description": "Free-form list of the client codebases/platforms that consume this repo's API, as the team names them (e.g. `iOS (Swift)`, `Android (Kotlin)`, `web SPA (React)`, `partner integrations`). Rendered into the skill's audience line and per-operation migration-notes instruction. Must be non-empty — an API-only repo with no named consumers has no handoff audience.",
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "uniqueItems": true,
+              "minItems": 1
+            },
+            "api_style": {
+              "description": "The API paradigm, free-form (e.g. `REST`, `GraphQL`, `gRPC`, `REST + webhooks`). Drives how the rendered skill names operations (method+path vs query/mutation vs service/rpc).",
+              "type": "string",
+              "minLength": 1,
+              "default": "REST"
+            },
+            "api_spec_path": {
+              "description": "Repo-relative path to a machine-readable API spec (OpenAPI file, GraphQL schema, proto dir) plus, ideally, the command that regenerates it — e.g. `docs/openapi.yaml (regenerate: make openapi)`. When set, the rendered skill diffs the regenerated spec between base and branch as its primary change-enumeration source. Omit when no spec exists; the skill then works from route/serializer code alone.",
+              "type": "string",
+              "minLength": 1
+            },
+            "output_dir": {
+              "description": "Directory where generated client-handoff documents land, repo-relative.",
+              "type": "string",
+              "minLength": 1,
+              "default": ".vinta-ai-workflows/client-handoffs"
+            }
+          }
+        },
         "prepare-worktree": {
           "description": "Configuration for the `prepare-worktree` foundation skill. Optional when `foundation_skills.prepare-worktree` is `enabled` — every field has a sensible default. Consumed by the skill at runtime to bias the per-worktree symlink-vs-copy-vs-fork decisions.",
           "type": "object",

package/skills/vinta-analyze-codebase/SKILL.md

@@ -155,7 +155,7 @@ This is a load-bearing input for the rest of the bootstrap flow — surface ever
 For each skill, also classify:
 
 - `vinta-managed` — directory name starts with `vinta-` (installed by `vinta-ai-workflows`; can be left alone or refreshed via that CLI).
-- `foundation-shape` — name matches the Vinta foundation set (`plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `add-e2e-test`, `add-env-var`).
+- `foundation-shape` — name matches the Vinta foundation set (`plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `implement-phase`, `review-phase`, `integrate-phase`, `amend-plan`, `add-e2e-test`, `add-env-var`). `implement-phase` / `review-phase` / `integrate-phase` are the plan-execution sub-skills co-shipped with `implement-plan`.
 - `project-custom` — anything else; written by the team.
 
 **Sub-agents** — list every agent file with its name + description:

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

@@ -83,7 +83,7 @@ These bleed across sub-skills, so capture once now:
 
 ### D. Optional foundation skills
 
-Five skills are part of the foundation set but aren't always needed. Ask explicitly:
+Seven skills are part of the foundation set but aren't always needed. Ask explicitly:
 
 1. **`add-e2e-test`** — does the project have e2e tests (Playwright / Cypress / similar) or plan to add them? `AskUserQuestion` options: `Yes — already has them`, `Yes — planning to add`, `No — skip`. If yes, [vinta-derive-skills](../vinta-derive-skills/SKILL.md)'s **Optional — ask the user** bucket follows up to ask whether the user has a template or wants to draft from scratch. **This answer also governs `create-qa-use-cases` and the e2e content inside `plan-feature`**: on `No — skip`, set `foundation_skills.create-qa-use-cases: disabled` too — derive-skills won't ship `create-qa-use-cases` and strips `plan-feature`'s `<!-- e2e:start/end -->` regions so no-e2e projects carry zero Playwright / `QA_USE_CASES.md` / `pr-screenshots/` references. On either `Yes`, set both `add-e2e-test` and `create-qa-use-cases` to `enabled`.
 2. **`add-env-var`** — does the project have a non-trivial env-var propagation flow (multiple files / build configs / CI updates per new var) or a single `.env` file is enough? `AskUserQuestion` options: `Yes — non-trivial flow`, `No — single .env is enough`. Skip if `No`.
@@ -112,7 +112,17 @@ Five skills are part of the foundation set but aren't always needed. Ask explici
    - Do **not** seed the cache file at bootstrap. The first debug run preflights all configured servers and writes the file then. An empty / missing `.vinta-ai-workflows/cache.yaml` is a valid initial state.
    - Mention to the user how to refresh: delete the file to re-preflight everything, or edit one entry's `status` to `dirty` to refresh that one server. Token rotated → cache will catch the auth error on the next call and flip the entry to `dirty` automatically.
 
-If the user answers "No" to any of the five, that skill won't ship. If the user answers "Yes" to `add-e2e-test` / `add-env-var` but doesn't have a template, derive-skills drafts one via interview. `systematic-debugging` is always template-rendered — no per-project drafting interview, just the MCP-server inventory above. `add-one-off-script` is copied verbatim from [vinta-derive-skills/resources/foundation-skills/add-one-off-script/](../vinta-derive-skills/resources/foundation-skills/add-one-off-script/) — its body is project-agnostic; the per-project variability lives in the `skills.add-one-off-script.*` config block above and in env vars consumed at runtime. `prepare-worktree` is also copied verbatim from [vinta-derive-skills/resources/foundation-skills/prepare-worktree/](../vinta-derive-skills/resources/foundation-skills/prepare-worktree/) — same pattern: project-agnostic body, per-project defaults under `skills.prepare-worktree.*`.
+6. **`thermo-nuclear-code-quality-review`** — does the team want an opt-in, deliberately harsh structural-maintainability audit available on demand (abstraction quality, giant files, spaghetti-condition growth), separate from the standard per-phase review? `AskUserQuestion` options: `Yes — enable`, `No — skip`. Recommend `Yes` for long-lived codebases where structural drift is a real cost, or teams that already run deep quality passes before merging large work. It ships as a user-invoked skill and is also the escalation target for the `review-phase` Layer 3 structural-simplification lens; it is never auto-run on every diff. No follow-up config — the body is project-agnostic.
+
+7. **`handoff-to-client`** — is this an API-only repo whose consumers live in separate client codebases (mobile apps, SPAs, partner integrations) that need API changes documented for them? Ask **only when the inventory suggests an API-only shape** — backend framework with no co-located frontend app (no SPA package, no templates-rendered UI beyond an admin). `AskUserQuestion` options: `Yes — enable`, `No — skip`. Skip the question entirely (set `disabled`) for full-stack repos and monorepos that contain their own clients — there the API diff is visible to the client code in the same PR. When enabled, agents can generate a markdown API-change handoff document (endpoints added / changed / deprecated / removed vs the default branch, request/response shapes, breaking-change flags, per-platform migration notes) for client implementers who cannot read this repo.
+
+   **Follow-up only when `handoff-to-client` = Yes — client-handoff config.** Four short questions land under `skills.handoff-to-client.*`:
+   - **Client platforms.** Open prose → free-form string array, e.g. `iOS (Swift)`, `Android (Kotlin)`, `web SPA (React)`, `partner integrations`. Required, non-empty — this is the document's audience and drives the per-operation migration-notes sections.
+   - **API style.** `AskUserQuestion`: `REST`, `GraphQL`, `gRPC`, other (free-form). Auto-pick from the inventory when unambiguous (e.g. DRF routers → REST, graphene/strawberry → GraphQL); ask only when mixed.
+   - **API spec path.** Open prose. Repo-relative path to a machine-readable spec (OpenAPI file, GraphQL schema, proto dir) plus the command that regenerates it, if one exists (e.g. `docs/openapi.yaml (regenerate: make openapi)`). Cross-check the inventory for spec files the user forgot. Empty is fine — the rendered skill then enumerates changes from route/serializer code alone.
+   - **Output dir.** Default `.vinta-ai-workflows/client-handoffs`. Override if the team wants handoffs committed (e.g. `docs/api-changes/`) — note that the default lives under the gitignored `.vinta-ai-workflows/`, so docs there must be shared manually.
+
+If the user answers "No" to any of the seven, that skill won't ship. If the user answers "Yes" to `add-e2e-test` / `add-env-var` but doesn't have a template, derive-skills drafts one via interview. `systematic-debugging` is always template-rendered — no per-project drafting interview, just the MCP-server inventory above. `add-one-off-script` is copied verbatim from [vinta-derive-skills/resources/foundation-skills/add-one-off-script/](../vinta-derive-skills/resources/foundation-skills/add-one-off-script/) — its body is project-agnostic; the per-project variability lives in the `skills.add-one-off-script.*` config block above and in env vars consumed at runtime. `prepare-worktree` is also copied verbatim from [vinta-derive-skills/resources/foundation-skills/prepare-worktree/](../vinta-derive-skills/resources/foundation-skills/prepare-worktree/) — same pattern: project-agnostic body, per-project defaults under `skills.prepare-worktree.*`. `thermo-nuclear-code-quality-review` is copied verbatim from [vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/](../vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/) with no follow-up config — its body is fully project-agnostic. `handoff-to-client` is always template-rendered from [vinta-derive-skills/resources/handoff-to-client-template.md](../vinta-derive-skills/resources/handoff-to-client-template.md) — no per-project drafting interview, just the client-handoff config follow-up above.
 
 ### E. Existing AI artifacts (per-artifact disposition)
 
@@ -132,7 +142,7 @@ For each artifact, read it (frontmatter + body), then ask the user via `AskUserQ
   - `Keep in current vendor path, don't touch` — leaves it where it is. AGENTS.md may reference it; downstream skill setup won't manage it.
   - `Drop` — delete (rare; usually the user wants to migrate).
 
-  Foundation-shape skills (name matches `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`) get an extra option: `Replace with Vinta foundation version` — overwrites with the canonical foundation content, preserving the user's name. Useful when the existing version is stale.
+  Foundation-shape skills (name matches `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `implement-phase`, `review-phase`, `integrate-phase`, `amend-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `deslop-comments`, `handoff`, `handoff-to-client`) get an extra option: `Replace with Vinta foundation version` — overwrites with the canonical foundation content, preserving the user's name. Useful when the existing version is stale. (`implement-phase` / `review-phase` / `integrate-phase` are the plan-execution sub-skills co-shipped with `implement-plan`; replace them as a unit.)
 
 - **Sub-agents** (each under any vendor `agents/` dir):
   - `Migrate to ai-tools/agents/<name>.yaml` — converts vendor-specific format → canonical YAML; `setup-ai-tools.mjs` re-emits per-vendor copies.
@@ -250,6 +260,10 @@ foundation_skills:
   systematic-debugging: <Optional foundation skills → systematic-debugging answer → enabled | disabled>
   add-one-off-script: <Optional foundation skills → add-one-off-script answer → enabled | disabled>
   prepare-worktree: <Optional foundation skills → prepare-worktree answer → enabled | disabled>
+  thermo-nuclear-code-quality-review: <Optional foundation skills → thermo-nuclear-code-quality-review answer → enabled | disabled>
+  deslop-comments: enabled  # always ships — review-phase Layer 2 comment-hygiene + fix loop depend on it
+  handoff: enabled  # always ships — project-agnostic session-continuation handoff docs
+  handoff-to-client: <Optional foundation skills → handoff-to-client answer → enabled | disabled; only asked for API-only repos>
 
 foundation_agents:
   implementer: enabled
@@ -263,6 +277,7 @@ run_options:
   implement-plan:
     pause_between_phases: false
     generate_inline_comments: false
+    full_test_suite: false  # default: each phase's outer gate runs scoped tests only; set true to run the full suite every phase
     use_worktree: <Optional foundation skills → prepare-worktree follow-up → default for Step 0 question (c); false unless team opted in>
   amend-plan:
     blast_radius_signal_threshold: 2
@@ -272,6 +287,13 @@ skills:
   systematic-debugging:
     observability_mcp_servers: <systematic-debugging follow-up — free-form array of MCP server identifiers, e.g. [sentry, datadog, our-internal-traces]>
 
+  # Only emit this block when foundation_skills.handoff-to-client = enabled.
+  handoff-to-client:
+    client_platforms: <handoff-to-client follow-up — free-form array, e.g. [iOS (Swift), Android (Kotlin), web SPA (React)]>
+    api_style: <handoff-to-client follow-up — REST | GraphQL | gRPC | free-form>
+    api_spec_path: <handoff-to-client follow-up — repo-relative spec path + regen command; omit when none>
+    output_dir: .vinta-ai-workflows/client-handoffs
+
   # Only emit this block when foundation_skills.prepare-worktree = enabled.
   prepare-worktree:
     worktree_root: <prepare-worktree follow-up — `.claude/worktrees` | `../<repo>-wt-`>
@@ -340,17 +362,24 @@ ai-tools/
 │   ├── plan-feature/SKILL.md            ← always (copied verbatim from derive-skills resources)
 │   ├── create-spec/SKILL.md             ← always (copied verbatim)
 │   ├── create-qa-use-cases/SKILL.md     ← always (copied verbatim)
-│   ├── implement-plan/SKILL.md          ← always (generated from template, project-specific)
-│   ├── amend-plan/SKILL.md              ← always (generated from template, project-specific)
+│   ├── deslop-comments/SKILL.md         ← always (copied verbatim; review-phase Layer 2 comment-hygiene + fix loop depend on it)
+│   ├── handoff/SKILL.md                 ← always (copied verbatim; session-continuation handoff docs under .vinta-ai-workflows/handoffs/)
+│   ├── implement-plan/SKILL.md          ← always (conductor; generated from template, project-specific)
+│   ├── implement-phase/SKILL.md         ← always (plan-execution unit; co-shipped with implement-plan)
+│   ├── review-phase/SKILL.md            ← always (plan-execution unit; shared by implement-plan / amend-plan / systematic-debugging)
+│   ├── integrate-phase/SKILL.md         ← always (plan-execution unit; push + PR. Under commit_strategy=ask: integrate-phase-stacked/ + integrate-phase-modular/ instead)
+│   ├── amend-plan/SKILL.md              ← always (conductor; generated from template, project-specific)
 │   ├── add-e2e-test/SKILL.md            ← optional — only if user opts in
 │   ├── add-env-var/SKILL.md             ← optional — only if user opts in
 │   ├── systematic-debugging/SKILL.md    ← optional — only if user opts in (template-rendered)
+│   ├── handoff-to-client/SKILL.md       ← optional — only for API-only repos, if user opts in (template-rendered; config under skills.handoff-to-client.*)
 │   ├── add-one-off-script/              ← optional — only if user opts in (verbatim copy + bundled BaseOneOffScript + LocalRuntime templates)
 │   │   ├── SKILL.md
 │   │   └── resources/
 │   │       ├── one_off_script_base.py
 │   │       └── one_off_script_base.ts
 │   ├── prepare-worktree/SKILL.md       ← optional — only if user opts in (verbatim copy; project-agnostic body, defaults under skills.prepare-worktree.*)
+│   ├── thermo-nuclear-code-quality-review/SKILL.md ← optional — only if user opts in (verbatim copy; deep structural-maintainability audit, escalation target for review-phase Layer 3)
 │   ├── run-one-off-script-django/       ← optional sister skill — only when stack matches + user supplies template (authors Jupyter notebook / mgmt command runner + JupyterRuntime / DjangoMgmtRuntime adapter in the per-script folder)
 │   ├── run-one-off-script-medplum/      ← optional sister skill — only when stack matches + user supplies template (authors Medplum bot + MedplumBotRuntime adapter in the per-script folder)
 │   └── <stack-specific skills>/SKILL.md ← only if user supplied templates
@@ -379,9 +408,9 @@ Plus the symlinks + per-vendor generated files, set up by the install step.
 
 Foundation skills break into three buckets — see [vinta-derive-skills](../vinta-derive-skills/SKILL.md) for the full mechanics:
 
-- **Always copy verbatim**: `plan-feature`, `create-spec`, `create-qa-use-cases`. Bundled with the bootstrap skill set; project-agnostic enough to ship as-is (with light path scrubs).
-- **Always generate**: `implement-plan`, `amend-plan`. Bodies have too much project-specific content (test commands, branch convention, PR + co-author policy, agent dispatch) — generated from parameterized templates using interview answers + inventory.
-- **Optional, ask first**: `add-e2e-test`, `add-env-var`, `systematic-debugging`, `add-one-off-script`, `prepare-worktree`. Skipped by default; orchestrator asks via `AskUserQuestion` whether the project has the relevant flow at all. `add-e2e-test` / `add-env-var`: if yes + user has a template → copy + adapt; if yes + no template → draft from scratch via interview; if no → don't ship. `systematic-debugging`: if yes → render the bundled template plus the per-tool MCP catalogue blocks for the observability tools selected in its follow-up; if no → don't ship. `add-one-off-script`: if yes → copy the bundled SKILL.md verbatim plus the language-specific `BaseOneOffScript` template (`one_off_script_base.py` / `one_off_script_base.ts`) chosen via its follow-up; if no → don't ship. `prepare-worktree`: if yes → copy the bundled SKILL.md verbatim, populate `skills.prepare-worktree.*` defaults from its follow-ups, and (when the user opted in via the worktree-default follow-up) flip `run_options.implement-plan.use_worktree` to `true` so `implement-plan`'s Step 0 question (c) defaults to yes; if no → don't ship.
+- **Always copy verbatim**: `plan-feature`, `create-spec`, `create-qa-use-cases`, `deslop-comments`, `handoff`. Bundled with the bootstrap skill set; project-agnostic enough to ship as-is (with light path scrubs). `deslop-comments` always ships because `review-phase`'s Layer 2 comment-hygiene check + fix loop dispatch it. `handoff` always ships because its session-continuation body is fully project-agnostic.
+- **Always generate**: the plan-execution unit — `implement-plan` (conductor) + its co-shipped sub-skills `implement-phase` / `review-phase` / `integrate-phase`, plus `amend-plan` (conductor). Bodies have too much project-specific content (test commands, branch convention, PR + co-author policy, agent dispatch) — generated from parameterized templates + shared partials using interview answers + inventory. The sub-skills are not independently opt-in; they always ship with the conductors.
+- **Optional, ask first**: `add-e2e-test`, `add-env-var`, `systematic-debugging`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `handoff-to-client`. Skipped by default; orchestrator asks via `AskUserQuestion` whether the project has the relevant flow at all. `add-e2e-test` / `add-env-var`: if yes + user has a template → copy + adapt; if yes + no template → draft from scratch via interview; if no → don't ship. `systematic-debugging`: if yes → render the bundled template plus the per-tool MCP catalogue blocks for the observability tools selected in its follow-up; if no → don't ship. `add-one-off-script`: if yes → copy the bundled SKILL.md verbatim plus the language-specific `BaseOneOffScript` template (`one_off_script_base.py` / `one_off_script_base.ts`) chosen via its follow-up; if no → don't ship. `prepare-worktree`: if yes → copy the bundled SKILL.md verbatim, populate `skills.prepare-worktree.*` defaults from its follow-ups, and (when the user opted in via the worktree-default follow-up) flip `run_options.implement-plan.use_worktree` to `true` so `implement-plan`'s Step 0 question (c) defaults to yes; if no → don't ship. `thermo-nuclear-code-quality-review`: if yes → copy the bundled SKILL.md verbatim (no follow-up config); if no → don't ship. `handoff-to-client`: asked only for API-only repos; if yes → render the bundled template using `skills.handoff-to-client.*` (client platforms, API style, spec path, output dir) from its follow-ups; if no → don't ship.
 
 Stack-specific skills + agents land in the target only when the user provides templates for them. If they don't have templates yet, the orchestrator records the detected stacks + skill categories as a TODO list the user can address later via [vinta-derive-skills](../vinta-derive-skills/SKILL.md) / [vinta-derive-subagents](../vinta-derive-subagents/SKILL.md) standalone runs.