@laitszkin/apollo-toolkit 3.9.3 → 3.9.5

package/CHANGELOG.md

@@ -34,6 +34,18 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.9.5] - 2026-05-08
+
+### Changed
+- `implement-specs`: document read order (spec → design → contract → checklist → tasks), evidence-backed plan resolution, sequential multi-directory execution per `coordination.md`; drop `enhance-existing-features` / `develop-new-features` dependencies; trim frontmatter description; sync agent prompt.
+- `implement-specs-with-worktree`: align with updated `implement-specs` contract and dependencies; trim description; sync agent prompt.
+- `implement-specs-with-subagents`: replace sample hints with subagent scheduling examples (parallel four-spec batch vs preparation plus A → {B, C}).
+
+## [v3.9.4] - 2026-05-07
+
+### Changed
+- `implement-specs`, `implement-specs-with-worktree`, `implement-specs-with-subagents`: require full execution of every in-scope `tasks.md` line with no workload exemption; treat complete `checklist.md` wrap-up / acceptance / closing obligations as a hard gate before the spec may be considered done or merged (coordinators must not merge partial checklist closure); tighten workflow Pause prompts and agent-facing descriptions accordingly.
+
 ## [v3.9.3] - 2026-05-07
 
 ### Changed

package/implement-specs/SKILL.md

@@ -1,25 +1,26 @@
 ---
 name: implement-specs
 description: >-
-  Land an approved `docs/plans/{YYYY-MM-DD}/{change}` (or batch member path) on the currently checked-out branch: read the full planning bundle + `coordination.md` when relevant, execute every in-scope `tasks.md` item, backfill honest checklist/spec state, then **finalize through `commit-and-push`**—**do not** create branches/worktrees or widen to push/release unless the user explicitly asks mid-thread.
-  Choose this for “implement on this branch” scenarios. If isolation is required use **`implement-specs-with-worktree`**; if multiple specs need delegated workers use **`implement-specs-with-subagents`**.
-  Good: stay on `feature/foo`, finish tasks, run **`commit-and-push`**. Bad: `git worktree add` purely to avoid dirty trees—wrong skill unless user re-scoped.
+  Land approved `docs/plans/{YYYY-MM-DD}/{change}` (or batch member path) on the current branch: resolve path by user pointer or evidence-backed latest (no guesses); read spec→design→contract→checklist then run every `tasks.md` line and all `checklist.md` wrap-up; multi-directory work follows `coordination.md`—one directory fully done before the next; backfill plans; **`commit-and-push`** for final commit (no branch/worktree unless user rescopes). Isolation: **`implement-specs-with-worktree`**; delegation: **`implement-specs-with-subagents`**.
 ---
 
 # Implement Specs
 
 ## Dependencies
 
-- Required: `enhance-existing-features` and `develop-new-features` for implementation standards; **`commit-and-push`** for the **final** implementation commit (and push when the user explicitly requests remote update).
+- Required: **`commit-and-push`** for the **final** implementation commit (and push when the user explicitly requests remote update).
 - Conditional: `generate-spec` if spec files need clarification or updates; `recover-missing-plan` if the requested plan path is missing from the current checkout.
 - Optional: none.
-- Fallback: If **`enhance-existing-features`**, **`develop-new-features`**, or **`commit-and-push`** is unavailable, **MUST** stop immediately and report the missing dependency. Do not improvise substitute standards or ungated `git commit`.
+- Fallback: If **`commit-and-push`** is unavailable, **MUST** stop immediately and report the missing dependency. Do not improvise substitute standards or ungated `git commit`.
 
 ## Non-negotiables
 
-- **MUST** read and understand the full in-scope planning set (`spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`) and the parent `coordination.md` when its path applies, **before** editing product code or tests for this spec.
+- **MUST** read and understand the full in-scope planning set and the parent `coordination.md` when its path applies, **before** editing product code or tests for this spec. Read for meaning in this order: **`spec.md`** (requirements / intent), **`design.md`** (system design / boundaries), **`contract.md`** (external dependencies and interfaces), **`checklist.md`** (wrap-up, acceptance, and closing obligations), then treat **`tasks.md`** as the ordered implementation checklist. **MUST NOT** start coding until that read pass is complete for the current in-scope directory.
+- **MUST** when multiple spec directories apply to one request, follow parent **`coordination.md`** merge / sequencing guidance (or the user’s explicit order if coordination is absent or defers to them) and **complete** one directory end-to-end—**all** of its `tasks.md` lines **and** **all** of its `checklist.md` wrap-up / acceptance work—**before** starting implementation work in the next directory. **MUST NOT** interleave partial implementation across sibling specs.
 - **MUST NOT** create a branch, switch branches, or add or use a `git worktree` for this work unless the user explicitly changes the request in the same conversation.
