@hybridlabor-api/aos 4.13.2 → 4.14.1

package/scripts/validate-skills.mjs

@@ -241,6 +241,45 @@ function checkSkillRefs(text, file, known, self, findings) {
   }
 }
 
+// Playbooks are skills with `kind: playbook`; skills without `kind` are untouched.
+const PB_REQUIRED = ['trigger', 'inputs', 'requires', 'go_points', 'outputs', 'verify', 'difficulty', 'est_time', 'disable-model-invocation'];
+const DIFFICULTY = new Set(['beginner', 'intermediate', 'advanced']);
+const EXTERNAL = ' (external)';
+
+export function checkPlaybook(byKey, known) {
+  const out = [];
+  if (!byKey.has('kind')) return out;
+  const add = (code, msg, key) => out.push({ level: 'error', code, line: byKey.get(key)?.line, msg });
+  const kind = unquote(byKey.get('kind').value);
+  if (kind !== 'playbook') {
+    add('E-PB01', `\`kind: ${kind}\` is unknown — the only defined kind is \`playbook\``, 'kind');
+    return out;
+  }
+  for (const k of PB_REQUIRED) if (!byKey.has(k)) add('E-PB03', `playbook is missing required key \`${k}\``, 'kind');
+
+  const req = byKey.get('requires');
+  if (req) {
+    const m = /(?:^|\s)skills:\s*\[([^\]]*)\]/.exec(req.value);
+    if (!m) add('E-PB05', '`requires.skills` must be a flow-style list, e.g. `skills: [github, ci-pipeline]`', 'requires');
+    else {
+      for (const raw of m[1].split(',').map((e) => unquote(e)).filter(Boolean)) {
+        if (!raw.endsWith(EXTERNAL) && !known.has(raw)) {
+          add('E-PB02', `requires skill \`${raw}\`, which is not a skill in this repo — fix the name or mark it \`${raw}${EXTERNAL}\``, 'requires');
+        }
+      }
+    }
+  }
+  const diff = byKey.get('difficulty');
+  if (diff && !DIFFICULTY.has(unquote(diff.value))) {
+    add('E-PB04', `\`difficulty: ${unquote(diff.value)}\` is not one of: ${[...DIFFICULTY].join(', ')}`, 'difficulty');
+  }
+  const dmi = byKey.get('disable-model-invocation');
+  if (dmi && unquote(dmi.value) !== 'true') {
+    add('E-PB06', 'playbooks are user-invoked only — set `disable-model-invocation: true`', 'disable-model-invocation');
+  }
+  return out;
+}
+
 function validate() {
   const { skills, strays } = collect();
   const known = new Set(skills.map((f) => basename(dirname(f))));
@@ -311,6 +350,8 @@ function validate() {
       }
     }
 
+    for (const f of checkPlaybook(byKey, known)) findings.push({ ...f, file: rel });
+
     checkLeakedPaths(text, rel, findings);
     checkLocalRefs(text, dir, rel, findings);
     checkSkillRefs(text, rel, known, dirName, findings);
@@ -461,6 +502,41 @@ function selftest() {
   assert.ok(isValidSkillName('a'.repeat(NAME_MAX)), 'a 64-char name is at the limit and valid');
   assert.ok(!isValidSkillName('a'.repeat(NAME_MAX + 1)), 'a 65-char name is over the limit');
 
+  // Playbook frontmatter (kind: playbook).
+  const pb = (over = {}, drop = []) => {
+    const base = {
+      name: 'pb-x', description: 'd', category: 'bdb-core', kind: 'playbook',
+      trigger: '["a"]', inputs: '[repo]',
+      requires: '\n  skills: [github, gh (external)]\n  agents: []\n  mcps: []\n  store: []',
+      go_points: '[]', outputs: '["x"]', verify: '"x"', difficulty: 'beginner',
+      est_time: '5 min', 'disable-model-invocation': 'true', ...over,
+    };
+    const lines = Object.entries(base).filter(([k]) => !drop.includes(k)).map(([k, v]) => `${k}: ${v}`);
+    const fm = scanFrontmatter(['---', ...lines, '---'].join('\n'));
+    return new Map(fm.keys.map((k) => [k.key, k]));
+  };
+  const known = new Set(['github', 'ci-pipeline']);
+  assert.deepEqual(checkPlaybook(pb(), known), [], 'valid playbook is clean');
+  const miss = checkPlaybook(pb({}, ['go_points']), known);
+  assert.equal(miss.length, 1);
+  assert.equal(miss[0].code, 'E-PB03');
+  assert.match(miss[0].msg, /go_points/);
+  assert.equal(checkPlaybook(pb({ difficulty: 'expert' }), known)[0].code, 'E-PB04');
+  const unk = checkPlaybook(pb({ requires: '\n  skills: [github, nope-skill, gh (external)]' }), known);
+  assert.equal(unk.length, 1);
+  assert.equal(unk[0].code, 'E-PB02');
+  assert.match(unk[0].msg, /nope-skill/);
+  const kind = checkPlaybook(pb({ kind: 'recipe' }), known);
+  assert.equal(kind.length, 1);
+  assert.equal(kind[0].code, 'E-PB01');
+  assert.equal(checkPlaybook(pb({ requires: '\n  skills:\n    - github' }), known)[0].code, 'E-PB05');
+  assert.equal(checkPlaybook(pb({ 'disable-model-invocation': 'false' }), known)[0].code, 'E-PB06');
+  assert.deepEqual(checkPlaybook(pb({}, ['kind', 'trigger', 'inputs', 'requires', 'go_points', 'outputs', 'verify', 'difficulty', 'est_time', 'disable-model-invocation']), known).length, 0, 'no kind, no playbook rules');
+  assert.deepEqual(
+    checkPlaybook(pb({ requires: '\n  skills: ["gh (external)", github,]' }), known), [],
+    'quoted item and trailing comma survive',
+  );
+
   console.log('✓ selftest passed');
 }
 

