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

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/claude-worktree-write-guard.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""claude-worktree-write-guard.py — Claude Code PreToolUse hook that blocks
+file-tool writes escaping a worktree into the protected main checkout.
+
+Why this exists: Claude Code runs sub-agents (the Task tool) IN-PROCESS — they
+share the orchestrator's OS process and tool pipeline, so there is no child
+launch command to wrap with an OS sandbox (that model only works on harnesses
+that spawn sub-agents as subprocesses, e.g. `codex exec`). A session-level
+PreToolUse hook, by contrast, fires for every tool call in the session —
+orchestrator AND Task sub-agents alike — because they run through the same
+pipeline. This hook is the in-process equivalent of prepare-worktree's
+`sandbox-run.sh` deny-main/allow-rest guard, scoped to the file-editing tools.
+
+Scope: the file-write tools only — Edit, Write, MultiEdit, NotebookEdit. Bash
+writes are NOT covered here (a hook can't reliably know every path a shell
+command touches); use Claude Code's native `sandbox` (see
+gen-claude-sandbox-settings.sh `--os-sandbox`) for OS-level Bash confinement,
+and rely on implement-plan's post-run `git -C <main> status` backstop otherwise.
+
+Model — deny-main, allow-rest (mirrors sandbox-run.sh): every path is allowed
+EXCEPT ones that resolve under a --deny root, and an --allow root punches a
+subtree back to writable even when nested under a --deny root. The worktree
+usually lives UNDER the main checkout (.claude/worktrees/<name>/), and git
+worktrees write commits into <main>/.git, so both the worktree and <main>/.git
+are passed as --allow. Symlinks are resolved (realpath) before the check, so a
+write through a symlink that lands back in the main checkout (e.g. a shared
+node_modules) is correctly caught.
+
+Usage (wired by gen-claude-sandbox-settings.sh into settings.json hooks):
+    claude-worktree-write-guard.py \
+        --deny  <main-checkout-root> \
+        --allow <worktree-path> \
+        --allow <main-checkout-root>/.git \
+        --allow <main-checkout-root>/.vinta-ai-workflows
+
+Reads the PreToolUse event JSON on stdin. Blocks by exiting 2 with a reason on
+stderr — Claude Code feeds that stderr back to the model as the denial reason,
+so the agent retries against the correct worktree path. Any non-write tool, or
+a write that stays inside an --allow subtree, exits 0 (allowed). The guard fails
+OPEN (exit 0) on malformed input or its own errors — it is a safety net layered
+under the OS sandbox and the post-run backstop, never the sole gate, and must
+never wedge a run by denying on a parsing hiccup.
+"""
+import json
+import os
+import sys
+
+# Tool-input keys that carry a write target, per tool.
+PATH_KEYS = ("file_path", "notebook_path")
+GUARDED_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+
+
+def canon(path):
+    """Absolute, symlink-resolved path. realpath resolves a shared node_modules
+    / .vinta-ai-workflows symlink back to its real location so the prefix check
+    reflects where the byte actually lands, not the symlink's apparent path."""
+    return os.path.realpath(os.path.abspath(path))
+
+
+def under(path, root):
+    """True if `path` is `root` or nested beneath it. Compares canonical paths
+    with a trailing separator so /main-evil is not treated as under /main."""
+    path, root = canon(path), canon(root)
+    return path == root or path.startswith(root.rstrip(os.sep) + os.sep)
+
+
+def parse_args(argv):
+    deny, allow = [], []
+    i = 0
+    while i < len(argv):
+        if argv[i] == "--deny" and i + 1 < len(argv):
+            deny.append(argv[i + 1]); i += 2
+        elif argv[i] == "--allow" and i + 1 < len(argv):
+            allow.append(argv[i + 1]); i += 2
+        else:
+            i += 1
+    return deny, allow
+
+
+def main():
+    deny, allow = parse_args(sys.argv[1:])
+    if not deny:
+        # Nothing to protect — nothing to do.
+        return 0
+
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        return 0  # fail open — never wedge a run on a parse error
+
+    if event.get("tool_name") not in GUARDED_TOOLS:
+        return 0
+
+    tool_input = event.get("tool_input") or {}
+    target = next((tool_input[k] for k in PATH_KEYS if tool_input.get(k)), None)
+    if not target:
+        return 0  # no write target we recognize
+
+    # allow wins over deny (the worktree + .git + .vinta-ai-workflows are nested
+    # under the denied main root and must stay writable).
+    if any(under(target, a) for a in allow):
+        return 0
+    if any(under(target, d) for d in deny):
+        resolved = canon(target)
+        wt = allow[0] if allow else "the worktree"
+        sys.stderr.write(
+            f"Blocked write to the main checkout: {resolved}\n"
+            f"This file is outside the worktree. Write to the worktree instead "
+            f"(under {wt}). If you meant to edit a shared file, it is protected "
+            f"for the duration of this plan run.\n"
+        )
+        return 2  # exit 2 → Claude Code blocks the call, stderr is the reason
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-claude-sandbox-settings.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# gen-claude-sandbox-settings.sh — generate a Claude Code settings.json that
+# confines a worktree session (orchestrator + its in-process Task sub-agents)
+# to writing inside the worktree, blocking stray writes to the main checkout.
+#
+# Claude Code runs sub-agents in-process (the Task tool shares the orchestrator's
+# OS process), so the subprocess-wrapping model of sandbox-run.sh does not apply
+# — the guard has to live in the harness's own settings. This script wires two
+# complementary layers, matching prepare-worktree's deny-main/allow-rest model:
+#
+#   Layer A (always) — a PreToolUse hook (claude-worktree-write-guard.py) that
+#     blocks the file-editing tools (Edit/Write/MultiEdit/NotebookEdit) from
+#     writing outside the worktree. Filesystem-only; no network impact. Fires
+#     for the orchestrator AND every Task sub-agent (shared session pipeline).
+#
+#   Layer B (opt-in, --os-sandbox) — Claude Code's NATIVE OS sandbox
+#     (`sandbox.filesystem.denyWrite`/`allowWrite`, Seatbelt on macOS / bwrap on
+#     Linux) so Bash-issued writes are blocked at the kernel too. NOTE: enabling
+#     the native sandbox also turns on NETWORK isolation — dep installs and
+#     `git push` break unless you allow-list registries/remotes. Pass the hosts
+#     the plan needs via --allow-domain (repeatable). Without --os-sandbox, Bash
+#     writes fall back to implement-plan's post-run `git -C <main> status` check.
+#
+# Both layers keep <worktree>, <main>/.git (git worktrees commit into the main
+# repo's .git), and the shared .vinta-ai-workflows dir writable.
+#
+# Usage:
+#   gen-claude-sandbox-settings.sh \
+#     --worktree <worktree-path> \
+#     --main     <main-checkout-root> \
+#     [--allow <extra-writable-path>]...   # e.g. .vinta-ai-workflows if elsewhere
+#     [--out <settings-file>]              # default: <worktree>/.claude/settings.json
+#     [--os-sandbox]                       # also emit the native sandbox block
+#     [--allow-domain <host>]...           # network hosts to allow under --os-sandbox
+#
+# The generated file is meant to govern a Claude Code session ROOTED IN THE
+# WORKTREE (`cd <worktree> && claude`), the recommended claude-code topology for
+# an isolated plan run — the settings are read at session start. See Step 5.5 of
+# ../SKILL.md for the two deployment models and their timing caveats.
+#
+# Exit: 0 on success; 2 on argument/setup errors.
+
+set -u
+
+die() { echo "gen-claude-sandbox-settings: $*" >&2; exit 2; }
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+GUARD="$SCRIPT_DIR/claude-worktree-write-guard.py"
+
+WORKTREE=""; MAIN=""; OUT=""; OS_SANDBOX=0
+EXTRA_ALLOW=(); DOMAINS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --worktree)     shift; [ $# -gt 0 ] || die "--worktree needs a path"; WORKTREE="$1"; shift ;;
+    --main)         shift; [ $# -gt 0 ] || die "--main needs a path"; MAIN="$1"; shift ;;
+    --out)          shift; [ $# -gt 0 ] || die "--out needs a path"; OUT="$1"; shift ;;
+    --allow)        shift; [ $# -gt 0 ] || die "--allow needs a path"; EXTRA_ALLOW+=("$1"); shift ;;
+    --allow-domain) shift; [ $# -gt 0 ] || die "--allow-domain needs a host"; DOMAINS+=("$1"); shift ;;
+    --os-sandbox)   OS_SANDBOX=1; shift ;;
+    *)              die "unknown arg: $1" ;;
+  esac
+done
+
+[ -n "$WORKTREE" ] || die "--worktree <path> required"
+[ -n "$MAIN" ]     || die "--main <path> required"
+[ -f "$GUARD" ]    || die "guard hook not found next to this script: $GUARD"
+
+# Canonicalize (leaf need not exist).
+canon() {
+  local p="$1" d b
+  if [ -d "$p" ]; then (cd "$p" && pwd -P); return; fi
+  d=$(dirname "$p"); b=$(basename "$p")
+  if [ -d "$d" ]; then echo "$(cd "$d" && pwd -P)/$b"; else echo "$p"; fi
+}
+
+WORKTREE=$(canon "$WORKTREE")
+MAIN=$(canon "$MAIN")
+[ -d "$WORKTREE" ] || die "worktree path is not a directory: $WORKTREE"
+[ -d "$MAIN" ]     || die "main checkout path is not a directory: $MAIN"
+[ -z "$OUT" ] && OUT="$WORKTREE/.claude/settings.json"
+
+# Writable exceptions punched back through the main-checkout deny: the worktree,
+# the shared git database (worktree commits land in <main>/.git), the shared
+# .vinta-ai-workflows dir, plus any caller extras.
+ALLOW=("$WORKTREE" "$MAIN/.git" "$MAIN/.vinta-ai-workflows")
+for p in "${EXTRA_ALLOW[@]:-}"; do [ -n "$p" ] && ALLOW+=("$(canon "$p")"); done
+
+if [ "$OS_SANDBOX" -eq 1 ] && [ "${#DOMAINS[@]}" -eq 0 ]; then
+  echo "gen-claude-sandbox-settings: WARNING --os-sandbox with no --allow-domain — network" >&2
+  echo "  isolation is ON, so dep installs / git push over the network will fail. Pass the" >&2
+  echo "  registry + git remote hosts via --allow-domain, or drop --os-sandbox for hook-only." >&2
+fi
+
+mkdir -p "$(dirname "$OUT")" || die "cannot create settings dir for $OUT"
+
+# Emit JSON via python3 (safe escaping of paths); merge into an existing file if
+# one is present so we don't clobber unrelated settings the worktree may carry.
+GUARD="$GUARD" OUT="$OUT" MAIN="$MAIN" WORKTREE="$WORKTREE" OS_SANDBOX="$OS_SANDBOX" \
+python3 - "${ALLOW[@]}" -- "${DOMAINS[@]:-}" <<'PY' || die "failed to write settings"
+import json, os, sys
+
+guard, out, main, worktree = (os.environ[k] for k in ("GUARD", "OUT", "MAIN", "WORKTREE"))
+os_sandbox = os.environ["OS_SANDBOX"] == "1"
+
+sep = sys.argv.index("--")
+allow = [a for a in sys.argv[1:sep] if a]
+domains = [d for d in sys.argv[sep + 1:] if d]
+
+# Layer A — PreToolUse write-guard hook (always).
+guard_cmd = " ".join(
+    [json.dumps(guard) if " " in guard else guard, "--deny", main]
+    + sum((["--allow", a] for a in allow), [])
+)
+hook_entry = {
+    "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+    "hooks": [{"type": "command", "command": guard_cmd}],
+}
+
+# Merge into an existing settings file if present (preserve unrelated keys).
+settings = {}
+if os.path.exists(out):
+    try:
+        with open(out) as f:
+            settings = json.load(f) or {}
+    except Exception:
+        settings = {}
+
+hooks = settings.setdefault("hooks", {})
+pre = hooks.setdefault("PreToolUse", [])
+# Drop any prior guard entry (idempotent re-runs) then append the fresh one.
+pre = [e for e in pre if "claude-worktree-write-guard" not in json.dumps(e)]
+pre.append(hook_entry)
+hooks["PreToolUse"] = pre
+
+# Layer B — native OS sandbox (opt-in).
+if os_sandbox:
+    settings["sandbox"] = {
+        "enabled": True,
+        # Degrade to unsandboxed on platforms without Seatbelt/bwrap rather than
+        # hard-failing the run; the hook (Layer A) still guards file writes.
+        "failIfUnavailable": False,
+        "filesystem": {
+            "denyWrite": [main],
+            "allowWrite": allow,
+        },
+        "network": {
+            # Sandbox forces network isolation; without an allow-list, installs
+            # and pushes break. Callers pass registry + remote hosts.
+            "allowedDomains": domains,
+        },
+    }
+
+with open(out, "w") as f:
+    json.dump(settings, f, indent=2)
+    f.write("\n")
+
+print(f"wrote {out}")
+print(f"  layer A (hook): guard on Edit|Write|MultiEdit|NotebookEdit, deny {main}")
+print(f"  allow-write: {', '.join(allow)}")
+if os_sandbox:
+    dom = ", ".join(domains) if domains else "(none — network will be blocked)"
+    print(f"  layer B (os sandbox): enabled, network allowedDomains: {dom}")
+else:
+    print("  layer B (os sandbox): OFF (hook-only; Bash writes rely on the post-run backstop)")
+PY
+
+echo "gen-claude-sandbox-settings: done."

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/sandbox-run.sh