-- **MUST** treat the approved `tasks.md` / contracts as the scope boundary: complete every item that is in scope for this request, run the relevant tests, and **MUST** backfill the planning documents with factual completion status (no aspirational checkboxes).
+- **`tasks.md` completeness (hard stop)**: **MUST** execute **every** actionable item listed in the in-scope `tasks.md` for this request—**no exceptions** for perceived size, duration, file count, refactor depth, or session length. **MUST NOT** stop early, “defer” unchecked tasks while claiming the spec is done, collapse multiple task lines into a partial summary, or substitute narrative progress for completing a remaining line. If a line is truly impossible under written contracts, **MUST** stop with evidence and **MUST NOT** treat the implementation pass as complete until the plan is amended through the governing planning workflow (`generate-spec` / user-approved update) and the revised `tasks.md` is then fully satisfied.
+- **`checklist.md` wrap-up / acceptance (hard stop for “spec complete”)**: **MUST** complete **all** `checklist.md` obligations that constitute **wrap-up, acceptance, verification, release-prep, doc or index sync, or other closing/hand-off** work tied to this change—**same no-exemption bar as `tasks.md`** (workload, duration, or breadth **do not** waive checklist-only items). The **entire** in-scope spec is **not** **complete** until those checklist items are **actually satisfied** and truthfully marked. **MUST NOT** treat “implementation done” or proceed to final **`commit-and-push`** / completion reporting while checklist-defined closing work remains open or is waved away with narrative. If a checklist item is impossible under contracts or facts on the ground, **MUST** stop with evidence and **MUST NOT** declare the spec complete until the plan is amended through the governing workflow and the revised `checklist.md` is then fully satisfied.
+- **MUST** treat the approved `tasks.md`, `checklist.md`, and contracts as the scope boundary: on top of the rules above, run the relevant checklist-backed verifications and tests, and **MUST** backfill the planning documents with factual completion status (no aspirational checkboxes).
 - **MUST NOT** expand scope to unrelated sibling spec directories solely because they share a batch folder.
 - **MUST** finalize the implementation through **`commit-and-push`** after staging the intended change set (shared readiness, reviews per that skill’s classification, conventional commit message); **MUST NOT** complete the deliverable with a bare `git commit`, IDE-only commit, or other shortcut that skips **`submission-readiness-check`** / mandated gates.
 - **MUST NOT** `git push`, tag, or perform release steps **outside** **`commit-and-push`** (unless **`version-release`** / **`open-source-pr-workflow`** explicitly applies per user request).
@@ -28,17 +29,17 @@ description: >-
 ## Standards (summary)
 
 - **Evidence**: Same as Non-negotiables: no coding until the spec set is fully read; no guessed plan paths.
-- **Execution**: Current checkout only; dependent-skill standards apply to all implementation and testing steps.
-- **Quality**: All in-scope tasks done; tests executed; docs reflect reality; no scope creep into sibling specs.
+- **Execution**: Current checkout only; implement and test against the approved **`spec.md` / `design.md` / `contract.md`** and **`tasks.md`** lines—no parallel branch or worktree (unless the user rescopes to another skill).
+- **Quality**: **All** `tasks.md` lines **and** **all** `checklist.md` wrap-up / acceptance obligations for this scope satisfied (see Non-negotiables—workload is not an excuse); tests and checklist verifications executed as required; docs reflect reality; no scope creep into sibling specs.
 - **Output**: Current branch contains a clean, reviewable implementation of this spec only.
 
 ## Workflow
 
 **Chain-of-thought:** Before advancing each numbered step, answer the **`Pause →`** questions (even if only internally). A “no” or “unknown” answer **MUST** be resolved or surfaced as a blocker before continuing.
 