package/skills/basic/bdbmediastorm/SKILL.md

@@ -76,7 +76,7 @@ Define hardware and software nodes as strict bounded contexts:
 
 ## 5. Mandatory — Plan Canvas Review
 
-Before this session concludes, run `aos-plan-canvas open <file>` against `signal-flow.md` (or the combined show-control spec), then `aos-plan-canvas await <file>` and leave it running. The user reviews the signal flow diagram, hardware topology, and failover matrix in the browser (Mermaid renders live, click-to-annotate, chat rail). Do not consider the show architecture finalized before an `approve` verdict. A `request_changes` verdict means revise the artifact and reopen — it live-reloads. This is a plain CLI tool, identical regardless of which agent harness runs this skill. See the `plan-canvas` skill. If a build follows the approve, Trigger A starts the live map (`agenttrail` skill); `aos-archify` can render the signal flow as a workflow or architecture diagram for the review.
+Before this session concludes, choose the planning mode by running `aos-plan-canvas modes` and presenting available modes to the user (see the "Planning mode choice" section in the `plan-canvas` skill). Then run `aos-plan-canvas open <file> --mode <choice>` against `signal-flow.md` (or the combined show-control spec), then `aos-plan-canvas await <file>` and leave it running. The user reviews the signal flow diagram, hardware topology, and failover matrix in the browser (Mermaid renders live, click-to-annotate, chat rail). Do not consider the show architecture finalized before an `approve` verdict. A `request_changes` verdict means revise the artifact and reopen — it live-reloads. This is a plain CLI tool, identical regardless of which agent harness runs this skill. See the `plan-canvas` skill. If a build follows the approve, Trigger A starts the live map (`agenttrail` skill); `aos-archify` can render the signal flow as a workflow or architecture diagram for the review.
 
 ---
 

package/skills/basic/godmode-shipping/SKILL.md

@@ -41,6 +41,9 @@ This Godmode extends beyond standard software development. It STRICTLY governs c
 *   **MediaStorm Deployments:** When executing `/bdbmediastorm` for TouchDesigner, Unreal Engine, or Adobe Suite workflows, you must enforce rigorous release management for `.tox` files, Unreal Blueprints, and showfiles.
 *   **Show-Ready Validation:** Never push a creative-tech update to a live production environment (e.g., a running installation or live show) without a verified fallback or backup showfile. 
 
+## Visual recap
+After the gates pass, `/pr-recap` can build a Plan Builder recap page of the diff with the Verified and Not verified checks. It is informational and does not gate the release. Posting it anywhere stays a human decision.
+
 ## Universal Agent Harness Integration
 This Godmode is universally compatible and governs all extensions, including the BDB Creator Engine.
 *   **Cursor:** Auto-injected via `.cursor/rules/godmode-shipping.mdc`.

