@laitszkin/apollo-toolkit 3.9.4 → 3.9.6

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this repository are documented in this file.
 
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [v3.9.6] - 2026-05-09
+
+### Changed
+
+- `generate-spec`: refocus `design.md`/`contract.md` templates as coarse `INT-###`/`EXT-###` guiding context above `tasks.md` (avoid mirroring runnable checklist rows); tighten SKILL/README/agent prompt layering; clarify `tasks.md` notes accordingly.
+- `implement-specs`: treat `tasks.md` as the authoritative runnable queue; read `design`/`contract` as constraints/anchors; align execution standards copy.
+- `implement-specs-with-subagents`: remove fixed four-subagent ceiling and stagger-only pacing language; generalize parallel phase examples and agent prompt.
+- Root `README.md`: simplify `implement-specs-with-subagents` compatibility blurb.
+
 ## [v3.7.0] - 2026-04-29
 
 ### Added
@@ -29,10 +46,12 @@ All notable changes to this repository are documented in this file.
 - Simplify `maintain-project-constraints` to produce `AGENTS.md`/`CLAUDE.md` with exactly three sections: Common Development Commands, Project Business Goals, and Project Documentation Index
 - Update `archive-specs` to delegate documentation generation to the refactored `align-project-documents` and constraint-file refresh to `maintain-project-constraints`; replace flat-category reference templates with the new three-category structure
 
-## [Unreleased]
+## [v3.9.5] - 2026-05-08
 
-### Added
-- (None yet)
+### 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
 

package/README.md

@@ -200,7 +200,7 @@ The install commands below were checked with the Skills CLI unless otherwise not
 Compatibility note:
 
 - `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`, and it can produce either a single spec set under `docs/plans/{YYYY-MM-DD}/{change_name}/` or a coordinated parallel batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with shared `coordination.md`.
-- `implement-specs-with-subagents` coordinates one `implement-specs-with-worktree` subagent per spec directory for approved multi-spec batches, with staggered launches and a maximum of four active implementation subagents.
+- `implement-specs-with-subagents` coordinates one `implement-specs-with-worktree` subagent per spec directory for approved multi-spec batches.
 - `recover-missing-plan` is a local skill used by `enhance-existing-features` and `ship-github-issue-fix` when a referenced `docs/plans/...` spec set is missing or archived.
 - `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
 - `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.

package/generate-spec/README.md

@@ -12,7 +12,7 @@ A shared planning skill for feature work. It centralizes creation and maintenanc
 - Backfills task and checklist status after implementation and testing.
 - Keeps requirement, task, and test coverage mapping traceable.
 - Uses `test-case-strategy` to choose test levels, define meaningful oracles, and add focused unit drift checks to atomic implementation tasks.
-- Standardizes external dependency contracts in `contract.md` and architecture/design deltas in `design.md`.
+- Standardizes **`design.md` / `contract.md` as high-level context** (architecture + external truth, `INT-###`/`EXT-###` anchors)—**`tasks.md` remains the sole file-level execution queue** implementing that context.
 
 ## Repository layout
 
@@ -95,8 +95,8 @@ docs/plans/<today>/membership-cutover/
 - `spec.md`: use BDD keywords `GIVEN / WHEN / THEN / AND / Requirements`.
 - `tasks.md`: use `## **Task N: ...**` and atomic implementation queue items with allowed scope, output, completion condition, verification hook, and unit drift check.
 - `checklist.md`: use `- [ ]` only, adapt items to real scope, record actual results, and map behavior risks to test IDs plus oracles selected through `test-case-strategy`.
