@laitszkin/apollo-toolkit 2.4.3 → 2.6.0

package/solana-development/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: solana-development
+description: Build or maintain Solana applications in Rust using official Solana development docs. Use when users ask for native Solana programs, Rust SDK clients, account modeling, instruction design, PDAs, CPIs, local testing, deployment, upgrades, or Solana-specific debugging in Rust codebases.
+---
+
+# Solana Development
+
+## Dependencies
+
+- Required: none.
+- Conditional: `systematic-debug` when the task is about failing Solana tests, runtime errors, or observed-vs-expected on-chain behavior.
+- Optional: none.
+- Fallback: If the repository pins Solana crates or CLI behavior that differs from the latest official docs, follow the repository's pinned versions and document the mismatch explicitly.
+
+## Standards
+
+- Evidence: Ground commands, crate choices, and account-model decisions in the current repository plus official Solana docs under `solana.com/docs`.
+- Execution: Classify the task as on-chain Rust, off-chain Rust client work, or both before changing code.
+- Quality: Prefer minimal account surfaces, explicit instruction schemas, deterministic PDA seeds, and tests for every state transition or authority check.
+- Output: Deliver Rust-focused changes with touched accounts, instructions, test commands, deployment notes, and any cluster or authority assumptions.
+
+## Goal
+
+Implement Solana Rust work in a way that matches the official execution model: accounts and instructions first, then PDAs/CPIs, then testing and deployment safety.
+
+## Required Reference
+
+- Read `references/official-solana-rust.md` before making non-trivial Solana changes.
+- Refresh the linked official pages when crate versions, CLI commands, or deployment behavior appear different from the reference snapshot.
+
+## Use This Skill For
+
+- Native Solana programs written directly in Rust
+- Rust clients, indexers, or operational tools built with the Solana Rust SDK
+- Account modeling, authority rules, PDA design, and CPI orchestration
+- Local validator workflows, Rust-native tests, build/deploy/upgrade flows
+- Solana-specific debugging such as signer, owner, writable, rent, compute, and instruction-data issues
+
+## Workflow
+
+### 1) Classify the repository shape first
+
+- Identify whether the codebase contains on-chain programs, Rust clients, or both.
+- Detect whether the repository uses native Solana Rust or a higher-level framework already. Do not rewrite framework conventions unless the user asks.
+- Locate program IDs, deploy scripts, test harnesses, keypair handling, and cluster configuration before editing.
+
+### 2) Design the instruction and account contract up front
+
+- List each instruction, the accounts it needs, which accounts must be signer or writable, and which program owns each account.
+- Record PDA seeds, bump handling, rent expectations, realloc rules, and close authorities before implementing handlers.
+- Reject invalid ownership, signer, and writable assumptions explicitly instead of relying on downstream runtime failures.
+
+### 3) Keep native Rust program structure explicit
+
+- Follow the official native Rust flow: `entrypoint` receives the program call, instruction parsing is explicit, and processor logic is separated from account data definitions.
+- Keep serialization and versioning explicit for any state stored inside accounts.
+- Prefer custom program errors over panics so failures remain diagnosable.
+
+### 4) Use PDAs and CPIs deliberately
+
+- Use PDAs for program-controlled state or authorities that should not require a private key.
+- Use `invoke` for regular cross-program calls and `invoke_signed` only when the current program must sign as one of its PDAs.
+- Treat signer and writable privileges as inherited, not escalated; verify every CPI account list carefully.
+
+### 5) Choose the correct Rust crates for the job
+
+- For on-chain code, center the implementation around `solana-program`.
+- For off-chain Rust clients and tooling, use `solana-sdk` for transaction primitives and `solana-client` for RPC access.
+- When a project mirrors CLI behavior, inspect whether it also depends on `solana-cli-config` or `solana-clap-utils`.
+
+### 6) Validate locally before deploy
+
+- Prefer fast Rust-native tests first, then run the repository's validator or end-to-end flow if available.
+- Build with the repository's pinned toolchain when present; otherwise use the current official Solana build/deploy workflow from the reference.
+- Exercise account initialization, authority checks, PDA signing, and failure paths instead of only happy-path success.
+
+### 7) Deploy and upgrade safely
+
+- Confirm target cluster, payer, program ID, and upgrade authority before deploy.
+- Call out any action that makes a program immutable or permanently closes program state.
+- When deployment changes operational assumptions, summarize the exact commands and authority implications in the final handoff.
+
+## Final Checklist
+
+- Account ownership, signer, writable, and PDA assumptions are explicit
+- Instruction data and state serialization are version-aware where needed
+- Local tests cover success and failure paths for state transitions
+- Deployment or upgrade commands match the target cluster and authority setup
+- Any mismatch between repo-pinned Solana versions and current docs is documented