-1. **Locate and read** — Resolve `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`. Read the five core files; read parent `coordination.md` when present. Stay inside the directories the user asked for.
-   - **Pause →** Is this directory the **exact** scope the user asked for, verified by listing or viewing those five files—not a sibling “similar” folder?
-   - **Pause →** Have I explicitly linked each material requirement / task to evidence I understood (still no code edits)?
+1. **Locate and read** — Resolve `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` using the path the **user** gave **or**, when none is given, the **most recent** plan location proven by repository evidence (issue links, manifests, `docs/plans` listing—**MUST NOT** pick a sibling folder by guess). Read parent `coordination.md` when present (merge order, parallelism rules, collisions). For **each** in-scope directory, before any code edits, read the five core files for substance in this order: `spec.md` → `design.md` → `contract.md` → `checklist.md` → `tasks.md` (execution list). If multiple directories are in scope, establish their **sequence** from `coordination.md` (or the user) and plan to implement **one directory at a time** to full completion (Non-negotiables).
+   - **Pause →** Is this directory the **exact** scope—or ordered list—the user (or coordination) requires, verified by listing or viewing those five files—not a sibling “similar” folder?
+   - **Pause →** Have I explicitly linked each material requirement / task to evidence I understood from **spec** / **design** / **contract** (still no code edits)?
    - **Pause →** If the path were missing or wrong, what **verifiable** step would locate the authoritative plan—and have I executed it?
 
 2. **Branch sanity** — Run `git status -sb`. Do not modify unrelated dirty files; surface blockers. Confirm the current branch is where this work should land.
@@ -46,20 +47,22 @@ description: >-
    - **Pause →** What dirty paths are **out of scope**, and how will I avoid touching them inadvertently?
    - **Pause →** Is the integration target branch (where the user expects work) identical to what `git status -sb` shows?
 
-3. **Implement** — Execute approved `tasks.md` per `enhance-existing-features` / `develop-new-features`. Run relevant tests.
+3. **Implement** — Execute **the entire** approved `tasks.md` (every line) for the **current** in-scope directory only, honoring requirements and design you read in step 1; do not close this step until **no** applicable unchecked tasks remain **for that directory**. Run relevant tests and **any** verification commands or artifact steps that `checklist.md` already assigns to the implementation phase (do not postpone checklist-only closing items that belong here). When the request spans multiple directories, **repeat** steps 3–4 **per directory** in the coordination order **after** the previous directory’s tasks **and** checklist obligations are satisfied.
+   - **Pause →** Have I listed **every** remaining `tasks.md` line—and is the count **zero** before I leave this step?
    - **Pause →** For the next task item, what is the **single** concrete change and its **single** primary verification—before I type code?
    - **Pause →** Am I about to touch a file that belongs to a **sibling** spec or an unrelated module without an in-scope task line?
    - **Pause →** After this chunk of work, which test command **proves** I did not break the contract’s stated behavior?
 
-4. **Backfill** — Update `checklist.md` / `tasks.md` (and any other plan files your standards require) so completion status matches what you actually did.
+4. **Backfill** — Update `checklist.md` / `tasks.md` (and any other plan files your standards require) so completion status matches what you actually did. **MUST NOT** advance to **Submit** until **every** checklist item that defines wrap-up or acceptance for this spec is **done** or the batch is an honest documented halt per Non-negotiables.
    - **Pause →** If I checked a box, can I point to **commit + test run** (or equivalent) that makes that check true—no wishful checking?
+   - **Pause →** Are **zero** checklist obligations that mean “before spec complete” still open—validated by re-reading `checklist.md`, not from memory?
    - **Pause →** Did any scope shrink or shift during implementation; if so, is the plan text updated **honestly**?
 
-5. **Submit** — Stage the intended implementation/backfill diff. Run **`commit-and-push`** through commit using that staged intent (and **push** only when the user explicitly requested remote update). Keep scope to this spec only; split into multiple submission passes only when an unavoidable checkpoint requires separate commits.
+5. **Submit** — Stage the intended implementation/backfill diff. Run **`commit-and-push`** through commit using that staged intent (and **push** only when the user explicitly requested remote update). Keep scope to this spec only; split into multiple submission passes only when an unavoidable checkpoint requires separate commits. **Only** reach this step when **both** `tasks.md` and `checklist.md` Non-negotiable closures are satisfied.
    - **Pause →** Does `git diff --cached` (or the equivalent staged view) show only this spec’s intended surface, or do I need to unstage/revert noise first?
    - **Pause →** Am I on the **same** branch I named in step 2, without a silent branch switch?
 