-- `contract.md`: when external dependencies materially shape the change, record their official-source-backed invocation surface, constraints, and caller obligations in the standard dependency-record format.
-- `design.md`: record the architecture/design delta in the standard format, including affected modules, flow, invariants, tradeoffs, and validation plan.
+- `contract.md`: cite-backed **facts/limits/security** + **`EXT-###` anchors** (coarser than **`tasks.md`**); **no parallel checklist**—task rows may cite `EXT-###` when useful.
+- `design.md`: architecture + coarse **`INT-###` ordering/coupling hints** for **authoring** **`tasks.md`**; **no file-level checkbox mirror**; vendor detail belongs in **`contract.md`**.
 - `coordination.md`: for multi-spec batches only, record ownership boundaries, replacement direction, file ownership guardrails, known collision candidates, pre-agreed edit rules for shared surfaces, shared API/schema freeze or additive-only rules, compatibility-shim retention rules, merge order, and cross-spec integration checkpoints, but never use it to make one spec depend on another spec's implementation before it can be completed.
 - `preparation.md`: optional batch-level prerequisite plan used only when specs cannot be made parallel-safe without prior shared work; keep it tasks-like, minimal, verified, and free of core business logic or target outcomes.
 - If clarification responses change the plan, update the docs and obtain approval again before coding.

package/generate-spec/SKILL.md

@@ -33,7 +33,7 @@ description: >-
 
 - **Evidence**: Official docs when externally constrained; record cites in `spec.md` / `contract.md`.
 - **Execution**: Scaffold → fill templates in place → clarification loop → approval gate → (later) backfill after implementation.
-- **Quality**: Synchronized artifacts; applicable template sections only; realistic checklist vs boilerplate (add/remove by risk); finalized docs read as an approved plan, not a fully checked starter; `contract.md` standardized records or honest `None` with reason.
+- **Quality**: Synchronized artifacts; **`tasks.md`** is unique runnable granularity; **`design.md`/`contract.md`** constrain and orient without mirroring checklist rows—**`TBD`/honest `None`** when facts missing.
 - **Output**: `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`; batch root `coordination.md` when intentionally parallel; `preparation.md` only when prerequisite batch work is required first.
 
 ## Workflow
@@ -60,7 +60,7 @@ apltk create-specs "<feature_name>" --change-name <kebab-case> --output-dir "$WO
 
 Multi-spec parallel batch: add `--batch-name <kebab-case>` and `--with-coordination`. **Only** if parallel safety needs prior shared work: add `--with-preparation`.
 
-Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md` from `references/templates/`. Add `coordination.md` / `preparation.md` at batch root only when flags require. Save under `docs/plans/{YYYY-MM-DD}/...`. After generation, fill in place **without** removing template headings unless truly N/A (document reason). Run a **template-drift pass** before approval: sections present, placeholders removed or justified.
+Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md` from `references/templates/`. Add `coordination.md` / `preparation.md` at batch root only when flags require. Save under `docs/plans/{YYYY-MM-DD}/...`. After generation, fill in place **without** stripping section headings unless truly N/A (document inline); drop unused repeatable blocks (extra component or dependency stubs). Run a **template-drift pass** before approval: required fields covered, placeholders removed or justified.
    - **Pause →** List the **module names** (≤3) this spec set will touch; if more, where is my **split plan**?
    - **Pause →** For every shared file two specs might touch, where is the **named** resolution in `coordination.md` or why is `preparation.md` required instead?
    - **Pause →** Did I run `apltk create-specs` from the **skill** context so template paths resolve correctly?
