@laitszkin/apollo-toolkit 3.4.0 → 3.5.0

package/AGENTS.md

@@ -39,6 +39,8 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
 - Users can implement approved spec planning sets directly in the current checkout and commit them to the active branch.
+- Users can implement approved spec planning sets inside isolated git worktrees and keep the parent checkout clean.
+- Users can coordinate approved multi-spec implementation batches by assigning each spec directory to an independent worktree-backed subagent with bounded concurrency.
 - Users can summarize mistakes into separate multiple-choice and long-answer error books backed by structured reference files and rendered PDFs.
 - Users can build or review marginfi protocol integrations using official SDK, CLI, protocol, and The Arena documentation.
 - Users can create or maintain `AGENTS.md` so project constraints stay aligned with the repository.

package/CHANGELOG.md

@@ -7,6 +7,19 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.5.0] - 2026-04-28
+
+### Added
+- Add `implement-specs-with-subagents`, a coordinator skill that assigns each approved spec directory to an independent worktree-backed subagent with staggered starts and a maximum of four active implementation agents.
+
+### Changed
+- Tighten `generate-spec` so current templates remain the binding format even when older project specs use different layouts.
+
+## [v3.4.1] - 2026-04-28
+
+### Changed
+- Clarify `generate-spec` unit drift check template fields so agents fill in expected results or assertions instead of the ambiguous `oracle` shorthand.
+
 ## [v3.4.0] - 2026-04-28
 
 ### Added

package/README.md

@@ -23,6 +23,8 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - generate-spec
 - harden-app-security
 - implement-specs
+- implement-specs-with-subagents
+- implement-specs-with-worktree
 - improve-observability
 - iterative-code-performance
 - iterative-code-quality