-6. **Report** — State current branch, commit hash, tests run, and which plan files were backfilled.
+6. **Report** — State current branch, commit hash, tests run, which plan files were backfilled, and explicit confirmation that **`tasks.md` and checklist-defined wrap-up work are complete** for this in-scope spec (or cite the documented blocker).
    - **Pause →** Would another engineer **reproduce** my conclusion from the branch name, commit hash, and test commands I listed alone?
 
 If this skill directory contains `references/implement-specs-common.md`, treat it as an optional extension to the steps above; if it is absent, the Workflow section here is authoritative.
@@ -67,13 +70,13 @@ If this skill directory contains `references/implement-specs-common.md`, treat i
 ## Sample hints
 
 - **Resolve path**: user says “implement `oauth-scope`”; read `docs/plans/2026-05-01/oauth-scope/` first, **not** a sibling folder like `docs/plans/2026-05-01/batch/oauth-scope/` unless that is where the five files actually live per user or manifest.
+- **Read order**: keep the mandated sequence (**spec → design → contract → checklist → tasks**); use **`checklist.md`** after **spec/design/contract** so acceptance checks map to stated requirements and boundaries.
+- **Multi-directory batch (same branch)**: `coordination.md` says merge order `api-layer` then `cli-wrapper` — finish **`api-layer`** `tasks.md` **and** **`api-layer`** `checklist.md` completely, then start **`cli-wrapper`**; do not split half of each.
 - **Branch sanity excerpt**: expect `git status -sb` like `## feature/x …` plus a dirty `README.md` you do **not** own — leave that file untouched; implement only paths from `tasks.md`.
 - **Completion report sketch**: `Branch: feature/x · Commit: a1b2c3d · Tests: npm test -- lib/auth.test.js · Backfill: tasks.md (done), checklist.md (R1.3 → passed).`
 - **Anti-pattern**: `git checkout -b impl/oauth-scope` for this skill — **wrong** unless the user changed scope mid-conversation.
 
 ## References
 
-- `enhance-existing-features`: brownfield implementation standards
-- `develop-new-features`: greenfield implementation standards
 - `recover-missing-plan`: missing or mismatched plan recovery
 - **`commit-and-push`**: final commit/readiness (push only when user requests remote update)

package/implement-specs/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implement Specs"
   short_description: "Implement approved specs in the current checkout"
-  default_prompt: "Use $implement-specs to read the full plan set under docs/plans, including parent coordination.md when the spec belongs to a parallel batch, implement all approved tasks in the current checkout without creating branches or git worktrees, backfill completion status into the planning docs, and commit the result to the current branch."
+  default_prompt: "Use $implement-specs to resolve the user-named docs/plans path or the evidence-backed latest plan (never guess), read parent coordination.md when present, read spec.md then design.md then contract.md then checklist.md before executing every tasks.md line; when multiple member directories apply, finish one directory completely before the next per coordination.md; never create branches or git worktrees unless the user rescopes, backfill the planning docs, and finalize with $commit-and-push."

package/implement-specs-with-subagents/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: implement-specs-with-subagents
 description: >-
-  Coordinator-only workflow for multispec batches: ingest `coordination.md`/`preparation.md`, run prerequisite work yourself, derive topological phases, launch ≤4 staggered **`implement-specs-with-worktree`** workers (one `{change}` each), **`merge-changes-from-local-branches`** after every phase succeeds, ledger every branch/test/merge—not for solo specs unless user explicitly insists on delegation overload. **Multi-phase: do not declare done until every non-blocked spec is merged across all phases** (or pipeline stopped on explicit blocker).
+  Coordinator-only workflow for multispec batches: ingest `coordination.md`/`preparation.md`, run prerequisite work yourself, derive topological phases, launch ≤4 staggered **`implement-specs-with-worktree`** workers (one `{change}` each; **full** `tasks.md` + **full** `checklist.md` wrap-up—no partial handoff), **`merge-changes-from-local-branches`** after every phase succeeds, ledger every branch/test/merge—not for solo specs unless user explicitly insists on delegation overload. **Multi-phase: do not declare done until every non-blocked spec is merged across all phases** (or pipeline stopped on explicit blocker).
   Wrong tool for one directory without parallel mandate—pick **`implement-specs-with-worktree`** / **`implement-specs`** depending on isolation. Publication/versioning stays outside this orchestration layer unless another skill attaches.
   Ledger sample: `oauth-scope | phase=1 | merged | npm test ✅`. Burst-launching four agents simultaneously—disallowed pacing required…
 ---