@@ -68,15 +68,16 @@ Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `desig
 ### 3) Author content (fill templates)
 
 - **`spec.md`**: Concrete scope; BDD (`GIVEN` / `WHEN` / `THEN` / `AND` / `Requirements`); testable requirements; boundaries, auth, failure, idempotency/concurrency/integrity where relevant; doc references; `3-5` clarification questions or `None`.
-- **`tasks.md`**: `## **Task N: [Title]**` with Purpose, Requirements, Scope, Out of scope; atomic `- N [ ]` lines obeying the triple requirement above; split tasks that exceed three files / multiple behavior slices / undocumented decisions; integrate `test-case-strategy` for test IDs and drift checks for non-trivial logic.
-- **`contract.md`**: One record per material external dependency (source, surface, I/O, limits, security, failures); else `None` + short reason—**no** fabricated deps.
-- **`design.md`**: Delta vs baseline; modules, responsibilities, flow, state, risks; cross-ref requirement IDs; parallel batch: pointer to `coordination.md`, assumptions for safe concurrency, **no** duplicating batch rules; with `preparation.md`, assume prep **done**—**do not** duplicate prep tasks.
+- **`tasks.md`**: `## **Task N: [Title]**` with Purpose, Requirements, Scope, Out of scope; atomic `- N [ ]` triple (path · change · verify). **Derive sequencing and decomposition from** **`spec.md` + `design.md` + `contract.md`**; **`tasks.md` stays the only enumerated runnable checklist**. Optionally cite **`INT-###` / `EXT-###`** on rows an anchor constrains—and **keep design/contract coarser**, never a second copy of checklist lines. Integrate `test-case-strategy` for drift checks where needed.
+- **`contract.md`**: Cite-backed **external facts / limits / failure semantics / security**, plus **`EXT-###`** integration **anchors** (typically fewer rows than **`tasks.md` items)—**constraints and anti-hallucination context**, **not** a parallel implementation runbook (`TBD` instead of guesses; **`Dependencies` → None** when genuinely no externals).
+- **`design.md`**: **High-level architectural context for composing `tasks.md`**—baseline/target shape, boundaries, modules, **`INT-###`** coarse coupling/order hints (`task` granularity lives only in **`tasks.md`**). No file-level chores; batches defer ownership grids to **`coordination.md`**; **`preparation.md`** assumed done—don't replay prep execution here.
 - **`coordination.md`** (batch root, parallel only): **Business Goals** (outcome, member specs, parallel readiness, exclusions, blockers → `preparation.md` or list); **Design Principles** (baseline, shared invariants, compat, cleanup—high level); **Spec Boundaries** → **Ownership Map** (allowed/forbidden touchpoints per spec) and **Collisions & Integration** (shared-file rules, freeze owners, merge order, checkpoints, re-coordination trigger)—**every** collision candidate **MUST** have a named resolution.
 - **`preparation.md`** (batch root, only if required): Preparation Goal (why, no core business logic, dependents, start condition); **Task P[N]** like `tasks.md` (atomic triple items); **Validation**; **Handoff** (assumptions, must-not-change, if prep changes later). Strip duplicate prep from member specs.
 - **`checklist.md`**: `- [ ]` adapted to scope; map behaviors to requirement/test IDs via `test-case-strategy`; behavior lines `[CL-xx]: … — R?.? → [Test IDs] — Result: …`; property-based logic **required** unless `N/A` + reason; honest execution/completion records—**no** checking unused examples or unchosen options.
    - **Pause →** Pick one **random** `tasks.md` checkbox: does it still fail the triple rule (target, change, verify)—if yes, rewrite now?
    - **Pause →** Does every **R** requirement ID I care about appear in `tasks.md` or `checklist.md` with a test or explicit `N/A`?
-   - **Pause →** For parallel batches, does `design.md` **avoid** duplicating what `coordination.md` already owns?
+   - **Pause →** Do **`design.md` / `contract.md`** stay **coarser than `tasks.md`** (no mirrored checkbox choreography / file paths)—yet still constrain ordering and forbidden hallucinations?
+   - **Pause →** For parallel batches, does `design.md` **avoid** duplicating batch ownership grids already locked in **`coordination.md`**?
 
 ### 4) Clarifications and approval
 
@@ -93,8 +94,8 @@ When implementation exists: mark `tasks.md`; sync `checklist.md` outcomes/`N/A`;
 ## Sample hints
 
 - **`tasks.md` line — bad**: `- [ ] Add tests` → **reject** (no path, change, verifier).
-- **`tasks.md` line — ok**:
-  `- [ ] src/auth/scope.rs — add deny-by-default matcher for unknown scopes · Verify: cargo test scope::defaults`
+- **`tasks.md` line — ok (with ledger wiring)**:
+  `- [ ] 2 src/api/handlers/oauth.rs — implement handler path for POST /oauth/token satisfying INT-003, INT-004 · EXT-001 client config loaded from env per contract · Verify: cargo test oauth::handlers::token_exchange`
 - **Batch scaffold** (three member specs): `WORKSPACE_ROOT=... apltk create-specs "OAuth batch" --change-name oauth-api --batch-name oauth-may-batch --with-coordination --output-dir "$WORKSPACE_ROOT/docs/plans"` (then repeat or use generator rules for additional `change-name` dirs as your tooling permits).
 - **`checklist.md` behavior row sketch**: `[CL-01]: invalid token rejected — R2.1 → TU-Scope-01,TU-Scope-02 — Result: pending`
 - **Split-trigger**: change touches `src/auth/*`, `src/cli/*`, `src/db/*`, `infra/terraform/*` (four modules) ⇒ **minimum two spec sets**, not one.