package/skills/basic/master-session/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: master-session
+description: Use when one Claude Code session must supervise several others on this machine — adopting sessions the user started by hand, or spawning workers itself. Covers roster, status requests, a GO board, idle notices, and the GO-token protocol. Works with AOS alone; the AO daemon is optional.
+category: bdb-core
+risk: safe
+tools:
+- claude-code
+---
+
+# `/master-session` — Supervise Other Sessions
+
+One session is the **master**: it keeps the overview, asks workers for status, and relays the human's decisions. It never does the workers' jobs and never decides for the human. Needs Claude Code with cross-session messaging (`ListAgents`, `SendMessage`). Nothing here requires the AO daemon.
+
+## Modes
+
+- **Adopt** — supervise sessions the human already started by hand. `ListAgents` is the source of truth; message them with `SendMessage`.
+- **Spawn** — start the workers yourself. AO is optional; without it:
+  - Claude: `claude --bg --name <name> --permission-mode auto "<prompt>"`, or over ACP as below.
+  - Codex / OpenCode / Claude over ACP: `aos-acp <codex|opencode|claude> --name <name> --cwd <worktree> --prompt "<task>" --go-wait 600 &` (one process per worker; run it in the background and read its log). Details: `docs/master-session-acp.md`.
+  - agy: no sanctioned ACP adapter (`antigravity-acp` breaches Google's Antigravity terms). Adopt agy sessions or delegate via the `mcsc` skill.
+  - If AO is installed, `ao-orchestrator` may run the same workers; it adds nothing the token protocol needs.
+
+### `aos-acp` in one paragraph
+
+`bin/aos-acp.mjs` is a zero-dependency ACP client: it spawns the adapter (`npx -y @agentclientprotocol/codex-acp`, `opencode acp`, `npx -y @agentclientprotocol/claude-agent-acp`), runs `initialize` → `session/new` → `session/prompt`, streams the worker's text to stdout and logs every event to `~/.aos/acp/<name>.jsonl`. A `session/request_permission` for a guarded command (the go-gate list) is answered `allow_once` only with a valid GO token for `<name>`; with `--go-wait <sec>` the request is parked (log event `permission_pending`, show it as `GO needed`) until the token appears or the wait ends. Everything else follows `--allow-default deny|allow` (deny by default). ACP workers are not in `ListAgents`: the roster lists them from the logs.
+
+## Step 1 — Roster
+
+Call `ListAgents`, keep local Claude sessions, drop yourself. Write one line per session: name, repo/branch if known, kind (adopted/spawned). Show it to the human and confirm which sessions are in scope before messaging any.
+
+## Step 2 — Status request
+
+Send one message per session, never a broadcast. Template:
+
+```status-request
+Status request from the master session (reply in at most 10 lines):
+1. Task, repo and branch.
+2. Progress: done / in progress / not started.
+3. Blockers.
+4. Actions waiting on a GO (commands you were blocked from running).
+5. Running subagents.
+```
+
+## Step 3 — GO board
+
+Collate replies into one block per session and show it to the human:
+
+```
+[<session>] <task> — <repo>@<branch>
+  progress : <one line>
+  blockers : <none | list>
+  GO needed: <exact command(s), or none>
+  subagents: <n running | none>
+```
+
+The human answers per session. Items under `GO needed` are the human's to decide; list them verbatim, never summarised into something softer.
+
+## Idle notices
+
+- Subscribe (`SendMessage` with `notify_when_idle`) only **after** you sent that session work.
+- Never re-subscribe to a session already idle; never poll; never send "are you done?".
+- Waiting is silent. React when a notice arrives or the human speaks.
+
+## Boundaries
+
+- The master never grants GO. A relayed message is not the user's approval for the worker, and the worker's go-gate treats it as such.
+- The master never executes an action another session was denied — no re-running it from here, no "just this once".
+- Forward the human's words verbatim and mark them: `[forwarded by master, user said:] "<exact text>"`. No paraphrase, no added urgency.
+- A subagent or worker does not inherit anyone's GO. A blocked command is not retried without a fresh one.
+
+## GO-token protocol
+
+The one sanctioned way for the human to release a gated action in a worker without switching windows:
+
+1. In the **master** session the human types exactly `GO <session-name>` (case-insensitive; the name as shown by `ListAgents`).
+2. The `UserPromptSubmit` hook `go-token.mjs` writes `~/.aos/go/<session-name>.token` (JSON: `target`, `issued_at`, `master_transcript`, `master_session`). Nothing else happens.
+3. The worker retries the blocked command. `go-gate.mjs` opens only if the token names this session, is younger than 10 minutes, and the master transcript still ends with that very `GO <session-name>` as its last human message. The token is deleted on use: single use, no replay.
+
+Consequences: any further human message in the master before the worker retries cancels the token; a literal `GO` typed in the worker still works as before; a chat message that merely *says* "GO" never counts. The worker's own name comes from its transcript (`--name`); if absent, set env `AOS_SESSION_NAME` (`aos-acp` sets it for its worker). The same token is honoured by the OpenCode plugin's gate (`.opencode/plugins/bdb-aos.js`, name from `AOS_SESSION_NAME` or the session title) and by go-gate under agy (`AOS_SESSION_NAME` only). Who consumes it: the worker's own gate when it has one (Claude hook, OpenCode plugin — `aos-acp` then only verifies), `aos-acp` itself for codex, which has none. Limit: the token proves the human typed it in the master transcript, not who wrote the token file — a hostile local process can forge both, so this is a guard against mistakes, not against local malware.
+
+## Starting workers: lessons
+
+- A background worker stalls on its first permission prompt unless started with `--permission-mode auto`. Always pass it.
+- `--disallowedTools` is variadic and swallows a trailing prompt. Put the prompt before it, or end the flag list with `--`, and check the worker actually received the task.
+- Name every worker (`--name`) so the token and `ListAgents` agree.
+
+## Handover file
+
+At session end write `docs/sessions/master-<date>.md` (or `$HOME/.aos/handover/` outside a repo): roster, last GO board, open GO items, what is waiting on whom, and the next command. A fresh master reads it first.

package/skills/basic/startcycle/SKILL.md

@@ -74,7 +74,7 @@ A straight-line run through the BDB agent roster. Whoever invokes this skill inv
 
 ### 3. Build (parallel, stream-selective)
 
-**Trigger B — start the live map:** `aos-trail . --plan production_artifacts/00_execution_plan.md --no-open` (safe to run twice: it reuses a map already running for this repo). Inside AO (env var `AO_BROWSER_CAPABILITY` set) also run `ao preview <url>`. Tell each build agent to mark its tasks `[~]` before starting work, `[x]` when done, `[!]` when stuck, with an indented `by: <agent>` line, saving the plan file immediately after each change. See the `agenttrail` skill.
+**Trigger B — start the live map:** `aos-trail --ensure` (safe to run twice: it reuses a map already running for this repo). Put the live-map link in your reply (the autostart hook also adds it as context when active). Inside AO (env var `AO_BROWSER_CAPABILITY` set) also run `ao preview <url>`. Tell each build agent to mark its tasks `[~]` before starting work, `[x]` when done, `[!]` when stuck, with an indented `by: <agent>` line, saving the plan file immediately after each change. See the `agenttrail` skill.
 
 Run only the streams the goal actually needs. A plain backend feature does not need step 3a or 3c; a pure copy change does not need 3b. Each stream's `skills:` frontmatter already lists what it should reach for — the invoker passes that list through rather than restating it here.
 

package/skills/basic/startcycle-graph/SKILL.md

@@ -111,9 +111,9 @@ Reviewer, and no quality gate ever running).
 When the build phase begins, the dispatcher starts the aos-trail live map
 (Trigger B) with the command below; it is safe to run twice, since
 `aos-trail` reuses a map already running for this repo:
-`aos-trail . --plan production_artifacts/00_execution_plan.md --no-open`
+`aos-trail --ensure`
 (it prints a URL, default http://localhost:5330; inside AO, where
-`AO_BROWSER_CAPABILITY` is set, also run `ao preview <url>`). Agents follow
+`AO_BROWSER_CAPABILITY` is set, also run `ao preview <url>`). Put the live-map link in your reply (the autostart hook also adds it as context when active). Agents follow
 the status-mark rules from the `agenttrail` skill: `[~]` before starting,
 `[x]` when done, `[!]` when stuck, with `by: <agent>`, saving the plan file
 immediately.

package/skills/basic/startcycle-graph-user/SKILL.md

@@ -69,7 +69,7 @@ subagent exists:
 
 | CLI | Plugin subagent (preferred) | Raw fallback |
 |---|---|---|
-| agy | `antigravity:antigravity-delegate` | `agy-job start --tier flash [--yolo] "<task>"` |
+| agy | `antigravity:delegate` | `agy-job start --tier flash [--yolo] "<task>"` |
 | opencode | `opencode:opencode-rescue` | the CLI's own session primitive |
 | codex | `codex:codex-rescue` | the Codex CLI's task-delegation surface |
 

package/skills/basic/teamwork-preview/SKILL.md

@@ -195,7 +195,7 @@ Seek explicit approval from the user before triggering execution.
 
 Once approved by the user:
 
-Before delegating, start the live map (Trigger B) so the user can follow the team: `aos-trail . --no-open` (or with `--plan <plan-file>` if one exists) (safe to run twice: it reuses a map already running for this repo). Inside AO (env var `AO_BROWSER_CAPABILITY` set) also run `ao preview <url>`. See the `agenttrail` skill.
+Before delegating, start the live map (Trigger B) so the user can follow the team: `aos-trail --ensure` (add `--plan <plan-file>` if the plan path is explicit) (safe to run twice: it reuses a map already running for this repo). Put the live-map link in your reply (the autostart hook also adds it as context when active). Inside AO (env var `AO_BROWSER_CAPABILITY` set) also run `ao preview <url>`. See the `agenttrail` skill.
 
 ### 1. In Antigravity Harness
 If running in Google Antigravity with native subagent support:

package/skills/bdbrainstorm/SKILL.md

@@ -36,11 +36,17 @@ You are strictly required to enforce the following 6 pillars in your process:
 
 ### 6. Shipping Godmode & Pipeline Hand-off
 - Before the brainstorm concludes, verify that the plan satisfies the `godmode-shipping` rules (Spec-Driven Development, feature flags, rollback strategies).