@@ -23,7 +23,8 @@ description: >-
 - **MUST** build a directed dependency graph from `coordination.md` plus each spec’s `spec.md` / `design.md` (edges: *provider spec must merge before consumer spec*). **MUST** partition specs into phases by topological **layers**: Phase 1 = specs with **no** in-batch prerequisites; for *k* ≥ 2, Phase *k* = specs whose in-batch prerequisites all appear in phases before *k*. **MUST NOT** start phase *k* until phase *k − 1* is fully merged into the integration branch (or you have an explicit user override). If the graph has a cycle, **MUST** stop and report it.
 - **MUST** assign **exactly one** spec directory per implementation subagent; **MUST NOT** assign multiple directories to one implementation subagent.
 - **MUST** cap **active** implementation subagents at **four**; **MUST** start them **one at a time** with confirmation each is running before the next start; **MUST** back off on rate limits (no burst launches). Four is a ceiling, not a quota.
-- **MUST** give each subagent only task-local context (repo root, exact spec path, `coordination.md` path if relevant, instruction to run `implement-specs-with-worktree`, baseline commit when preparation exists, requirement to read the full bundle before edits, worktree isolation, tests, backfill, local commit, and reporting branch/worktree/commit/tests/blockers). **MUST NOT** leak unrelated reasoning or other subagents’ private diffs unless resolving a concrete conflict.
+- **`tasks.md` + `checklist.md` completeness (hard stop)**: Every implementation subagent **MUST** finish **all** actionable items in its assigned directory’s `tasks.md` **and** **all** `checklist.md` wrap-up, acceptance, verification, and closing obligations before reporting success—**no** partial completion, **no** “good enough” stops for large batches, **no** deferrals disguised as done. The coordinating agent **MUST NOT** merge a phase branch, advance the ledger to **`merged`**, or treat a spec as complete while **any** in-scope `tasks.md` line **or** checklist-defined closing item remains undone unless the batch is explicitly **`blocked`** with documented user/contract halt. **MUST** repeat this mandate in **every** subagent envelope so workers cannot interpret scope loosely.
+- **MUST** give each subagent only task-local context (repo root, exact spec path, `coordination.md` path if relevant, instruction to run `implement-specs-with-worktree`, explicit **`tasks.md` full-completion** and **`checklist.md` wrap-up full-completion** requirements, baseline commit when preparation exists, requirement to read the full bundle before edits, worktree isolation, tests, backfill, local commit, and reporting branch/worktree/commit/tests/blockers). **MUST NOT** leak unrelated reasoning or other subagents’ private diffs unless resolving a concrete conflict.
 - After each phase: **MUST** merge every **completed** spec branch from that phase into the integration branch via `merge-changes-from-local-branches` before starting the next phase; **MUST** resolve conflicts using spec contracts as the correctness tie-breaker; **MUST** record merge result in the ledger; if merge is blocked, **MUST** stop the pipeline and report.
 - **Multi-phase completion**: When the planned ledger has **more than one** phase, **MUST** loop steps **5→6→7** until **every** in-scope spec is either **`merged`** on the integration branch or explicitly **`blocked`** with a documented stop (user abort, irresolvable conflict, failed dependency, etc.). **MUST NOT** yield, summarize as “phase complete”, or imply the batch is finished while **any** phase still has a successful, unmerged branch or **`pending`** / **`in_progress`** rows for specs that should run—unless the coordinating agent is halted by a preceding Non-negotiable blocker **and** that halt is stated plainly.
 - Model: If the user names a model, **MUST** use it for implementation subagents when the platform allows; if not supported, **MUST** state that fact and continue only if the default is acceptable to the user’s intent.
@@ -32,7 +33,7 @@ description: >-
 
 - **Evidence**: Batch read (`coordination.md`, `preparation.md`, every in-scope `spec.md` / `design.md`) before scheduling; ledger stays live.
 - **Execution**: Preparation → dependency graph → **repeat** (run phase *k* → merge phase *k*) until all phases reconciled on the integration branch; never skip merges between dependent phases; **multi-phase ⇒ no early “done” narrative** until ledger proves full merge-set (or documented blockers).
