@laitszkin/apollo-toolkit 2.4.3 → 2.5.0

package/AGENTS.md

@@ -12,12 +12,11 @@
 This repository enables users to install and run a curated set of reusable agent skills for software delivery, research, repository maintenance, and media-generation workflows.
 
 - Users can align project documentation with the current codebase.
-- Users can consolidate accumulated project specs into a standardized README and categorized project documentation set.
+- Users can consolidate completed project specs into a standardized README and categorized project documentation set, then archive the consumed planning files.
 - Users can investigate application logs and produce evidence-backed root-cause findings.
 - Users can answer repository-backed questions with additional web research when needed.
 - Users can commit and push local changes without performing version or release work.
 - Users can manage Codex user-preference memory by reviewing the last 24 hours of chats, storing categorized memory documents under `~/.codex/memory`, and syncing a memory index into `~/.codex/AGENTS.md`.
-- Users can orchestrate Codex subagents for most non-trivial tasks by reusing or creating focused custom agents under `~/.codex/agents`, then delegating exploration, review, verification, and unrelated module work while keeping tightly coupled execution in the main agent.
 - Users can research a topic deeply and produce evidence-based deliverables.
 - Users can research the latest completed market week and produce a PDF watchlist of tradeable instruments for the coming week.
 - Users can turn a marked weekly finance PDF into a concise evidence-based financial event report.

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.5.0] - 2026-03-19
+
+### Changed
+- Rename `specs-to-project-docs` to `archive-specs` and refocus the skill on converting completed specs into project docs while archiving the consumed planning files.
+- Update `develop-new-features` and `enhance-existing-features` so completed work must backfill requirement completion status in `spec.md` alongside `tasks.md` and `checklist.md`.
+- Update `commit-and-push` and `version-release` to treat planning-file checkboxes semantically during conversion, and to invoke `archive-specs` when completed spec sets should become project documentation.
+- Update the npm installer to remove stale linked skills that no longer exist in the latest packaged skill list during managed installs.
+
+### Removed
+- Remove the `codex-subagent-orchestration` skill and clean related multi-agent guidance from affected skill documents.
+
 ## [v2.4.3] - 2026-03-19
 
 ### Changed

package/README.md

@@ -6,10 +6,10 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 
 - align-project-documents
 - analyse-app-logs
+- archive-specs
 - answering-questions-with-research
 - commit-and-push
 - codex-memory-manager
-- codex-subagent-orchestration
 - deep-research-topics
 - develop-new-features
 - discover-edge-cases
@@ -34,7 +34,6 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - review-change-set
 - review-codebases
 - scheduled-runtime-health-check
-- specs-to-project-docs
 - systematic-debug
 - text-to-short-video
 - version-release
@@ -54,6 +53,7 @@ The interactive installer:
 - installs a managed copy into `~/.apollo-toolkit`
 - lets you multi-select `codex`, `openclaw`, `trae`, or `all`
 - creates symlinks from `~/.apollo-toolkit/<skill>` into each selected target
+- in the same npm/npx install flow, removes stale linked skills that existed in the previous installed version but no longer exist in the current package skill list
 
 ### Global install
 

package/{specs-to-project-docs → archive-specs}/README.md

@@ -1,6 +1,6 @@
-# specs-to-project-docs
+# archive-specs
 
-A documentation skill that consolidates scattered spec files into standardized project docs. It produces a concise `README.md` plus a categorized document set grounded in real repository evidence.
+A documentation skill that converts completed spec files into standardized project docs and archives the consumed planning files. It produces a concise `README.md` plus a categorized document set grounded in real repository evidence.
 
 ## Core capabilities
 
@@ -8,7 +8,7 @@ A documentation skill that consolidates scattered spec files into standardized p
 - Reconciles spec claims against code, config, scripts, and deployment files.
 - Standardizes both new and existing project docs into topic-based files for setup, configuration, architecture, features, and developer onboarding.
 - Provides dedicated reference templates for the top-level README, the documentation index/reference list, and each category document.
-- Deletes superseded spec source files after a successful conversion, unless they still need to stay active or be archived explicitly.
+- Archives superseded spec source files after a successful conversion, and deletes them only when the repository clearly does not need historical retention.
 - Keeps unknown or unverifiable details explicit instead of guessing.
 
 ## Repository layout

