Enroll in the canonical agent-skill substrate

.agents/skills/architecture-pre-flight/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: architecture-pre-flight
+description: "High-level umbrella router for navigating broad, cross-substrate architectural ambiguity. Triggers: Use when no narrower pre-flight clearly applies, or when work spans multiple trigger families such as new subsystems, protocols, MCP tools, or cross-substrate refactors."
+---
+
+# Architecture Pre-Flight
+
+This skill maps to the authoritative routing protocol for architectural ambiguity.
+
+**MANDATORY ACTION:** Use `view_file` to read `references/architecture-pre-flight-workflow.md` before deciding on broad architecture.

.agents/skills/architecture-pre-flight/references/architecture-pre-flight-workflow.md

@@ -0,0 +1,48 @@
+# Architecture Pre-Flight Workflow
+
+This skill acts as the "router-of-uncertainty" for high-level architectural decisions, new daemons, subsystems, or cross-substrate refactors.
+
+## Trigger Rule
+
+Fire only when no narrower mandatory trigger applies OR when the proposed work spans multiple distinct trigger families.
+
+## Bypass Rules (Preventing Substrate Fatigue)
+
+Do NOT invoke this skill for routine or already-governed actions. If a more specific pre-flight exists, use it instead:
+- Plainly `.mjs` placement? Route to `/structural-pre-flight`.
+- Plainly skill creation? Route to `/create-skill`.
+- Plainly substrate placement (turn/skill-loaded memory)? Route to `/turn-memory-pre-flight`.
+- Plainly tech-debt sweep? Route to `/tech-debt-radar`.
+- Plainly discussion-grade uncertainty? Route to `/ideation-sandbox`.
+
+**This is NOT a universal mandatory prelude** — invoking it on every change recreates the substrate fatigue it's meant to reduce.
+
+## Output Requirement
+
+When you invoke this skill to make a routing decision, your reasoning/output MUST include:
+1. The **selected discipline** (the skill you are routing to).
+2. **Why not `<nearest alternative>`** (why another discipline was rejected).
+3. The **blast-radius class** of the change.
+
+## The Architectural Routing Protocol
+
+When facing genuine cross-substrate architectural ambiguity, follow these steps:
+
+1. **Verify Before Assert (Tier 1):** Execute local tool runs to gather empirical evidence. Check the Knowledge Base (`ask_knowledge_base`) and historical discussions (`memory-mining`).
+2. **Impact Radius Assessment:** Determine the scope of the change. Does it alter core primitives? Does it introduce new build steps or dependencies?
+3. **Escalate (Tier 3/4):** If the change is irreversible, introduces breaking API shifts, or creates new daemons/subsystems, you MUST route the proposal to the `/ideation-sandbox` for peer review before implementation. Do not proceed with implementation until consensus is reached.
+4. **Document the Decision:** If the change is reversible and within local authority (Tier 2), implement it and document the rationale clearly in the PR description, referencing the evidence gathered in Step 1.
+
+## Empirical Anchors
+
+- **PR #11250:** Empirical anchor for substrate-placement gaps.
+- **#10449:** `ai/daemons/wake/daemon.mjs` (originally misplaced in `ai/scripts/` as `bridge-daemon.mjs`) misplacement origin.
+- **PR #11008 → #11009:** `orchestrator-daemon.mjs` misplacement and corrective action.
+- **PR #11246 → #11251:** One-shot script "playbook" framing corrective action.
+- **Epic #11256:** Serves as the router-of-uncertainty anchor itself.
+
+## Cross-Skill References
+
+- Substrate placement decisions route to `/turn-memory-pre-flight`.
+- `.mjs` file placements route to `/structural-pre-flight`.
+- Skill creation routes to `/create-skill`.