-- **Quality**: No duplicate delegation; subagents base on the branch that already contains preparation (and prior phases); pause on shared file collisions, batch-wide defects, or rate-limit pressure.
+- **Quality**: No duplicate delegation; subagents base on the branch that already contains preparation (and prior phases); **every** spec lands with **complete** `tasks.md` execution **and** **complete** `checklist.md` wrap-up, or a documented **blocked** state—workload is never a merge excuse; pause on shared file collisions, batch-wide defects, or rate-limit pressure.
 - **Output**: Concise ledger: per spec → phase, depends-on, subagent id/label, branch/worktree, commit or blocker, tests, merge status.
 
 ## Workflow
@@ -59,7 +60,8 @@ description: >-
    - **Pause →** How many subagents are **active** right now vs the cap of four; did I start the last one only **after** the previous was confirmed running?
    - **Pause →** Did two running subagents report **overlapping** paths; if yes, did I stop launching until ownership is clear?
 
-6. **Merge phase *k*** — When every item in phase *k* is **done or explicitly blocked**, merge **each successful** branch via `merge-changes-from-local-branches`; rerun critical tests if your standards say so; update ledger. Merge failure ⇒ **stop** before phase *k+1*.
+6. **Merge phase *k*** — When every item in phase *k* is **done or explicitly blocked**, merge **each successful** branch via `merge-changes-from-local-branches`; rerun critical tests if your standards say so; update ledger. Merge failure ⇒ **stop** before phase *k+1*. **“Done”** here **requires** full `tasks.md` completion **and** full `checklist.md` wrap-up / acceptance per Non-negotiables—not merely a subagent “looks finished” report.
+   - **Pause →** For **each** spec I am about to merge, can I cite **evidence** (branch + `tasks.md` **and** `checklist.md` state) that **zero** applicable task lines **and** **zero** outstanding checklist closing items remain—or is this a documented **`blocked`** outcome instead?
    - **Pause →** Has **every** successful branch in this phase been merged into the **same** integration branch I will use to **start** phase *k+1*?
    - **Pause →** If a merge conflict touches a **contract** field, which spec’s `contract.md` / `design.md` is the tie-breaker I will apply?
 
@@ -74,13 +76,13 @@ description: >-
 
 **Repository regression check:** The coordinating agent must complete and commit explicitly documented prerequisite preparation on the integration branch before launching implementation subagents when `preparation.md` or equivalent mandates it.
 
-## Sample hints
+## Sample hints (subagent scheduling)
 
-- **Ledger row (one line per spec)**:
-  `oauth-scope | phase=1 | depends-on: — | branch feat/oauth-scope | status merged | tests: npm test ✓`
-- **Subagent envelope (minimal)** — repo root `/repo`; spec `/repo/docs/plans/2026-05-01/batch-a/oauth-scope/`; instruction: run skill **`implement-specs-with-worktree`** on that path only; baseline `prep_sha=deadbeef` when preparation landed; reply with branch, `worktree path`, commit, tests.
-- **Tiny dependency graph**: `api-layer` blocks `cli-wrapper` ⇒ Phase 1: `{ api-layer }`, Phase 2: `{ cli-wrapper }`. Independent specs share a phase layer (e.g. both in Phase 1) **only** if neither lists the other as prerequisite in spec/design/coordination.
-- **Launch cadence**: with cap 4, acceptable active counts over time: `1 → 2 → 3 → 4 → (finish one) → 4`; **not** spawn 4 in one burst with no pacing.
+- **Parallel batch (four independent specs)** — The batch contains **four** member directories and `coordination.md` allows parallel implementation with **no** in-batch prerequisites. Treat them as **one phase**: assign **exactly one** spec per subagent, start up to **four** **`implement-specs-with-worktree`** workers **staggered** (never burst—Non-negotiables), each finishing **all** of its directory’s **`tasks.md`** and **`checklist.md`** before reporting success; when **every** branch in the phase is green, run **`merge-changes-from-local-branches`** to bring **all four** into the integration branch **before** declaring the batch done or starting a follow-on phase.
+
+- **Preparation plus A → {B, C}** — Specs **A**, **B**, and **C** share a batch with **`preparation.md`**; `coordination.md` / design shows **B** and **C** depend on merged work from **A**. Coordinating agent: (1) complete **preparation** on the integration branch and **`commit-and-push`** (push only if the user asked); (2) **Phase 1**: launch **one** subagent for **A** only; **`merge-changes-from-local-branches`** for **A** when it passes; (3) **Phase 2**: launch **two** subagents for **B** and **C** from the branch that already contains **A**’s merge, still staggering starts; (4) merge **B** and **C** when both finish. **MUST NOT** start **B** or **C** until **A** is merged into the baseline they branch from.
+
+- **Ledger reminder** — One row per spec remains mandatory (`phase`, `depends-on`, branch/worktree, `merged` / `blocked`, tests); see Non-negotiables for full fields.
 
 ## References
 