package/{specs-to-project-docs → archive-specs}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: specs-to-project-docs
-description: Turn a project's accumulated spec files into standardized project documentation and README content. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.md` files into maintainable docs covering installation and deployment, configuration, external service setup, architecture, feature introductions, and developer onboarding context.
+name: archive-specs
+description: Convert completed project spec sets into maintainable project documentation and archive the consumed planning files. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.md` files into evidence-backed docs covering installation and deployment, configuration, external service setup, architecture, feature introductions, and developer onboarding context.
 ---
 
-# Specs To Project Docs
+# Archive Specs
 
 ## Dependencies
 
@@ -17,11 +17,11 @@ description: Turn a project's accumulated spec files into standardized project d
 - Evidence: Treat code, config, deployment files, and current spec files as evidence sources; never guess when a detail is missing.
 - Execution: Inventory all relevant specs first, reconcile them with the current repository, then generate or update standardized docs from the provided templates.
 - Quality: Prefer source-of-truth behavior over stale plan text, align existing docs to the same standard structure, and call out unknowns explicitly instead of inventing missing setup details.
-- Output: Produce a concise `README.md` plus a categorized project-doc set, then remove superseded spec files after the conversion is complete.
+- Output: Produce a concise `README.md` plus a categorized project-doc set, then archive or remove superseded spec files after the conversion is complete.
 
 ## Goal
 
-Convert scattered planning artifacts into stable, standardized project documentation that helps operators and developers quickly open the exact document they need for setup, configuration, architecture, feature understanding, or development onboarding.
+Convert completed planning artifacts into stable, standardized project documentation, then archive the consumed specs so active planning files stay separate from durable project docs.
 
 ## Workflow
 
@@ -85,12 +85,12 @@ Ensure the split project docs cover all of the following:
 - Each category doc should stay focused on one topic instead of acting like another monolithic handbook.
 - Remove template placeholders and stale planning language before finishing.
 
-### 7) Remove superseded spec files after successful conversion
+### 7) Archive superseded spec files after successful conversion
 
-- After the standardized project docs are complete and verified, delete the old source spec files that were converted.
-- Remove the full spec directory when it only exists to hold the consumed `spec.md`, `tasks.md`, and `checklist.md` files.
-- Do not delete any spec file that is still actively needed for unfinished implementation work or explicit archival requirements.
-- If a repository needs historical retention, move the source specs into a clearly marked archive path instead of leaving them mixed with active docs.
+- After the standardized project docs are complete and verified, archive the old source spec files that were converted.
+- Prefer moving the consumed `spec.md`, `tasks.md`, and `checklist.md` files, or their containing plan directory, into a clearly marked archive path instead of leaving them mixed with active docs.
+- Delete converted spec files only when the repository clearly does not need historical retention.
+- Do not archive or delete any spec file that is still actively needed for unfinished implementation work.
 
 ## Working Rules
 

package/archive-specs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "archive-specs"
+  short_description: "Convert completed specs into project docs and archive the consumed plans"
+  default_prompt: "Use $archive-specs to inventory the project's spec.md/tasks.md/checklist.md files, reconcile them with the current repository, rewrite existing project docs into a standardized categorized structure when needed, generate or update a concise README plus split project docs for getting started, configuration, architecture, features, and developer guidance, maintain a docs/README.md reference list, then archive the consumed source specs after successful conversion, deleting them only when the repository clearly does not need historical retention."

package/commit-and-push/README.md

@@ -7,9 +7,9 @@ A Codex skill for commit-and-push workflows without release/version operations.
 `commit-and-push` helps agents safely submit local changes by:
 
 1. Inspecting git status and staged state.
-2. Running `specs-to-project-docs` when the repository contains spec files or existing project docs need normalization.
+2. Running `archive-specs` during submission to convert completed spec sets and archive them, or when existing project docs need normalization.
 3. Running `align-project-documents` and `maintain-project-constraints` before commit.
-4. Running additional dependency skills for code-affecting diffs through isolated parallel review subagents when available.
+4. Running additional dependency skills for code-affecting diffs when their coverage is needed.
 5. Committing with a concise Conventional Commit message.
 6. Pushing to the current branch.
 
@@ -21,6 +21,6 @@ Use this skill when the user asks to commit/push/submit changes and does **not**
 - tagging
 - release changelog workflows
 
-If the repository contains spec files, or if existing project docs still use a non-standard layout, normalize them into the categorized `specs-to-project-docs` structure first and let that skill remove or archive superseded spec files when appropriate.
+If the repository contains a completed spec set, convert it into the categorized `archive-specs` project-doc structure during submission and archive the consumed plan files. Treat `spec.md`, `tasks.md`, and `checklist.md` semantically: unchecked task or decision checkboxes do not automatically mean the work is unfinished when the docs clearly show they were not selected, replaced, deferred, or marked `N/A`.
 
 For release workflows, use `version-release`.

package/commit-and-push/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: commit-and-push
-description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. If the repository contains active planning artifacts or existing project docs do not match the `specs-to-project-docs` structure, run `specs-to-project-docs` before the final commit so project docs are standardized into categorized files and the old specs are removed or archived when appropriate."
+description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. During submission, run `archive-specs` to convert completed spec sets into project documentation and archive the consumed plans, and also use it when existing project docs do not match the standardized project-doc structure."
 ---
 
 # Commit and Push
@@ -8,15 +8,15 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Dependencies
 
 - Required: `align-project-documents` and `maintain-project-constraints` before the final commit.
-- Conditional: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting changes; `specs-to-project-docs` when the repository contains active planning artifacts or existing project docs need normalization into the standard categorized structure.
+- Conditional: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting changes; `archive-specs` during submission when completed spec sets should be converted into project docs and archived, or when existing project docs need normalization into the standard categorized structure.
 - Optional: none.
-- Fallback: If any required dependency is unavailable, or if `specs-to-project-docs` is required for spec conversion but unavailable, stop and report the missing dependency.
+- Fallback: If any required dependency is unavailable, or if `archive-specs` is required for spec conversion but unavailable, stop and report the missing dependency.
 
 ## Standards
 
 - Evidence: Inspect git state and classify the change set before deciding which quality gates apply.
-- Execution: Run code-review dependency skills as independent parallel subagents when applicable, keep their contexts isolated to reduce review bias, standardize project docs into categorized outputs whenever specs or doc-structure mismatches are present, preserve staging intent, then commit and push without release steps.
-- Quality: Re-run relevant validation for runtime changes and keep project docs plus agent constraints synchronized before committing; treat `specs-to-project-docs` outputs as the canonical project-doc structure when normalization is required.
+- Execution: Run the required quality-gate skills when applicable, convert completed spec sets into categorized project docs during submission, normalize non-standard project docs when needed, preserve staging intent, then commit and push without release steps.
+- Quality: Re-run relevant validation for runtime changes and keep project docs plus agent constraints synchronized before committing; treat `archive-specs` outputs as the canonical project-doc structure when normalization is required.
 - Output: Produce a concise Conventional Commit and push it to the current branch only.
 
 ## Overview
@@ -39,23 +39,24 @@ Load only when needed:
 2. Classify changes
    - `code-affecting`: runtime code, tests, build scripts, CI logic, or behavior-changing config.
    - `docs-only`: content updates only (for example README, docs, comments).
-   - `repo-specs-present`: the repository contains active project planning artifacts such as `spec.md`, `tasks.md`, `checklist.md`, or plan directories that represent unfinished or recently completed work; exclude reference examples, templates, and archived samples that are not live project plans.
-   - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `specs-to-project-docs`.
+   - `repo-specs-present`: the repository contains live project planning artifacts such as `spec.md`, `tasks.md`, `checklist.md`, or plan directories; exclude reference examples, templates, and archived samples.
+   - `repo-specs-ready-for-conversion`: the relevant `spec.md`, `tasks.md`, and `checklist.md` have been updated to reflect the actual outcome of the work, and any unchecked task/decision checkbox that is clearly not selected, replaced, deferred, or `N/A` (for example, E2E intentionally not created) does not by itself mean the spec set is unfinished.
+   - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `archive-specs`.
 3. Run code-affecting dependency skills (when applicable)
-   - Launch `review-change-set`, `discover-edge-cases`, and `harden-app-security` as parallel review subagents for the same code-affecting scope when delegation is available.
-   - Keep each review subagent in an isolated context window; do not reuse the implementation thread as the reviewer context.
-   - Treat every reviewer as independent and unbiased, then consolidate and resolve all confirmed findings before continuing.
+   - Run `review-change-set`, `discover-edge-cases`, and `harden-app-security` for the same code-affecting scope when their coverage is needed.
+   - Consolidate and resolve all confirmed findings before continuing.
    - Re-run relevant tests when runtime logic changes.
 4. Standardize project docs when specs or doc normalization is needed
-   - Execute `specs-to-project-docs` when `repo-specs-present` or `project-doc-structure-mismatch` is true and the related implementation scope is already complete enough for documentation consolidation.
-   - Let `specs-to-project-docs` convert the relevant specs into categorized project docs such as `docs/README.md`, `docs/getting-started.md`, `docs/configuration.md`, `docs/architecture.md`, `docs/features.md`, and `docs/developer-guide.md`.
-   - Let the skill normalize any existing project docs to the same structure and remove or archive superseded source spec files.
-   - If the specs still represent active unfinished work, do not convert them yet; report that the spec files remain active and should not be deleted.
+   - During submission, execute `archive-specs` when `repo-specs-ready-for-conversion` is true or when `project-doc-structure-mismatch` is true.
+   - Let `archive-specs` convert the relevant specs into categorized project docs such as `docs/README.md`, `docs/getting-started.md`, `docs/configuration.md`, `docs/architecture.md`, `docs/features.md`, and `docs/developer-guide.md`.
+   - Let the skill normalize any existing project docs to the same structure and archive superseded source spec files.
+   - Do not treat unchecked task or decision checkboxes alone as blocking unfinished work; read the surrounding notes and requirement status semantically.
+   - If the docs still show unresolved implementation scope that is neither completed, intentionally deferred, nor explicitly `N/A`, do not convert them yet; report that the spec files remain active and should not be deleted.
 5. Run pre-commit sync dependencies
    - Execute `align-project-documents` after spec conversion and code/doc scans are complete.
    - Execute `maintain-project-constraints` immediately before the commit.
 6. Keep docs synchronized when needed
-   - Apply the output from `specs-to-project-docs` when repository specs were converted or existing project docs were normalized into categorized project docs.
+   - Apply the output from `archive-specs` when repository specs were converted or existing project docs were normalized into categorized project docs.
    - Apply the output from `align-project-documents` when behavior or usage changed.
    - Apply the output from `maintain-project-constraints` when agent workflow/rules changed.
 7. Commit

package/commit-and-push/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Commit and Push"
   short_description: "Submit local changes with commit and push only"
-  default_prompt: "Use $commit-and-push to inspect the current git state, classify the diff, run required dependency skills ($align-project-documents and $maintain-project-constraints, plus $review-change-set, $discover-edge-cases, and $harden-app-security as isolated parallel review subagents for code-affecting changes when available), run $specs-to-project-docs when the repository contains spec files or existing project docs need normalization so project docs are standardized into categorized files and old specs are removed or archived when appropriate, then create a concise Conventional Commit and push to the current branch without any versioning or release steps."
+  default_prompt: "Use $commit-and-push to inspect the current git state, classify the diff, run required dependency skills ($align-project-documents and $maintain-project-constraints, plus $review-change-set, $discover-edge-cases, and $harden-app-security for code-affecting changes when their coverage is needed), then during submission run $archive-specs to convert any completed spec set into categorized project docs, archive the consumed plans, and normalize existing project docs when needed. Treat spec.md, tasks.md, and checklist.md semantically: unchecked task or decision checkboxes alone do not block conversion when the docs show they were not selected, replaced, deferred, or marked N/A. Then create a concise Conventional Commit and push to the current branch without any versioning or release steps."

package/develop-new-features/README.md

@@ -8,7 +8,7 @@ A spec-first feature development skill for new behavior and greenfield work. It
 - Treats `spec.md`, `tasks.md`, and `checklist.md` as approval-gated artifacts, not optional notes.
 - Covers unit, regression, property-based, integration, E2E, and adversarial testing based on actual risk.
 - Reuses existing architecture and avoids speculative expansion.
-- Backfills planning docs after implementation and testing complete.
+- Backfills `spec.md`, `tasks.md`, and `checklist.md` after implementation and testing complete.
 
 ## Repository layout
 
@@ -32,7 +32,7 @@ A spec-first feature development skill for new behavior and greenfield work. It
 2. Run `generate-spec` to create and maintain `docs/plans/{YYYY-MM-DD}_{change_name}/`.
 3. Wait for explicit approval on the spec set.
 4. Implement the approved behavior with minimal changes.
-5. Run risk-driven tests and backfill `tasks.md` and `checklist.md`.
+5. Run risk-driven tests and backfill `spec.md`, `tasks.md`, and `checklist.md`.
 
 ## Testing expectations
 

package/develop-new-features/SKILL.md

@@ -17,7 +17,7 @@ description: >-
 
 ## Dependencies
 
-- Required: `generate-spec` for `spec.md`, `tasks.md`, `checklist.md`, clarification handling, approval gating, and status backfill.
+- Required: `generate-spec` for `spec.md`, `tasks.md`, `checklist.md`, clarification handling, approval gating, and completion-status backfill.
 - Conditional: none.
 - Optional: none.
 - Fallback: If `generate-spec` is unavailable, stop and report the missing dependency.
@@ -50,7 +50,7 @@ Use a shared spec-generation workflow for all new feature work, then implement t
   - filling BDD requirements and risk-driven test plans
   - handling clarification responses
   - obtaining explicit approval before coding
-  - backfilling document status after implementation and testing
+  - backfilling document status after implementation and testing, including requirement completion in `spec.md`
 - Do not modify product code before the approved spec set exists.
 
 ### 3) Explore architecture and reuse opportunities
@@ -86,7 +86,8 @@ Rules:
 
 ### 6) Completion updates
 
-- Backfill `tasks.md` and `checklist.md` through `$generate-spec` workflow after implementation and testing.
+- Backfill `spec.md`, `tasks.md`, and `checklist.md` through `$generate-spec` workflow after implementation and testing.
+- In `spec.md`, mark each approved requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
 - Report the implemented scope, test execution, and any concrete `N/A` reasons.
 
 ## Working Rules

package/develop-new-features/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Develop New Features"
   short_description: "Spec-first feature development that depends on generate-spec"
-  default_prompt: "Use $develop-new-features to design new behavior through a spec-first workflow: review the required external docs, run $generate-spec to create and maintain docs/plans/<date>_<change_name>/{spec.md,tasks.md,checklist.md}, wait for explicit approval, then implement the approved feature with risk-driven tests and backfill the planning docs after execution."
+  default_prompt: "Use $develop-new-features to design new behavior through a spec-first workflow: review the required external docs, run $generate-spec to create and maintain docs/plans/<date>_<change_name>/{spec.md,tasks.md,checklist.md}, wait for explicit approval, then implement the approved feature with risk-driven tests and backfill spec.md, tasks.md, and checklist.md after execution, including requirement completion status in spec.md."

package/enhance-existing-features/README.md

@@ -32,7 +32,7 @@ A brownfield feature-extension skill: map dependencies first, decide whether sha
 2. Trigger `generate-spec` only when the change is high complexity, hits a critical module, or crosses module boundaries.
 3. Wait for explicit approval if planning docs were generated.
 4. Implement the smallest safe brownfield change.
-5. Run risk-driven tests and backfill planning docs when they exist.
+5. Run risk-driven tests and backfill `spec.md`, `tasks.md`, and `checklist.md` when specs exist.
 
 ## Test requirements
 

package/enhance-existing-features/SKILL.md

@@ -59,6 +59,7 @@ If triggered:
 - Run `$generate-spec` and follow its workflow completely.
 - Use it to create or update `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, and `checklist.md`.
 - Ensure planned behaviors and edge cases cover external dependency states, abuse/adversarial paths, and any relevant authorization/idempotency/concurrency/data-integrity risks.