.agents/skills/blocked-task-state/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: blocked-task-state
+description: "Authoritative protocol for signaling blocked or input-required task states. Mandates targeted A2A pings using the Task.state envelope rather than global capacity broadcasts. Triggers: Use this skill whenever your execution becomes blocked, requires explicit operator input, or encounters a failure that halts progress."
+---
+
+# Blocked Task-State Coordination
+
+If you are an agent and your task transitions into a blocked, input-required, or failed state, you MUST NOT broadcast a global idle signal. 
+
+You MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/blocked-task-state/references/blocked-task-state-workflow.md` before sending any A2A messages.

.agents/skills/blocked-task-state/references/blocked-task-state-workflow.md

@@ -0,0 +1,64 @@
+# Blocked Task-State Coordination Protocol
+
+This document codifies the Swarm's authoritative pattern for signaling that an agent is blocked but not completed (`InputRequired`, `Blocked`, or `Failed`).
+
+The swarm relies natively on the A2A v1.0 `Task.state` at the message-level to signal transitions when an agent is genuinely blocked. We do NOT use continuous-presence polling or global "idle" capacity broadcasts.
+
+## 1. Targeted Ping Mandate (AC1)
+
+Blocked-task transitions (`InputRequired`, `Blocked`, `Failed`) MUST trigger a targeted ping to the specific task-assignee and the human operator.
+- You MUST NOT send a global `AGENT:*` broadcast.
+- Global broadcasts for routine tasks are explicitly banned to prevent mailbox spam.
+
+## 2. A2A Task Envelope Integration (AC2)
+
+The blocked signal MUST map exactly to the native A2A `Task.state` field within the existing `add_message` task envelope.
+
+Example `add_message` invocation:
+```javascript
+{
+  "to": "@neo-opus-ada", // Targeted explicitly
+  "subject": "Task Blocked: #10761 API rate limit",
+  "body": "I am blocked on issue #10761 due to an API rate limit...",
+  "task": {
+    "taskId": "10761",
+    "state": "Blocked" // MUST be one of: InputRequired, Blocked, Failed
+  }
+}
+```
+*(Note: A2A Protocol states are PascalCase per specification: `InputRequired`, `Blocked`, `Failed`)*
+
+## 3. Negative Examples (When NOT to trigger) (AC3)
+
+You MUST NOT trigger the blocked task-state pattern for the following routine events. These do NOT represent a blocked state:
+- **Ordinary PR comments:** Regular back-and-forth review feedback.
+- **Routine approvals:** Signaling that a PR looks good to me (LGTM).
+- **Completed merge eligibility:** A PR has all approvals and is waiting for the human merge gate.
+- **General availability:** Broadcasting that you have finished your current assignment and have free capacity. Idle/Capacity advertisement is strictly forbidden.
+
+## 4. Payload Schema Constraints (AC4)
+
+When sending the blocked-task A2A message, the `body` content MUST strictly contain the following constrained payload:
+
+- **Task/Issue ID:** Explicit reference to the GitHub issue or PR number.
+- **Prior State:** The execution state before becoming blocked (e.g., `Working`, `Submitted`).
+- **New State:** The explicit blocked transition (`InputRequired`, `Blocked`, `Failed`).
+- **Blocker Summary:** A concise, 1-2 sentence description of the blocker.
+- **Exact Requested Input:** Explicitly state what you need from the recipient to unblock (e.g., "Need approval for architectural shift", "Need updated API key").
+- **Current Owner:** The agent currently assigned to the ticket.
+- **Target Recipient:** The peer or operator who can resolve the blocker.
+- **Retry/Expiry Guidance:** Explicit rules for when you will retry or when the request expires (e.g., "Will wait 24h before dropping context").
+- **Public Artifact Link:** A URL to the relevant GitHub Issue/PR or a local workspace artifact path detailing the blocker.
+
+Example Payload in `body`:
+```markdown
+- **Task ID:** #10761
+- **Prior State:** Working
+- **New State:** Blocked
+- **Blocker Summary:** The embedding model endpoint is returning 400 errors for Qwen3-8b.
+- **Exact Requested Input:** @tobiu please verify if the local model needs to be re-pulled.
+- **Current Owner:** @neo-gemini-pro
+- **Target Recipient:** @tobiu
+- **Retry/Expiry Guidance:** Will drop context after 24h.
+- **Public Artifact Link:** https://github.com/neomjs/neo/issues/10761
+```

.agents/skills/blog-post/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: blog-post
+description: Authoring or revising a public-facing blog post (learn/blog/*.md + portal registration). Enforces hero-piece narrative arc, sourcing every external claim, killing the three over-claim flavors, and the mandatory cross-family review bar.
+---
+
+# Blog Post Authoring Skill
+
+If you are authoring or revising a public-facing blog post (`learn/blog/*.md` plus its manual portal registration in `apps/portal/resources/data/blog.json` — the SEO surfaces regenerate, never hand-edited), you MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/blog-post/references/blog-authoring-guide.md` before drafting or editing.
+
+A public post is held to its own thesis: a real narrative arc, every external claim sourced, zero over-claims, and cross-family review before it ships. Skipping the guide is the higher-cost path — #13486 took multiple cross-family cycles to converge on exactly these gates.

.agents/skills/blog-post/references/blog-authoring-guide.md

@@ -0,0 +1,60 @@
+# Blog Post Authoring Guide
+
+Fires when you author or revise a public-facing blog post: `learn/blog/<slug>.md` plus its manual portal registration in `apps/portal/resources/data/blog.json` (year node + leaf). The SEO surfaces are **generated, not hand-edited** — see §5. Sibling of the release-notes + `update-roadmap` skills.
+
+**The recursive principle.** A blog post is a *public artifact*, held to its own thesis. If the post argues for rigor, it must *be* rigorous. The empirical anchor for this entire guide is #13486 (the cross-family-verification post): it took multiple cross-family review cycles to converge, and each cycle caught exactly one of the failure modes below. This guide is that cycle distilled — so the *next* post starts where #13486 ended, not at the beginning.
+
+## 1. Narrative Arc — a hero piece, not a changelog
+
+Lead with the **thesis**, never the volume hook ("we shipped N things" is what a tired engineer downvotes on sight). The release-notes-level shape:
+
+- **TL;DR thesis** — one bold paragraph; the single idea, stated so a skimmer gets the whole bet.
+- **The hook** — the tension the reader already feels, framed in *their* terms, not yours. "Their terms" = a *real problem they have*, never a swipe at their tools ("Your AI can't…"). The tension comes from the problem, not from a taunt at the reader (see §3 flavors #4–#5).
+- **The arc** — problem → why the obvious fix falls short → your move → why it holds *by construction*. One claim per section; each section earns the next.
+- **Receipts, not prophecy** — concrete, linked, public evidence (PRs, issues, war stories). Pair the dramatic case with a mundane everyday one — the mundane one convinces harder.
+- **CTA** — the one question the piece leaves the reader holding, plus a single concrete next step. Not a link-dump.
+
+Diagrams (Mermaid) earn their place only when they carry information the prose can't — each **render-verified before merge** (`guide-authoring-bar` §3). Self-identify in a byline (named maintainer + model + the cross-family team).
+
+## 2. Source Every External Claim (verify-before-assert)
+
+Every claim about the *outside world* — a competitor, a quote, a statistic, a "first / most / fastest" — needs a real, linked source you have **verified**, before publish.
+
+- **An authority's verbal statement is NOT a citable source.** "The operator told me X" / "a lead said Y" is a pointer to *go verify*, not a citation. (On #13486 the OpenClaw "got the most stars fastest" claim went in as fact → GPT RC'd it; the fix was to WebSearch it, confirm it across outlets, and cite *those*.)
+- **Verify, then cite the verification.** WebSearch / WebFetch the claim; link the source whose own words support the *exact* claim you make. Never cite a source for a claim it does not make — read the title/body, not just the search snippet.
+- **If you can't source it, cut it.** A cut claim costs nothing; an unsourced claim in a verification-themed post is fatal.
+- **Internal claims** (your own PRs, counts, war stories) link to the public record — issue/PR numbers, the release notes — with the metric stated (e.g. "GitHub's count, since the prior release").
+
+## 3. Kill the Five Over-Claim Flavors
+
+A claim can be literally true yet imply something false — and a *title* can be accurate yet strike the wrong voice. Audit every claim (and every title) for *implication*, not just literal accuracy. Flavors 1–3 are **factual** over-claims (surfaced by #13486's cross-family review, recounted from the actual cycle — see the Empirical Anchor); flavors 4–5 are **tonal / identity** over-claims (from @tobiu's title feedback, #14877 — the "Your AI…" batch he would not publish):
+
+1. **Unsourced superlative** — "the most / first / fastest X." Source the exact ranking, or soften / cut. (OpenClaw "most stars, fastest ever" — GPT RC'd it as unsourced → cut, then re-added *attributed* to the star-count outlets.)
+2. **Universal quantifier** — "*all* N are X." One counterexample disproves it, and a skeptic will find it. Soften to defensible process framing unless the universal is *genuinely* true. ("all 1,307 PRs cross-reviewed" → "cross-family review the standard for substrate, a human on every merge" — and "a human on every merge" stays universal because it is the actual rule.)
+3. **Misleading fraction / framing** — a correct number that implies a false conclusion. ("129 of 151 tracked items shipped" is accurate but reads *almost done*, while the full system is a major-version horizon away.) Reframe so the *impression* matches reality.
+4. **False-human-author voice (provenance-inversion)** — a second-person "Your AI… / your stack…" title poses as a *human* addressing their tool, hiding that an AI maintainer wrote the post. The byline discloses the author, but the *title* has already set a false frame. Title from *inside* the organism — describe what we built; don't grade the reader's stack. ("Your AI can write the app. It still can't operate the running one." → "Possession, not code-generation: operating a running app from inside it.")
+5. **Competitive put-down** — "X does Y, but *mine* does it better" / gotcha-taunt hooks. Reads like "you have a nice watch, but I have the bigger one" — junior-dev flexing that *undercuts* a serious project. Lead with the strongest substance, stated plainly; let the work carry the confidence. ("Your AI Agent Grades Its Own Homework. Mine Gets Checked by a Rival Lab." → "Cross-family verification: an agent from a rival lab checks our work, in public.")
+
+**The test (claims):** for each claim ask *both* "is it accurate?" and "does the framing imply something I can't defend?" Both must pass.
+
+**The test (titles) — mechanical:** a title fails if it (a) opens with "Your AI… / Your stack…" (the vendor second-person frame), (b) is shaped "X does Y — but mine does it better" (comparative one-upmanship), or (c) would read as bragging to a senior engineer at a rival lab. Tension stays legal when it comes from a *real problem* in the story ("An AI predicted its own project's future. Ten weeks later, another AI graded it." has drama and zero put-down) — the ban is the swipe at the reader, not the tension.
+
+## 4. The Cross-Family Review Bar (mandatory)
+
+A public post ships only after **≥2 model reviews**. The cross-family review is the structural backstop that catches what the author — sharing the post's own priors — cannot.
+
+- **Route ≥2 reviewers, at least one from a different model family** than the author. For a post *about* cross-family verification, route every available family — it is the thesis, demonstrated.
+- **The authority/operator approves LAST.** If the authority approves first, peers anchor to that signal and rubber-stamp; approving last preserves their independent judgment. Corollary: do NOT record "X will approve anyway" in shared/telepathic memory — a peer reading it self-fulfills the rubber-stamp.
+- **Address every catch on the durable PR.** Map each fix to its reviewer (`[ADDRESSED]`), refresh the head, re-request. The review *is* the product — it is what makes the post trustworthy, and it is the thesis in motion.
+
+## 5. Mechanics
+
+- **File:** `learn/blog/<slug>.md` (front-matter + body) — the post itself.
+- **Register (manual):** add a year node + leaf to `apps/portal/resources/data/blog.json` (the portal blog-nav). Confirm it parses (`node -e "JSON.parse(require('fs').readFileSync('apps/portal/resources/data/blog.json','utf8'))"`).
+- **Do NOT hand-edit the SEO surfaces.** `apps/portal/sitemap.xml` and `apps/portal/llms.txt` are **generated** by `buildScripts/docs/seo/generate.mjs` (via `buildScripts/docs/rebuildContentIndexesAndSeo.mjs`) and committed by the `.github/workflows/data-sync-pipeline.yml` data-sync pipeline. A manual edit is overwritten on the next pipeline run.
+- **Ship:** commit + PR per the `pull-request` skill; the PR body `Evidence:` line is L1/L2 (docs — no unit tests). Public-artifact gate: **zero client names** (AGENTS.md §critical_gate).
+- **Identity:** byline carries the author's named-maintainer identity + model + the cross-family team framing (ADR 0018).
+
+## Empirical Anchor
+
+#13486 / #13485 — the cross-family-verification post. Authored, then cross-reviewed by Euclid (GPT), Grace, Ada, and the operator; every over-claim flavor above was caught and fixed in-cycle. This guide is that cycle, distilled — so it happens once, here, and not on every post.

.agents/skills/context-recovery/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: context-recovery
+description: "Post-compaction recovery runbook for reconstructing active lane state from Memory Core recency, semantic recall, session rollups, and A2A. Triggers: Use immediately after context compaction/compression, resuming a summarized session, or noticing the active lane was reconstructed from a lossy summary."
+---
+
+# Context Recovery Skill
+
+If you are recovering after context compaction/compression or a summarized-session resume, you MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/context-recovery/references/context-recovery-workflow.md` before asserting lane state or asking the operator to re-explain.