@@ -196,6 +198,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.
 - `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/SKILL.md

@@ -15,8 +15,8 @@ description: Generate and maintain shared feature planning artifacts (`spec.md`,
 ## Standards
 
 - Evidence: Review the relevant code, configs, and authoritative docs before filling requirements or test plans; when external dependencies, libraries, frameworks, APIs, or platforms are involved, checking their official documentation is mandatory during spec creation.
-- Execution: Generate the planning files first, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, ensure every batch spec is independently completable and truly parallel-implementable without depending on another spec set to land first, surface shared-file or shared-contract collision risks during planning, resolve those coordination rules before implementation starts, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
-- Quality: Keep `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` synchronized, use `test-case-strategy` to map each planned test to a concrete risk or requirement, and tailor the templates so only applicable items remain active.
+- Execution: Generate the planning files from this skill's current templates first, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, ensure every batch spec is independently completable and truly parallel-implementable without depending on another spec set to land first, surface shared-file or shared-contract collision risks during planning, resolve those coordination rules before implementation starts, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
+- Quality: Keep `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` synchronized, use `test-case-strategy` to map each planned test to a concrete risk or requirement, preserve the actual headings and field structure from this skill's templates, and tailor the templates so only applicable items remain active.
 - Output: Store planning artifacts under `docs/plans/{YYYY-MM-DD}/{change_name}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` plus `coordination.md` for multi-spec parallel work whose member specs remain independently approvable, independently implementable, and ready for concurrent worktree execution with pre-agreed collision rules, and keep them concise, executable, and easy to update.
 
 ## Goal
@@ -36,6 +36,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Inspect existing `docs/plans/` directories before deciding whether to edit an existing plan set.
 - Reuse an existing plan set only when it clearly matches the same requested issue/change scope.
 - If the requested work is adjacent to, but not actually covered by, an existing plan set, create a new directory instead of overwriting the neighboring one.
+- Treat existing or archived project-local specs as scope evidence only, not as formatting authority.
+- Do not copy older spec layouts, condensed repo conventions, or neighboring plan structures when they differ from this skill's current templates.
 
 ### 2) Generate the planning files
 
@@ -63,6 +65,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
   - `references/templates/design.md`
 - Generate `references/templates/coordination.md` at the batch root when multiple spec sets are intentionally created for parallel implementation.
 - Save files under `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`.
+- After generation, fill the files in place without renaming, removing, or collapsing template headings unless a heading is explicitly template-only and not applicable to the real scope.
+- Before approval, compare the drafted files against the current template headings and required fields; fix any drift caused by following older project examples.
 
 ### 3) Fill `spec.md`
 
@@ -174,6 +178,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Use kebab-case for `change_name`; avoid spaces and special characters.
 - Path rule: `scripts/...` and `references/...` in this file always mean paths under the current skill folder, not the target project root.
 - Never overwrite a nearby issue's plan set just because the technical area overlaps; shared modules are not sufficient evidence that the scope is the same.
+- Template authority rule: the current `references/templates/*.md` files in this skill are the binding format for new or refreshed spec documents. Older `docs/plans/...` files may inform scope, terminology, and historical decisions, but they must not override the current template structure.
+- Before presenting specs for approval, run a template-drift pass: verify the expected template sections are present, remove stale placeholder examples, and ensure any removed section has a scope-based reason rather than being omitted because an older project spec omitted it.
 
 ## References
 

package/generate-spec/agents/openai.yaml

@@ -1,4 +1,4 @@
 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 a shared coordination.md, but ensure every spec in a batch remains independently approvable, independently implementable, and safe for true parallel execution without depending on another batch spec landing first; 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 a shared coordination.md, treating this skill's current references/templates/*.md files as the binding format even when older project specs use different layouts; ensure every batch spec remains independently approvable, independently implementable, and safe for true parallel execution without depending on another batch spec landing first; 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."

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

@@ -31,7 +31,7 @@
   - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
   - External dependency strategy: [none / mocked service states / near-real dependency]
   - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit + oracle, or N/A with reason]
+  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
   - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
   - Notes (optional): [risk, limitation, observation]
 
@@ -43,7 +43,7 @@
   - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
   - External dependency strategy: [none / mocked service states / near-real dependency]
   - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit + oracle, or N/A with reason]
+  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
   - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
   - Notes (optional): [risk, limitation, observation]
 
@@ -55,7 +55,7 @@
   - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
   - External dependency strategy: [none / mocked service states / near-real dependency]
   - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit + oracle, or N/A with reason]
+  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
   - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
   - Notes (optional): [risk, limitation, observation]
 

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

@@ -16,7 +16,7 @@ Out of scope: [files/modules/behaviors this task must not change]
   - 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 + oracle, or N/A with reason]
+  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
   - Do not: [explicit implementation-drift guardrail]
 
 ## **Task 2: [Task Title]**
@@ -32,7 +32,7 @@ Out of scope: [files/modules/behaviors this task must not change]
   - 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 + oracle, or N/A with reason]
+  - 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]**
@@ -48,7 +48,7 @@ Out of scope: [files/modules/behaviors this task must not change]
   - 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 + oracle, or N/A with reason]
+  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
   - Do not: [explicit implementation-drift guardrail]
 
 ## Notes

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

@@ -0,0 +1,122 @@
+---
+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 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
+
+## Dependencies
+
+- Required: `implement-specs-with-worktree` for each delegated spec implementation.
+- 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` when present, enumerate the exact spec directories to implement, and verify each delegated spec has the required planning files before starting subagents.
+- Execution: 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.
+- Quality: Preserve spec ownership boundaries, avoid duplicate delegation for the same spec, 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.
+
+## Goal
+
+Coordinate a multi-spec implementation batch safely by delegating each approved spec set to an isolated subagent-backed worktree implementation.
+
+## Workflow
+
+### 1) Identify the batch and implementation queue
+
+- Locate the requested batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/`.
+- Read `coordination.md` first when it exists.
+- Enumerate only the spec directories that are in scope for this request.
+- For each spec directory, verify the presence of:
+  - `spec.md`
+  - `tasks.md`
+  - `checklist.md`
+  - `contract.md`
+  - `design.md`
+- Do not delegate archived, sibling, or approximate specs unless the user explicitly includes them.
+- If `coordination.md` says the batch is not ready for parallel implementation, stop and report the blocking coordination item instead of spawning subagents.
+
+### 2) Build a delegation plan
+
+- Create one queue item per spec directory.
+- Assign one subagent to one spec only; never ask one subagent to implement multiple spec directories.
+- Keep a visible ledger with:
+  - spec path
+  - intended branch/worktree name if known
+  - assigned subagent
+  - status
+  - commit
+  - tests
+  - blockers
+- Determine the model policy before launch:
+  - If the user specifies a model, use that model for the implementation subagents when the environment supports model selection.
+  - 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
+
+- Maintain a maximum of four active implementation subagents at any time.
+- Start subagents independently and one at a time.
+- After each start, confirm that the subagent was accepted or is running before starting the next one.
+- 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
+
+For each subagent, provide only task-local instructions:
+
+- Repository root.
+- Exact spec directory path.
+- Parent `coordination.md` path when present.
+- Requirement to use `implement-specs-with-worktree`.
+- Requirement to read the full spec bundle before editing.
+- Requirement to implement inside its own isolated worktree.
+- Requirement to run relevant tests.
+- Requirement to backfill the spec documents after implementation.
+- Requirement to commit locally unless the user explicitly changes the completion boundary.
+- Requirement to report branch, worktree path, commit hash, tests, and blockers.
+
+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
+
+- 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.
+- 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 failures indicate a batch-wide planning defect, stop scheduling new subagents and report the defect.
+
+### 6) Finish the batch report
+
+- 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`.
+
+## Working Rules
+
+- One spec directory maps to one implementation subagent.
+- Maximum active implementation subagents: 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.
+- 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.
+
+## References
+
+- `implement-specs-with-worktree`: required per-spec worktree implementation workflow.
+- `generate-spec`: clarification and planning repair workflow when a batch is not ready for parallel implementation.
+- `review-change-set`: optional post-implementation review workflow before merge or submission.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Implement Specs with Subagents"
+  short_description: "Coordinate parallel spec worktree implementations"
+  default_prompt: "Use $implement-specs-with-subagents to 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."

package/package.json

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