@laitszkin/apollo-toolkit 3.6.2 → 3.6.4

package/CHANGELOG.md

@@ -7,6 +7,16 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.6.4] - 2026-04-29
+
+### Changed
+- Simplify `generate-spec` tasks.md template with compact per-item format (inline file/change/outcome + Verify field), and strengthen SKILL.md §4 to require exact file path, modification, and verification step for every task item
+
+## [v3.6.3] - 2026-04-28
+
+### Changed
+- Extend `implement-specs-with-subagents` with multi-phase execution: analyse spec dependencies from `coordination.md`, build phased delegation plans via topological sort, execute phases sequentially with parallel subagents per phase, and merge completed spec branches back via `merge-changes-from-local-branches` between phases.
+
 ## [v3.6.2] - 2026-04-28
 
 ### Changed

package/generate-spec/SKILL.md

@@ -86,16 +86,19 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 ### 4) Fill `tasks.md`
 
-- Use `## **Task N: [Task Title]**` for each main task.
-- Describe each task's purpose and the related requirement IDs.
+- Use `## **Task N: [Task Title]**` for each main task with `Purpose`, `Requirements`, `Scope`, and `Out of scope` guardrails.
 - Use `- N. [ ]` for atomic task items; use `- N.x [ ]` only when a task must be split into additional atomic subtasks.
 - Treat `tasks.md` as an implementation queue, not a high-level summary.
-- Make each checkbox atomic: one verb, one responsibility, one concrete output, and one verification hook.
-- For every task, include allowed scope, out-of-scope guardrails, requirement/design/contract inputs, expected output, completion condition, and verification hook.
+- **Every checkbox must specify three things: (a) the exact file path or function, (b) the specific modification to make, and (c) a concrete verification step.** These three are mandatory — no item may omit any of them.
+- Per-item format (compact template):
+  - `[file/function]` — `[specific modification; expected outcome]`
+  - `- Verify:` — focused command, test reference, or manual inspection
+- Do not add extra sub-fields beyond what the template provides; put all change detail in the inline description.
+- Make each checkbox atomic: one verb, one file/function, one change outcome, and one verification hook.
 - If one task needs more than three files, more than one behavior slice, or an implementation decision not already captured in `design.md` or `contract.md`, split it before approval.
 - Use `$test-case-strategy` to define test IDs and unit drift checks for non-trivial local logic before implementation starts.
 - Include explicit tasks for testing, mocks/fakes, regression coverage, and adversarial or edge-case hardening when relevant.
-- Do not write vague tasks such as `Implement integration`, `Add tests`, or `Update docs`; replace them with task-local outputs, test IDs, and verification commands.
+- Vague items such as `Implement integration`, `Add tests`, or `Update docs` are forbidden; replace them with specific file paths, concrete changes, and executable verification commands.
 
 ### 5) Fill `contract.md`
 

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

@@ -7,59 +7,36 @@
 
 Purpose: [one sentence describing the narrow outcome]
 Requirements: [R1.x]
-Allowed scope: [files/modules/functions this task may touch]
+Scope: [files/modules/functions this task may touch]
 Out of scope: [files/modules/behaviors this task must not change]
 
-- 1. [ ] [Main task item]
-  - Input: [requirement/design/contract evidence]
-  - Touches: [specific file/function/module]
-  - Output: [specific code/doc/test artifact]
-  - Done when: [observable completion condition]
-  - Verify with: [focused command/check/manual inspection]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Do not: [explicit implementation-drift guardrail]
+- 1. [ ] **[file/function]** — **[specific modification to make; expected outcome]**
+  - Verify: [focused command/check/manual inspection; drift check ref if applicable]
+
+- 2. [ ] **[file/function]** — **[specific modification to make; expected outcome]**
+  - Verify: [focused command/check/manual inspection; drift check ref if applicable]
 
 ## **Task 2: [Task Title]**
 
 Purpose: [one sentence describing the narrow outcome]
 Requirements: [R2.x]
-Allowed scope: [files/modules/functions this task may touch]
+Scope: [files/modules/functions this task may touch]
 Out of scope: [files/modules/behaviors this task must not change]
 
-- 2. [ ] [Main task item]
-  - Input: [requirement/design/contract evidence]
-  - Touches: [specific file/function/module]
-  - Output: [specific code/doc/test artifact]
-  - Done when: [observable completion condition]
-  - Verify with: [focused command/check/manual inspection]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Do not: [explicit implementation-drift guardrail]
-
-## **Task 3: [Task Title]**
-
-Purpose: [one sentence describing the narrow outcome]
-Requirements: [R3.x]
-Allowed scope: [files/modules/functions this task may touch]
-Out of scope: [files/modules/behaviors this task must not change]
+- 1. [ ] **[file/function]** — **[specific modification to make; expected outcome]**
+  - Verify: [focused command/check/manual inspection; drift check ref if applicable]
 
