ship-playbook v1.10.2 — document warmWorktree (worktree seeding + sccache) in SKILL.md + README

The v1.10.0/.1 feature shipped without user-facing docs. Adds: - SKILL.md: warmWorktree in the Workflow args list + comment, and a Build-phase paragraph on fast worktree provisioning (CoW-seed node_modules/vendor/Pods, Rust sccache, frozen-install fallback, warmWorktree:false = plain install). - README.md: the ship-playbook section now describes fast worktree provisioning.
2026-09-19 03:35:17 +08:00 · 2026-07-05 06:30:12 +04:00
parent b793d2c49c
commit f5f262d7f6
2 changed files with 10 additions and 4 deletions
@@ -311,7 +311,7 @@ npx skills add https://github.com/ulpi-io/skills --skill ship-playbook

 **One feature prompt → planned, built, reviewed, and audited — end to end.**

-The delivery capstone: it chains the repo's own skills into a single runnable Workflow that runs **one pass** and returns the verified findings as feedback — it does **not** loop on its own (an autonomous fix-loop is what caused multi-hour grinds; the user decides whether to run a fix round). Up front it shows which composed skills and specialist agents are installed (with install commands), then asks **seven gate questions** — who writes the plan, who reviews it, who writes the code, who reviews each task, impl review, go-live audit, and an optional project-map refresh. Every role **independently** picks its executor (`native` / `codex` / `kiro`; reviews can `skip`; the writer and a reviewer may be different harnesses), so you control quality vs token cost. Then it runs: **plan** (`plan-to-task-list-with-dag`, assigning a specialist engineer + `-reviewer` + stack skill per task) → **plan review** (`plan-founder-review`, bounded loop) → **build** (per task across the DAG layers: specialist engineer in an isolated worktree → in-workflow `git merge` → matched `-reviewer` → bounded fix loop) → **impl review** (plan-vs-implementation) → **verify** (dedup + adversarial verification) → **go-live audit** (composes `go-live-audit` inline, only when requested and the build comes back clean). It returns the verified findings honestly rather than faking a clean verdict. Per-task review is **slice-scoped**: each reviewer judges only that task's own write-scope against its acceptance criteria (it's given the rest of the plan), so an unmet whole-codebase invariant a *later* task owns — a legacy path not yet removed, a route/export not yet wired — is recorded as an observation against the owning task, **never a false BLOCK on the current slice**, and the fix loop only retries findings the engineer can actually touch; the end-state is enforced once by **impl review** over the fully-integrated tree. It **follows the DAG**: every task carries `dependsOn`, the plan's `layers` must be a topological order, plan review BLOCKs an incomplete/mis-ordered graph, the build **aborts a plan whose layers schedule a task before its dependencies**, and at runtime a task builds only once its dependencies are actually integrated on the working branch (a missing one is `dep_blocked`, pointing at the root). The build runs a **per-task pipeline**: each task is its own `build → integrate → review → fix` unit, run concurrently within a DAG layer (merges serialized by a lock, reviews fire the moment each task integrates), so a slow task never holds up a fast one's review. Integrate is **merge-only** — the whole-workspace `validate` runs **once at a final gate** on the integrated tree, never per task (so a half-migrated suite can't false-block a clean slice); a merge **conflict** is *resolved* (combining both sides, validated before commit), not bailed. Every run writes a **live status file** at `.ulpi/workflows/<id>.json` that doubles as a **durable checkpoint**: a resume reads it and skips work already done (independent of the runtime agent cache), rebuilding only the rest. A bundled journal reader (`helpers/wf-status.mjs`) gives at-a-glance **status**, and **`--resume <id>`** emits the exact one-command relaunch (carrying `planPath` + `checkpointResume`, no args to hand-assemble). Every gate **fails closed** — a died/absent reviewer, a died go-live audit, a blocking verdict with no finding, or a RED final `validate` can never read as `converged` clean. (The build loop was hardened across a dozen adversarial verification passes.) **Already have a reviewed DAG plan?** Point it at the plan (`resume .ulpi/plans/<name>.md`) and it resumes at build, skipping planning and plan-review. Explicit-user-only; spawns many agents over the run, behind concurrency caps **and rate-limit retry with exponential backoff** — so a Claude API rate-limit storm is re-attempted, not mis-recorded as blocked tasks.
+The delivery capstone: it chains the repo's own skills into a single runnable Workflow that runs **one pass** and returns the verified findings as feedback — it does **not** loop on its own (an autonomous fix-loop is what caused multi-hour grinds; the user decides whether to run a fix round). Up front it shows which composed skills and specialist agents are installed (with install commands), then asks **seven gate questions** — who writes the plan, who reviews it, who writes the code, who reviews each task, impl review, go-live audit, and an optional project-map refresh. Every role **independently** picks its executor (`native` / `codex` / `kiro`; reviews can `skip`; the writer and a reviewer may be different harnesses), so you control quality vs token cost. Then it runs: **plan** (`plan-to-task-list-with-dag`, assigning a specialist engineer + `-reviewer` + stack skill per task) → **plan review** (`plan-founder-review`, bounded loop) → **build** (per task across the DAG layers: specialist engineer in an isolated worktree → in-workflow `git merge` → matched `-reviewer` → bounded fix loop) → **impl review** (plan-vs-implementation) → **verify** (dedup + adversarial verification) → **go-live audit** (composes `go-live-audit` inline, only when requested and the build comes back clean). It returns the verified findings honestly rather than faking a clean verdict. Per-task review is **slice-scoped**: each reviewer judges only that task's own write-scope against its acceptance criteria (it's given the rest of the plan), so an unmet whole-codebase invariant a *later* task owns — a legacy path not yet removed, a route/export not yet wired — is recorded as an observation against the owning task, **never a false BLOCK on the current slice**, and the fix loop only retries findings the engineer can actually touch; the end-state is enforced once by **impl review** over the fully-integrated tree. It **follows the DAG**: every task carries `dependsOn`, the plan's `layers` must be a topological order, plan review BLOCKs an incomplete/mis-ordered graph, the build **aborts a plan whose layers schedule a task before its dependencies**, and at runtime a task builds only once its dependencies are actually integrated on the working branch (a missing one is `dep_blocked`, pointing at the root). The build runs a **per-task pipeline**: each task is its own `build → integrate → review → fix` unit, run concurrently within a DAG layer (merges serialized by a lock, reviews fire the moment each task integrates), so a slow task never holds up a fast one's review. Each isolated worktree is **provisioned fast** (`warmWorktree`, default on): a one-time warm step primes caches while planning runs, then engineers copy-on-write-clone `node_modules`/`vendor`/`Pods` from the primary checkout when the lockfile is unchanged, and share Rust crate compilation via `sccache` (no `target/` clone) — falling back to a normal frozen install, and `warmWorktree:false` restores the plain install. Integrate is **merge-only** — the whole-workspace `validate` runs **once at a final gate** on the integrated tree, never per task (so a half-migrated suite can't false-block a clean slice); a merge **conflict** is *resolved* (combining both sides, validated before commit), not bailed. Every run writes a **live status file** at `.ulpi/workflows/<id>.json` that doubles as a **durable checkpoint**: a resume reads it and skips work already done (independent of the runtime agent cache), rebuilding only the rest. A bundled journal reader (`helpers/wf-status.mjs`) gives at-a-glance **status**, and **`--resume <id>`** emits the exact one-command relaunch (carrying `planPath` + `checkpointResume`, no args to hand-assemble). Every gate **fails closed** — a died/absent reviewer, a died go-live audit, a blocking verdict with no finding, or a RED final `validate` can never read as `converged` clean. (The build loop was hardened across a dozen adversarial verification passes.) **Already have a reviewed DAG plan?** Point it at the plan (`resume .ulpi/plans/<name>.md`) and it resumes at build, skipping planning and plan-review. Explicit-user-only; spawns many agents over the run, behind concurrency caps **and rate-limit retry with exponential backoff** — so a Claude API rate-limit storm is re-attempted, not mis-recorded as blocked tasks.

 ---