package/implement-specs-with-worktree/SKILL.md

@@ -1,16 +1,14 @@
 ---
 name: implement-specs-with-worktree
 description: >-
-  Same contract as **`implement-specs`** but every write happens inside a dedicated `git worktree` + feature branch; verify `pwd` equals `git rev-parse --show-toplevel` before touching code; parent checkout remains read-only for deliverables; honor `preparation.md` baselines and sibling collision rules from `coordination.md`.
-  Pick when the user or batch workflow demands isolation (“don’t disturb my dirty main”, per-spec worker). Plain same-branch edits stay on **`implement-specs`** instead.
-  Good: commands show matching paths after `git worktree add ../oauth-scope feat/oauth-scope`. Bad: patching files under the primary checkout tree for implementation output.
+  Like **`implement-specs`** (same read order, full `tasks.md`/`checklist.md`, sequential multi-spec per `coordination.md`) but all writes in a dedicated worktree+feature branch; `pwd` must match `git rev-parse --show-toplevel`; parent checkout read-only for deliverables; honor `preparation.md` and `coordination.md` collision rules. Use when isolation is required; otherwise **`implement-specs`**.
 ---
 
 # Implement Specs with Worktree
 
 ## Dependencies
 
-- Required: `implement-specs` for the shared discovery / implementation / backfill / **submit** / reporting lifecycle; **`commit-and-push`** for the **final** implementation commit (and push when the user explicitly requests remote update); `enhance-existing-features` and `develop-new-features` for implementation standards.
+- Required: `implement-specs` for the shared discovery / implementation / backfill / **submit** / reporting lifecycle; **`commit-and-push`** for the **final** implementation commit (and push when the user explicitly requests remote update).
 - Conditional: `generate-spec` if spec files need clarification or updates.
 - Fallback: If any required dependency skill is unavailable, **MUST** stop and report it.
 
@@ -23,7 +21,9 @@ description: >-
 - **MUST** use the spec directory name (`change_name`) as the canonical basename for the worktree path and branch stem; branch **`type`/name** must follow `references/branch-naming.md`.
 - **MUST** use `git show-ref` and `git worktree list --porcelain` (not shell guesses) when checking whether a branch or worktree already exists; if creation fails ambiguously, **MUST** re-query those commands before retrying.
 - When `preparation.md` exists: **MUST** treat it as an already-committed shared baseline for parallel work; **MUST NOT** redo its tasks inside the member spec unless the preparation commit is missing or the document states the prerequisite is still blocked. If baseline assumptions break, **MUST** update `preparation.md` or stop for coordination—**MUST NOT** silently move prerequisite work into the member spec.
-- **MUST** complete the same quality bar as `implement-specs`: all in-scope tasks, relevant tests, honest backfill, no sibling-spec scope creep, revert formatter-only noise outside owned files before commit.
+- **`tasks.md` completeness (hard stop)**: **MUST** satisfy the **`implement-specs` Non-negotiable** on **`tasks.md`**: execute **every** actionable line in the in-scope `tasks.md`, with **no** early exit for workload, duration, or breadth; partial task lists are **not** a mergeable or committable state. If a line cannot be met under contracts, **MUST** halt with evidence and resolve the plan through approved planning updates before claiming completion.
+- **`checklist.md` wrap-up / acceptance (hard stop for “spec complete”)**: **MUST** satisfy the **`implement-specs` Non-negotiable** on **`checklist.md`**: the spec is **not** **complete** and **must not** be merged or treated as finished until **all** checklist-defined wrap-up, acceptance, and closing obligations for the change are **done** and honestly recorded—**no** workload exemption.
+- **MUST** complete the same quality bar as `implement-specs`: on top of full `tasks.md` and **complete checklist wrap-up**, relevant tests, honest backfill, no sibling-spec scope creep, revert formatter-only noise outside owned files before commit.
 - **MUST NOT** `git push` **outside** **`commit-and-push`** unless the user explicitly requests remote update through that workflow (or a release/PR skill the user named).
 - For targeted Rust tests: **MUST** pass at most one positional `cargo test` filter per invocation; use separate commands or a broader confirmed filter when multiple selectors are needed.
 