-- 3. [ ] [Main task item]
-  - Input: [requirement/design/contract evidence]
-  - Touches: [specific file/function/module]
-  - Output: [specific code/doc/test artifact]
-  - Done when: [observable completion condition]
-  - Verify with: [focused command/check/manual inspection]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Do not: [explicit implementation-drift guardrail]
+- 2. [ ] **[file/function]** — **[specific modification to make; expected outcome]**
+  - Verify: [focused command/check/manual inspection; drift check ref if applicable]
 
 ## Notes
-- Task order should reflect actual implementation sequence.
-- Every main task must map back to `spec.md` requirement IDs.
-- Treat `tasks.md` as an implementation queue, not a high-level work summary.
-- Each checkbox must be atomic: one verb, one responsibility, one concrete output, and one verification hook.
-- Split any task that needs more than three files, more than one behavior slice, or a design decision not already captured in `design.md` or `contract.md`.
-- Use `$test-case-strategy` to define test IDs and unit drift checks before implementation.
-- Include explicit tasks for required test coverage (unit, regression, property-based, integration/E2E as applicable), mock scenario setup, and adversarial/edge-case hardening.
-- Do not write vague tasks such as `Implement integration`, `Add tests`, or `Update docs`; replace them with task-local outputs, test IDs, and verification commands.
-- For batch specs, tasks must never include "wait for Spec X to land first" as a prerequisite; if such a dependency appears, re-slice the plan or move the coordination rule into `coordination.md`.
-- After execution, the agent must update each checkbox (`[x]` for done, `[ ]` for not done).
-- Remove all placeholder guidance text in square brackets after filling.
+- 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.
+- Each item must include the exact file path (or function/module), the specific change, and a concrete verification step — vague items are forbidden.
+- Each checkbox is atomic: one verb, one file/function, one change outcome, one verification hook.
+- Use `N.x [ ]` for sub-items only when a parent item needs further breakdown.
+- Split tasks that exceed 3 files or span multiple behavior slices.
+- Use `$test-case-strategy` for drift checks before implementation.
+- After execution, update `[x]` for done, `[ ]` for pending.
+- Remove all `[...]` placeholder text after filling.

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

@@ -3,33 +3,38 @@ name: implement-specs-with-subagents
 description: >-
   Coordinate parallel implementation of multiple approved spec sets by assigning
   each `docs/plans/.../<change_name>/` spec directory to a separate subagent that
-  uses `implement-specs-with-worktree`. Use when a user asks to implement a
-  multi-spec batch with subagents, parallel agents, delegated agents, or isolated
-  workers while completing any explicitly documented shared prerequisite work
-  before delegation, keeping at most four implementation subagents active at
-  once, staggering starts to avoid rate-limit bursts, preserving independent
-  subagent contexts, and using the user's requested model when specified.
+  uses `implement-specs-with-worktree`. Supports multi-phase execution for
+  interdependent specs: analyse dependencies, implement base specs first, merge
+  back via `merge-changes-from-local-branches`, then implement dependent specs,
+  and finally submit with commit, push, and patch version bump. Use when a user
+  asks to implement a multi-spec batch with subagents, parallel agents, delegated
+  agents, or isolated workers while completing any explicitly documented shared
+  prerequisite work before delegation, keeping at most four implementation
+  subagents active at once, staggering starts to avoid rate-limit bursts,
+  preserving independent subagent contexts, and using the user's requested model
+  when specified.
 ---
 
-# Implement Specs with Subagents
+# Implement Specs with Subagents (Multi-Phase)
 
 ## Dependencies
 
 - Required: `implement-specs-with-worktree` for each delegated spec implementation.
+- Required: `merge-changes-from-local-branches` for merging worktree branches back between phases.
 - Conditional: `generate-spec` if the batch needs clarification before implementation; `review-change-set` if the user asks for an integration review after subagents finish.
 - Optional: none.
 - Fallback: If the environment cannot start independent subagents, report that limitation and fall back only if the user explicitly approves serial `implement-specs-with-worktree` execution.
 
 ## Standards
 