+- After implementation and testing, update the same plan set so `spec.md` reflects requirement completion status in addition to task and checklist progress.
 - If users answer clarification questions, update the planning docs and obtain explicit approval again before implementation.
 - Do not modify implementation code before approval.
 
@@ -100,7 +101,8 @@ Rules:
 
 ### 6) Completion updates
 
-- If specs were used, backfill `tasks.md` and `checklist.md` through `$generate-spec` workflow based on actual completion and test outcomes.
+- If specs were used, backfill `spec.md`, `tasks.md`, and `checklist.md` through `$generate-spec` workflow based on actual completion and test outcomes.
+- In `spec.md`, mark each relevant requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
 - If specs were not used, provide a concise execution summary including test IDs/results, regression coverage, mock scenario coverage, adversarial coverage, and any `N/A` reasons.
 
 ## Working Rules

package/enhance-existing-features/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "enhance-existing-features"
   short_description: "Extend brownfield features with conditional generate-spec planning and risk-driven tests"
-  default_prompt: "Use $enhance-existing-features to extend a brownfield feature: map the affected code and dependencies first, decide whether the change is high complexity / critical module / cross-module, run $generate-spec when specs are required, wait for explicit approval before coding, and always add risk-driven tests plus clear N/A reasons when a category truly does not apply."
+  default_prompt: "Use $enhance-existing-features to extend a brownfield feature: map the affected code and dependencies first, decide whether the change is high complexity / critical module / cross-module, run $generate-spec when specs are required, wait for explicit approval before coding, and always add risk-driven tests plus clear N/A reasons when a category truly does not apply, then backfill spec.md, tasks.md, and checklist.md when a spec set exists, including requirement completion status in spec.md."

