From f5f262d7f6bce2ddcfef79ca7245c43ca8a9de91 Mon Sep 17 00:00:00 2001 From: Ciprian Spiridon Date: Sun, 5 Jul 2026 06:30:12 +0400 Subject: [PATCH] =?UTF-8?q?ship-playbook=20v1.10.2=20=E2=80=94=20document?= =?UTF-8?q?=20warmWorktree=20(worktree=20seeding=20+=20sccache)=20in=20SKI?= =?UTF-8?q?LL.md=20+=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 2 +- ship-playbook/SKILL.md | 12 +++++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 196ff58..6c089a4 100644 --- a/README.md +++ b/README.md @@ -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/.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 `** 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/.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/.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 `** 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/.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. --- diff --git a/ship-playbook/SKILL.md b/ship-playbook/SKILL.md index b821046..642451f 100644 --- a/ship-playbook/SKILL.md +++ b/ship-playbook/SKILL.md @@ -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/.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)