-- Evidence: Read the batch-level `coordination.md` and `preparation.md` when present, enumerate the exact spec directories to implement, verify each delegated spec has the required planning files, and identify any explicit prerequisite notes before starting subagents.
-- Execution: Complete and commit explicitly documented prerequisite preparation on the working branch before delegation, then assign exactly one implementation subagent per spec directory, keep no more than four implementation subagents active at the same time, start subagents one at a time rather than in a burst, give each subagent an independent task-local context, and instruct every subagent to use `implement-specs-with-worktree` for its assigned spec.
+- Evidence: Read the batch-level `coordination.md` and `preparation.md` when present, enumerate the exact spec directories to implement, verify each delegated spec has the required planning files, and identify any explicit prerequisite or dependency notes before starting subagents.
+- Execution: Complete and commit explicitly documented prerequisite preparation on the working branch before delegation. Analyse spec dependencies from `coordination.md` and spec docs to build a multi-phase plan. For each phase, assign exactly one implementation subagent per spec directory, keep no more than four implementation subagents active at the same time, start subagents one at a time rather than in a burst, give each subagent an independent task-local context, and instruct every subagent to use `implement-specs-with-worktree` for its assigned spec. After each phase completes, use `merge-changes-from-local-branches` to merge all phase branches back before launching the next phase.
 - Quality: Preserve spec ownership boundaries, avoid duplicate delegation for the same spec, ensure subagents branch from a baseline that includes prerequisite commits, track branch/worktree/commit/test outcomes for every subagent, and pause new launches when a shared blocker, collision, or rate-limit pressure appears.
-- Output: Return a concise implementation ledger covering each spec, its subagent result, worktree branch, commit or blocker, verification run, and any integration follow-up needed.
+- Output: Return a concise implementation ledger covering each spec, its subagent result, worktree branch, commit or blocker, verification run, and the merge outcome.
 
 ## Goal
 
-Coordinate a multi-spec implementation batch safely by delegating each approved spec set to an isolated subagent-backed worktree implementation.
+Coordinate a multi-spec implementation batch safely by delegating each approved spec set to an isolated subagent-backed worktree implementation, handling interdependent specs through phased execution.
 
 ## Workflow
 
@@ -61,15 +66,37 @@ Coordinate a multi-spec implementation batch safely by delegating each approved
 - Do not start implementation subagents until the preparation commit exists and the working branch is clean.
 - If preparation cannot be completed or verified, stop and report the blocker instead of launching subagents.
 
-### 2) Build a delegation plan
+### 2) Analyse spec dependencies
 
-- Create one queue item per spec directory.
+- Read each in-scope spec's `spec.md` and `design.md` to identify explicit references to other in-scope specs.
+- Read `coordination.md` for any documented dependency ordering between specs (e.g. "spec A must be implemented before spec B").
+- For each spec dependency found, determine which specs are **base specs** (depended upon by others) and which are **dependent specs** (depend on base specs).
+- If a spec both depends on others and is depended upon, it belongs to its own middle phase.
+- If no dependencies exist between any specs, all specs can run in a single parallel phase.
+- Build a dependency graph and record it in the ledger:
+  - spec path
+  - phase number (starting from 1)
+  - depends-on (list of spec paths)
+  - depended-by (list of spec paths)
+- If the dependency graph contains a cycle, stop and report the cycle instead of proceeding.
+
+### 3) Build a multi-phase delegation plan
+
+- Group specs into ordered phases based on the dependency graph (topological sort order):
+  - **Phase 1**: Base specs with no in-batch dependencies (depended upon by others).
+  - **Phase N**: Specs whose dependencies are all satisfied by earlier phases.
+  - **Final Phase**: Specs with no dependents (leaf specs).
+- Each phase must have all its dependencies satisfied by earlier phases before it can start.
+- Within each phase, specs are independent and can run in parallel.
+- Create one queue item per spec directory per phase.
 - Assign one subagent to one spec only; never ask one subagent to implement multiple spec directories.
 - Keep a visible ledger with:
   - spec path
+  - phase number
+  - depends-on
   - intended branch/worktree name if known
   - assigned subagent
-  - status
+  - status (pending / in-progress / merged / blocked)
   - commit
   - tests
   - blockers
@@ -79,7 +106,11 @@ Coordinate a multi-spec implementation batch safely by delegating each approved
   - If the user does not specify a model, let subagents use the same model or default model policy as the coordinating agent.
   - If the environment does not expose model selection, state that the requested model cannot be enforced and continue only when the platform's default subagent model is acceptable.
 
-### 3) Launch subagents gradually
+### 4) Execute phases sequentially
+
+For each phase in order (Phase 1, Phase 2, ... Final Phase):
+
+#### 4.1) Launch subagents for this phase
 
 - Maintain a maximum of four active implementation subagents at any time.
 - Start subagents independently and one at a time.
@@ -87,7 +118,7 @@ Coordinate a multi-spec implementation batch safely by delegating each approved
 - If a start fails due to throttling, rate limits, capacity, or platform pressure, wait before retrying and do not start additional subagents during the cooldown.
 - Prefer steady scheduling over maximum burst parallelism; four is the ceiling, not a target that must always be filled.
 
