@laitszkin/apollo-toolkit 3.0.4 → 3.1.1

package/AGENTS.md

@@ -53,6 +53,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can investigate gated or shadow LLM APIs by capturing real client request shapes, replaying verified traffic patterns, and attributing the likely underlying model through black-box fingerprinting.
 - Users can build and maintain Solana programs and Rust clients using official Solana development workflows.
 - Users can add focused observability to opaque workflows through targeted logs, metrics, traces, and tests.
+- Users can iteratively improve repository code quality through behavior-neutral naming, simplification, module-boundary, logging, and test-coverage passes.
 - Users can build against Jupiter's official Solana swap, token, price, lending, trigger, recurring, and portfolio APIs with an evidence-based development guide.
 - Users can render and embed math formulas with KaTeX using official documentation-backed guidance and reusable rendering scripts.
 - Users can debug software systematically by reproducing causes, validating fixes, and testing outcomes.

package/CHANGELOG.md

@@ -7,6 +7,17 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.1.1] - 2026-04-22
+
+### Changed
+- Fix Apollo Toolkit installers so `codex`-only skills stay scoped to Codex targets, while shared skills continue to install across the selected destinations.
+- Align the CLI welcome/help text, non-interactive guidance, and README examples with the supported `agents` target and current installer behavior.
+
+## [v3.1.0] - 2026-04-22
+
+### Added
+- Add `iterative-code-quality`, a new repository-wide improvement skill that performs repeated behavior-neutral passes for naming cleanup, function simplification, module-boundary refactors, logging alignment, and risk-based test coverage, then synchronizes project docs and `AGENTS.md`.
+
 ## [v3.0.4] - 2026-04-22
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # Apollo Toolkit Skills
 
-A curated skill catalog for Codex, OpenClaw, Trae, and Claude Code with a managed installer that keeps the toolkit in `~/.apollo-toolkit` and copies each skill into the targets you choose.
+A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with a managed installer that keeps the toolkit in `~/.apollo-toolkit` and copies each skill into the targets you choose.
 
 ## Included skills
 
@@ -24,6 +24,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, and Claude Code with a manage
 - harden-app-security
 - implement-specs
 - improve-observability
+- iterative-code-quality
 - jupiter-development
 - katex
 - learn-skill-from-conversations
@@ -62,7 +63,7 @@ npx @laitszkin/apollo-toolkit
 The interactive installer:
 - shows a branded `Apollo Toolkit` terminal welcome screen with a short staged reveal
 - installs a managed copy into `~/.apollo-toolkit`
-- lets you multi-select `codex`, `openclaw`, `trae`, `claude-code`, or `all`
+- lets you multi-select `codex`, `openclaw`, `trae`, `agents`, `claude-code`, or `all`
 - copies `~/.apollo-toolkit/<skill>` into each selected target
 - removes stale previously installed skill directories that existed in the previous installed version but no longer exist in the current package skill list
 - replaces legacy symlink-based installs created by older Apollo Toolkit installers with real copied directories
@@ -90,6 +91,7 @@ apltk open-github-issue --help
 
 ```bash
 npx @laitszkin/apollo-toolkit codex
+npx @laitszkin/apollo-toolkit agents
 npx @laitszkin/apollo-toolkit claude-code
 npx @laitszkin/apollo-toolkit codex openclaw
 npx @laitszkin/apollo-toolkit all
@@ -102,6 +104,7 @@ APOLLO_TOOLKIT_HOME=~/custom-toolkit npx @laitszkin/apollo-toolkit codex
 CODEX_SKILLS_DIR=~/custom-codex-skills npx @laitszkin/apollo-toolkit codex
 OPENCLAW_HOME=~/.openclaw npx @laitszkin/apollo-toolkit openclaw
 TRAE_SKILLS_DIR=~/.trae/skills npx @laitszkin/apollo-toolkit trae
+AGENTS_SKILLS_DIR=~/.agents/skills npx @laitszkin/apollo-toolkit agents
 CLAUDE_CODE_SKILLS_DIR=~/.claude/skills npx @laitszkin/apollo-toolkit claude-code
 ```
 
@@ -119,12 +122,14 @@ Installers still live in `scripts/` for local repository usage and curl / iwr in
 ./scripts/install_skills.sh codex
 ./scripts/install_skills.sh openclaw
 ./scripts/install_skills.sh trae
+./scripts/install_skills.sh agents
 ./scripts/install_skills.sh all
 ```
 
 ```powershell
 ./scripts/install_skills.ps1
 ./scripts/install_skills.ps1 codex