package/lib/cli.js

@@ -371,7 +371,7 @@ async function run(argv, context = {}) {
       return 1;
     }
 
-    await syncToolkitHome({
+    const syncResult = await syncToolkitHome({
       sourceRoot,
       toolkitHome,
       version: packageJson.version,
@@ -380,6 +380,7 @@ async function run(argv, context = {}) {
     const installResult = await installLinks({
       toolkitHome,
       modes,
+      previousSkillNames: syncResult.previousSkillNames,
       env: {
         ...env,
         APOLLO_TOOLKIT_HOME: toolkitHome,

package/lib/installer.js

@@ -112,6 +112,7 @@ async function stageToolkitContents({ sourceRoot, destinationRoot, version }) {
 async function syncToolkitHome({ sourceRoot, toolkitHome, version }) {
   const parentDir = path.dirname(toolkitHome);
   const tempDir = path.join(parentDir, `.apollo-toolkit.tmp-${process.pid}-${Date.now()}`);
+  const previousSkillNames = await listSkillNames(toolkitHome).catch(() => []);
 
   await fsp.rm(tempDir, { recursive: true, force: true });
   await stageToolkitContents({ sourceRoot, destinationRoot: tempDir, version });
@@ -127,6 +128,7 @@ async function syncToolkitHome({ sourceRoot, toolkitHome, version }) {
 
   return {
     toolkitHome,
+    previousSkillNames,
     skillNames: await listSkillNames(toolkitHome),
   };
 }
@@ -191,13 +193,17 @@ async function replaceWithSymlink(sourcePath, targetPath) {
   await fsp.symlink(sourcePath, targetPath, type);
 }
 
-async function installLinks({ toolkitHome, modes, env = process.env }) {
+async function installLinks({ toolkitHome, modes, env = process.env, previousSkillNames = [] }) {
   const skillNames = await listSkillNames(toolkitHome);
   const targets = await getTargetRoots(modes, env);
   const linkedPaths = [];
+  const staleSkillNames = previousSkillNames.filter((skillName) => !skillNames.includes(skillName));
 
   for (const target of targets) {
     await ensureDirectory(target.root);
+    for (const staleSkillName of staleSkillNames) {
+      await fsp.rm(path.join(target.root, staleSkillName), { recursive: true, force: true });
+    }
     for (const skillName of skillNames) {
       const sourcePath = path.join(toolkitHome, skillName);
       const targetPath = path.join(target.root, skillName);

package/package.json

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

package/version-release/README.md

@@ -7,8 +7,8 @@ A Codex skill for explicit release workflows: code/documentation alignment, vers
 `version-release` helps agents perform release work in a repeatable flow:
 
 1. Inspect the release scope from git history.
-2. Run quality gates for code-affecting changes through isolated parallel review subagents when available.
-3. Run `specs-to-project-docs` when the repository contains active planning artifacts or existing project docs need normalization.
+2. Run quality gates for code-affecting changes when their coverage is needed.
+3. Run `archive-specs` before finalizing the release to convert completed spec sets and archive them, or when existing project docs need normalization.
 4. Align project code and categorized project docs.
 5. Resolve version and tag details.
 6. Update version files and changelog.
@@ -25,6 +25,6 @@ Use this skill only when the user explicitly asks for:
 - tag creation/publishing
 - GitHub release publication
 
-If the repository contains active planning artifacts, or if existing project docs still use a mixed or non-standard layout, normalize them into the categorized `specs-to-project-docs` structure first and let that skill remove or archive superseded spec files when appropriate.
+If the repository contains a completed spec set, convert it into the categorized `archive-specs` project-doc structure before finalizing the release and archive the consumed plan files. Treat `spec.md`, `tasks.md`, and `checklist.md` semantically: unchecked task or decision checkboxes do not automatically mean the work is unfinished when the docs clearly show they were not selected, replaced, deferred, or marked `N/A`.
 
 If the user only wants commit + push, use `commit-and-push`.

package/version-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: version-release
-description: "Guide the agent to prepare and publish a versioned release (version bump, changelog, tag, GitHub release, and push). Use only when users explicitly request version/tag/release work. If the repository contains active planning artifacts or existing project docs do not match the `specs-to-project-docs` structure, run `specs-to-project-docs` before finalizing the release so project docs are standardized into categorized files and the old specs are removed or archived when appropriate."
+description: "Guide the agent to prepare and publish a versioned release (version bump, changelog, tag, GitHub release, and push). Use only when users explicitly request version/tag/release work. Before finalizing the release, run `archive-specs` to convert completed spec sets into project documentation and archive the consumed plans, and also use it when existing project docs do not match the standardized project-doc structure."
 ---
 
 # Version Release
@@ -8,15 +8,15 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 ## Dependencies
 
 - Required: none.
-- Conditional: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting releases before metadata edits and the final commit; `specs-to-project-docs` when the repository contains active planning artifacts or existing project docs need normalization into the standard categorized structure.
+- Conditional: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting releases before metadata edits and the final commit; `archive-specs` before release finalization when completed spec sets should be converted into project docs and archived, or when existing project docs need normalization into the standard categorized structure.
 - Optional: none.
-- Fallback: If a required release dependency is unavailable for a code-affecting scope, or if `specs-to-project-docs` is required for spec conversion but unavailable, stop and report the missing dependency.
+- Fallback: If a required release dependency is unavailable for a code-affecting scope, or if `archive-specs` is required for spec conversion but unavailable, stop and report the missing dependency.
 
 ## Standards
 
 - Evidence: Inspect the active change set and the release range before touching version files, tags, or changelog entries.
-- Execution: Use this workflow only for explicit release intent, run the required quality gates through independent parallel review subagents when applicable, standardize project docs into categorized files whenever specs or doc-structure mismatches are present, then update versions, docs, commit, tag, push, and publish the GitHub release.
-- Quality: Never guess versions, align user-facing docs with actual code, convert completed planning docs into standardized categorized project docs before the release is published, and treat the `specs-to-project-docs` structure as the release-ready documentation format.
+- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, convert completed spec sets into categorized project docs before release finalization, normalize non-standard project docs when needed, then update versions, docs, commit, tag, push, and publish the GitHub release.
+- Quality: Never guess versions, align user-facing docs with actual code, convert completed planning docs into standardized categorized project docs before the release is published, and treat the `archive-specs` structure as the release-ready documentation format.
 - Output: Produce a versioned release commit and tag, publish a matching GitHub release, and keep changelog plus relevant repository documentation synchronized.
 
 ## Overview
@@ -51,25 +51,26 @@ Load only when needed:
 3. Classify changes and run dependencies when required
    - `code-affecting`: runtime code, tests, build scripts, CI logic, or behavior-changing config.
    - `docs-only`: documentation/content updates only.
-   - `repo-specs-present`: the repository contains active project planning artifacts such as `spec.md`, `tasks.md`, `checklist.md`, or plan directories that represent unfinished or recently completed work; exclude reference examples, templates, and archived samples that are not live project plans.
-   - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `specs-to-project-docs`.
-   - For code-affecting changes, launch `review-change-set`, `discover-edge-cases`, and `harden-app-security` as parallel review subagents for the same release scope when delegation is available.
-   - Keep each review subagent in an isolated context window; do not reuse the implementation thread as the reviewer context.
-   - Treat every reviewer as independent and unbiased, then consolidate all confirmed findings before continuing.
+   - `repo-specs-present`: the repository contains live project planning artifacts such as `spec.md`, `tasks.md`, `checklist.md`, or plan directories; exclude reference examples, templates, and archived samples.
+   - `repo-specs-ready-for-conversion`: the relevant `spec.md`, `tasks.md`, and `checklist.md` reflect the actual delivered outcome, and any unchecked task/decision checkbox that is clearly not selected, replaced, deferred, or `N/A` (for example, E2E intentionally not created) does not by itself mean the spec set is unfinished.
+   - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `archive-specs`.
+   - For code-affecting changes, run `review-change-set`, `discover-edge-cases`, and `harden-app-security` for the same release scope when their coverage is needed.
+   - Consolidate all confirmed findings before continuing.
    - Resolve all confirmed findings before changing version files, tags, or release metadata.
 4. Identify release range
    - Find latest version tag with `git describe --tags --abbrev=0` (fallback to `git tag --list`).
    - If no tags exist, use initial commit from `git rev-list --max-parents=0 HEAD`.
    - Review `git log --oneline <range>` and `git diff --stat <range>`.
 5. Standardize project docs when specs or doc normalization is needed
-   - Execute `specs-to-project-docs` when `repo-specs-present` or `project-doc-structure-mismatch` is true and the related implementation scope is complete enough for documentation consolidation.
-   - Let `specs-to-project-docs` convert the relevant specs into categorized project docs such as `docs/README.md`, `docs/getting-started.md`, `docs/configuration.md`, `docs/architecture.md`, `docs/features.md`, and `docs/developer-guide.md`.
-   - Let the skill normalize any existing project docs to the same structure and remove or archive superseded source spec files.
-   - If the specs still represent active unfinished work, do not convert them yet; report that the spec files remain active and should not be deleted.
+   - Before finalizing the release, execute `archive-specs` when `repo-specs-ready-for-conversion` is true or when `project-doc-structure-mismatch` is true.
+   - Let `archive-specs` convert the relevant specs into categorized project docs such as `docs/README.md`, `docs/getting-started.md`, `docs/configuration.md`, `docs/architecture.md`, `docs/features.md`, and `docs/developer-guide.md`.
+   - Let the skill normalize any existing project docs to the same structure and archive superseded source spec files.
+   - Do not treat unchecked task or decision checkboxes alone as blocking unfinished work; read the surrounding notes and requirement status semantically.
+   - If the docs still show unresolved implementation scope that is neither completed, intentionally deferred, nor explicitly `N/A`, do not convert them yet; report that the spec files remain active and should not be deleted.
 6. Align code and project docs
    - Compare release range changes with user-facing docs and operational docs to ensure they match actual code behavior.
    - Required alignment targets include project docs such as `README.md`, usage/setup docs, API docs, deployment/runbook docs, and release notes sources when present.
-   - After `specs-to-project-docs` runs, treat the categorized outputs as the canonical project-doc structure.
+   - After `archive-specs` runs, treat the categorized outputs as the canonical project-doc structure.
    - If existing project docs are present but still use a mixed or non-standard layout, normalize them into the same categorized structure before version bumping or tagging.
    - If mismatches are found, update the relevant project docs before version bumping/tagging.
 7. Decide version and tag format

package/version-release/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Version Release"
   short_description: "Prepare a versioned release with bump, changelog, tag, GitHub release, and push"
-  default_prompt: "Use $version-release only for explicit release/version/tag requests: inspect the release scope, and for code-affecting changes run $review-change-set, $discover-edge-cases, and $harden-app-security as isolated parallel review subagents when available, run $specs-to-project-docs when the repository contains active planning artifacts or existing project docs need normalization so project docs are standardized into categorized files and old specs are removed or archived when appropriate, align user-facing docs with real behavior, update version files and CHANGELOG, create the release commit and tag, push commits and tags, then publish the matching GitHub release and confirm any triggered publish workflow."
+  default_prompt: "Use $version-release only for explicit release/version/tag requests: inspect the release scope, and for code-affecting changes run $review-change-set, $discover-edge-cases, and $harden-app-security when their coverage is needed. Before finalizing the release, run $archive-specs to convert any completed spec set into categorized project docs, archive the consumed plans, and normalize existing project docs when needed. Treat spec.md, tasks.md, and checklist.md semantically: unchecked task or decision checkboxes alone do not block conversion when the docs show they were not selected, replaced, deferred, or marked N/A. Then align user-facing docs with real behavior, update version files and CHANGELOG, create the release commit and tag, push commits and tags, then publish the matching GitHub release and confirm any triggered publish workflow."

package/codex-subagent-orchestration/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Yamiyorunoshura
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/codex-subagent-orchestration/README.md

@@ -1,39 +0,0 @@
-# codex-subagent-orchestration
-
-Use Codex subagents on nearly every non-trivial task.
-
-This skill inspects existing custom agents under `~/.codex/agents`, reuses them when they fit, creates new focused custom agents in the official Codex TOML format when they do not, and coordinates parallel subagent work for exploration, review, verification, and unrelated module edits.
-
-## Highlights
-
-- Defaults to using subagents for most non-trivial work
-- Explicitly instructs Codex to spawn subagents for non-trivial work
-- Reuses existing custom agents before creating new ones
-- Persists new reusable agents to `~/.codex/agents`
-- Enforces narrow responsibilities and a fixed `developer_instructions` template
-- Restricts reusable subagent models to `gpt-5.4` and `gpt-5.3-codex`
-- Keeps tightly coupled serial work in the main agent
-
-## Project Structure
-
-```text
-.
-├── SKILL.md
-├── LICENSE
-├── README.md
-├── agents/
-│   └── openai.yaml
-└── references/
-    ├── custom-agent-template.toml
-    └── routing-rubric.md
-```
-
-## Requirements
-
-- Codex app or CLI with subagent support
-- Write access to `~/.codex/agents`
-- Custom agent TOML format support
-
-## License
-
-MIT. See `LICENSE` for details.

package/codex-subagent-orchestration/SKILL.md

@@ -1,224 +0,0 @@
----
-name: codex-subagent-orchestration
-description: Use for almost every non-trivial Codex task. Conduct muti-agents workflow to better finish your jobs. Use this skill for better muti-agents orchestration. Inspect existing custom agents under `~/.codex/agents`, reuse them when they already fit, create a new focused custom agent in the official Codex TOML format when needed, and coordinate parallel subagents for exploration, review, verification, or unrelated module work while keeping tightly coupled serial work in the main agent.
----
-
-# Codex Subagent Orchestration
-
-## Dependencies
-
-- Required: none.
-- Conditional: task-specific skills only when the delegated agent's job clearly benefits from them.
-- Optional: none.
-- Fallback: If subagent delegation is unavailable, continue in a single thread and report that orchestration was skipped. If `~/.codex/agents` does not exist, create it before persisting personal custom agents.
-
-## Standards
-
-- Evidence: Inspect the current task shape and the existing custom-agent catalog before creating or updating any agent.
-- Execution: Use this skill for nearly every non-trivial task. When current tool rules allow delegation, the agent must actually launch one or more subagents instead of only describing delegation in prose. Treat a parallel subagents workflow as the default whenever two or more independent workstreams can run safely in parallel, use a single helper agent only when there is exactly one bounded sidecar job, and keep shared planning, conflict resolution, and final synthesis in the main agent.
-- Quality: Keep each custom agent narrow, opinionated, and non-overlapping; prefer read-only sandboxes for explorers and reviewers; keep review contexts isolated from the implementation thread; avoid parallel write conflicts.
-- Output: State which agents were reused or created, what each owned, whether they waited in parallel or were staged, and what remained with the main agent.
-
-## Overview
-
-This skill adds a repeatable orchestration layer on top of Codex subagents.
-
-Use this custom-agent format:
-
-- personal custom agents live in `~/.codex/agents/`
-- project-scoped custom agents live in `.codex/agents/`
-- each custom agent is one standalone TOML file
-- required fields are `name`, `description`, and `developer_instructions`
-
-This skill adds these house rules:
-
-- use short English noun phrases normalized to snake_case for `name`
-- use the fixed `developer_instructions` structure from `references/custom-agent-template.toml`
-- restrict reusable subagent model choices in this repository to `gpt-5.4` and `gpt-5.3-codex`
-
-## Model policy
-
-Use only these reusable subagent models:
-
-- `gpt-5.3-codex` for most coding-focused explorers, reviewers, verifiers, and bounded implementers
-- `gpt-5.4` for the hardest tasks that need broader judgment, ambiguity handling, or heavier cross-cutting synthesis
-
-Set `model_reasoning_effort` by task complexity:
-
-- `low`: straightforward bounded lookups, narrow evidence gathering, or simple mechanical checks
-- `medium`: ordinary non-trivial exploration, review, test triage, and isolated edits
-- `high`: ambiguous debugging, multi-step review, or higher-risk implementation work
-- `xhigh`: only for the hardest investigations or synthesis-heavy subagents where latency is justified
-
-Prefer `gpt-5.3-codex` first for agentic coding roles. Escalate to `gpt-5.4` when the delegated job is less mechanical and more judgment-heavy.
-
-## When To Use
-
-Use this skill by default unless the task is genuinely trivial or current tool rules disallow delegation, such as:
-
-- a one-shot factual answer with no decomposition value
-- a single obvious command or one-line edit
-- a tiny serial fix where spawning another agent would add more coordination than value
-
-Subagents are most valuable for:
-
-- codebase exploration and architecture mapping
-- evidence gathering and independent review
-- live-doc or API verification
-- browser reproduction and debugging
-- parallel edits across unrelated files or modules
-
-Keep the main agent in charge when the work is highly continuous, tightly coupled, or depends on a single evolving mental model. In those cases, let subagents provide bounded context, not final ownership, and do not force parallel writers.
-
-This skill is not satisfied by merely writing that Codex should delegate later. When parallelizable sidecar work exists and delegation is allowed, the default compliant shape is a parallel subagents workflow.
-
-## Workflow
-
-### 1) Triage the task first
-
-- Decide whether the task is trivial, serial-but-complex, or parallelizable.
-- If the task is non-trivial and delegation is allowed, you must delegate at least one bounded subtask to a subagent.
-- If the task has two or more independent read/review/exploration tracks, you must use a parallel subagents workflow rather than a single helper agent or a staged suggestion-only plan.
-- Use subagents for most non-trivial tasks, but do not force them into tiny or tightly coupled work.
-- Prefer one writer plus supporting read-only agents when ownership would otherwise overlap.
-- If tool rules require explicit user intent before delegation, confirm that gate first; once satisfied, launch the chosen subagents and do not stay in suggestion-only mode.
-
-### 2) Inspect the current agent catalog
-
-- Read `~/.codex/agents/*.toml` first.
-- Read `.codex/agents/*.toml` next when the current repository has project-scoped agents.
-- Build a quick catalog of each agent's:
-  - `name`
-  - `description`
-  - tool or MCP surface
-  - sandbox mode
-  - effective responsibility
-- Reuse an existing agent when its responsibility already fits the task without stretching into adjacent work.
-
-### 3) Decide reuse vs create
-
-Reuse an existing custom agent when all of the following are true:
-
-- its `description` matches the delegated job
-- its `developer_instructions` already enforce the right boundaries
-- its tools, sandbox, and model profile are suitable
-- using it will not create role overlap with another active agent
-
-Create a new custom agent whenever the current task exposes a stable reusable role and:
-
-- no existing agent owns the job cleanly
-- the responsibility can be described independently from the current one-off prompt
-- the role can be named, bounded, and reused on future tasks even if this is its first appearance
-
-Do not require repeated historical use before creating a reusable custom agent. Treat "reusable" as a property of role clarity and stable boundaries, not as proof that the exact same task has already repeated many times.
-
-When a delegated job is task-specific in content but role-stable in shape, abstract it to the most general reusable agent that still preserves clear ownership boundaries.
-
-Prefer extracting a general role such as `code_reviewer` or `docs_researcher` before creating a narrowly phrased task agent such as `review_rust_pr_123`.
-
-If domain knowledge materially changes the workflow, create a specialized reusable agent such as `rust_reviewer`; otherwise keep the agent generic and reusable across languages or repositories.
-
-Do not create near-duplicates. Tighten or extend an existing agent when the gap is small and the responsibility remains coherent.
-
-### 4) Create the custom agent in the official format when needed
-
-- Persist reusable personal agents to `~/.codex/agents/<name>.toml`.
-- Use the file template in `references/custom-agent-template.toml`.
-- Match the filename to the `name` field unless there is a strong reason not to.
-- Keep `description` human-facing and routing-oriented: it should explain when Codex should use the agent.
-- Keep `developer_instructions` stable and role-specific; do not leak current task noise into reusable instructions.
-- Persist a custom agent as soon as its responsibility, inputs, workflow, and boundaries can be described independently from the current task details; do not wait for multiple repeats before persisting it.
-- Set `model` to either `gpt-5.3-codex` or `gpt-5.4`.
-- Set `model_reasoning_effort` from actual task complexity, not from agent prestige or habit.
-
-Naming rule for this skill:
-
-- choose a short English noun phrase
-- normalize it to snake_case
-- examples: `code_mapper`, `code_reviewer`, `docs_researcher`, `rust_reviewer`, `browser_debugger`
-
-### 5) Use the fixed instruction format
-
-Every reusable custom agent created by this skill must keep the same section order inside `developer_instructions`:
-
-1. `# Role`
-2. `## Use when`
-3. `## Do not use when`
-4. `## Inputs`
-5. `## Workflow`
-6. `## Output`
-7. `## Boundaries`
-
-The `Use when` and `Do not use when` lists are the applicability contract. Keep them concrete.
-
-### 5.5) Use a fixed runtime handoff format
-
-Whenever you prompt a subagent, include:
-
-- the exact job split
-- whether Codex should wait for all agents before continuing
-- the expected summary or output format
-- the file or module ownership boundary
-- the stop condition if the agent hits uncertainty or overlap
-- the instruction to stay within current tool-rule limits for delegation, sandbox, and write scope
-
-### 6) Decompose ownership before spawning
-
-Give each subagent one exclusive job. Good ownership boundaries include:
-
-- `code_mapper`: map files, entry points, and dependencies
-- `docs_researcher`: verify external docs or APIs
-- `security_reviewer`: look for concrete exploit or hardening risks
-- `test_reviewer`: find missing coverage and brittle assumptions
-- `browser_debugger`: reproduce UI behavior and capture evidence
-- `ui_fixer` or `api_fixer`: implement a bounded change after the problem is understood
-
-Avoid combining exploration, review, and editing into one reusable agent when those responsibilities can stay separate.
-
-### 7) Orchestrate the run
-
-- Use actual subagent tool calls when delegation is allowed; do not stop at writing that Codex should spawn agents later.
-- State exactly how to split the work before each launch.
-- Say whether to wait for all agents before continuing or to stage them in sequence.
-- Ask for concise returned summaries, not raw logs.
-- Treat single-subagent delegation as the exception path, not the default orchestration pattern.
-
-Preferred patterns:
-
-- Parallel read-only agents for exploration, review, tests, logs, or docs.
-- Explorer first, implementer second, reviewer third when the work is serial but benefits from bounded context.
-- Multiple write-capable agents only when their modules and edited files do not overlap.
-
-Practical default:
-
-- spawn 2-4 agents for a complex task
-- spawn at least 2 agents when the task clearly contains parallelizable investigation or review tracks
-- keep within the current `agents.max_threads`
-- keep nesting shallow; many Codex setups leave `agents.max_depth` at 1 unless configured otherwise
-
-### 8) Keep the main agent responsible for continuity
-
-The main agent must:
-
-- own the todo list and the overall plan
-- decide task boundaries
-- merge results from parallel threads
-- resolve conflicting findings or overlapping edits
-- perform final validation and final user-facing synthesis
-
-If the task turns into one tightly coupled stream of work, stop delegating new edits and bring execution back to the main agent.
-
-### 9) Maintain the agent catalog after the task
-
-- Persist any new reusable custom agent to `~/.codex/agents/`.
-- If the current task revealed a cleaner reusable abstraction than the one you first considered, persist the more general role unless domain-specific workflow differences are materially important.
-- If a newly created agent proved too broad, narrow its description and instructions before finishing.
-- If two agents overlap heavily, keep one and tighten the other instead of letting both drift.
-- Do not persist throwaway agents that are really just one-off prompts.
-
-## References
-
-Load only when needed:
-
-- `references/custom-agent-template.toml`
-- `references/routing-rubric.md`

package/codex-subagent-orchestration/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Codex Subagent Orchestration"
-  short_description: "Reuse or create focused Codex custom agents for most non-trivial tasks"
-  default_prompt: "Use $codex-subagent-orchestration for almost every non-trivial task: explicitly instruct Codex to spawn the needed subagents, inspect existing custom agents under `~/.codex/agents` and `.codex/agents`, reuse a focused agent when one already fits, otherwise create a new reusable custom agent in TOML format with a narrow role, noun-phrase snake_case name, explicit task applicability lists, and fixed developer-instructions sections, then coordinate those spawned subagents for exploration, review, verification, or unrelated module edits while keeping tightly coupled serial work and final synthesis in the main agent. Persist any new reusable agents to `~/.codex/agents`."
-policy:
-  allow_implicit_invocation: true

package/codex-subagent-orchestration/references/custom-agent-template.toml

@@ -1,40 +0,0 @@
-name = "code_mapper"
-description = "Read-only codebase explorer for locating the relevant files, entry points, and dependency paths before implementation starts."
-model = "gpt-5.3-codex"
-model_reasoning_effort = "medium"
-sandbox_mode = "read-only"
-developer_instructions = """
-# Role
-You are Code Mapper, a focused exploration subagent.
-
-## Use when
-- The parent agent needs architecture mapping before editing.
-- The task requires identifying entry points, ownership, or dependency flow.
-- A writer or reviewer needs a bounded evidence packet first.
-
-## Do not use when
-- The task is a tiny obvious fix.
-- The task requires owning the final implementation.
-- The work is mostly external-doc research or browser reproduction.
-
-## Inputs
-- The parent task summary.
-- The repository or file scope to inspect.
-- Any known symptoms, failing behavior, or suspected areas.
-
-## Workflow
-1. Stay in exploration mode.
-2. Trace the real execution path.
-3. Prefer fast search and targeted file reads over broad scans.
-4. Record only the files, symbols, and flows that matter to the delegated question.
-
-## Output
-- Relevant files and symbols.
-- The most likely execution path.
-- Key risks, unknowns, and follow-up questions for the parent agent.
-
-## Boundaries
-- Do not edit code.
-- Do not drift into solution design unless the parent explicitly asks.
-- Keep the response concise and evidence-based.
-"""

package/codex-subagent-orchestration/references/routing-rubric.md

@@ -1,100 +0,0 @@
-# Routing Rubric
-
-Use this rubric before spawning or creating a custom agent.
-
-## 1. Delegate by default for non-trivial work
-
-Subagents are usually worth it when the task benefits from:
-
-- parallel read-heavy exploration
-- independent review or verification
-- bounded evidence gathering
-- unrelated module edits that can proceed without conflicts
-
-Keep the task in the main agent when it is:
-
-- tiny and obvious
-- one continuous chain of reasoning with no clean split
-- likely to create overlapping edits across the same files
-- blocked by an environment rule that disallows live delegation
-
-## 2. Reuse before creating
-
-Reuse an existing custom agent when:
-
-- the `description` matches the delegated job
-- the `developer_instructions` already define the correct boundaries
-- the tool surface and sandbox mode are appropriate
-
-Create a new one only when the job is both reusable and clearly distinct.
-
-## 3. Keep roles independent
-
-Good reusable roles:
-
-- `code_mapper`
-- `docs_researcher`
-- `security_reviewer`
-- `test_reviewer`
-- `browser_debugger`
-- `ui_fixer`
-- `api_fixer`
-
-Bad reusable roles:
-
-- agents that both explore and fix
-- agents that both review and implement
-- agents whose name depends on one temporary bug ticket
-
-## 4. Prefer read-only support agents
-
-Default to read-only for:
-
-- exploration
-- review
-- docs verification
-- browser reproduction without app edits
-
-Use write-capable agents only when they own a bounded implementation scope.
-
-## 5. Control parallel writes
-
-Parallel writes are acceptable only when:
-
-- file ownership does not overlap
-- module boundaries are clear
-- the main agent can merge results cheaply
-
-Otherwise use one writer and several read-only helpers.
-
-## 6. Use a fixed handoff prompt
-
-Every subagent handoff should include:
-
-- `Objective`
-- `Inputs and scope`
-- `File or module ownership`
-- `Constraints and stop conditions`
-- `Expected output shape`
-- `Blocking or non-blocking status`
-
-Use direct spawning language, for example: "spawn 2 subagents", "spawn a code-mapping subagent and a review subagent", or "do not spawn subagents because this task is trivial".
-
-## 7. Pick model and reasoning by complexity
-
-Allowed reusable subagent models for this skill:
-
-- `gpt-5.3-codex`
-- `gpt-5.4`
-
-Default selection:
-
-- use `gpt-5.3-codex` for most code-centered delegated work
-- use `gpt-5.4` when the delegated task needs broader synthesis, harder judgment, or more cross-domain reasoning
-
-Reasoning effort guide:
-
-- `low` for simple, bounded, low-risk delegated tasks
-- `medium` for standard non-trivial delegated tasks
-- `high` for complex or ambiguous delegated tasks
-- `xhigh` only when the extra latency is justified by especially difficult synthesis or investigation

package/specs-to-project-docs/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "specs-to-project-docs"
-  short_description: "Convert project specs into standardized categorized project docs"
-  default_prompt: "Use $specs-to-project-docs to inventory the project's spec.md/tasks.md/checklist.md files, reconcile them with the current repository, rewrite existing project docs into a standardized categorized structure when needed, generate or update a concise README plus split project docs for getting started, configuration, architecture, features, and developer guidance, maintain a docs/README.md reference list, then remove or archive superseded source specs after successful conversion."