@@ -75,7 +75,9 @@ fi
 
 # ---- macOS: sandbox-exec -----------------------------------------------------
 if command -v sandbox-exec >/dev/null 2>&1; then
-  profile=$(mktemp -t vinta-sandbox) || die "mktemp failed"
+  # Explicit XXXXXX template (portable across BSD mktemp on stock macOS and GNU
+  # mktemp from coreutils — `mktemp -t prefix` is not portable between them).
+  profile=$(mktemp "${TMPDIR:-/tmp}/vinta-sandbox.XXXXXX") || die "mktemp failed"
   trap 'rm -f "$profile"' EXIT
   {
     echo '(version 1)'

package/skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: thermo-nuclear-code-quality-review
+description: Run an extremely strict maintainability review of a diff — abstraction quality, giant files, and spaghetti-condition growth. This is a deep, on-demand structural audit, harsher than the normal per-phase review: it hunts for "code judo" reframes that make whole branches, helpers, modes, or layers disappear rather than polishing what's there. Use when the user asks for a "thermo-nuclear code quality review", "thermonuclear review", "deep code quality audit", or "harsh maintainability review", or when the standard review flow escalates a structural concern. Opt-in only — do not auto-run it on every diff; it is meant to be invoked deliberately. Read-only: it reports findings and hands each fix to a fixer, it does not edit code itself.
+disable-model-invocation: true
+---
+
+# Thermo-nuclear code quality review
+
+An intentionally severe maintainability audit. The normal review checks that a change is correct, tested, and in-convention. This review asks a harder question: **is the change structured as well as it could be, or did it grow complexity that a better framing would have avoided?**
+
+The mindset is **ambitious structural simplification**, not incremental cleanup. Look for reframes that make whole branches, helpers, modes, conditionals, or layers disappear entirely — a "code judo" move that preserves behavior while collapsing the structure. Do not approve a change merely because it works.
+
+This is a heavy, deliberate pass. It is **not** part of the automatic per-phase review — run it when asked, or when the standard `review-phase` review escalates a structural concern it can't fully resolve. (See "Relationship to the standard review flow" below.)
+
+## When to use / when to skip
+
+Use it when:
+- The user explicitly asks for a thermo-nuclear / deep / harsh maintainability review.
+- A phase touched core architecture, added a large file, or introduced branching that "smells" — and the standard reviewer flagged it for a deeper look.
+- Before merging something large or long-lived where structure matters more than speed.
+
+Skip it when:
+- The diff is a small, self-contained fix, a docs/comment change, or generated output. Running a thermo-nuclear pass on a two-line change wastes effort and produces noise.
+- Correctness is the open question, not structure — use the standard review or the `systematic-debugging` skill for that.
+
+## Scope
+
+Default scope is the current change set: find it with `git diff --stat` / `git status --short` against the base the work started from (or the phase diff, when a review conductor passes one). If the user names a PR, a directory, or specific files, use that scope instead.
+
+Read the **full diff** of every file in scope, plus enough of each touched file's surroundings to judge structure — a diff line looks innocent until you see the 1,200-line file it lands in.
+
+## The standards (all non-negotiable)
+
+0. **Ambitious structural simplification.** Look for opportunities to reframe the change so that whole branches, helpers, modes, conditionals, or layers disappear entirely. This is the primary lens; the rest are specific ways it shows up.
+1. **File-size boundary.** Do not let a change push a file from under ~1,000 lines to over ~1,000 lines without a very strong reason, especially when the added code is extractable.
+2. **Spaghetti growth.** Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows.
+3. **Design-first bias.** If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version.
+4. **Direct code preference.** Treat brittle, ad-hoc, or "magic" behavior as a code-quality problem, not a clever solution.
+5. **Type and boundary cleanliness.** Question unnecessary optionality, `unknown`, `any`, or cast-heavy code when a clearer type boundary could exist. (Apply the equivalent in the project's language — loose typing, stringly-typed data, escape hatches.)
+6. **Canonical layer logic.** Call out feature logic leaking into shared paths, or implementation details leaking through an API boundary. Reuse existing canonical utilities instead of bespoke duplicates.
+7. **Sequential orchestration.** If independent work is serialized for no good reason, ask whether the flow should run in parallel, and whether partial-update logic leaves state less atomic than it should be.
+
+## Primary review questions
+
+Apply these systematically to the diff:
+
+1. Is there a "code judo" move that would make this dramatically simpler?
+2. Can this change be reframed so fewer concepts, branches, or helper layers are needed?
+3. Does this improve or worsen the local architecture?
+4. Did the diff add branching complexity where a better abstraction should exist?
+5. Did a previously cohesive module become more coupled, more stateful, or harder to scan?
+6. Is this logic living in the right file and layer?
+7. Did this change enlarge a file or component past a healthy size boundary?
+8. Are there repeated conditionals that signal a missing model or missing helper?
+9. Is the implementation direct and legible, or does it rely on special cases and incidental control flow?
+10. Is this abstraction actually earning its keep, or is it just a wrapper?
+11. Did the diff introduce casts, optionality, or ad-hoc object shapes that obscure the real invariant?
+12. Is this logic in the canonical layer, or did the diff leak details across a boundary?
+13. Is this orchestration more sequential or less atomic than it needs to be?
+
+## Flag aggressively
+
+- A complicated implementation where a cleaner reframe could eliminate whole categories of complexity.
+- Refactors that move code without reducing conceptual overhead for readers.
+- Files crossing ~1,000 lines because of this change, especially when the added code is extractable.
+- New conditionals bolted onto unrelated code paths.
+- One-off booleans, nullable modes, or flags complicating existing control flow.
+- Feature-specific logic leaking into general-purpose modules.
+- Generic "magic" handling that obscures a simple structure.
+- Thin wrappers or identity abstractions adding indirection without clarity.
+- Unnecessary casts, `any` / `unknown`, or optional params muddying contracts.
+- Copy-pasted logic instead of an extracted helper.
+- Narrow edge-case handling wedged into the middle of already-busy functions.
+- Refactors that technically pass tests but reduce modularity or readability.
+- "Temporary" branching that is likely to become permanent debt.
+- Bespoke helpers duplicating existing canonical utilities.
+- Logic placed in the wrong layer/package when more central ownership exists.
+- Sequential async flow where independent work could run in parallel.
+- Partial-update logic that leaves state less atomic than necessary.
+
+## Approval bar
+
+Treat these as blockers unless there is a strong, stated justification:
+
+- Plausible code-judo moves exist but were left unexplored.
+- A file crosses ~1,000 lines because of this change without a compelling reason.
+- Ad-hoc branching tangles an existing flow.
+- Feature checks scatter across shared code to solve a local problem.
+- Unnecessary abstractions, wrappers, or cast-heavy contracts increase indirection.
+- Existing helpers are duplicated, or logic lands in the wrong canonical layer.
+
+Do not approve merely because behavior seems correct.
+
+## Output format
+
+Report findings prioritized in this order:
+
+1. Structural code-quality regressions.
+2. Missed opportunities for dramatic simplification / code-judo restructuring.
+3. Spaghetti / branching complexity increases.
+4. File-size and layering violations.
+5. Type / boundary and duplication issues.
+
+For each finding: name the file and lines, state the concrete regression, and — this is the point of the review — describe the reframe that removes it, not just "this is complex." Do not flood the review with low-value nits when larger structural issues exist; a page of naming quibbles buries the one restructuring that matters.
+
+Triage each finding like the standard review does:
+- **BLOCKER** — must fix before merge (matches the approval-bar list above).
+- **SHOULD-FIX** — fix now if cheap, otherwise a tracked follow-up.
+- **NIT** — mention only if trivially cheap.
+
+## Relationship to the standard review flow
+
+This skill is read-only, like the project's normal review. It does not edit code. When a finding warrants a change, hand it to the project's `fixer` agent ([ai-tools/agents/fixer.md](ai-tools/agents/fixer.md)) with the finding quoted verbatim, exactly as the standard fix loop does.
+
+The per-phase review (the `reviewer` agent, [ai-tools/agents/reviewer.md](ai-tools/agents/reviewer.md)) applies a condensed version of standard 0 on every phase — "is there an obvious code-judo reframe?" When that lens surfaces something structural that deserves a full audit, the reviewer escalates by invoking this skill against the phase diff. Reserve the full pass for when it earns its cost; the condensed lens is enough for routine phases.
+
+## Pitfalls
+
+- **Nit flooding.** The failure mode of a harsh review is a wall of trivial comments that hides the one finding that matters. Lead with structure; drop the nits.
+- **"Cleaner" that is not.** A reframe that trades one form of complexity for another, or that hurts readability to save lines, is not a win. Only push a change when it genuinely reduces conceptual overhead.
+- **Rewriting for taste.** Behavior must be preserved. This is a review, not a redesign mandate — propose reframes, quote them as findings, and let the fixer and conductor decide.
+- **Running it everywhere.** It is opt-in for a reason. Auto-running it on every small diff produces noise and slows the flow.
+
+## Verification
+
+- Every finding names a concrete file/line and a specific reframe, not a vague "too complex."
+- Findings are ordered by the priority list above, BLOCKER first.
+- The pass edited no code directly — any change went through a fixer.
+- If nothing structural was found on a large, multi-file diff, you looked again before saying so.

package/skills/vinta-derive-skills/resources/handoff-to-client-template.md

@@ -0,0 +1,107 @@
+---
+name: handoff-to-client
+description: Generate a markdown API-change handoff document for the client teams consuming {{PROJECT_NAME}}'s {{API_STYLE}} API ({{CLIENT_PLATFORMS_LIST}}). Documents every endpoint/operation added, changed, deprecated, or removed on the current branch relative to `{{DEFAULT_BRANCH}}` — request/response shapes, auth, errors, breaking-change flags, and per-platform migration notes — so client implementers can adopt the changes without reading this repo's source. Use when the user says "write the client handoff", "document the API changes for the clients", "hand off to the frontend/mobile team", or before merging an API-changing branch.
+---
+
+# Handoff to client
+
+{{PROJECT_NAME}} ({{STACK_SUMMARY}}) is an API-only repo — its consumers live in separate codebases: {{CLIENT_PLATFORMS_LIST}}. Client implementers cannot read this repo's diff; this skill turns an API-changing branch into a self-contained markdown document they implement against.
+
+The document is a contract description, not a changelog: every change carries enough shape detail (fields, types, nullability, examples) that a client engineer can code against it without opening this repo.
+
+## Step 0 — Resolve the scope
+
+Default scope is the **current branch vs `{{DEFAULT_BRANCH}}`**:
+
+```
+git fetch origin {{DEFAULT_BRANCH}}
+git diff origin/{{DEFAULT_BRANCH}}...HEAD --stat
+```
+
+Overrides, when the user asks: an explicit commit range (`<from>..<to>`), a merged PR, or a whole feature plan (enumerate the plan's phase branches/commits from its tracking file and union their diffs). State the resolved scope in the output doc's header.
+
+If the resolved diff touches no API surface at all, say so and stop — do not fabricate a document.
+
+## Step 1 — Enumerate the API surface changes
+
+Work from the diff, never from memory:
+
+1. List changed files in the scope and keep the API-relevant ones: route/URL declarations, controllers/views/resolvers, serializers/schemas/DTOs, auth/permission code, error handlers, API versioning config.
+2. For each, read the changed hunks and map them to concrete operations (method + path for REST; query/mutation/subscription for GraphQL; service/rpc for gRPC).
+3. Classify every operation touched: **added**, **changed**, **deprecated**, or **removed**.
+4. For each **changed** operation, diff the request and response shapes field by field: added fields, removed fields, type changes, nullability changes, renamed fields, default changes, new/changed validation rules, pagination or filtering changes.
+5. Flag **breaking** vs **non-breaking**. Breaking = anything an existing client call could fail or misbehave on: removed/renamed field or endpoint, narrowed type, newly-required request field, changed status code or error shape, auth/permission tightening. Additive-and-optional is non-breaking.
+
+{{API_SPEC_BLOCK}}
+
+Also sweep for non-endpoint contract changes clients still feel: auth flows (token lifetimes, scopes, header names), rate limits, webhooks/event payloads, websocket messages, file-upload conventions, and deprecation timelines.
+
+## Step 2 — Write the document
+
+Path: `{{CLIENT_HANDOFF_DIR}}/{YYYY-MM-DD}-{branch-or-feature-slug}.md`. Create the directory if missing.
+
+```markdown
+# API changes: {feature / branch title}
+
+- **Date:** {YYYY-MM-DD}
+- **Scope:** {branch} vs {{DEFAULT_BRANCH}} ({short-sha range})
+- **Audience:** {{CLIENT_PLATFORMS_LIST}}
+- **Breaking changes:** {count, or "none"}
+
+## Summary
+2–5 sentences: what shipped and why clients care. Lead with breaking changes.
+
+## Breaking changes  ← omit section if none; never bury these
+Per change: what breaks, which operations, what the client must do, and the
+deadline/version after which the old behavior disappears.
+
+## {Operation-by-operation sections, grouped added / changed / deprecated / removed}
+
+### {METHOD /path}  or  {operationName}
+- **Status:** added | changed | deprecated | removed — {breaking? yes/no}
+- **Auth:** {scheme, required scopes/permissions}
+- **Request:** field table or annotated example — name, type, required?,
+  constraints, default. For *changed*: call out exactly what differs from before.
+- **Response:** per status code — annotated example JSON with field meanings,
+  nullability, enum values spelled out.
+- **Errors:** status codes + error body shape + when each fires.
+- **Example:** one complete request/response pair with realistic (fake) data.
+- **Client migration notes:** what each platform ({{CLIENT_PLATFORMS_LIST}})
+  concretely changes — omit platforms unaffected by this operation.
+
+## Other contract changes
+Auth flow / rate limits / webhooks / versioning changes from the Step 1 sweep.
+
+## Rollout
+Is the change live, behind a flag, or awaiting deploy? Environment availability
+(staging first?), and the sequencing clients must respect.
+```
+
+Rules for the body:
+
+- **Examples over prose.** Every operation gets at least one realistic request/response example. Use plausible fake data — never real user data, tokens, or secrets copied from fixtures or logs.
+- **Shape from code, not intent.** Derive field names, types, and nullability from the serializer/schema/resolver code in the diff (or the regenerated spec), not from the plan document or commit messages.
+- **Self-contained.** No links into this repo's source as the primary explanation; the audience may not have repo access. Citing paths as *provenance* is fine.
+- **Neutral tone for migration notes.** Describe what the client must handle; don't prescribe their internal architecture.
+
+## Step 3 — Verify before handing off
+
+1. Re-read each documented operation against the actual code one final time — signatures drift during writing.
+2. Grep the diff for API-relevant files you did NOT document and confirm each is genuinely client-invisible (internal refactor, tests, comments).
+3. Confirm every **breaking** flag: would an unmodified existing client call still succeed? If unsure, mark it breaking — false alarms are cheaper than silent breakage.
+4. Exercise at least one added/changed endpoint against a locally running instance when feasible, and paste the real (redacted) response into the doc's example.
+5. Report the doc path to the user, flag the breaking-change count, and remind them `{{CLIENT_HANDOFF_DIR}}` may be gitignored — share or commit the file deliberately so it actually reaches the client teams.
+
+## Pitfalls
+
+- **Documenting the plan instead of the code.** Plans drift during implementation; the diff is the truth. Always derive shapes from what actually merged into the branch.
+- **Missing error-shape changes.** Clients parse error bodies too. A changed error envelope breaks clients just as hard as a changed success payload.
+- **"Non-breaking" by wishful thinking.** A field that changed from `string` to `string | null` breaks any client that never null-checks. Judge breakage from the strictest plausible client, not the friendliest.
+- **Serializer-level changes hidden behind unchanged routes.** A diff can change a response shape without touching any route file — sweep serializers/schemas/DTOs even when the route list looks untouched.
+- **Stale doc after review fixes.** If review feedback changes the API after the handoff was written, regenerate the doc — a superseded handoff to clients is worse than none.
+
+## Verification
+
+- The doc exists under `{{CLIENT_HANDOFF_DIR}}/`, is scoped-and-dated, and every API-relevant file in the diff is either documented or consciously excluded.
+- Every breaking change appears in the **Breaking changes** section, not only in its per-operation entry.
+- A client engineer with zero access to this repo could implement every documented change from the doc alone.

package/skills/vinta-derive-skills/resources/plan-execution/README.md

@@ -0,0 +1,42 @@
+# `plan-execution/` — shell templates + shared partials
+
+Source-of-truth fragments for the **plan-execution skill family** that
+`vinta-derive-skills` renders into a target project's `ai-tools/skills/`:
+
+- `implement-plan` (conductor) — parse → classify → resolve `WORKROOT` → per-phase loop → track → report.
+- `implement-phase` — compose prompt + pick model + spawn implementer (one phase).
+- `review-phase` — three-layer review + fix loop (shared by all three conductors).
+- `integrate-phase` — push + open PR via context file (commit-strategy-resolved).
+- `amend-plan` (conductor) — history-rewriting topology; reuses `review-phase` + the implementer-prompt partial.
+
+## Layout
+
+```
+plan-execution/
+├─ shell/       one *-template.md per rendered SKILL.md (thin; mostly includes)
+└─ partials/    shared bodies authored once, included by multiple shells
+```
+
+## Assembly mechanism (executed by the `vinta-derive-skills` agent)
+
+Each shell carries include directives. The derive-skills agent, per skill:
+
+1. **Expand includes.**
+   - `<!-- include: partials/<file>.md -->` — splice the whole partial body in place of the marker.
+   - `<!-- include: partials/<file>.md#BLOCK -->` — splice only the block between `<!-- block-begin: BLOCK -->` and `<!-- block-end: BLOCK -->` inside that partial (markers themselves excluded).
+2. **Substitute `{{PLACEHOLDER}}`** using the inventory + Step 0 interview answers (same substitution table as every other Bucket B template — see [../../SKILL.md](../../SKILL.md)).
+3. **Write** the assembled, fully-substituted body to `ai-tools/skills/<name>/SKILL.md`.
+
+Partials and shells are **not** `SKILL.md` files, so they legitimately keep `{{...}}` and `<!-- include -->` markers; `validate-skill-md` never walks them. The **shipped** SKILL.md must have every include expanded and every placeholder substituted — validate that before saving.
+
+## The `WORKROOT` seam (why worktree branching is gone)
+
+The conductor resolves three values **once** (see `partials/worktree-seam.md#WORKROOT_RESOLUTION`) and passes them to every sub-skill as data:
+
+| Value | `use_worktree = false` | `use_worktree = true` |
+|---|---|---|
+| `WORKROOT` | `<main_checkout>` | `<worktree_path>` |
+| `BASE_BRANCH` | `{{DEFAULT_BRANCH}}` | `<worktree_branch>` |
+| `SANDBOX_TIER` | `none` | `enforced` \| `none` (probed by prepare-worktree) |
+
+Every `git` / lint / test / build call in every sub-skill uses `git -C <WORKROOT>` **uniformly** — no `if use_worktree` inside them. Only two genuine conditionals remain, each local and data-driven: the `SANDBOX_TIER`-gated spawn wrap in `implement-phase`, and the `WORKROOT != main_checkout`-gated stray-write check in `review-phase`.