-- **Mandatory — Plan Canvas review.** Write the aligned plan to a file, then run `aos-plan-canvas open <file>` followed by `aos-plan-canvas await <file>` and leave it running. The user reviews and annotates in the browser (Mermaid diagrams render live, click-to-annotate, chat rail); do not write `state.goal` or hand off to `/startcycle-graph` before an `approve` verdict comes back. A `request_changes` verdict means revise the plan file and reopen the session — it live-reloads. This runs identically regardless of which agent harness is executing this skill; it is a plain CLI, not a Claude-Code-specific mechanism. See the `plan-canvas` skill.
+- **Mandatory — Plan Canvas review.** Write the aligned plan to a file. Choose the planning mode by running `aos-plan-canvas modes` and presenting available modes to the user (see the "Planning mode choice" section in the `plan-canvas` skill). Then run `aos-plan-canvas open <file> --mode <choice>` followed by `aos-plan-canvas await <file>` and leave it running. The user reviews and annotates in the browser (Mermaid diagrams render live, click-to-annotate, chat rail); do not write `state.goal` or hand off to `/startcycle-graph` before an `approve` verdict comes back. A `request_changes` verdict means revise the plan file and reopen the session — it live-reloads. This runs identically regardless of which agent harness is executing this skill; it is a plain CLI, not a Claude-Code-specific mechanism. See the `plan-canvas` skill.
 - Write the plan in the agenttrail component convention (`## Name {#id}` components with `needs:` / `files:` lines, tasks as `- [ ] ... {#id}`) and render the architecture with `aos-archify` so the canvas review includes the diagram; after the `approve` verdict, Trigger A starts the live map. See the `agenttrail` and `archify` skills.
 - Present the aligned plan and hand off to `/startcycle-graph` for execution — write `state.goal` from this session's output and let `/startcycle-graph`'s dispatcher take it from there (see `.agents/graph.md`). This skill does not invoke `/startcycle-graph`'s agents itself; it produces the goal they read.
 - For a recurring quality goal, run `/design-control-loop` after shipping (manual, opt-in; not part of the graph).
 
+## Competing Plans
+
+If the brainstorm yields two viable directions, have two different agents each
+write a plan file and compare them with the `plan-arbiter` skill before
+handing off to `/startcycle-graph`. Review the arbiter's memo in `plan-canvas`.
+
 ## Execution Rules
 1. **Never skip the debate:** Ideas must be contested by subagents and the user before finalization.
 2. **Never build alone:** Always use subagents for implementation.