@@ -1,6 +1,6 @@
 ---
 name: ship-playbook
-version: 1.10.1
+version: 1.10.2
 description: |
  Take one feature request and run the entire delivery playbook automatically: plan it, review the
  plan, build it task by task, review the build, and optionally audit it for launch — then return the
@@ -356,12 +356,14 @@ Then launch `references/workflow-template.js` via the **Workflow** tool, passing
 Workflow({ scriptPath: ".../references/workflow-template.js",
           args: { prompt, root, workingBranch, validate, hardRules, goLive,
                   planHarness, planReview, buildHarness, taskReview, implReview,
-                   auditScriptPath, availableAgents, allowGeneralFallback,
+                   auditScriptPath, availableAgents, allowGeneralFallback, warmWorktree,
                   planPath, kiroModel,
                   workflowId, statusFile, trackStatus, checkpointResume } })   // planPath → RESUME at build;
                                                              // workflowId/statusFile → live .ulpi/workflows/<id>.json
                                                              // (trackStatus:false disables); checkpointResume:false →
-                                                              // force a full rebuild (default true: skip done tasks)
+                                                              // force a full rebuild (default true: skip done tasks);
+                                                              // warmWorktree:false → plain per-worktree install
+                                                              // (default true: CoW-seed node_modules/vendor/Pods + sccache)
 ```

 **After launch, stamp the run id AND the full launch args.** The Workflow tool returns a `runId` (`wf_…`)
@@ -404,6 +406,10 @@ The Workflow then executes the playbook in one pass, running each gate at the le
 - **Build (steps 10–11)** — walk the DAG layers; per task: engineer (worktree, task branch) →
  in-workflow integrate agent (`git merge` onto the working branch, removing each merged worktree as it
  goes) → reviewer (unless `taskReview skip`) → bounded fix loop until it passes; barrier between layers.
+  Each fresh worktree is **provisioned fast** (`warmWorktree`, default on): a one-time warm step (overlapping
+  planning) primes caches, then engineers CoW-clone `node_modules`/`vendor`/`Pods` from the primary checkout
+  when the lockfile is unchanged (Rust shares crate compilation via `sccache` instead of cloning `target/`),
+  falling back to a normal frozen install; `warmWorktree:false` restores a plain per-worktree install.
  Engineer routes per `buildHarness`; reviewer per `taskReview` — and the two are INDEPENDENT (write
  codex, review kiro is fine). The build and verify fan-outs run behind concurrency gates so a wide DAG
  layer or a long findings list can't trip Claude's API rate limits: at most `MAX_BUILD_PARALLEL` (4)