@@ -31,7 +31,7 @@ description: >-
 
 - **Evidence**: Read full spec set plus `coordination.md` and `preparation.md` when present; verify whether the spec is already implemented on the baseline before opening a new worktree; if the plan is missing in the worktree, sync the authoritative copy and re-read before coding.
 - **Execution**: Isolated worktree only; branch naming per `references/branch-naming.md`; check sibling worktrees before editing shared boundaries in a parallel batch.
-- **Quality**: Same as `implement-specs`, plus collision awareness with sibling worktrees per `coordination.md`.
+- **Quality**: Same as `implement-specs` (including **all** `tasks.md` items **and** **all** `checklist.md` wrap-up obligations—no workload excuse), plus collision awareness with sibling worktrees per `coordination.md`.
 - **Output**: Clean local branch in the worktree with intended commits only; parent working tree unchanged by this implementation.
 
 ## Workflow
@@ -59,7 +59,7 @@ description: >-
 
 ### C) Implement, backfill, commit, report
 
-- Execute **`implement-specs` Workflow steps 3–6** (implement, backfill, **submit via `commit-and-push`**, report) **entirely from the worktree root**, applying `enhance-existing-features` / `develop-new-features` standards.
+- Execute **`implement-specs` Workflow steps 3–6** (implement—including **full** `tasks.md` and checklist-backed work per Non-negotiables—backfill—including **complete** `checklist.md` wrap-up before submit—**submit via `commit-and-push`**, report) **entirely from the worktree root**, honoring the same **`spec.md` / `design.md` / `contract.md` / `checklist.md` / `tasks.md`** read-and-execute rules as **`implement-specs`** (including **one directory at a time** to completion when the request spans multiple member specs on the same integration cadence—typically **one worktree lifecycle per directory** unless the user batches otherwise).
 - In the report, **MUST** include branch name, worktree path, commit hash, tests run, backfilled docs, and an explicit statement that the parent checkout was not modified for implementation files.
   - **Pause →** Am I honoring **implement-specs** step 3–6 **constraints** literally while respecting that all writes happen **only** under this worktree root?
   - **Pause →** If I used Rust `cargo test` filters, did I violate the **single positional filter** rule; how would I split the commands?
@@ -80,6 +80,5 @@ description: >-
 
 ## References
 
-- `implement-specs`: shared lifecycle (read → implement → backfill → **`commit-and-push`** → report)
+- `implement-specs`: shared lifecycle (locate → read bundle in order → implement → backfill → **`commit-and-push`** → report)
 - `references/branch-naming.md`: branch naming
-- `enhance-existing-features`, `develop-new-features`: implementation standards

package/implement-specs-with-worktree/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implement Specs with Worktree"
   short_description: "Implement an approved spec set inside an isolated git worktree"
-  default_prompt: "Use $implement-specs-with-worktree to read the full plan set under docs/plans, including parent coordination.md when the spec belongs to a parallel batch, identify the parent branch that the worktree should inherit from, inspect sibling worktrees when shared runtime/config boundaries may overlap, create or reuse an isolated git worktree whose branch and directory names are derived from the spec name, implement all approved tasks within the shared ownership and replacement-direction constraints, backfill completion status into the planning docs, and commit the result to the local worktree branch without affecting the parent branch."
+  default_prompt: "Use $implement-specs-with-worktree to follow the same docs/plans resolution and read-order rules as $implement-specs (spec then design then contract then checklist then tasks; one directory fully done before the next per coordination.md when multiple apply), identify the parent branch, create or reuse an isolated worktree and matching branch, verify pwd matches git rev-parse --show-toplevel before any write, keep the parent checkout read-only for deliverables, complete every tasks.md line and checklist.md wrap-up in the worktree, backfill planning docs, and finalize with $commit-and-push on the worktree branch."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.9.3",
+  "version": "3.9.5",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",