-### 4) Give each subagent independent context
+#### 4.2) Give each subagent independent context
 
 For each subagent, provide only task-local instructions:
 
@@ -105,31 +136,40 @@ For each subagent, provide only task-local instructions:
 
 Do not pass the coordinating agent's full reasoning, unrelated sibling specs, or other subagents' private work unless a concrete coordination conflict requires it.
 
-### 5) Monitor and coordinate
+#### 4.3) Monitor and coordinate
 
 - While subagents run, track completions and blockers in the ledger.
 - When one subagent finishes, record its branch, worktree path, commit, verification results, and changed ownership boundaries.
-- Start the next queued spec only when the active count drops below four and no shared blocker is unresolved.
+- Start the next queued spec for this phase only when the active count drops below four and no shared blocker is unresolved.
 - If two subagents report overlapping edits to a shared file or contract, pause new launches, inspect the conflict against `coordination.md`, and resolve the ownership question before continuing.
-- If a subagent fails for a spec-local issue, keep other independent subagents running, but do not launch additional work that depends on the failed scope.
+- If a subagent fails for a spec-local issue, keep other independent subagents in the same phase running, but do not launch additional work that depends on the failed scope.
 - If failures indicate a batch-wide planning defect, stop scheduling new subagents and report the defect.
+- If all specs in the current phase are completed (or blocked), proceed to the merge step.
 
-### 6) Finish the batch report
+#### 4.4) Merge phase branches back
 
-- Do not merge branches, archive specs, push, or release unless the user explicitly requests that follow-up.
-- Summarize every spec outcome from the ledger.
-- Distinguish completed local commits from blocked or partial specs.
-- Report any integration review, merge order, or post-merge validation required by `coordination.md`.
+- After all subagents in the current phase complete, use `merge-changes-from-local-branches` to merge each completed spec's worktree branch back into the current working branch.
+- For each successful spec in the phase:
+  - Identify the branch name from the ledger.
+  - Merge the branch using `merge-changes-from-local-branches`.
+  - Resolve any merge conflicts that arise, prioritising correctness from the spec contracts.
+  - Verify the working branch is clean and tests still pass after merging.
+- Record the merge outcome in the ledger (success / conflicts / blockers).
+- If a merge fails and cannot be resolved, stop and report the merge blocker before proceeding to the next phase.
+- Once merged, the current working branch now includes all changes from this phase, making them available as a baseline for dependent specs in later phases.
 
 ## Working Rules
 
 - One spec directory maps to one implementation subagent.
 - Explicitly documented prerequisite preparation is completed, verified, and committed by the coordinating agent before any implementation subagent starts.
-- Maximum active implementation subagents: four.
+- Spec dependencies are analysed before delegation to determine phase ordering.
+- Phases execute sequentially; within a phase, specs are independent and run in parallel.
+- Maximum active implementation subagents per phase: four.
 - Subagents must be started gradually, not all at once.
 - Every subagent must have independent context scoped to its assigned spec.
 - Every implementation subagent must use `implement-specs-with-worktree`.
-- The coordinating agent owns scheduling, ledger tracking, and conflict escalation; implementation subagents own their assigned worktree commits.
+- After each phase, `merge-changes-from-local-branches` merges all completed spec branches back into the working branch.
+- The coordinating agent owns scheduling, ledger tracking, dependency analysis, inter-phase merging, and conflict escalation; implementation subagents own their assigned worktree commits.
 - The coordinating agent owns shared prerequisite commits; implementation subagents must not redo or overlap that preparation unless the preparation commit is missing or invalid.
 - User-specified subagent model choices should be honored when supported; otherwise inherit the coordinating agent's model/default model policy.
 - Do not use this skill for a single spec unless the user explicitly wants subagent delegation.
@@ -137,6 +177,8 @@ Do not pass the coordinating agent's full reasoning, unrelated sibling specs, or
 ## References
 
 - `implement-specs-with-worktree`: required per-spec worktree implementation workflow.
+- `merge-changes-from-local-branches`: required for merging worktree branches back between phases.
 - `generate-spec`: clarification and planning repair workflow when a batch is not ready for parallel implementation.
 - `preparation.md`: optional batch-level prerequisite plan that must be completed before parallel subagent work starts.
-- `review-change-set`: optional post-implementation review workflow before merge or submission.
+- `coordination.md`: batch-level coordination plan that may contain dependency ordering information.
+- `review-change-set`: optional post-implementation review workflow before final submission.

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, then 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, honor any requested model when supported, track each branch, commit, test result, and blocker, and report the batch ledger without merging or pushing unless explicitly requested."
+  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."

package/package.json

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