@laitszkin/apollo-toolkit 3.9.4 → 3.9.5

package/CHANGELOG.md

@@ -34,6 +34,13 @@ 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

package/implement-specs/SKILL.md

@@ -1,23 +1,22 @@
 ---
 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 actionable line in `tasks.md` with no exemption for workload or session length**, **complete every `checklist.md` wrap-up / acceptance obligation so the spec is not “done” until checklist-backed closing work is satisfied**, backfill honest plan 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 all `tasks.md` and `checklist.md` closing work, 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.
 - **`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.
@@ -30,7 +29,7 @@ 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.
+- **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.
 
@@ -38,9 +37,9 @@ description: >-
 
 **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.
@@ -48,7 +47,7 @@ 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 **the entire** approved `tasks.md` (every line) per `enhance-existing-features` / `develop-new-features`; do not close this step until **no** applicable unchecked tasks remain. 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).
+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?
@@ -71,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

@@ -76,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; **mandate: complete every line in that directory’s `tasks.md` and every `checklist.md` wrap-up / acceptance item**; baseline `prep_sha=deadbeef` when preparation landed; reply with branch, `worktree path`, commit, tests, and confirmation that **no** applicable `tasks.md` items **or** checklist closing obligations remain open.
-- **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`**—including **complete execution of every `tasks.md` line and every `checklist.md` wrap-up / acceptance obligation regardless of workload**—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.
 
@@ -61,7 +59,7 @@ description: >-
 
 ### C) Implement, backfill, commit, report
 
-- 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**, 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?
@@ -82,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.4",
+  "version": "3.9.5",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",