package/solana-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Solana Development"
+  short_description: "Build Solana Rust programs and clients from official docs"
+  default_prompt: "Use $solana-development to inspect the repository, determine whether the task is on-chain Rust, off-chain Rust client work, or both, follow the official Solana model for accounts, instructions, PDAs, CPIs, testing, and deployment, and deliver concise Rust-focused implementation notes grounded in current Solana docs."

package/solana-development/references/official-solana-rust.md

@@ -0,0 +1,199 @@
+# Official Solana Rust Development Reference
+
+Snapshot date: 2026-03-20 (Asia/Hong_Kong).
+
+Use this file when building, reviewing, or debugging Solana work in Rust. It condenses the most important development guidance from the official Solana documentation so the main skill can stay concise.
+
+## Official source map
+
+- Core accounts: `https://solana.com/docs/core/accounts`
+- Core instructions: `https://solana.com/docs/core/instructions`
+- Core transactions: `https://solana.com/docs/core/transactions`
+- Core fees: `https://solana.com/docs/core/fees`
+- Program Derived Addresses: `https://solana.com/docs/core/pda`
+- Cross Program Invocation: `https://solana.com/docs/core/cpi`
+- Native Rust programs overview: `https://solana.com/docs/programs/rust`
+- Native Rust program structure: `https://solana.com/docs/programs/rust/program-structure`
+- Program deployment and upgrades: `https://solana.com/docs/programs/deploying`
+- Official Rust SDK overview: `https://solana.com/docs/clients/official/rust`
+
+If any page changes structure, search `site:solana.com/docs <topic>` and refresh this reference before locking in version-sensitive commands.
+
+## 1. Core execution model you must preserve
+
+- Solana programs operate by receiving instruction data plus an ordered account list. Most implementation mistakes are really account-contract mistakes.
+- Accounts are the durable storage boundary. Before editing logic, identify each account's owner, mutability, signer requirement, lamports behavior, and serialized data layout.
+- Transactions package one or more instructions and execute atomically. Design instruction handlers with atomic state transitions in mind.
+- The official fees model separates:
+  - base fee, currently documented as `5000` lamports per signature
+  - prioritization fee, computed from compute-unit limit and compute-unit price
+- When performance or cost matters, review compute usage per instruction and avoid unnecessary account writes.
+
+## 2. Native Rust program structure
+
+The official native Rust docs and program-structure page emphasize a small, explicit layout:
+
+- `entrypoint.rs`: Solana entrypoint and handoff into program logic
+- `instruction.rs`: instruction enum / decoding
+- `processor.rs`: instruction handlers and business logic
+- `state.rs`: account data structs and serialization
+- `error.rs`: custom program errors
+
+Keep the logic readable and explicit:
+
+- parse instruction data up front
+- validate account shape before mutation
+- separate state serialization from business logic
+- return `ProgramError`-compatible failures instead of panicking
+
+The official Rust-program walkthrough currently documents these setup details:
+
+- create a library crate
+- add `solana-program` as the primary on-chain dependency
+- set `[lib] crate-type = ["cdylib", "lib"]`
+- build SBF output with the Solana build flow documented on the page
+
+As of the 2026-03-20 snapshot, the official examples show `solana-program@2.2.0` in native Rust setup examples. Re-check before pinning new projects because Solana crate versions move.
+
+## 3. Instruction and account design checklist
+
+Before writing handlers, lock down:
+
+- instruction enum and binary format
+- per-instruction account list order
+- which accounts are signer
+- which accounts are writable
+- which program owns each account
+- PDA seeds and bump strategy
+- account initialization, realloc, close, and rent expectations
+
+Useful rule: every handler should be reviewable from a table with columns for account, owner, signer, writable, PDA seeds, and failure conditions.
+
+## 4. Program Derived Addresses (PDAs)
+
+Official PDA guidance centers on these ideas:
+
+- A PDA is a deterministic address derived from seeds plus a program ID.
+- PDAs are intentionally off the Ed25519 curve, so they have no private key.
+- Programs use PDAs for program-controlled authorities and state accounts.
+- The same seeds plus the same program ID must derive the same PDA every time.
+- The bump seed exists to find a valid off-curve address.
+
+The official PDA page also documents practical limits to remember:
+
+- up to 16 seeds per derivation
+- each seed can be up to 32 bytes
+
+Design advice:
+
+- Use stable, domain-specific seeds such as fixed prefixes plus relevant public keys.
+- Keep seed schemes obvious and documented near the instruction that consumes them.
+- Prefer one clear PDA purpose per seed scheme instead of overloading one PDA for unrelated roles.
+
+## 5. Cross Program Invocation (CPI)
+
+Official CPI guidance highlights:
+
+- Solana programs can invoke instructions in other programs.
+- Use `invoke` when no PDA signature is required.
+- Use `invoke_signed` when the current program must sign on behalf of one of its PDAs.
+- Signer and writable privileges extend from the caller into the callee; CPI does not create new privileges.
+
+Practical implications:
+
+- Validate the entire downstream account list before the CPI.
+- Never assume a callee can write to an account unless the outer instruction passed it as writable.
+- When debugging CPI failures, inspect signer propagation, writable flags, PDA seed correctness, and program ownership first.
+
+The official page notes a practical limit of 16 PDA signers in `invoke_signed`.
+
+## 6. Fees and compute-budget awareness
+
+The official fees page is the baseline for performance-sensitive work:
+
+- base fee is charged per signature
+- prioritization fee depends on compute-unit limit and compute-unit price
+- transactions can set compute budget explicitly when needed
+
+When implementing Rust clients or relayers:
+
+- size transaction account lists carefully
+- avoid unnecessary signatures
+- consider compute budget instructions only when the workflow truly needs them
+
+When implementing programs:
+
+- keep account validation linear and obvious
+- avoid redundant serialization passes
+- separate expensive CPIs from cheap pure-validation paths when possible
+
+## 7. Local testing workflow
+
+Official Solana docs currently show a Rust-native local test flow for native programs.
+
+From the current documentation snapshot:
+
+- official examples show `litesvm@0.6.1` and `solana-sdk@2.2.0` as dev dependencies in the Rust testing walkthrough
+- the docs position LiteSVM as a fast local execution harness for native Rust programs
+
+Recommended execution order:
+
+1. unit-test pure helpers and serialization logic
+2. run Rust-native program tests for instruction/state behavior
+3. run validator-backed integration flow only when the repository or task needs cluster realism
+
+Test the following explicitly:
+
+- initialization and duplicate-initialization rejection
+- authority checks
+- signer and writable enforcement
+- PDA derivation and PDA signing flows
+- state transitions, close flows, and realloc paths
+- failure paths for malformed instruction data or wrong account order
+
+## 8. Deployment, upgrades, and irreversible operations
+
+The official deployment docs cover the core operational loop:
+
+- local development often starts with `solana-test-validator`
+- deploy with `solana program deploy ...`
+- visibility can lag by roughly one slot after deployment
+- a program becomes immutable when its upgrade authority is removed
+- `solana program close` permanently closes the program and the same program ID cannot be reused for redeployment
+
+Before any deploy or upgrade:
+
+- confirm cluster URL
+- confirm payer keypair
+- confirm intended program ID
+- confirm upgrade authority ownership
+- confirm whether the deploy changes any downstream configuration or address registry
+
+For production-facing tasks, always surface immutable or close operations as explicit risk points in the handoff.
+
+## 9. Official Rust SDK crate roles
+
+The official Rust SDK overview maps the common crates this way:
+
+- `solana-program`: on-chain program primitives
+- `solana-sdk`: transactions, instructions, keypairs, signatures, and shared primitives for Rust clients
+- `solana-client`: RPC access for off-chain Rust applications
+- `solana-cli-config`: reuse CLI config from Rust tools
+- `solana-clap-utils`: CLI-oriented helper utilities
+
+Default crate choice:
+
+- on-chain program logic: `solana-program`
+- Rust service/tool that talks to RPC: `solana-sdk` + `solana-client`
+- Rust CLI that should mirror Solana CLI config behavior: add `solana-cli-config`
+
+## 10. When to refresh the official docs before coding
+
+Refresh the linked pages instead of relying on this snapshot when:
+
+- the repository pins newer or older Solana crate versions
+- CLI subcommands or flags differ from this reference
+- the task depends on recently changed runtime features
+- the repository uses Anchor or another framework that wraps native Solana APIs
+
+When docs and code disagree, preserve the repository's actual pinned behavior and note the divergence.

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