@laitszkin/apollo-toolkit 3.9.5 → 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,11 +46,6 @@ 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]
-
-### Added
-- (None yet)
-
 ## [v3.9.5] - 2026-05-08
 
 ### Changed

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

@@ -15,7 +15,8 @@ description: >-
 
 ## Non-negotiables
 
-- **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** 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.
@@ -29,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; 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).
+- **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.
 

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.
@@ -78,9 +77,9 @@ description: >-
 
 ## Sample hints (subagent scheduling)
 
-- **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.
+- **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, 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.
+- **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.
 

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/package.json

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