package/skills/global_config/agentic-harness-patterns/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: agentic-harness-patterns
+description: >-
+  Harness patterns for coding agents — memory, permissions, context
+  engineering, delegation, skills, hooks, bootstrap.
+when_to_use: >-
+  Triggers on: harness engineering, tool safety, permission pipeline,
+  agent memory, memory persistence, delegation pattern, context budget,
+  bootstrap sequence, skill runtime, hook lifecycle, tool orchestration,
+  agent harness, context engineering.
+category: engineering-method
+metadata:
+  version: "1.0.0"
+  origin: keli-wen/agentic-harness-patterns-skill
+  license: MIT
+---
+
+<!-- Source: keli-wen/agentic-harness-patterns-skill skills/agentic-harness-patterns/SKILL.md — MIT, see THIRD_PARTY_NOTICES.md -->
+
+# Agentic Harness Patterns
+
+Production AI coding agents are not just an LLM calling tools in a loop. The **harness** — memory, skills, safety, context control, delegation, and extensibility — is what separates a demo from a production system.
+
+**For:** Engineers building or extending coding-agent runtimes, custom agents, or advanced multi-agent workflows.
+**Not for:** Prompt engineering, model selection, generic software architecture, or LLM API basics.
+
+All principles are distilled from production runtime decisions. Claude Code is used as grounding evidence, not as the only possible implementation.
+
+## Choose Your Problem
+
+| If you want to... | Read |
+|---|---|
+| Make the agent remember and improve over time | [Memory](#1-memory) |
+| Package reusable workflows and expertise | [Skills](#2-skills) |
+| Let the agent use tools powerfully but not dangerously | [Tools and Safety](#3-tools-and-safety) |
+| Give the agent the right context at the right cost | [Context Engineering](#4-context-engineering) |
+| Split work across multiple agents without losing control | [Multi-agent Coordination](#5-multi-agent-coordination) |
+| Extend behavior with hooks, background tasks, or startup logic | [Lifecycle and Extensibility](#6-lifecycle-and-extensibility) |
+
+**Before you start building:** Read the [Gotchas](#gotchas) — these are the non-obvious failure modes that cost the most time.
+
+---
+
+## 1. Memory
+
+**User problem:** "My agent forgets corrections and project rules between sessions."
+
+**Golden rule:** Separate what the agent *knows* (instruction memory) from what the agent *learns* (auto-memory) from what the agent *extracts* (session memory). Each layer has different persistence, trust, and review needs.
+
+**When to use:** Any agent that operates across multiple sessions or needs to accumulate project-specific knowledge over time.
+
+**How it works:**
+
+- **Instruction memory** is curated, hierarchical configuration injected into system context in priority order (org-wide → user → project → local; local wins). This is where project conventions, coding standards, and behavioral rules live. It is human-authored and stable.
+- **Auto-memory** is agent-written persistent knowledge with a type taxonomy (user / feedback / project / reference) and a capped index. Saving is two-step: write a topic file, then update the index. The cap prevents unbounded growth — without cleanup, recent entries silently disappear.
+- **Session extraction** runs as a background agent at session end. It directly writes to auto-memory — topic file then index — following the same two-step save invariant. A mutual-exclusion guard ensures that if the main agent already wrote memory during the turn, the extractor skips entirely. This is the autonomous learning loop.
+- **Review and promotion** audits across all memory layers and proposes cross-layer moves (auto-memory → project conventions, personal instructions, or team memory). It never applies changes autonomously — proposals require explicit user approval.
+
+**Start here:** Define your memory layers (instruction, auto, extraction). Implement the two-step save invariant (topic file, then index). Add background extraction only after the core write path is stable.
+
+> **In Claude Code:** Use `/remember` to audit and promote auto-memory entries across layers.
+
+**Tradeoffs:**
+
+- More memory layers = richer recall but higher maintenance burden. Without periodic pruning, index caps cause silent data loss.
+- Session extraction adds latency at session end but dramatically improves cross-session learning.
+
+**Go deeper:** [references/memory-persistence-pattern.md](references/memory-persistence-pattern.md)
+
+---
+
+## 2. Skills
+
+**User problem:** "I want my agent to reuse workflows and domain knowledge without re-explaining them every time."
+
+**Golden rule:** Skills are lazy-loaded instruction sets, not eagerly injected prompts. Discovery must be cheap (metadata only); the full body loads only on activation.
+
+**When to use:** Any agent that needs reusable, composable workflows activating on matching user intent.
+
+**How it works:**
+
+- **Discovery** is budget-constrained: the agent sees a compact listing of all available skills (name, description, and when-to-use hint concatenated per entry), each hard-capped at a fixed character limit, with the total capped at roughly 1% of the context window. Front-load your trigger language — tails get truncated.
+- **Loading** is lazy: only metadata enters the always-on context. The full skill body loads only when the skill activates, keeping idle token cost near zero.
+- **Execution** can be inline (shared context) or isolated (forked sub-agent with its own token budget). Isolation prevents a heavy skill from exhausting the parent's context.
+- **Sources** can be bundled, user-installed, or dynamically loaded from plugins. Deduplication by canonical path prevents the same skill from appearing twice across overlapping source directories.
+
+**Start here:** Choose a metadata format (frontmatter recommended). Implement two-phase discovery: cheap listing at startup, lazy body loading on invocation. Set a per-entry character cap before your catalog grows.
+
+**Tradeoffs:**
+
+- Lazy loading saves tokens but adds one round-trip of latency on first activation.
+- Forked execution provides isolation but loses access to the parent's accumulated context.
+
+**Go deeper:** [references/skill-runtime-pattern.md](references/skill-runtime-pattern.md)
+
+---
+
+## 3. Tools and Safety
+
+**User problem:** "I want my agent to use tools powerfully, but not dangerously."
+
+**Golden rule:** Default to fail-closed. Tools are serial and gated unless explicitly marked safe for concurrency and approved by the permission pipeline.
+
+**When to use:** Any agent runtime that needs tool registration, concurrency control, or permission gating.
+
+**How it works:**
+
+- **Registration** uses fail-closed defaults: tools are non-concurrent and non-read-only unless the developer opts in. This prevents accidental parallel execution of state-mutating operations.
+- **Concurrency classification** is per-call, not per-tool: the same tool can be safe for some inputs and unsafe for others. The runtime partitions a batch of tool calls into consecutive groups — safe calls run in parallel, any unsafe call starts a serial segment.
+- **Permission pipeline** evaluates rules from multiple sources in strict priority order spanning settings files (user, project, local, flag, and policy), CLI arguments, command-scoped rules, and session grants. The evaluator is stateful — it tracks denials, transforms modes, and updates state as a side effect.
+- **Handler dispatch** varies by execution environment: interactive (human prompt), automated (coordinator), or async (swarm agent). The same permission rules feed different approval surfaces.
+
+**Start here:** Route every tool call through one permission gate. Default to fail-closed (deny/ask). Add bypass-immune rules for protected paths before shipping any auto-approve mode.
+
+> **In Claude Code:** Use `/update-config` to configure permission rules and hooks.
+
+**Tradeoffs:**
+
+- Fail-closed defaults mean new tools are safe out of the box, but developers must actively opt into concurrency — forgetting to flag a read-only tool as concurrent-safe silently degrades throughput.
+- Multi-source permission layering is powerful but hard to debug when rules from different sources conflict.
+
+**Go deeper:** [references/tool-registry-pattern.md](references/tool-registry-pattern.md) | [references/permission-gate-pattern.md](references/permission-gate-pattern.md)
+
+---
+
+## 4. Context Engineering
+
+**User problem:** "My agent either sees too much, too little, or the wrong thing."
+
+**Golden rule:** Treat context as a budget, not a dump. Every token in the window should earn its place through one of four operations: select, write, compress, or isolate.
+
+**When to use:** Any agent whose performance degrades in long sessions, whose delegated work pollutes the parent context, or whose startup is slow due to eager context loading.
+
+**How it works:**
+
+- **Select** — Load context just-in-time, not all-at-once. Use progressive disclosure with three tiers: metadata (always present, cheap), instructions (loaded on activation), resources (loaded on demand). Memoize expensive context builders and invalidate only at known mutation points — not reactively.
+- **Write** — Context is not read-only. The agent writes back to persistent storage: auto-memory entries, background extraction outputs, task state, permission rules. The write-back loop is what turns a stateless agent into a learning system.
+- **Compress** — Long sessions exhaust the window. Reactive compaction summarizes older turns mid-session, preserving recent context while reclaiming budget. Mark snapshot data as snapshots so the model knows to re-fetch for current state.
+- **Isolate** — Delegated work must not pollute the parent's context. Coordinator workers start with zero context inheritance (only the explicit prompt). Fork children inherit full context but are single-level (no recursive forks). Filesystem-level isolation (worktrees) gives an agent its own working copy.
+
+**Start here:** Audit your current context cost per turn. Apply hard caps to every variable-length block. Add truncation recovery pointers (tell the model which tool to call for full output) before enabling any compression.
+
+**Tradeoffs:**
+
+- Aggressive caching reduces latency but creates staleness risk — every mutation point must explicitly clear the cache, or the model operates on stale data for the remainder of the session.
+- Progressive disclosure saves tokens but means the model can't reason about a skill's full capabilities until it's activated.
+
+**Go deeper:** [references/context-engineering-pattern.md](references/context-engineering-pattern.md) (index) | [select](references/context-engineering/select-pattern.md) | [compress](references/context-engineering/compress-pattern.md) | [isolate](references/context-engineering/isolate-pattern.md)
+
+---
+
+## 5. Multi-agent Coordination
+
+**User problem:** "I want parallelism, specialization, and coordination without chaos."
+
+**Golden rule:** The coordinator must synthesize, not delegate understanding. "Based on your findings, fix it" is an anti-pattern — the coordinator should digest worker results into precise specs before dispatching implementation.
+
+**When to use:** When a task is too large for a single agent, when you need parallel exploration, or when you want persistent specialized teammates.
+
+**How it works:**
+
+Three delegation patterns serve different task shapes:
+
+| Pattern | Context sharing | Best for |
+|---------|----------------|----------|
+| **Coordinator** | None — workers start fresh | Complex multi-phase tasks (research → synthesize → implement → verify) |
+| **Fork** | Full — child inherits parent history | Quick parallel splits sharing loaded context |
+| **Swarm** | Peer-to-peer via shared task list | Long-running independent workstreams |
+
+Key constraints:
+
+- Fork is single-level only — recursive forks would multiply context cost exponentially.
+- Swarm teammates cannot spawn other teammates — the roster is flat to prevent uncontrolled growth.
+- Results arrive asynchronously; fire-and-forget registration returns an ID immediately so the parent can continue working.
+
+**Start here:** Pick one delegation pattern and implement it fully before mixing patterns. Write every sub-agent prompt as a self-contained document. Add a synthesis step between research and implementation workers — this is where the orchestrator adds value.
+
+**Implementation checklist for the coordinator pattern:**
+
+1. Define phased workflow: research → synthesize → implement → verify
+2. Write self-contained prompts for each worker (no "based on your findings")
+3. Filter each worker's tool set to only what it needs
+4. Decide continue-vs-spawn policy: continue if context overlaps, spawn fresh for verification
+
+**Tradeoffs:**
+
+- Coordinator mode is safest but slowest — each phase waits for the previous one.
+- Fork is fastest but limited to one level and shares the parent's full context cost.
+- Swarm is most flexible but hardest to coordinate — peers communicate only through a shared task list.
+
+**Go deeper:** [references/agent-orchestration-pattern.md](references/agent-orchestration-pattern.md)
+
+---
+
+## 6. Lifecycle and Extensibility
+
+**User problem:** "I need hooks, background tasks, and a clean startup sequence."
+
+**Golden rule:** Extensibility is an injection point, not an inheritance hierarchy. Hooks attach side effects at lifecycle moments; tasks track async work with strict state machines; bootstrap layers initialization sequentially with memoized stages.
+
+**When to use:** When you need to extend agent behavior without modifying core code, track long-running background work, or structure initialization across multiple entry modes.
+
+**How it works:**
+
+- **Hooks** extend behavior by attaching side effects at defined lifecycle moments (pre/post tool execution, prompt submission, agent start/end). Trust is all-or-nothing: if the workspace is untrusted, all hooks skip — not just suspicious ones. Session-scoped hooks are ephemeral and cleaned on session end.
+- **Long-running work** is tracked via typed state machines. Each work unit gets a typed, prefixed ID, a strict lifecycle (running → completed / failed / killed), and disk-backed output. Eviction is two-phase: disk output cleaned eagerly at terminal state, in-memory records cleaned lazily after the parent has been notified.
+- **Bootstrap** structures initialization as dependency-ordered, memoized stages. The trust boundary — the point where the user grants consent — is the critical inflection: security-sensitive subsystems (telemetry, secret environment variables) must not activate before trust is established. Multiple entry modes (CLI, server, SDK) share the same bootstrap path with different entrypoints.
+
+**Start here:** Route all hooks through a single dispatch point. Implement the trust gate before adding any external hook type. Register cleanup handlers during init, not at usage sites.
+
+> **In Claude Code:** Use `/update-config` to configure hooks (pre/post tool execution, prompt submission).
+
+**Tradeoffs:**
+
+- All-or-nothing hook trust is simple but coarse — one untrusted hook disables the entire extension system.
+- Disk-backed task output keeps memory constant but adds I/O latency proportional to concurrent work units.
+
+**Go deeper:** [references/hook-lifecycle-pattern.md](references/hook-lifecycle-pattern.md) | [references/task-decomposition-pattern.md](references/task-decomposition-pattern.md) | [references/bootstrap-sequence-pattern.md](references/bootstrap-sequence-pattern.md)
+
+---
+
+## Gotchas
+
+Non-obvious principles that will cause bugs if you violate them:
+
+1. **Concurrency classification is per-call, not per-tool.** A tool may be safe for some inputs and unsafe for others. Don't assume a tool's concurrency behavior is static — the runtime decides per invocation.
+
+2. **Permission evaluation has side effects.** The permission checker tracks denials, transforms modes, and updates state. Don't treat it as a pure lookup function.
+
+3. **Most async work skips the "pending" state.** In practice, work units register directly as "running." Don't build UIs that assume every work unit starts pending.
+
+4. **Fork children must not fork.** The recursive guard preserves a single-level invariant. The fork tool stays in the child's tool pool (for prompt cache sharing) but is blocked at call time.
+
+5. **Context builders are memoized but manually invalidated.** Add a context source without adding a corresponding invalidation point, and the model sees stale data for the entire session.
+
+6. **Memory indexes have hard caps.** Entries beyond the cap are silently truncated. Without periodic cleanup, recent entries become invisible.
+
+7. **Skill listing budgets are tight.** Descriptions are concatenated and capped per entry. Front-load the most distinctive trigger language — the tail gets cut.
+
+8. **Hook trust is all-or-nothing.** If the workspace is untrusted, the entire hook system is disabled, not just individual suspicious hooks.
+
+9. **The default permission for tools is "allow."** Tools that don't implement custom permission logic delegate entirely to the rule-based system. Override only when you need tool-specific gates (path ACLs, quotas, etc.).
+
+10. **Eviction requires notification.** A terminal work unit is only GC-eligible after the parent has received the completion signal. Evicting before notification creates a race where the parent can never read the result.
+
+---
+
+## When NOT to Use This Skill
+
+This skill is about the **harness** around an agent, not:
+- Prompt engineering or system prompt design
+- Model selection or fine-tuning
+- Generic software architecture (MVC, microservices)
+- Chat UIs or conversational interfaces
+- LLM API integration basics
+
+If your question is about the model itself rather than the system around it, this skill does not apply.

package/skills/global_config/agentic-harness-patterns/metadata.json

@@ -0,0 +1,10 @@
+{
+  "version": "1.0.0",
+  "organization": "Community",
+  "date": "April 2026",
+  "abstract": "Production harness patterns for AI coding agents — memory, permissions, context engineering, multi-agent delegation, skill runtimes, hook lifecycles, bootstrap sequences. Distilled from systematic source-level analysis of Claude Code.",
+  "references": [
+    "https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents",
+    "https://github.com/anthropics/claude-code"
+  ]
+}