+./scripts/install_skills.ps1 agents
 ./scripts/install_skills.ps1 all
 ```
 

package/iterative-code-quality/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+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/iterative-code-quality/README.md

@@ -0,0 +1,30 @@
+# iterative-code-quality
+
+Improve an existing repository through repeated, evidence-backed code-quality passes while preserving intended business behavior and macro architecture.
+
+## Core capabilities
+
+- Scans the full codebase and builds a prioritized quality backlog before editing.
+- Clarifies ambiguous variable, parameter, field, helper, and test-data names.
+- Simplifies complex functions and extracts reusable helpers only when they centralize real behavior.
+- Splits mixed-responsibility code into narrower modules without changing macro architecture.
+- Repairs stale or missing logs and adds tests for important observability contracts.
+- Adds high-value unit, property-based, integration, or E2E tests based on risk.
+- Repeats the pass cycle until remaining issues are low-value, blocked, or require explicit product/architecture approval.
+- Synchronizes project docs and `AGENTS.md` through `align-project-documents` and `maintain-project-constraints` after implementation.
+
+## Repository structure
+
+- `SKILL.md`: Main iterative workflow, dependencies, guardrails, and output contract.
+- `agents/openai.yaml`: Agent interface metadata and default prompt.
+- `references/`: Focused guides for scanning, naming, simplification, module boundaries, logging, testing, and iteration gates.
+
+## Typical usage
+
+```text
+Use $iterative-code-quality to improve this repository's code quality end to end without changing business behavior or macro architecture.
+```
+
+## License
+
+MIT. See `LICENSE`.

package/iterative-code-quality/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: iterative-code-quality
+description: >-
+  Improve an existing codebase through repeated evidence-based code-quality
+  passes: clarify poor variable names, simplify or extract reusable functions,
+  split oversized code into single-responsibility modules, repair stale or
+  missing logs, and add high-value tests while preserving business behavior and
+  macro architecture. Use when users ask for comprehensive refactoring, code
+  cleanup, maintainability hardening, naming cleanup, log alignment, or test
+  coverage improvement across a repository.
+---
+
+# Iterative Code Quality
+
+## Dependencies
+
+- Required: `align-project-documents` and `maintain-project-constraints` after implementation changes are complete.
+- Conditional: `systematic-debug` when a new or existing test reveals a real business-logic defect that must be fixed.
+- Optional: `discover-edge-cases` for high-risk boundary exploration before choosing missing tests; `improve-observability` for complex telemetry design.
+- Fallback: If required completion dependencies are unavailable, finish code and tests, then report exactly which documentation or constraint sync step could not run.
+
+## Standards
+
+- Evidence: Read repository docs, project constraints, source, tests, logs, and entrypoints before editing; every rename, extraction, split, log update, or test must be backed by code context.
+- Execution: Work in bounded passes, prioritize behavior-neutral improvements with the highest maintainability and test value, validate after each pass, and repeat until the remaining quality gaps are low-value or unsafe to change.
+- Quality: Preserve business behavior and macro architecture unless tests expose an existing logic defect; avoid style-only churn, compatibility theater, broad rewrites, and unverified "cleanup".
+- Output: Deliver a concise pass-by-pass summary, changed behavior-neutral surfaces, test coverage added, validation results, unresolved risks, and documentation/`AGENTS.md` sync status.
+
+## Goal
+
+Raise code quality across an existing repository without changing intended product behavior or the system's macro architecture.
+
+This skill is intentionally implementation-oriented, not report-only. It should identify high-value improvements, apply them, test them, and keep iterating until further changes would be speculative, low-value, or architecture-changing.
+
+## Required Reference Loading
+
+Load references only when they match the active pass:
+
+- `references/repository-scan.md`: scope mapping, generated-file exclusions, and quality backlog selection.
+- `references/naming-and-simplification.md`: variable renames, function simplification, reusable extraction, and behavior-preservation checks.
+- `references/module-boundaries.md`: single-responsibility split heuristics and safe module extraction rules.
+- `references/logging-alignment.md`: stale log detection, missing log criteria, and behavior-neutral observability updates.
+- `references/testing-strategy.md`: risk-based unit, property, integration, and E2E coverage selection.
+- `references/iteration-gates.md`: multi-pass quality gates, stopping criteria, and validation cadence.
+
+## Workflow
+
+### 1) Establish the repository baseline
+
+- Read root guidance first: `AGENTS.md`, `README*`, major docs, package manifests, task runners, CI configs, and test setup.
+- Map runtime entrypoints, domain modules, external integrations, logging/telemetry utilities, and existing test suites.
+- Identify generated, vendored, lock, build-output, fixture, or snapshot files; exclude them from refactoring unless evidence shows they are human-maintained source.
+- Run or inspect the most relevant existing validation commands before editing when feasible, so pre-existing failures are distinguishable from new regressions.
+- Build an initial quality backlog with concrete file/function/test targets before changing code.
+- Use `references/repository-scan.md` for the scan checklist and backlog scoring.
+
+### 2) Execute bounded improvement passes
+
+Run focused passes in the order that fits the repository evidence. A typical order is:
+
+1. Naming clarity for variables, parameters, fields, local helpers, and test data.
+2. Function simplification and reusable extraction for duplicated or hard-coded workflows.
+3. Single-responsibility module splits for oversized or mixed-concern code.
+4. Logging alignment for stale, misleading, missing, or low-context diagnostics.
+5. Risk-based test coverage for high-value business logic and boundary cases.
+
+For each pass:
+
+- Read all directly affected callers, tests, and public interfaces before editing.
+- Keep the pass small enough to validate and review; split broad cleanups into multiple passes.
+- Prefer repository-native abstractions over new parallel frameworks.
+- Preserve public behavior, data contracts, side effects, error classes, and macro architecture.
+- Add or update tests in the same pass when the change touches non-trivial logic, observability contracts, or extracted helpers.
+- Validate the touched scope before starting another pass.
+
+### 3) Rename for clarity without churn
+
+- Rename only when the current name hides domain meaning, confuses ownership, conflicts with real units, or makes tests/logs misleading.
+- Prefer names that encode domain role, unit, lifecycle stage, or canonical owner.
+- Update all references, tests, fixtures, structured log fields, docs, and comments that describe the renamed concept.
+- Avoid renaming stable public API fields or persisted schema names unless the user explicitly requested a breaking migration.
+- Use `references/naming-and-simplification.md` before broad rename passes.
+
+### 4) Simplify and extract reusable functions
+
+- Simplify functions when branches, temporary state, repeated transformations, or hard-coded workflows obscure the invariant.
+- Extract helpers only when they reduce duplication, centralize one business rule, clarify caller intent, or make a behavior testable.
+- Keep helper placement aligned with current module ownership.
+- Do not create abstractions for one-off code unless they isolate a meaningful domain rule or external contract.
+- Preserve observable behavior unless a test proves the current behavior is a defect.
+
+### 5) Split modules by responsibility
+
+- Split code only when one file/module owns multiple change reasons, domain boundaries, external integrations, or lifecycle stages.
+- Define the new module's responsibility before moving code.
+- Keep interfaces narrow, explicit, and consistent with existing project style.
+- Avoid macro-architecture changes such as new layers, new service boundaries, new persistence strategies, or framework swaps unless the user explicitly expands scope.
+- Use `references/module-boundaries.md` for extraction rules and anti-patterns.
+
+### 6) Repair logging and observability drift
+
+- Compare log messages, event names, structured fields, metrics, and trace names against the current code ownership model.
+- Fix stale terminology after renames or refactors so logs describe the live workflow.
+- Add logs only at high-value decision points: branch selection, skipped work, external dependency outcome, persistence side effect, retry/rollback, and final outcome.
+- Use structured fields already accepted by the project; never log secrets, tokens, full sensitive payloads, or personal data.
+- Add tests or assertions for important log fields when the project has log-capture helpers.
+- Use `references/logging-alignment.md` for detailed criteria.
+
+### 7) Add high-value tests
+
+- Start from risk, not coverage percentage.
+- Prioritize tests for business rules, state transitions, error handling, extracted helpers, edge cases, observability contracts, and integration boundaries.
+- Use unit tests for local logic, property-based tests for invariants and generated input spaces, integration tests for cross-module chains, and E2E tests only when external services are stable or can be controlled reliably.
+- Mock or fake external services unless the real service contract is the subject under test.
+- If a new test exposes an existing business-logic bug, invoke `systematic-debug`, fix the true owner, and keep the regression test.
+- Use `references/testing-strategy.md` for coverage selection and required `N/A` reasoning.
+
+### 8) Iterate until quality gates pass
+
+- After each pass, run the narrowest relevant tests first, then broaden validation when confidence increases.
+- Re-scan touched areas for new naming drift, duplicated helper candidates, module-boundary cracks, logging drift, and missing tests.
+- Repeat the full pass cycle when significant gaps remain and can be fixed safely without changing business behavior or macro architecture.
+- Stop only when remaining issues are low-value, speculative, blocked, or require explicit product/architecture approval.
+- Use `references/iteration-gates.md` for stopping criteria.
+
+### 9) Synchronize docs and constraints
+
+After code and tests are complete:
+
+- Invoke `align-project-documents` when README, docs, architecture notes, debugging docs, setup instructions, or test guidance may have drifted.
+- Invoke `maintain-project-constraints` to verify `AGENTS.md` still reflects architecture, business flow, common commands, macro purpose, and coding conventions.
+- Update only documentation that is affected by real code, command, logging, or test changes.
+
+## Hard Guardrails
+
+- Do not change intended business logic while refactoring.
+- Do not change macro architecture, framework choice, storage model, deployment model, or service boundaries unless the user explicitly approves that expanded scope.
+- Do not use one-off scripts to rewrite product code.
+- Do not perform style-only churn that does not improve naming, reuse, modularity, observability, or test confidence.
+- Do not weaken tests to make refactors pass; update tests to stable invariants or fix the implementation defect.
+- Do not add E2E tests that depend on unreliable external services when a controlled integration test can prove the same business risk.
+
+## Completion Report
+
+Return:
+
+1. Passes completed and why they were ordered that way.
+2. Key files changed and the quality issue each change resolved.
+3. Business behavior preservation evidence.
+4. Tests added or updated, including property/integration/E2E `N/A` reasons where relevant.
+5. Validation commands and results.
+6. Documentation and `AGENTS.md` synchronization status.
+7. Remaining quality gaps, blockers, or deferred architecture/product decisions.

package/iterative-code-quality/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Iterative Code Quality"
+  short_description: "Refactor names, functions, modules, logs, and tests in repeated behavior-safe passes"
+  default_prompt: "Use $iterative-code-quality to scan this repository, build an evidence-backed quality backlog, then iteratively clarify variable names, simplify or extract reusable functions, split code into single-responsibility modules, repair stale or missing logs, and add high-value unit/property/integration/E2E tests while preserving business behavior and macro architecture; after code and tests are complete, run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md."

package/iterative-code-quality/references/iteration-gates.md

@@ -0,0 +1,73 @@
+# Iteration Gates And Stopping Criteria
+
+## Pass discipline
+
+Each pass must have:
+
+- a concrete quality target,
+- a bounded file/symbol scope,
+- expected behavior-neutral outcome,
+- validation plan,
+- rollback point if evidence contradicts the change.
+
+Avoid starting a broad second pass before validating the first.
+
+## Validation cadence
+
+Run validation from narrow to broad:
+
+1. Formatter or type check for touched files when available.
+2. Unit tests for touched helpers and modules.
+3. Integration tests for affected chains.
+4. Broader suite or build once multiple passes interact.
+
+If validation fails:
+
+- determine whether the failure is pre-existing, stale test expectation, test isolation issue, or real product bug,
+- fix the true owner,
+- keep regression coverage for real defects,
+- do not mask failures by weakening assertions.
+
+## Re-scan after each pass
+
+Inspect touched areas for:
+
+- new naming drift from moved or extracted concepts,
+- duplicated logic that remains after extraction,
+- module boundaries that are still mixed,
+- logs that now use stale names,
+- tests that cover only the happy path,
+- documentation or `AGENTS.md` drift.
+
+## Continue when
+
+Repeat the cycle when:
+
+- high-impact unclear names remain,
+- duplicated or hard-coded workflows still have safe extraction paths,
+- a module still mixes distinct responsibilities and can be split locally,
+- logs are still misleading or missing at critical decisions,
+- high-value business logic remains untested and is testable.
+
+## Stop when
+
+Stop when remaining candidates are:
+
+- low-value style preference,
+- speculative without concrete evidence,
+- public contract migrations,
+- macro-architecture changes,
+- product behavior changes needing user approval,
+- blocked by unavailable credentials, unstable external systems, or missing documentation,
+- untestable with the current repository tooling and too risky to change safely.
+
+## Completion evidence
+
+The final report should make the stopping point auditable:
+
+- passes completed,
+- validation commands and outcomes,
+- tests added by risk category,
+- behavior-preservation evidence,
+- docs and constraints sync status,
+- deferred items with reason and required approval or dependency.

package/iterative-code-quality/references/logging-alignment.md

@@ -0,0 +1,67 @@
+# Logging Alignment And Missing Observability
+
+## Purpose
+
+Keep logs and diagnostics synchronized with the real code path while preserving behavior.
+
+## Stale log signals
+
+Update logs when they:
+
+- mention retired owners, lifecycle stages, resource names, or field names,
+- describe a branch that no longer matches the condition,
+- use generic text like `failed` without the operation or reason,
+- report aggregate success without identifiers that let operators reconcile details,
+- keep compatibility-era names after code has moved to a new canonical model,
+- conflict with structured field names or metrics in the same path.
+
+## Missing log criteria
+
+Add logs only where they answer a concrete debugging question.
+
+High-value locations:
+
+- workflow start and final outcome for long-running jobs,
+- branch selection or skipped work with reason code,
+- validation rejection with safe context,
+- external dependency outcome including status class, retry count, request id, and latency when available,
+- persistence side effect or emitted command,
+- rollback, compensation, idempotency, duplicate, or replay decisions.
+
+Low-value locations:
+
+- every line of a tight loop,
+- logs that only restate the function name,
+- dumping raw payloads,
+- duplicating an exception already logged with equal context,
+- noisy success logs in hot paths without operational value.
+
+## Structured field rules
+
+- Reuse the project's existing logger, field naming, metric naming, and trace conventions.
+- Prefer stable identifiers, counts, reason codes, status classes, and lifecycle stages.
+- Keep field names aligned with canonical owners, not stale compatibility projections.
+- Do not log secrets, tokens, private keys, passwords, raw personal data, or full sensitive payloads.
+- Avoid high-cardinality values unless they are necessary identifiers already used by the project.
+
+## Behavior-neutral updates
+
+Logging changes must not:
+
+- alter retry, error, persistence, or branch behavior,
+- swallow exceptions,
+- add blocking network calls,
+- create expensive serialization in hot paths,
+- change public output unless logs are the product output.
+
+## Tests
+
+Add or update tests when:
+
+- the project already captures logs in tests,
+- branch-specific reason codes matter,
+- stale field names were renamed,
+- extracted helpers need observability contracts,
+- aggregate and detail telemetry must stay reconcilable.
+
+Assert stable fields and event names, not timestamps or full formatted strings.

package/iterative-code-quality/references/module-boundaries.md

@@ -0,0 +1,61 @@
+# Module Boundary And Single Responsibility Refactoring
+
+## When to split a module
+
+Split only when the module has multiple independent reasons to change, such as:
+
+- domain rules mixed with IO, formatting, CLI parsing, or external service calls,
+- unrelated workflows sharing one file because of history, not ownership,
+- test setup forced to instantiate unrelated dependencies,
+- large files where local changes frequently touch distant concepts,
+- circular or awkward imports caused by unclear ownership,
+- logging, validation, persistence, and presentation all living in one function or class.
+
+## Before splitting
+
+Define:
+
+- the current module's actual responsibilities,
+- the target responsibility of each new module,
+- which module owns the canonical business rule,
+- which interfaces must remain stable,
+- which tests prove behavior did not change.
+
+## Safe split patterns
+
+- Move pure domain logic into a domain-owned helper module.
+- Move external adapter code into an integration or infrastructure-adjacent module if the repository already uses that boundary.
+- Move formatting/reporting away from computation.
+- Move test helpers into existing test utility locations rather than production modules.
+- Keep orchestration modules thin: validate inputs, call owners, handle outcomes.
+
+## Interface design
+
+Use narrow interfaces:
+
+- pass only data the callee needs,
+- return explicit result objects or existing domain types,
+- avoid leaking framework/request/database objects into pure domain modules,
+- preserve existing error taxonomy,
+- keep naming aligned with current project vocabulary.
+
+## Anti-patterns
+
+Avoid:
+
+- creating a generic `utils` dumping ground,
+- moving code only to reduce file length,
+- adding new layers that duplicate existing architecture,
+- introducing dependency injection frameworks or service locators without explicit approval,
+- splitting tightly coupled state machines before defining the state owner,
+- changing public boundaries during a cleanup pass.
+
+## Validation checklist
+
+After a split:
+
+- imports remain acyclic or no worse than before,
+- public entrypoints still call the same behavior,
+- tests cover moved logic and orchestration glue,
+- logs still carry the same correlation identifiers,
+- docs or `AGENTS.md` are updated only if the visible architecture or command surface changed.

package/iterative-code-quality/references/naming-and-simplification.md

@@ -0,0 +1,71 @@
+# Naming And Function Simplification
+
+## Naming improvements
+
+Rename only when the current name creates real ambiguity.
+
+Good rename reasons:
+
+- hides domain role, unit, quantity, ownership, or lifecycle stage,
+- uses stale terminology after a refactor,
+- collides with another concept in the same scope,
+- makes boolean, enum, or state-transition meaning unclear,
+- forces readers to inspect implementation before understanding intent.
+
+Avoid renaming when:
+
+- the name is already clear in local context,
+- the change is pure personal preference,
+- the name is part of a stable external API, database schema, event contract, or migration-sensitive field,
+- the rename would create broad churn without reducing ambiguity.
+
+## Naming patterns
+
+- Prefer domain nouns over implementation nouns: `selectedAccount` over `item`.
+- Include units for quantities: `timeoutMs`, `amountCents`, `windowDays`.
+- Use booleans that read as predicates: `isEligible`, `hasPendingRetry`, `shouldPersist`.
+- Name collections by contents: `pendingInvoices`, not `list`.
+- Name state transitions by lifecycle: `markSettlementComplete`, not `updateStatus`.
+- Keep test data names meaningful: `expiredSubscription`, `duplicateEvent`, `unauthorizedActor`.
+
+## Function simplification signals
+
+Simplify functions that contain:
+
+- repeated guard clauses or duplicated validation,
+- mixed parsing, validation, orchestration, persistence, and formatting,
+- nested branches that hide the main path,
+- temporary variables whose names encode implementation steps rather than domain state,
+- hard-coded workflow steps repeated in multiple callers,
+- comments explaining what code structure should make obvious.
+
+## Safe simplification moves
+
+- Extract pure transformations and validations into small helpers.
+- Replace repeated literal mappings with a named table or function.
+- Flatten nested conditionals with explicit guard clauses when it clarifies failure paths.
+- Centralize one business rule behind one function when multiple callers duplicate it.
+- Split orchestration from local computation when tests need a deterministic unit.
+- Delete dead compatibility paths only when reachability evidence and tests support deletion.
+
+## Extraction rules
+
+Create a reusable helper only when at least one condition is true:
+
+- two or more call sites duplicate the same rule,
+- the extracted logic has a clear domain name and stable contract,
+- the helper makes a high-value invariant testable,
+- the helper isolates an external dependency contract or side-effect boundary,
+- the current function has multiple reasons to change.
+
+Keep extracted helpers close to the owner module unless the repository already has a shared utility location for that domain.
+
+## Behavior preservation checklist
+
+Before and after simplification, verify:
+
+- inputs, outputs, exceptions, side effects, and ordering are unchanged,
+- persisted data and emitted events keep the same contract,
+- public API and CLI behavior remain stable,
+- log fields remain compatible unless stale names were intentionally corrected,
+- existing tests still pass and new tests cover extracted rules.

package/iterative-code-quality/references/repository-scan.md

@@ -0,0 +1,59 @@
+# Repository Scan And Backlog Selection
+
+## Purpose
+
+Build a factual map before changing code, then choose the highest-value quality improvements.
+
+## Required scan
+
+- Read `AGENTS.md`, `README*`, project docs, manifests, task runners, CI configs, and test setup.
+- List entrypoints: CLI commands, servers, workers, jobs, frontend routes, scripts, libraries, or public packages.
+- Identify core domain modules, external integrations, persistence boundaries, logging utilities, and test helpers.
+- Inspect current git state before editing so unrelated user changes are not overwritten.
+- Identify generated, vendored, lock, snapshot, build-output, and fixture files; exclude them from refactoring unless they are human-maintained source.
+
+## Code quality backlog signals
+
+Prioritize files or functions with:
+
+- high fan-in or many call sites,
+- critical business rules or money/security/data-integrity decisions,
+- duplicated condition trees, conversions, validation, or external-call choreography,
+- unclear naming around ownership, units, state, or lifecycle,
+- large functions that mix parsing, validation, orchestration, side effects, and formatting,
+- log messages that describe old concepts or omit branch/failure context,
+- low or missing tests around meaningful invariants and edge cases.
+
+## Evidence to capture
+
+For each candidate record:
+
+- file path and symbol name,
+- observed quality problem,
+- why it matters to maintainability or correctness confidence,
+- expected behavior-neutral change,
+- tests or validations needed to prove safety,
+- reason to defer if the candidate requires product or architecture approval.
+
+## Exclusion rules
+
+Do not refactor:
+
+- third-party, generated, or compiled artifacts,
+- snapshots where churn would hide signal,
+- code the user marked as actively edited elsewhere,
+- public schema/API names that require migration planning,
+- areas that cannot be validated and are not causing a clear quality risk.
+
+## Backlog scoring
+
+Prefer a small set of high-confidence improvements over an exhaustive sweep.
+
+Score each candidate by:
+
+1. **Impact**: criticality, call frequency, future change risk.
+2. **Confidence**: evidence that the change is behavior-neutral.
+3. **Validation**: ability to test or otherwise prove equivalence.
+4. **Blast radius**: number of modules, public contracts, and migrations affected.
+
+Start with high-impact, high-confidence, low-blast-radius items. Escalate broad changes only when smaller passes cannot resolve the root problem.

package/iterative-code-quality/references/testing-strategy.md

@@ -0,0 +1,78 @@
+# Risk-Based Testing Strategy
+
+## Principle
+
+Choose tests from the risk inventory, not from a generic coverage target.
+
+For every non-trivial pass, ask what could regress silently if the cleanup were wrong.
+
+## Unit tests
+
+Use for:
+
+- extracted helpers,
+- renamed or simplified business rules,
+- validation and rejection logic,
+- branch-specific errors and side effects,
+- formatting or parsing boundaries.
+
+Good oracles:
+
+- exact return values,
+- exact domain state transitions,
+- exact error class or reason code,
+- emitted side effect or explicit lack of side effect.
+
+## Property-based tests
+
+Use when logic has invariants or broad input space:
+
+- serialization or parsing round trips,
+- sorting, grouping, deduplication, aggregation,
+- authorization or eligibility predicates,
+- idempotency, retry, replay, and state-machine transitions,
+- generated mocked external-service states.
+
+Record `N/A` only with a concrete reason, such as "no generated input space; pass only renamed local variables."
+
+## Integration tests
+
+Use when the risk spans modules:
+
+- orchestration calling extracted domain helpers,
+- persistence plus domain transition,
+- API/CLI handler plus service layer,
+- logging contract across a real execution path,
+- adapter behavior with mocked external services.
+
+For external services, prefer mocks, fakes, local emulators, or recorded stable fixtures unless the real contract is explicitly under test.
+
+## E2E tests
+
+Use only when:
+
+- the project already has reliable E2E infrastructure,
+- the path is user-critical,
+- required external services are stable, controlled, or safely mocked,
+- the same confidence cannot be gained from faster integration tests.
+
+If E2E is unreliable or too costly, add stronger integration coverage and state the reason.
+
+## Edge and adversarial coverage
+
+Consider:
+
+- null, empty, malformed, duplicate, oversized, and boundary inputs,
+- unauthorized actors and invalid transitions,
+- stale, duplicate, out-of-order, or replayed events,
+- dependency timeout, 429/500, partial response, and inconsistent response,
+- partial write, rollback, compensation, and idempotency behavior,
+- concurrency or shared-state contamination when the code is stateful.
+
+## Test hygiene
+
+- Keep tests deterministic and close to the behavior owner.
+- Prefer table-driven cases for many similar business permutations.
+- Preserve failing seeds or examples from property-based tests.
+- Do not weaken existing tests to fit the refactor.
+- If old tests asserted implementation details, rewrite them around stable behavior while preserving the business invariant.

package/lib/cli.js

@@ -3,6 +3,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const {
+  TARGET_DEFINITIONS,
   VALID_MODES,
   installLinks,
   normalizeModes,
@@ -15,11 +16,7 @@ const { checkForPackageUpdate } = require('./updater');
 
 const TARGET_OPTIONS = [
   { id: 'all', label: 'All', description: 'Install every supported target below' },
-  { id: 'codex', label: 'Codex', description: '~/.codex/skills' },
-  { id: 'openclaw', label: 'OpenClaw', description: '~/.openclaw/workspace*/skills' },
-  { id: 'trae', label: 'Trae', description: '~/.trae/skills' },
-  { id: 'agents', label: 'Agents', description: '~/.agents/skills' },
-  { id: 'claude-code', label: 'Claude Code', description: '~/.claude/skills' },
+  ...TARGET_DEFINITIONS,
 ];
 
 const WORDMARK_LINES = [
@@ -64,6 +61,22 @@ function buildBanner({ version, colorEnabled }) {
   ].join('\n');
 }
 
+function buildModeUsagePattern() {
+  return `${VALID_MODES.join('|')}|all`;
+}
+
+function buildInteractiveModeHint() {
+  const quotedModes = [...VALID_MODES, 'all'].map((mode) => `\`${mode}\``);
+  return `${quotedModes.slice(0, -1).join(', ')}, or ${quotedModes.at(-1)}`;
+}
+
+function buildSupportedTargetLines({ colorEnabled }) {
+  const labelWidth = TARGET_DEFINITIONS.reduce((max, target) => Math.max(max, target.label.length), 0);
+  return TARGET_DEFINITIONS.map((target) => (
+    `  ${color(target.label.padEnd(labelWidth, ' '), '1', colorEnabled)} ${target.description}`
+  )).join('\n');
+}
+
 function buildWelcomeScreen({ version, colorEnabled, stage = 4 }) {
   const lines = [buildBanner({ version, colorEnabled })];
 
@@ -90,11 +103,7 @@ function buildWelcomeScreen({ version, colorEnabled, stage = 4 }) {
     lines.push(
       '',
       color('Supported targets:', '2', colorEnabled),
-      `  ${color('Codex', '1', colorEnabled)}     ~/.codex/skills`,
-      `  ${color('OpenClaw', '1', colorEnabled)}  ~/.openclaw/workspace*/skills`,
-      `  ${color('Trae', '1', colorEnabled)}      ~/.trae/skills`,
-      `  ${color('Agents', '1', colorEnabled)}     ~/.agents/skills`,
-      `  ${color('Claude Code', '1', colorEnabled)} ~/.claude/skills`,
+      buildSupportedTargetLines({ colorEnabled }),
     );
   }
 
@@ -123,8 +132,8 @@ function buildHelpText({ version, colorEnabled }) {
     buildBanner({ version, colorEnabled }),
     '',
     'Usage:',
-    '  apltk [install] [codex|openclaw|trae|agents|claude-code|all]...',
-    '  apollo-toolkit [install] [codex|openclaw|trae|agents|claude-code|all]...',
+    `  apltk [install] [${buildModeUsagePattern()}]...`,
+    `  apollo-toolkit [install] [${buildModeUsagePattern()}]...`,
     '  apltk tools',
     '  apltk <tool> [...args]',
     '  apltk tools <tool> [...args]',
@@ -270,7 +279,7 @@ function renderSelectionScreen({ output, version, cursor, selected, message, env
 
 async function promptForModes({ stdin, stdout, version, env }) {
   if (!stdin.isTTY || !stdout.isTTY) {
-    throw new Error('Interactive install requires a TTY. Re-run with targets like `codex`, `openclaw`, `trae`, `claude-code`, or `all`.');
+    throw new Error(`Interactive install requires a TTY. Re-run with targets like ${buildInteractiveModeHint()}.`);
   }
 
   await animateWelcomeScreen({ output: stdout, version, env });

package/lib/installer.js

@@ -3,7 +3,14 @@ const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 
-const VALID_MODES = ['codex', 'openclaw', 'trae', 'agents', 'claude-code'];
+const TARGET_DEFINITIONS = Object.freeze([
+  { id: 'codex', label: 'Codex', description: '~/.codex/skills' },
+  { id: 'openclaw', label: 'OpenClaw', description: '~/.openclaw/workspace*/skills' },
+  { id: 'trae', label: 'Trae', description: '~/.trae/skills' },
+  { id: 'agents', label: 'Agents', description: '~/.agents/skills' },
+  { id: 'claude-code', label: 'Claude Code', description: '~/.claude/skills' },
+]);
+const VALID_MODES = TARGET_DEFINITIONS.map(({ id }) => id);
 const COPY_FILES = new Set(['AGENTS.md', 'CHANGELOG.md', 'LICENSE', 'README.md', 'package.json']);
 const COPY_DIRS = new Set(['scripts']);
 
@@ -63,7 +70,7 @@ function normalizeModes(inputModes) {
 
 async function listSkillNames(rootDir, modes = []) {
   const entries = await fsp.readdir(rootDir, { withFileTypes: true });
-  const skillNames = [];
+  const skillNames = new Set();
 
   for (const entry of entries) {
     if (!entry.isDirectory()) {
@@ -71,7 +78,7 @@ async function listSkillNames(rootDir, modes = []) {
     }
 
     if (fs.existsSync(path.join(rootDir, entry.name, 'SKILL.md'))) {
-      skillNames.push(entry.name);
+      skillNames.add(entry.name);
     }
   }
 
@@ -82,13 +89,42 @@ async function listSkillNames(rootDir, modes = []) {
       const codexEntries = await fsp.readdir(codexDir, { withFileTypes: true });
       for (const entry of codexEntries) {
         if (entry.isDirectory() && fs.existsSync(path.join(codexDir, entry.name, 'SKILL.md'))) {
-          skillNames.push(entry.name);
+          skillNames.add(entry.name);
         }
       }
     }
   }
 
-  return skillNames.sort();
+  return [...skillNames].sort();
+}
+
+async function listCodexSkillNames(rootDir) {
+  const codexDir = path.join(rootDir, 'codex');
+  if (!fs.existsSync(codexDir)) {
+    return [];
+  }
+
+  const entries = await fsp.readdir(codexDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(codexDir, entry.name, 'SKILL.md')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function getTargetSkillNames({ targetMode, sharedSkillNames, codexSkillNames }) {
+  if (targetMode !== 'codex') {
+    return sharedSkillNames;
+  }
+
+  return [...new Set([...sharedSkillNames, ...codexSkillNames])].sort();
+}
+
+function resolveInstallSourcePath({ toolkitHome, targetMode, skillName, codexSkillNames }) {
+  if (targetMode === 'codex' && codexSkillNames.includes(skillName)) {
+    return path.join(toolkitHome, 'codex', skillName);
+  }
+
+  return path.join(toolkitHome, skillName);
 }
 
 function shouldCopyEntry(sourceRoot, entry) {
@@ -265,24 +301,33 @@ async function replaceWithCopy(sourcePath, targetPath) {
 
 async function installLinks({ toolkitHome, modes, env = process.env, previousSkillNames = [] }) {
   const normalizedModes = normalizeModes(modes);
-  const skillNames = await listSkillNames(toolkitHome, normalizedModes);
+  const sharedSkillNames = await listSkillNames(toolkitHome);
+  const codexSkillNames = normalizedModes.includes('codex') ? await listCodexSkillNames(toolkitHome) : [];
+  const skillNames = normalizedModes.includes('codex')
+    ? [...new Set([...sharedSkillNames, ...codexSkillNames])].sort()
+    : sharedSkillNames;
   const targets = await getTargetRoots(normalizedModes, env);
   const copiedPaths = [];
-  const staleSkillNames = previousSkillNames.filter((skillName) => !skillNames.includes(skillName));
 
   for (const target of targets) {
+    const targetSkillNames = getTargetSkillNames({
+      targetMode: target.mode,
+      sharedSkillNames,
+      codexSkillNames,
+    });
+    const staleSkillNames = previousSkillNames.filter((skillName) => !targetSkillNames.includes(skillName));
+
     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) {
-      // For codex skills, use the ./codex/ subdirectory as source
-      let sourcePath;
-      if (normalizedModes.includes('codex') && fs.existsSync(path.join(toolkitHome, 'codex', skillName))) {
-        sourcePath = path.join(toolkitHome, 'codex', skillName);
-      } else {
-        sourcePath = path.join(toolkitHome, skillName);
-      }
+    for (const skillName of targetSkillNames) {
+      const sourcePath = resolveInstallSourcePath({
+        toolkitHome,
+        targetMode: target.mode,
+        skillName,
+        codexSkillNames,
+      });
       const targetPath = path.join(target.root, skillName);
       await replaceWithCopy(sourcePath, targetPath);
       copiedPaths.push({ target: target.label, path: targetPath, skillName });
@@ -298,6 +343,7 @@ async function installLinks({ toolkitHome, modes, env = process.env, previousSki
 
 module.exports = {
   expandUserPath,
+  TARGET_DEFINITIONS,
   VALID_MODES,
   getTargetRoots,
   installLinks,

package/package.json

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

package/scripts/install_skills.ps1

@@ -110,15 +110,16 @@ else {
   $RepoRoot = $ToolkitHome
 }
 
-function Get-SkillPaths {
+function Get-SkillPathGroups {
   param([string[]]$SelectedModes)
 
   $dirs = Get-ChildItem -Path $RepoRoot -Directory | Sort-Object Name
-  $skills = @()
+  $sharedSkills = @()
+  $codexSkills = @()
 
   foreach ($dir in $dirs) {
     if (Test-Path -LiteralPath (Join-Path $dir.FullName "SKILL.md") -PathType Leaf) {
-      $skills += $dir.FullName
+      $sharedSkills += $dir.FullName
     }
   }
 
@@ -129,17 +130,20 @@ function Get-SkillPaths {
       $codexDirs = Get-ChildItem -Path $codexDir -Directory | Sort-Object Name
       foreach ($dir in $codexDirs) {
         if (Test-Path -LiteralPath (Join-Path $dir.FullName "SKILL.md") -PathType Leaf) {
-          $skills += $dir.FullName
+          $codexSkills += $dir.FullName
         }
       }
     }
   }
 
-  if ($skills.Count -eq 0) {
+  if ($sharedSkills.Count -eq 0) {
     throw "No skill folders found in: $RepoRoot"
   }
 
-  return $skills
+  [PSCustomObject]@{
+    Shared = $sharedSkills
+    Codex = $codexSkills
+  }
 }
 
 function Add-ModeOnce {
@@ -343,15 +347,15 @@ if ($Modes.Count -gt 0 -and ($Modes[0] -eq "-h" -or $Modes[0] -eq "--help")) {
 }
 
 $selectedModes = Resolve-Modes -Requested $Modes
-$skillPaths = Get-SkillPaths -SelectedModes $selectedModes
+$skillPathGroups = Get-SkillPathGroups -SelectedModes $selectedModes
 
 foreach ($mode in $selectedModes) {
   switch ($mode) {
-    "codex" { Install-Codex -SkillPaths $skillPaths }
-    "openclaw" { Install-OpenClaw -SkillPaths $skillPaths }
-    "trae" { Install-Trae -SkillPaths $skillPaths }
-    "agents" { Install-Agents -SkillPaths $skillPaths }
-    "claude-code" { Install-ClaudeCode -SkillPaths $skillPaths }
+    "codex" { Install-Codex -SkillPaths ($skillPathGroups.Shared + $skillPathGroups.Codex) }
+    "openclaw" { Install-OpenClaw -SkillPaths $skillPathGroups.Shared }
+    "trae" { Install-Trae -SkillPaths $skillPathGroups.Shared }
+    "agents" { Install-Agents -SkillPaths $skillPathGroups.Shared }
+    "claude-code" { Install-ClaudeCode -SkillPaths $skillPathGroups.Shared }
     default { throw "Unknown mode: $mode" }
   }
 }

package/scripts/install_skills.sh

@@ -78,14 +78,16 @@ else
   SCRIPT_DIR="$REPO_ROOT/scripts"
 fi
 SELECTED_MODES=()
-SKILL_PATHS=()
+SHARED_SKILL_PATHS=()
+CODEX_SKILL_PATHS=()
 
 collect_skills() {
   local dir
-  SKILL_PATHS=()
+  SHARED_SKILL_PATHS=()
+  CODEX_SKILL_PATHS=()
   while IFS= read -r dir; do
     if [[ -f "$dir/SKILL.md" ]]; then
-      SKILL_PATHS+=("$dir")
+      SHARED_SKILL_PATHS+=("$dir")
     fi
   done < <(find "$REPO_ROOT" -mindepth 1 -maxdepth 1 -type d | sort)
 
@@ -95,13 +97,13 @@ collect_skills() {
     if [[ -d "$codex_dir" ]]; then
       while IFS= read -r dir; do
         if [[ -f "$dir/SKILL.md" ]]; then
-          SKILL_PATHS+=("$dir")
+          CODEX_SKILL_PATHS+=("$dir")
         fi
       done < <(find "$codex_dir" -mindepth 1 -maxdepth 1 -type d | sort)
     fi
   fi
 
-  if [[ ${#SKILL_PATHS[@]} -eq 0 ]]; then
+  if [[ ${#SHARED_SKILL_PATHS[@]} -eq 0 ]]; then
     echo "No skill folders found in: $REPO_ROOT" >&2
     exit 1
   fi
@@ -124,17 +126,17 @@ replace_with_copy() {
 }
 
 install_codex() {
-  local codex_skills_dir
+  local codex_skills_dir src
   codex_skills_dir="$(expand_user_path "${CODEX_SKILLS_DIR:-$HOME/.codex/skills}")"
 
   echo "Installing to codex: $codex_skills_dir"
-  for src in "${SKILL_PATHS[@]}"; do
+  for src in "${SHARED_SKILL_PATHS[@]}" "${CODEX_SKILL_PATHS[@]}"; do
     replace_with_copy "$src" "$codex_skills_dir"
   done
 }
 
 install_openclaw() {
-  local openclaw_home workspace skills_dir
+  local openclaw_home workspace skills_dir src
   local -a workspaces
 
   openclaw_home="$(expand_user_path "${OPENCLAW_HOME:-$HOME/.openclaw}")"
@@ -152,38 +154,38 @@ install_openclaw() {
   for workspace in "${workspaces[@]}"; do
     skills_dir="$workspace/skills"
     echo "Installing to openclaw workspace: $skills_dir"
-    for src in "${SKILL_PATHS[@]}"; do
+    for src in "${SHARED_SKILL_PATHS[@]}"; do
       replace_with_copy "$src" "$skills_dir"
     done
   done
 }
 
 install_trae() {
-  local trae_skills_dir
+  local trae_skills_dir src
   trae_skills_dir="$(expand_user_path "${TRAE_SKILLS_DIR:-$HOME/.trae/skills}")"
 
   echo "Installing to trae: $trae_skills_dir"
-  for src in "${SKILL_PATHS[@]}"; do
+  for src in "${SHARED_SKILL_PATHS[@]}"; do
     replace_with_copy "$src" "$trae_skills_dir"
   done
 }
 
 install_agents() {
-  local agents_skills_dir
+  local agents_skills_dir src
   agents_skills_dir="$(expand_user_path "${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}")"
 
   echo "Installing to agents: $agents_skills_dir"
-  for src in "${SKILL_PATHS[@]}"; do
+  for src in "${SHARED_SKILL_PATHS[@]}"; do
     replace_with_copy "$src" "$agents_skills_dir"
   done
 }
 
 install_claude_code() {
-  local claude_code_skills_dir
+  local claude_code_skills_dir src
   claude_code_skills_dir="$(expand_user_path "${CLAUDE_CODE_SKILLS_DIR:-$HOME/.claude/skills}")"
 
   echo "Installing to claude-code: $claude_code_skills_dir"
-  for src in "${SKILL_PATHS[@]}"; do
+  for src in "${SHARED_SKILL_PATHS[@]}"; do
     replace_with_copy "$src" "$claude_code_skills_dir"
   done
 }
@@ -233,7 +235,7 @@ read_choice_from_user() {
   elif [[ -r /dev/tty ]]; then
     read -r -p "$prompt" result < /dev/tty
   else
-    echo "Interactive input unavailable. Pass mode arguments (e.g. codex/openclaw/trae/all)." >&2
+    echo "Interactive input unavailable. Pass mode arguments (e.g. codex/openclaw/trae/agents/claude-code/all)." >&2
     exit 1
   fi
 
@@ -264,7 +266,7 @@ choose_modes_interactive() {
       3) add_mode_once "trae" ;;
       4) add_mode_once "agents" ;;
       5) add_mode_once "claude-code" ;;
-      6) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae"; add_mode_once "claude-code" ;;
+      6) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae"; add_mode_once "agents"; add_mode_once "claude-code" ;;
       *)
         echo "Invalid choice: $raw_choice" >&2
         exit 1