package/generate-spec/agents/openai.yaml

@@ -1,4 +1,6 @@
 interface:
   display_name: "generate-spec"
   short_description: "Generate shared feature spec, task, and checklist docs before coding"
-  default_prompt: "Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, a minimal non-business preparation.md; treat this skill's current references/templates/*.md files as the binding format even when older project specs use different layouts, ensure member specs assume preparation is already complete and do not duplicate its tasks, surface shared-file or shared-contract collision risks during planning, settle ownership and additive-only rules in coordination.md before implementation starts, fill BDD requirements, use $test-case-strategy for risk-driven test planning and unit drift checks, make tasks.md an atomic implementation queue with concrete outputs and verification hooks, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, process clarification updates, and wait for explicit approval before implementation."
+  default_prompt: >-
+    Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, minimal non-business preparation.md; treat references/templates/*.md as binding format; member specs assume preparation finished—do not duplicate preparation tasks; surface collisions early and resolve ownership via coordination.md; fill BDD in spec.md; integrate $test-case-strategy into tasks/checklists.
+    **Critical layering:** design.md + contract.md are higher-level guiding context only (architecture + cite-backed external truth; coarse INT-### / EXT-### anchors). tasks.md MUST be the ONLY enumerated runnable queue with path-level edits and verification hooks—derive tasks FROM spec + design + contract WITHOUT mirroring checklist rows into design/contract; optionally cite INT/EXT on task lines for traceability—never duplicate task choreography inside design.md or contract.md.

package/generate-spec/references/templates/contract.md

@@ -4,62 +4,69 @@
 - Feature: [Feature Name]
 - Change Name: [change_name]
 
-## Purpose
-[Describe why external dependency contracts matter for this change.]
-
-## Usage Rule
-- Write one dependency record per external library, framework, SDK, API, CLI, platform service, or hosted system that materially constrains implementation.
-- If no external dependency materially affects the change, write `None` under `## Dependency Records` and briefly explain why this document is not needed for the current scope.
-- Every claim in this file must be backed by the official documentation or the verified upstream source actually used during planning.
-
-## Dependency Records
-
-### Dependency 1: [Dependency Name]
-- Type: [library / framework / SDK / API / CLI / hosted service / platform]
-- Version / Scope: [exact version, major line, API version, or `Not fixed`]
-- Official Source: [link]
-- Why It Matters: [what this dependency is responsible for in the change]
-- Invocation Surface:
-  - Entry points: [package import / endpoint / command / webhook / queue topic]
-  - Call pattern: [sync / async / streaming / webhook / batch / polling]
-  - Required inputs: [auth, headers, env vars, config keys, payload fields]
-  - Expected outputs: [return shape, side effects, emitted events, persisted state]
-- Constraints:
-  - Supported behavior: [documented supported modes relevant to this change]
-  - Limits: [rate limits, payload limits, timeout, ordering, pagination, size, quota]
-  - Compatibility: [runtime / platform / version / region / account constraints]
-  - Security / access: [auth model, scopes, permissions, secret handling]
-- Failure Contract:
-  - Error modes: [documented errors, degraded states, retries, eventual consistency]
-  - Caller obligations: [retry rules, idempotency keys, backoff, validation, cleanup]
-  - Forbidden assumptions: [what the implementation must not assume]
-- Verification Plan:
-  - Spec mapping: [R?.?]
-  - Design mapping: [section in `design.md`]
-  - Planned coverage: [UT / PBT / IT / E2E / mock scenario IDs]
-  - Evidence notes: [specific doc section or source snippet summary]
-
-### Dependency 2: [Dependency Name]
-- Type: [library / framework / SDK / API / CLI / hosted service / platform]
-- Version / Scope: [exact version, major line, API version, or `Not fixed`]
-- Official Source: [link]
-- Why It Matters: [what this dependency is responsible for in the change]
-- Invocation Surface:
-  - Entry points: [package import / endpoint / command / webhook / queue topic]
-  - Call pattern: [sync / async / streaming / webhook / batch / polling]
-  - Required inputs: [auth, headers, env vars, config keys, payload fields]
-  - Expected outputs: [return shape, side effects, emitted events, persisted state]
-- Constraints:
-  - Supported behavior: [documented supported modes relevant to this change]
-  - Limits: [rate limits, payload limits, timeout, ordering, pagination, size, quota]
-  - Compatibility: [runtime / platform / version / region / account constraints]
-  - Security / access: [auth model, scopes, permissions, secret handling]
-- Failure Contract:
-  - Error modes: [documented errors, degraded states, retries, eventual consistency]
-  - Caller obligations: [retry rules, idempotency keys, backoff, validation, cleanup]
-  - Forbidden assumptions: [what the implementation must not assume]
-- Verification Plan:
-  - Spec mapping: [R?.?]
-  - Design mapping: [section in `design.md`]
-  - Planned coverage: [UT / PBT / IT / E2E / mock scenario IDs]
-  - Evidence notes: [specific doc section or source snippet summary]
+> **Purpose:** **High-level external-dependency context for `tasks.md`**: cite-backed facts, limits, failures, security—so integrations are not hallucinated. **Not** a runnable checklist; **`tasks.md` executes** wiring (files, calls, mocks, tests). Internal coupling intent stays in **`design.md`** (`INT-###`).
+>
+> **Anti-duplication:** Do not enumerate per-file edits, checkbox steps, or copy task ordering. **`EXT-###`** are **constraints / anchors** that task rows may cite.
+>
+> **Undocumented gaps:** **`TBD`** + clarification—never invent payloads, endpoints, or semantics.
+
+## Scope
+
+- **External deps in this doc:** [`0` \| ≥1]
+- **`0`:** under **Dependencies** write **`None.`** plus one line (what “no deps” excludes for coders).
+
+## Dependencies
+
+If **external dep count is 0:** keep **only**:
+
+**None.** [one line — e.g. no network SDKs/APIs beyond stdlib/process]
+
+**Delete everything** from “### \[Dependency name]” downward.
+
+If **≥1 dependency:** delete the `None.` block above; copy one `### [Dependency name]` section per dependency.
+
+### [Dependency name]
+
+#### Evidence
+
+| Primary docs URL(s)             | Sections / anchors used |
+| ------------------------------- | ----------------------- |
+| […]                             | […]                     |
+
+**Version revision assumed:** [pinned \| line \| `Not fixed` — how pinning lands in **`tasks.md`**]
+
+#### Facts we rely on (must be citeable)
+
+| Fact / capability needed | Doc location |
+| ------------------------ | ------------ |
+| […]                      | […]          |
+
+#### Limits & failures (coding obligations)
+
+| Category                         | Doc fact | Meaning while executing **`tasks.md`** |
+| -------- | --------- | ---------------------------------------- |
+| Quotas · size · timeout · paging | […] | [backoff / batching — policy level] |
+| Errors / degraded modes | […] | [map-to-app policy—not file paths unless standard] |
+
+#### Security & secrets (policy level)
+
+| Concern           | Constraint |
+| ----------------- | ---------- |
+| Auth / scopes    | […]        |
+| Secret keys (names)| […]       |
+
+#### Integration anchors (`EXT-###`)
+
+**Grain:** Boundary truth + obligations—**fewer anchors than typical task rows**. Multiple checkboxes often satisfy one anchor.
+
+| ID        | What we integrate at this boundary *(doc-named surface)* | Non‑negotiables (handling, retries, idempotency *per doc*) | Forbidden assumptions |
+| --------- | ---------------------------------------------------------- | ----------------------------------------------------------- | --------------------- |
+| `EXT-001` | [endpoint · SDK symbol · topic — **verbatim-ish** from doc] | […]                                                        | […]                   |
+
+**Doc-level ordering constraint (if any):** [e.g. token before resource call—or `None`]
+
+#### Trace hooks (no task parroting)
+
+- Spec IDs covered: [R?.?]
+- Related **`design.md`** module keys / `INT-###`: [optional]
+- **Unknown / `TBD`:** [list or `None`]

package/generate-spec/references/templates/design.md

@@ -4,65 +4,80 @@
 - Feature: [Feature Name]
 - Change Name: [change_name]
 
-## Design Goal
-[Describe the architecture/design objective for this spec change.]
-
-## Change Summary
-- Requested change: [one sentence]
-- Existing baseline: [current architecture or behavior relevant to the change]
-- Proposed design delta: [what will change structurally]
-
-## Scope Mapping
-- Spec requirements covered: [R?.?]
-- Affected modules: [module/file/service list]
-- External contracts involved: [dependency names from `contract.md`, or `None`]
-- Coordination reference: [`../coordination.md` or `None`]
-- Parallel implementation assumption: [why this spec can be implemented concurrently, or `None` for single-spec work]
-
-## Current Architecture
-[Describe the relevant current components, data flow, control flow, and boundaries.]
-
-## Proposed Architecture
-[Describe the new or updated structure, ownership boundaries, and interaction flow.]
-
-## Component Changes
-
-### Component 1: [Name]
-- Responsibility: [what this component owns after the change]
-- Inputs: [events, params, payloads, config]
-- Outputs: [return values, writes, emitted events, calls]
-- Dependencies: [internal modules and external contracts]
-- Invariants: [business or technical rules that must hold]
-
-### Component 2: [Name]
-- Responsibility: [what this component owns after the change]
-- Inputs: [events, params, payloads, config]
-- Outputs: [return values, writes, emitted events, calls]
-- Dependencies: [internal modules and external contracts]
-- Invariants: [business or technical rules that must hold]
-
-## Sequence / Control Flow
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-## Data / State Impact
-- Created or updated data: [schemas, fields, caches, files, queues, config]
-- Consistency rules: [ordering, transactionality, idempotency, deduplication]
-- Migration / rollout needs: [if none, write `None`]
-
-## Risk and Tradeoffs
-- Key risks: [failure, concurrency, authorization, partial-write, dependency risk]
-- Rejected alternatives: [alternative + why it was not chosen]
-- Operational constraints: [performance, quota, observability, deployment coupling]
-- Cross-spec collision notes: [known shared-file/shared-contract collision avoided by ownership rules, or `None`]
-
-## Validation Plan
-- Tests: [UT / PBT / IT / E2E / adversarial]
-- Contract checks: [how `contract.md` constraints will be validated]
-- Rollback / fallback: [how to contain or reverse impact]
-
-## Open Questions
-[Write `None` if the design is settled.]
-- [Question 1]
-- [Question 2]
+> **Purpose:** **High-level architectural context for `tasks.md`**—structure, coupling, sequencing intent—not a second implementation list. Requirement intent stays in `spec.md`; **documented vendor truth** stays in **`contract.md`**. **`tasks.md` owns** every runnable step (paths, edits, verifies).
+>
+> **Do not duplicate `tasks.md`:** no checkbox-style chores, no per-file implementation lines, no verifiers—the executable queue exists only under **`tasks.md`**. Optional **`INT-###`** labels are **coarse anchors** that task rows cite for traceability.
+>
+> **Audience:** Humans/agents authoring **`tasks.md`**, and implementers needing **mental model before** ticking task boxes—not a standalone execution script.
+
+## Traceability
+
+|                             |                                                                              |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| Requirement IDs             | [R?.?]                                                                      |
+| In-scope modules (≤3)       | [paths / services]                                                           |
+| External systems touched    | [names only—full truth in **`contract.md`**, or `None`]                      |
+| Batch coordination          | [`../coordination.md` or `None`]                                            |
+
+## Target vs baseline
+
+|                       | Baseline (today) | Target (after this change) |
+| --------------------- | ---------------- | --------------------------- |
+| Structure / ownership | […]              | […]                         |
+
+## Boundaries
+
+- Entry surface(s): [HTTP · CLI · job · subscriber · FFI — whichever applies]
+- Trust boundary crossed: [`None` / brief]
+- Outside → inside (one line): `[Actor]` → `[our entry]` → `[…]` (vendor touchpoints **`contract.md` only`)
+
+## Modules (nouns only)
+
+| Module key | Responsibility (one sentence) | Owned artifacts (types, tables, queues) |
+| ---------- | ---------------------------- | ---------------------------------------- |
+| `[key]`    | […]                          | [none / list]                             |
+
+---
+
+## Interaction anchors (`INT-###`)
+
+**Grain:** **Above `tasks.md`**. One anchor ≈ a **meaningful handshake** between module keys—not one checkbox. Several task lines may realize a single `INT-###`.
+
+| ID        | Intent (when this coupling matters) | Caller → Callee | Coupling kind (route pattern · RPC · event · sync call—**name/pattern**, not file path) | Information / state crossing (summary) | Failure / propagation expectation (summary) |
+| --------- | ------------------------------------ | --------------- | ---------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------- |
+| `INT-001` | […]                                  | `A` → `B`       | […]                                                                                      | […]                                    | […]                                         |
+
+**Ordering / concurrency (design-level):** [parallelism rules, critical sections, or `None`—still no file-level steps]
+
+## Requirement linkage (coarse ordering)
+
+Maps **which `R` clusters** depend on **which anchor order**. **`tasks.md` decomposes** into concrete steps.
+
+### [Scenario / `R?.?` cluster]
+
+- Anchor order hint: `INT-…` → `INT-…` → …
+- Narrative glue (≤3 bullets): [why this order; what must not reorder]
+
+[`None` if one anchor suffices—say so]
+
+## Data & persistence (design-level)
+
+| Resource                      | Typical readers/writers (module keys) | Consistency expectation (ordering, idempotency) |
+| ----------------------------- | ------------------------------------- | ------------------------------------------------ |
+| [store · schema · queue …] | […]                                   | […]                                             |
+
+## Invariants (system-level)
+
+| Invariant | What breaks it architecturally           | Symptoms if violated |
+| --------- | ---------------------------------------- | -------------------- |
+| […]       | [coupling mistake / wrong owner / …]     | […]                  |
+
+## Tradeoffs inherited by implementation
+
+| Decision | Rejected alternative | Locks in (for **`tasks.md`**) |
+| -------- | -------------------- | ---------------------------- |
+| […]      | […]                  | […]                           |
+
+## Batch-only
+
+[`None` \| single line: responsibilities **not** in this spec → see **`coordination.md`**]

package/generate-spec/references/templates/tasks.md

@@ -30,6 +30,8 @@ Out of scope: [files/modules/behaviors this task must not change]
   - Verify: [focused command/check/manual inspection; drift check ref if applicable]
 
 ## Notes
+- **Layering:** **`design.md`** / **`contract.md`** are **guiding context** only (architecture + external truth). **`tasks.md` is the sole numbered, file-level execution queue**—do not expect design/contract to re-list its checkboxes.
+- When drafting, derive task order and scope from **`spec.md`** + **`design.md`** + **`contract.md`**; optionally cite **`INT-###` / `EXT-###`** on rows those anchors constrain.
 - Task order reflects implementation sequence.
 - Every task must map back to `spec.md` requirement IDs.
 - Treat `tasks.md` as an implementation queue, not a summary.

package/implement-specs/SKILL.md

@@ -1,23 +1,23 @@
 ---
 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`** (high-level architecture + coarse `INT-###` anchors—**guidance for structuring work**), **`contract.md`** (cite-backed external facts/constraints + `EXT-###` anchors), **`checklist.md`**, then treat **`tasks.md`** as **the authoritative ordered runnable checklist**. **MUST NOT** start coding until that read pass is complete for the current in-scope directory.
+- **MUST** execute **every** **`tasks.md`** line in listed order—the **executable source of truth** for what to ship. **`design.md` / `contract.md`** **inform** decomposition and forbid contradictions (**`INT-###` / `EXT-###`** when present are **constraints/anchors referenced from tasks**, not a second queue). **MUST NOT** silently wire alternate module flows or vendor surfaces that conflict with approved **`design`** / **`contract`**; resolve conflicts via **`generate-spec`** / explicit approved plan edits first.
+- **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 +30,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; **`tasks.md`** defines runnable order and file targets; **`spec`/`design`/`contract`** constrain meaning and forbid contradictory wiring—implement and test until obligations are met—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 +38,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 +48,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 +71,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,9 +1,9 @@
 ---
 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; **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).
+  Coordinator-only workflow for multispec batches: ingest `coordination.md`/`preparation.md`, run prerequisite work yourself, derive topological phases, launch **`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…
+  Ledger sample: `oauth-scope | phase=1 | merged | npm test ✅`.
 ---
 
 # Implement Specs with Subagents (Multi-Phase)
@@ -22,7 +22,6 @@ description: >-
 - **MUST** complete, verify, and **finalize** documented shared preparation on the integration branch **through `commit-and-push`** before any implementation subagent starts when `preparation.md` exists or specs mandate pre-work; the coordinating agent **MUST NOT** delegate that preparation. Subagents **MUST NOT** start until this branch is clean at the preparation commit (or there is no required preparation).
 - **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.
 - **`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.
@@ -56,8 +55,8 @@ description: >-
    - **Pause →** Is there **exactly one** spec directory per queued subagent—never two in one prompt?
    - **Pause →** What will I **repeat** in every subagent envelope so they cannot “improvise” the wrong skill or wrong path?
 
-5. **Run phase *k*** — Start ≤4 subagents sequentially with task-local payloads (see Non-negotiables). Monitor ledger; pause new launches on shared blockers; on conflicting edits to shared files, resolve ownership using `coordination.md` before more launches; if one spec fails and others depend on it, **MUST NOT** start those dependents until resolved; batch-wide planning failure ⇒ stop all scheduling.
-   - **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?
+5. **Run phase *k*** — Launch subagents for each spec in the phase with task-local payloads (see Non-negotiables). Monitor ledger; pause new launches on shared blockers; on conflicting edits to shared files, resolve ownership using `coordination.md` before more launches; if one spec fails and others depend on it, **MUST NOT** start those dependents until resolved; batch-wide planning failure ⇒ stop all scheduling.
+   - **Pause →** Does every active subagent have a **distinct** spec directory assignment—no duplicate or overlapping paths?
    - **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*. **“Done”** here **requires** full `tasks.md` completion **and** full `checklist.md` wrap-up / acceptance per Non-negotiables—not merely a subagent “looks finished” report.
@@ -76,13 +75,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 (independent specs)** — The batch has multiple member directories and `coordination.md` allows parallel implementation with **no** in-batch prerequisites. Treat them as **one phase**: assign **exactly one** spec per subagent, launch one **`implement-specs-with-worktree`** worker per spec, 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 **every** member 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; (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-subagents/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implement Specs with Subagents"
   short_description: "Coordinate parallel spec worktree implementations"
-  default_prompt: "Use $implement-specs-with-subagents to read coordination.md and any preparation.md first, complete and commit explicitly documented prerequisite preparation on the working branch before delegation, analyse spec dependencies to build a multi-phase plan, for each phase assign each approved docs/plans spec directory to one independent subagent that uses $implement-specs-with-worktree, launch at most four implementation subagents at once with staggered starts, after each phase use $merge-changes-from-local-branches to merge completed spec branches back into the working branch before launching the next phase, honor any requested model when supported, and track each branch, commit, test result, and blocker."
+  default_prompt: "Use $implement-specs-with-subagents to read coordination.md and any preparation.md first, complete and commit explicitly documented prerequisite preparation on the working branch before delegation, analyse spec dependencies to build a multi-phase plan, for each phase assign each approved docs/plans spec directory to one independent subagent that uses $implement-specs-with-worktree, after each phase use $merge-changes-from-local-branches to merge completed spec branches back into the working branch before launching the next phase, honor any requested model when supported, and track each branch, commit, test result, and blocker."

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.6",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",