opencode-skills-collection 4.0.36 → 4.0.38

package/README.md

@@ -208,14 +208,17 @@ skipped silently. Re-running the pipeline with the same patches is idempotent.
 
 ## Development
 
-**Requirements:** Node.js ≥ 20, TypeScript ≥ 5
+**Requirements:** Bun ≥ 1.3
 
 ```bash
 # Install dependencies
-npm install
+bun install
 
 # Build
-npm run build
+bun run build
+
+# Test
+bun test
 
 # Output is in dist/
 ```

package/bundled-skills/.antigravity-install-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "updatedAt": "2026-08-19T00:32:21.776Z",
+  "updatedAt": "2026-08-21T00:34:53.602Z",
   "entries": [
     "00-andruia-consultant",
     "007",
@@ -33,6 +33,7 @@
     "agent-evaluation",
     "agent-evaluation-reporting",
     "agent-framework-azure-ai-py",
+    "agent-harness-fault-injection",
     "agent-manager-skill",
     "agent-memory",
     "agent-memory-mcp",
@@ -171,6 +172,7 @@
     "atlas-ledger",
     "attack-tree-construction",
     "audio-transcriber",
+    "audit-agent-run-evidence",
     "audit-context-building",
     "audit-skills",
     "auri-core",
@@ -349,6 +351,7 @@
     "blockrun",
     "blog-writing-guide",
     "blueprint",
+    "boost-asio-pro",
     "box-automation",
     "brain-to-docs",
     "brainstorming",
@@ -1261,6 +1264,7 @@
     "multi-agent-task-orchestrator",
     "multi-cloud-architecture",
     "multi-platform-apps-multi-platform",
+    "multi-source-search",
     "n8n-agents",
     "n8n-binary-and-data",
     "n8n-code-javascript",
@@ -1531,6 +1535,7 @@
     "reverse-engineer",
     "review-and-simplify-changes",
     "review-animations",
+    "review-multi-agent-orchestration",
     "review-swarm",
     "revops",
     "rich-elicitation",
@@ -1870,6 +1875,7 @@
     "ui-setup",
     "ui-skills",
     "ui-skills-root",
+    "ui-slop-score",
     "ui-tokens",
     "ui-update",
     "ui-ux-designer",

package/bundled-skills/agent-harness-fault-injection/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: agent-harness-fault-injection
+description: "Use when an agent workflow needs deterministic recovery evidence for sandbox, MCP/tool, worker, checkpoint, memory, or orchestration failures."
+category: development
+risk: safe
+source: self
+source_type: self
+date_added: "2026-08-19"
+author: Whxuan0701
+tags: [agent-harness, fault-injection, recovery, state-machine, mcp, multi-agent]
+tools: [claude, cursor, gemini, codex-cli]
+---
+
+# Agent Harness Fault Injection
+
+## Overview
+
+Use a deterministic, non-production fault schedule to test whether an agent
+workflow preserves state, budgets, safety boundaries, and evidence when a
+dependency fails. The output is a small fault matrix, an event timeline, and a
+verdict that distinguishes recovered, contained, unrecoverable, and
+inconclusive runs.
+
+## When to Use This Skill
+
+- Use when a multi-step agent, state machine, loop, or multi-agent workflow has a new recovery path.
+- Use when sandbox execution, an MCP/tool call, a worker, a checkpoint store, or memory can time out or disappear.
+- Use before claiming retry, resume, deadline, isolation, or partial-failure behavior is production-ready.
+- Use when a regression needs reproducible failure evidence instead of a random chaos run.
+
+Do not use this skill against a production target, real user data, live credentials,
+or an unbounded external service. Convert those cases to a local simulator or an
+authorized staging harness first.
+
+## Safety and Boundary Preconditions
+
+1. Freeze the workflow revision, model/prompt configuration, tool schemas, seed,
+   input fixture, timeout, retry budget, deadline, and expected terminal states.
+2. Run in a disposable sandbox with synthetic inputs and stubbed tools. Keep
+   network disabled unless the test explicitly needs a local test server.
+3. Make every injected failure an in-memory or fixture-controlled event. Never
+   delete real data, revoke real credentials, kill an unrelated process, or
+   mutate a live service to create a failure.
+4. Record the test scope and a run identifier before starting. A missing scope,
+   fixture, or recovery contract makes the verdict `inconclusive`.
+
+## Recovery Contract
+
+Write the invariant before injecting a fault. A useful contract names the state
+that must survive and the side effects that must not repeat:
+
+```text
+After recovery, resume from the latest durable checkpoint, preserve the task
+identity and safety policy, spend no more than the remaining retry/deadline
+budget, and commit each externally visible effect at most once.
+```
+
+Model the workflow with explicit states. For example:
+
+```text
+created -> running -> checkpointed -> waiting_for_tool
+                       |                |
+                       v                v
+                    failed <--------- recovering -> resumed -> completed
+```
+
+For each transition, define the owner, durable fields, allowed retry count,
+and terminal behavior. In-memory values are not checkpoints unless the harness
+proves they survive the simulated restart.
+
+## Fault Matrix
+
+Select the smallest set of faults that covers the new recovery logic. Do not
+randomize the schedule until a deterministic schedule has passed.
+
+| Fault | Injection boundary | Required observation | Expected containment |
+|---|---|---|---|
+| sandbox denial | before a tool starts | no unsafe side effect; reason is retained | retry only when policy allows |
+| MCP/tool timeout | after request id is assigned | timeout is attributed to that request | bounded retry with same idempotency key |
+| worker restart | after checkpoint write | worker reloads the same task version | resume from latest checkpoint |
+| missing/stale checkpoint | before resume | stale data is rejected or marked | stop safely; never invent progress |
+| parallel branch failure | one branch after fan-out | sibling status is preserved | join policy decides retry, degrade, or stop |
+| memory loss | clear ephemeral context | durable facts are reconstructed | ask or stop when required facts are absent |
+| retry/deadline exhaustion | on the final attempt | no extra call is scheduled | terminal `failed` or `timed_out` |
+
+## Deterministic Injection Schedule
+
+Use event numbers rather than wall-clock randomness. A schedule should be
+portable across harnesses:
+
+```json
+{
+  "seed": "harness-fixture-07",
+  "faults": [
+    {"event": "tool.call", "ordinal": 2, "kind": "timeout", "tool": "search"},
+    {"event": "worker.start", "ordinal": 2, "kind": "restart"},
+    {"event": "branch.join", "ordinal": 1, "kind": "partial_failure", "branch": "summarize"}
+  ]
+}
+```
+
+The harness should emit the schedule, not merely the seed. Keep fault identity
+separate from the observed error so a wrapper cannot accidentally turn a
+timeout into a generic failure. Run the same schedule twice and compare the
+normalized timeline before trying a different schedule.
+
+## Recovery Rules by Boundary
+
+### Sandbox and MCP/tool failures
+
+- Assign a request id and idempotency key before the call.
+- Distinguish timeout, explicit tool error, invalid output, and policy denial.
+- Retry only the declared retryable classes; preserve the original error and
+  attempt count in the evidence.
+- Do not retry a side effect unless the tool contract says the key is safe to
+  replay. A read timeout is not proof that a write did not happen.
+- When the deadline or retry budget is exhausted, emit one terminal event and
+  stop scheduling work.
+
+### Worker restart and checkpoints
+
+- Persist task id, workflow version, state name, completed effects, remaining
+  budgets, and the checkpoint sequence before a restart test.
+- Reload the newest valid checkpoint and reject a future-version or corrupted
+  checkpoint instead of guessing.
+- Verify that resumption does not replay a committed effect. If exactly-once
+  cannot be proven, downgrade the verdict and require reconciliation.
+
+### Parallel branches
+
+Represent each branch as its own child attempt. The join record must retain
+success, failure, timeout, and not-started states. Choose one predeclared join
+policy:
+
+- `all_required`: any required branch failure stops the join;
+- `best_effort`: continue with an explicit degraded marker;
+- `compensate`: run a bounded compensating action and then stop or resume.
+
+Never let a successful sibling erase a failed branch from the final ledger.
+
+### Memory loss
+
+Clear only the ephemeral context named in the schedule. Rebuild from the
+checkpoint and durable evidence, then check that the agent does not fabricate
+missing user intent, tool output, or approval. If a required fact is absent,
+the safe result is `inconclusive` or a human clarification state.
+
+## Budgets and Terminal Verdicts
+
+Track remaining attempts and remaining time after every event. Do not reset a
+budget on a worker restart or branch retry. Use these verdicts:
+
+| Verdict | Meaning |
+|---|---|
+| `recovered` | The declared invariant held and the workflow completed within budget. |
+| `contained_failure` | The fault was isolated and the workflow stopped safely as designed. |
+| `unrecoverable` | Recovery violated an invariant, repeated a side effect, crossed a boundary, or exceeded budget. |
+| `inconclusive` | The fixture, checkpoint, contract, or evidence was insufficient to judge. |
+
+`contained_failure` is not autonomous success. Report it separately from
+completed work and include the terminal reason.
+
+## Evidence Output
+
+Produce one machine-readable record and one concise human summary. Every event
+should include `run_id`, monotonic `seq`, logical `time`, `state_before`,
+`state_after`, `actor`, `event`, `fault_id` (when injected), `attempt`,
+`checkpoint_seq`, `retry_remaining`, `deadline_remaining_ms`, and a redacted
+`evidence_ref`.
+
+```json
+{
+  "run_id": "fi-2026-08-19-07",
+  "verdict": "recovered",
+  "invariants": {"resume_from_checkpoint": "pass", "effect_at_most_once": "pass", "budget": "pass"},
+  "faults": [{"id": "f1", "kind": "tool_timeout", "at": "tool.call#2", "handled": true}],
+  "timeline": [
+    {"seq": 4, "event": "checkpoint.write", "checkpoint_seq": 3},
+    {"seq": 5, "event": "tool.timeout", "fault_id": "f1", "retry_remaining": 1},
+    {"seq": 8, "event": "workflow.completed", "checkpoint_seq": 4}
+  ],
+  "limitations": ["Tool output was synthetic; no deployed MCP was exercised."]
+}
+```
+
+The human summary should state the frozen contract, injected schedule, verdict,
+failed invariants, budget consumption, and the narrowest next verification.
+Redact prompts, tokens, private records, and tool payloads; stable references
+are enough for replay.
+
+## Example: Local Harness Run
+
+```text
+Fixture: checkout planner / seed harness-fixture-07
+Schedule: search timeout on call 2; worker restart after checkpoint 3
+Policy: one retry, 2s deadline, all_required branch join
+
+Result: recovered
+Proof: checkpoint 3 reloaded, search request key replayed once, no duplicate
+commit, deadline remaining 640ms, final ledger contains both branch outcomes.
+```
+
+## Best Practices
+
+- Freeze inputs and schedules so a failure can be replayed from the evidence.
+- Test one boundary at a time, then add a combined schedule for interaction risk.
+- Assert invariants after every recovery transition, not only at final output.
+- Keep attempt-level faults and task-level outcomes in separate ledgers.
+- Treat missing evidence as `inconclusive`, never as a passing recovery.
+
+## Limitations
+
+- A local stub cannot prove behavior of a deployed model, MCP server, scheduler,
+  filesystem, or network.
+- Deterministic schedules cover named paths; they do not estimate random-fault
+  frequency or discover unknown failure modes.
+- At-most-once effects require an idempotent, observable contract; a timeline
+  alone cannot prove an external write was not duplicated.
+- This skill does not select production SLOs, repair broken workflows, or grant
+  permission to test systems outside the declared sandbox.
+
+## Security & Safety Notes
+
+- Keep tests local-only and read-only by default; use synthetic fixtures and
+  fake credentials that cannot access a real account.
+- Require explicit authorization and a disposable staging boundary before any
+  test that could contact a non-local service.
+- Do not include destructive commands, exploit payloads, credential material,
+  or automatic cleanup of user data in a harness or report.
+- Redact secrets and personal data before storing timelines or attaching them
+  to a pull request.
+
+## Common Pitfalls
+
+- **Problem:** A retry clears the original timeout and hides the fault.
+  **Solution:** Keep fault id, original class, attempt, and retry lineage in the ledger.
+- **Problem:** A restart passes because the test reused in-memory state.
+  **Solution:** Serialize, clear, and reload only the declared checkpoint fields.
+- **Problem:** A partial fan-out is reported as success.
+  **Solution:** Preserve every branch state and apply the predeclared join policy.
+- **Problem:** A missing checkpoint is replaced with guessed progress.
+  **Solution:** Stop safely and return `inconclusive` or `unrecoverable` with evidence.
+- **Problem:** A green final answer hides a deadline or duplicate-effect violation.
+  **Solution:** Gate the verdict on invariants and remaining budget, not output text alone.
+
+## Related Skills
+
+- `@agent-evaluation-reporting` - Report autonomous, assisted, failed, timed-out, and invalid outcomes.
+- `@cross-platform-contract-propagation-audit` - Trace recovery fields and status contracts across consumers.
+- `@multi-agent-patterns` - Choose a multi-agent topology before testing its failure behavior.

package/bundled-skills/audit-agent-run-evidence/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: audit-agent-run-evidence
+description: "Use when an agent, harness, gateway, MCP workflow, or multi-step automation claims completion and the available traces, checkpoints, approvals, tool calls, or deployment records must be judged without trusting self-reported success."
+risk: safe
+source: self
+date_added: "2026-08-19"
+---
+
+# Audit Agent Run Evidence
+
+## Overview
+
+Turn an end-to-end success statement into independently decidable claims. Reconstruct what happened from available records, grade each claim against the strongest witness, and keep missing evidence distinct from failure.
+
+This is a read-only audit. Do not rerun tools, approve actions, resume workers, deploy artifacts, or modify evidence unless the user separately authorizes those actions.
+
+## When to Use
+
+- Auditing a completed or interrupted agent run from traces and artifacts.
+- Checking whether an agent's end-to-end success claim is actually supported.
+- Reviewing MCP, gateway, sandbox, checkpoint, retry, memory, approval, or deployment evidence.
+- Separating autonomous success from human-assisted or merely requested outcomes.
+
+Do not use this skill to design instrumentation for a future run or to perform the missing actions. It evaluates evidence that already exists.
+
+## Establish the Contract
+
+Record these inputs before judging the run:
+
+- declared goal and terminal success criteria;
+- run, workflow, task, and parent identifiers;
+- immutable code, configuration, model, prompt, tool-schema, and artifact revisions when available;
+- actors and trust boundaries: orchestrator, worker, sandbox, MCP server, gateway, human approver, CI, and deployment platform;
+- retry, deadline, token, cost, concurrency, and human-escalation budgets;
+- supplied evidence inventory and known collection gaps.
+
+Do not silently strengthen the original success criteria. Do not weaken them to match the evidence that happens to exist.
+
+## Build a Claim Ledger
+
+Split the overall claim into atomic predicates. Give every row a stable claim ID.
+
+| Field | Required content |
+|---|---|
+| `claim_id` | Stable identifier |
+| `predicate` | One falsifiable statement |
+| `required_witness` | Source that can independently prove it |
+| `evidence_refs` | Exact event, log, artifact, or record IDs |
+| `counterevidence_refs` | Conflicting records |
+| `coverage` | Required instances versus observed instances |
+| `verdict` | `proven`, `partially_proven`, `contradicted`, or `not_proven` |
+| `gap` | Missing field, actor, interval, or verification |
+
+Typical predicates include:
+
+- every required step reached its terminal postcondition;
+- sandbox isolation held for every executing worker;
+- each required MCP/tool call has a correlated response;
+- retries respected idempotency and did not duplicate committed effects;
+- a checkpoint was durably written, verified, and actually used for resume;
+- parallel branches satisfied the declared join policy;
+- memory reads cite a versioned source rather than an untracked summary;
+- retry, deadline, token, cost, and escalation budgets were respected;
+- approval was granted by an authorized human for the exact artifact and target;
+- the platform deployed that same artifact and passed the declared health checks.
+
+## Normalize Evidence
+
+Preserve original records and create a normalized event view with:
+
+```json
+{
+  "run_id": "run-123",
+  "event_id": "evt-42",
+  "sequence": 42,
+  "observed_at": "RFC3339 timestamp",
+  "actor": {"type": "worker", "id": "worker-2"},
+  "operation": "mcp.search",
+  "state_before": "researching",
+  "state_after": "researching",
+  "attempt": 2,
+  "request_id": "req-9",
+  "idempotency_key": "task-7:search:2",
+  "input_digest": "sha256:...",
+  "output_digest": "sha256:...",
+  "checkpoint_seq": 3,
+  "parent_event_id": "evt-41",
+  "status": "succeeded",
+  "evidence_ref": "tool-log:991"
+}
+```
+
+Use `null` or `unknown` for absent values. Never synthesize IDs, timestamps, digests, costs, approvals, or outcomes.
+
+Verify bundle hashes or signatures when supplied. Check duplicate IDs, broken parent links, non-monotonic per-source sequences, impossible state transitions, unaccounted clock skew, and unexplained trace gaps. Treat an integrity failure as counterevidence for claims that depend on the affected records.
+
+## Rank Witnesses
+
+Prefer the witness closest to the effect:
+
+| Claim | Strong witness | Insufficient alone |
+|---|---|---|
+| Code changed | Commit/tree and diff | Agent narration |
+| Test passed | Complete test result bound to revision | Command invocation |
+| MCP effect occurred | Server or provider audit record | Client request |
+| Checkpoint resumed | Durable checkpoint plus verified load event | Checkpoint file exists |
+| Human approved | Authorization-system decision bound to artifact and target | Approval requested |
+| Deployment succeeded | Platform record plus required health checks | Deployment started |
+| Memory grounded a decision | Versioned memory read and citation | Final answer resembles memory |
+
+An orchestrator and its child worker are not independent witnesses when they repeat the same unverified result. A cryptographic digest proves byte identity, not semantic correctness.
+
+## Reconstruct the Run
+
+1. Order events by causal links and per-source sequence; use timestamps only as supporting evidence.
+2. Build the state-transition path and mark every gap or illegal transition.
+3. Link each retry chain by logical operation, request ID, and idempotency key.
+4. Link checkpoints to the state they contain and the resume event that consumes them.
+5. Preserve every parallel branch outcome; apply the declared `all_required`, `quorum`, `first_success`, or other join rule.
+6. Track remaining budgets at each transition. A late success after budget exhaustion is a budget violation.
+7. Bind approvals and deployment records to exact artifact digests and targets.
+
+Do not infer successful completion from a final state label when required intermediate predicates are missing.
+
+## Assign Verdicts
+
+- `proven`: authentic evidence covers every instance of the predicate and no reliable counterevidence remains.
+- `partially_proven`: some required instances or fields are proven and the uncovered portion is named.
+- `contradicted`: reliable evidence conflicts with the predicate.
+- `not_proven`: evidence is absent, circular, unverifiable, or only self-reported.
+
+Use `not_proven`, not `contradicted`, for missing logs. Use `contradicted` when the trace shows a failed health check, duplicate effect, unauthorized approver, corrupt checkpoint, skipped required branch, or exhausted budget.
+
+The end-to-end verdict cannot be stronger than its weakest required predicate. Optional diagnostics may remain unproven without failing the run if they were never part of the declared contract.
+
+## Report
+
+Return sections in this order:
+
+1. **Scope and evidence inventory** — run identity, declared criteria, records inspected, integrity checks.
+2. **Claim ledger** — one row per predicate with verdict and exact references.
+3. **Reconstructed timeline** — only state-changing, fault, retry, checkpoint, join, approval, and deployment events.
+4. **Gaps and counterevidence** — identify the affected claims and whether collection can still recover the evidence.
+5. **Overall verdict** — one sentence plus the blocking claim IDs.
+
+Example conclusion:
+
+> `partially_proven`: repository steps C1-C18 and checkpoint recovery C22 are proven, but deployment success is not proven because C31 has only a client-side start event and no platform health result.
+
+## Common Mistakes
+
+- Treating a successful process exit as proof of the business postcondition.
+- Counting retries as separate successful logical operations.
+- Accepting a child agent's summary as independent corroboration.
+- Calling a checkpoint recoverable without observing a verified reload.
+- Calling an approval request an approval grant.
+- Reporting percentages without listing the denominator and missing instances.
+- Recommending instrumentation as though it were evidence from the completed run.
+
+## Limitations
+
+- An audit cannot recover facts that no trusted source recorded.
+- Provider logs may establish external effects without proving the agent's internal reasoning.
+- Redaction may be necessary for secrets and personal data; record the redaction scope and preserve stable references.
+- If evidence collection would mutate external state or expose sensitive data, stop and request authorization.

package/bundled-skills/boost-asio-pro/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: boost-asio-pro
+description: "Use when writing asynchronous C++ networking code with Boost.Asio or standalone Asio — TCP/UDP servers and clients, SSL/TLS, timers, strands, composed async ops. Covers io_context, co_spawn, awaitable, async_read/async_write, asio::spawn, yield_context, and pre-C++20 callback styles."
+category: development
+risk: safe
+source: community
+source_repo: alexprivalov/boost-asio-skill
+source_type: community
+date_added: "2026-08-18"
+author: alexprivalov
+tags: [cpp, boost, asio, async, networking, coroutines]
+tools: [claude, cursor, gemini]
+license: "MIT"
+license_source: "https://github.com/alexprivalov/boost-asio-skill/blob/main/LICENSE"
+---
+
+# Boost.Asio / standalone Asio
+
+## Overview
+
+Write async C++ networking code that compiles on the *user's* Boost, not the newest one. Asio's API changed shape three times (classic `io_service` → `io_context` → C++20 coroutines) and most Asio code on the internet is from the first era, so **pick the style from the toolchain first**, then follow that style's reference file.
+
+**References:** [Boost.Asio](https://www.boost.org/doc/libs/latest/doc/html/boost_asio.html) · [standalone Asio](https://think-async.com/Asio/)
+
+Asio's API changed shape three times, so the same task has three correct answers depending on the Boost version in front of you. This skill makes the agent establish that version first, then apply the rules that are genuinely easy to get wrong — strand versus write serialization, buffer and connection lifetime, composed reads for framing — and finally check its own output against a list before calling it done.
+
+## When to Use This Skill
+
+- Use when writing or reviewing async C++ networking code with Boost.Asio or standalone Asio: TCP/UDP servers and clients, SSL/TLS streams, timers, resolvers.
+- Use when the code involves `io_context`, `io_service`, `co_spawn`, `awaitable`, `async_read`, `async_write`, `strand`, `asio::spawn`, `yield_context`, or completion-handler callbacks.
+- Use when the target toolchain is old: an older Boost or a pre-C++20 standard, where coroutine examples will not compile.
+- Use when async code compiles but misbehaves: interleaved writes, dangling buffers, sockets closing early, `operation_aborted` treated as an error.
+
+## Step 1: pick the style (do this before writing code)
+
+Determine the Boost (or Asio) version and the C++ standard actually in use — `find_package(Boost)` output, `dpkg -l libboost-dev`, `brew info boost`, `CMAKE_CXX_STANDARD`, or ask. Do not assume the newest.
+
+| Boost | C++ std | Style | Read |
+|-------|---------|-------|------|
+| ≥ 1.77 | C++20 | Coroutines (`co_await` + `awaitable<T>`) — preferred | [references/coroutines.md](references/coroutines.md) |
+| ≥ 1.74 | C++11–17 | Completion handlers (callbacks) — the portable baseline | [references/pre-cpp20.md](references/pre-cpp20.md) |
+| ≥ 1.80 | C++11–17 | Stackful `asio::spawn` + `yield_context` (links Boost.Coroutine — not header-only) | [references/pre-cpp20.md](references/pre-cpp20.md) |
+| 1.62–1.65 | C++11 | Classic `io_service` / `strand.wrap` / `expires_from_now` | [references/classic-boost.md](references/classic-boost.md) |
+
+SSL/TLS in any style: [references/ssl.md](references/ssl.md). CMake for any style: [references/build.md](references/build.md).
+
+`io_context`, `make_strand`, `bind_executor`, `steady_timer`, `signal_set`, `async_read`/`async_write`/`async_read_until`, buffers and `resolver` are **library** features — identical in the coroutine and callback styles. Only the suspension mechanism differs.
+
+## Step 2: version floors (verified by compiling, not from docs)
+
+Reach for one of these and the build breaks on older distros:
+
+| Feature | Floor |
+|---------|-------|
+| `experimental/awaitable_operators.hpp` (the `\|\|` / `&&` operators) | **Boost ≥ 1.77** / Asio ≥ 1.20 |
+| `as_tuple` completion token | **Boost ≥ 1.79** / Asio ≥ 1.21 |
+| `co_composed` (custom composed ops) | **Boost ≥ 1.85** / Asio ≥ 1.30 |
+| 3-arg `asio::spawn(ex, fn, token)` | **Boost ≥ 1.80** (older Boost has only `spawn(ex, fn)`) |
+| `any_io_executor` (`strand<any_io_executor>`, `tcp::socket`'s default executor) | **Boost ≥ 1.74** — the floor for the callback style; below it, use legacy `io_context::strand` |
+| `io_context`, `make_strand`, `expires_after` | **Boost ≥ 1.66** — below it, classic `io_service` |
+
+Distro floors that bite: **Debian bookworm ships Boost 1.74** (no `awaitable_operators.hpp` — `#include` fails outright), Ubuntu 20.04 ships 1.71 (no `any_io_executor`), Debian 9 ships 1.62.
+
+Language, not library: the chrono literals `250ms` / `30s` are **C++14**. For a true C++11 build write `std::chrono::milliseconds(250)`.
+
+## Step 3: the rules that are actually easy to get wrong
+
+**A strand does not serialize writes.** A strand serializes handler *execution*, not whole composed operations. Two `async_write`s in flight on the same strand still **interleave bytes on the wire**. Full-duplex (a read loop plus concurrent pushes/replies) needs a per-connection strand **and** an outbound queue with an in-flight flag, so at most one `async_write` exists at a time. This is the single most common wrong answer about Asio.
+
+**Buffers do not own memory.** `asio::buffer()` is a view. Storage must outlive the operation: coroutine locals are fine across `co_await` in the same frame; in callback style the same data must become a **member**, not a local.
+
+**Connections must outlive their handlers.** `enable_shared_from_this`, and capture `self` in *every* `co_spawn` / handler — read loop, write loop, and each timer.
+
+**Frame with composed reads.** `async_read` (fills the buffer exactly) for a length prefix and then the body; never `async_read_some`, which returns short.
+
+**Wrap `as_tuple`.** Always `as_tuple(use_awaitable)`. Bare `as_tuple` resolves against the operation's default token and compiles in some contexts, fails in others.
+
+**`async_accept(make_strand(...))` changes two things**: it forces an explicit completion token back on the call, and the accepted socket is `basic_stream_socket<tcp, strand<...>>`, not `tcp::socket`. Take it **by value** or with `auto` — binding it to `tcp::socket&` will not compile.
+
+**Re-arming a timer resolves the pending wait with `operation_aborted`.** In an idle-timeout loop that is the signal to keep waiting, not an error.
+
+**GCC needs `-fcoroutines`** for the C++20 style, and header-only Boost needs `BOOST_ERROR_CODE_HEADER_ONLY` defined in exactly one place (CMake).
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Buffer dangling (local goes out of scope during async op) | Ensure buffer lifetime ≥ operation lifetime; coroutine locals or members, not callback locals |
+| Forgetting `io.run()` | No handlers dispatch without `run()` / `run_one()` |
+| Concurrent socket access without strand | Wrap in `strand<>` or serialize via one coroutine chain |
+| Assuming a strand prevents interleaved writes | Add a write queue — see Step 3 |
+| Using `use_awaitable` where `deferred` suffices | Omit the token (default is `deferred`) unless using `\|\|` / `&&` |
+| Ignoring short reads/writes | Use composed `async_read` / `async_write` / `async_read_until`, not `async_read_some` |
+| Not setting `reuse_address` on the acceptor | Set before `bind`/`listen` or restarts hit "address in use" |
+| SSL operations without a strand | *All* `ssl::stream` ops need strand synchronization |
+| Blocking inside a handler | Never block in a completion handler |
+| Accepting a socket with the wrong executor type | See `async_accept(make_strand(...))` in Step 3 |
+| Requiring the `Boost::system` component | Header-only since 1.74: `Boost::headers` + `BOOST_ERROR_CODE_HEADER_ONLY`. Only classic (pre-1.66) needs the link |
+| Missing `-fcoroutines` on GCC | Build fails — add `$<$<CXX_COMPILER_ID:GNU>:-fcoroutines>` |
+| Writing coroutine code for a Boost that predates it | Do Step 1 first |
+
+## Boost.Asio vs standalone Asio
+
+Same author, same API — namespace and includes differ.
+
+| Aspect | Boost.Asio | Standalone Asio |
+|--------|-----------|-----------------|
+| Namespace / include | `boost::asio` / `<boost/asio.hpp>` | `asio` / `<asio.hpp>` |
+| Error code | `boost::system::error_code` | `asio::error_code` (or `std::error_code`) |
+| Install (brew) | `brew install boost` | `brew install asio` |
+| CMake | `Boost::headers` | manual include path |
+| Version (2025) | 1.87–1.90 (with Boost) | 1.30–1.36 (independent) |
+| Macro prefix | `BOOST_ASIO_` | `ASIO_` |
+
+Support both with a shim, then use `net::` throughout:
+```cpp
+#ifdef USE_STANDALONE_ASIO
+  #include <asio.hpp>
+  namespace net = asio;
+  using error_code = asio::error_code;
+#else
+  #include <boost/asio.hpp>
+  namespace net = boost::asio;
+  using error_code = boost::system::error_code;
+#endif
+namespace ssl = net::ssl;
+using tcp = net::ip::tcp;
+```
+
+## Before you call it done
+
+Check the code you just wrote against this list:
+
+- [ ] Style matches the target Boost version and C++ standard (Step 1), and every API used clears its floor (Step 2).
+- [ ] Every buffer passed to an async op outlives that op — no callback locals, no dangling `string_view`.
+- [ ] At most one `async_write` per socket in flight, enforced by a queue + flag, if anything writes concurrently with reading.
+- [ ] Every async chain on a shared object runs on the same strand; `self` captured in every handler and `co_spawn`.
+- [ ] Framing / delimited reads use composed `async_read` / `async_read_until`.
+- [ ] Errors are handled, not swallowed: `as_tuple(use_awaitable)` destructured, or the callback's `ec` checked, on every op.
+- [ ] `operation_aborted` distinguished from real errors wherever a timer is re-armed or an op is cancelled.
+- [ ] Acceptor sets `reuse_address`; shutdown path closes the acceptor and drains sessions.
+- [ ] CMake has the standard, `-fcoroutines` for GCC (C++20 only), `BOOST_ERROR_CODE_HEADER_ONLY` in one place, and `Boost::coroutine` only if using stackful `spawn`.
+- [ ] It compiles. Build it — most of the mistakes above are compile-time, and the version floors are only real once tested.
+
+## Worked examples
+
+Three CI-verified implementations of the same full-duplex framed-protocol server, one per style — copy from the one matching Step 1. Paths are relative to this skill directory; if only the skill was installed, they are at https://github.com/alexprivalov/boost-asio-skill/tree/main/examples.
+
+- `../../examples/market-data-feed/` — C++20 coroutines (Boost 1.77+; verified 1.83–1.90)
+- `../../examples/market-data-feed-precpp20/` — callbacks, C++11-clean (verified Boost 1.74+, incl. Windows/MSVC)
+- `../../examples/market-data-feed-classic/` — classic `io_service` (verified back to Boost 1.62 / Debian 9)
+
+## Official documentation
+
+- Overview: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/overview.html
+- Reference: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference.html
+- Examples: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/examples.html
+
+## Limitations
+
+- This skill does not replace compiling and testing against the target toolchain. The version floors it documents are only real once built — build the code.
+- It does not cover Boost.Beast (HTTP/WebSocket), io_uring backends, or UDP multicast specifics.
+- Stop and ask when the Boost version and C++ standard cannot be determined; the style choice depends on them.
+
+## Security & Safety Notes
+
+- Read-only guidance: this skill contains no shell commands, network fetches, credentials, or mutation instructions. The commands it names (`dpkg -l libboost-dev`, `brew info boost`) are local version queries.
+- Networking code it produces accepts untrusted input. Validate length prefixes before allocating (`std::string body(n, 0)` with an attacker-controlled `n` is a memory-exhaustion vector — cap it), and verify peer certificates when using TLS rather than disabling verification to make a handshake pass.
+
+## Related Skills
+
+- `@cpp-pro` — general modern C++ idioms; this skill assumes them and adds the Asio-specific rules.