@hybridlabor-api/aos 4.13.2 → 4.14.0

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"
+  ]
+}

package/skills/global_config/agentic-harness-patterns/references/agent-orchestration-pattern.md

@@ -0,0 +1,97 @@
+# Agent Orchestration Pattern
+
+## Problem
+
+Without deliberate orchestration structure, multi-agent systems collapse into one of two failure modes: a single overloaded agent that serializes everything and runs out of context, or an uncontrolled fan-out where every sub-agent spawns more sub-agents, producing recursive depth that is impossible to track or cancel. A third failure is "lazy delegation" — passing raw research findings to implementation workers instead of synthesizing them into precise specifications, which degrades output quality proportionally to task complexity.
+
+These problems emerge in any agent runtime that supports delegation to sub-agents — they are not specific to a single implementation.
+
+## Golden Rules
+
+### Synthesize, don't delegate understanding
+
+The orchestrator's job is not to forward raw findings from one worker to the next. After a research phase completes, the orchestrator must read the results, extract the relevant facts, and compose a self-contained specification for the next worker. A worker prompt that says "based on your findings" delegates understanding to a process that has no findings — it started from a blank context. Every worker prompt must be interpretable by someone who has never seen the prior conversation.
+
+### Choose delegation patterns deliberately; do not mix conflicting assumptions
+
+The delegation patterns (coordinator, fork, swarm/peer) solve fundamentally different problems and make different assumptions about context sharing, depth, and lifecycle. Before mixing patterns in a single session, verify that their assumptions are compatible. Coordinator workers that start from blank context are incompatible with the context-sharing assumption of forking. Swarm peers that coordinate through shared state are incompatible with coordinator-style phased sequencing. If your runtime enforces mutual exclusion between modes, that is a valid simplification — it eliminates an entire class of ownership ambiguity at the cost of flexibility.
+
+### Depth must be bounded by design
+
+Recursive delegation is the single most dangerous failure mode in agent orchestration. Every pattern must enforce a hard depth limit: coordinator workers may spawn sub-workers but the overall tree must remain tractable; fork children cannot fork again; swarm peers cannot spawn other peers. These constraints exist because unbounded depth produces exponential fan-out that is impossible to monitor, cancel, or reason about.
+
+### Workers get only the tools they need
+
+Sub-agents that inherit the full tool set of the parent can take actions the orchestrator never intended — spawning their own background workers, modifying orchestration state, or accessing resources outside their task scope. Filter each worker's available tools down to what their specific task requires. Asynchronous workers need a more restricted set than synchronous ones, because they run without direct supervision.
+
+## When To Use
+
+- Your agent needs to split work across multiple concurrent sub-agents.
+- A task has distinct phases that must sequence (research, then synthesis, then implementation, then verification).
+- You need parallel execution of independent subtasks while maintaining a single coordination point.
+- A parent agent has accumulated significant context and needs to share it with workers without re-deriving it.
+- Long-running peer agents need to collaborate on shared state over many turns.
+- You need independent verification of implementation quality by a worker that does not share the implementer's assumptions.
+
+## Tradeoffs
+
+| Decision | Benefit | Cost |
+|---|---|---|
+| Three distinct patterns instead of one | Each pattern is simple and well-suited to its use case | Developers must choose correctly; wrong choice degrades performance |
+| Coordinator starts workers from blank context | Clean separation of concerns; no stale assumptions leak through | Orchestrator must do real synthesis work to produce self-contained prompts |
+| Fork inherits full parent context | Workers immediately have all relevant background; no re-research needed | Context size is doubled per child; parent changes after fork are invisible to children |
+| Single-level fork constraint | Prevents exponential fan-out; keeps the process tree shallow and cancellable | Cannot decompose fork children's work further; parent must plan granularity up front |
+| Flat swarm roster | Every peer is visible and addressable; no hidden sub-teams | Coordination complexity grows linearly with team size; no hierarchical delegation |
+| Mutual exclusion between modes (if enforced) | No ambiguity about who owns orchestration | Cannot combine coordinator's phased workflow with fork's context sharing in one session |
+| Worker tool filtering | Workers cannot take unintended actions outside their task scope | Filtering logic must be maintained as the tool set evolves |
+| Continue-vs-spawn decision | Reusing a worker preserves loaded context; spawning fresh avoids assumption leakage | Continuing with stale context is worse than the cost of re-loading from scratch |
+
+## Implementation Patterns
+
+- Decide on the delegation pattern before dispatching work. If your runtime enforces mutual exclusion between modes, gate checks should reject conflicting activations explicitly rather than silently degrading.
+- When using the coordinator pattern, structure work in explicit phases: research workers gather information, the coordinator synthesizes findings into specifications, implementation workers execute against those specifications, and verification workers independently confirm results.
+- Write every worker prompt as a self-contained document. Include the specific file paths, exact changes required, and success criteria. Never reference "prior findings" or "the context above" — the worker has no prior context.
+- After research workers report back, read their full results before dispatching implementation work. The synthesis step is where the orchestrator adds value — skipping it produces the "lazy delegation" failure.
+- When forking, construct the child's initial messages so that the divergence point is as late as possible and the shared prefix is as long as possible. This maximizes cache hits across sibling workers. Only the per-child task directive should differ.
+- Enforce the single-level fork constraint at invocation time, not at tool-definition time. Removing the delegation tool from a fork child's schema would change the tool set, breaking cache alignment with siblings. Instead, keep the tool present but reject the call with a clear error.
+- For swarm peers, coordinate through a shared artifact (task list, file, or message bus) rather than through peer-to-peer spawning. The roster is defined at swarm creation and does not grow during execution.
+- Filter each worker's tool set based on its role. Read-only research workers do not need write tools. Implementation workers do not need the ability to spawn their own background agents. Asynchronous workers get a more restrictive allow-list than synchronous ones.
+- Decide whether to continue an existing worker or spawn a fresh one based on context relevance. If the worker's loaded context directly overlaps the next task, continue it. If the next task requires a different perspective (especially for verification), spawn fresh to avoid assumption leakage.
+- For workers running in an isolated filesystem copy, inject a notice explaining that paths from the parent context refer to a different root. The worker must translate inherited paths to its own working directory.
+- Include a purpose statement in every worker prompt so the worker can calibrate depth and scope. "This research will inform a PR description" produces different output than "this research will inform a security audit."
+
+## Gotchas
+
+**Do not skip the synthesis step.** The most common coordinator failure is passing a research worker's raw output directly to an implementation worker. The research worker optimized for breadth; the implementation worker needs precise, actionable specifications. The orchestrator must bridge that gap.
+
+**Verification workers must start fresh.** Never continue a verification task from the implementation worker's context. The implementer's loaded context carries assumptions about correctness that will blind the verifier to the exact bugs it should catch.
+
+**Fork children cannot fork.** Do not design prompts that instruct fork children to further decompose their work via forking. The recursive guard rejects the attempt at call time, wasting a turn. Plan the decomposition granularity at the parent level.
+
+**Identical shared prefixes are load-bearing for cache efficiency.** When forking, the placeholder content in shared message slots must be byte-identical across all siblings. Customizing per-child content in the shared prefix region destroys the cache benefit that justifies forking over coordinator-style delegation.
+
+**Swarm peers cannot spawn other peers.** The team roster is fixed at creation. Design coordination around shared state, not dynamic team expansion. If you need a new peer, the session orchestrator adds it — peers do not recruit.
+
+**In-process peers have lifecycle constraints.** A peer agent running inside the leader's process cannot manage independent background work, because its lifecycle is tied to the leader's. If a peer needs autonomous long-running tasks, it must run in its own process (e.g., a separate terminal session).
+
+**Tool filtering has layers.** Different agent types may receive different tool subsets. Built-in, custom, and asynchronous agents each face their own filtering rules. Custom or less-trusted agents face additional restrictions beyond the base disallow-list. A tool's trust source — built-in, user-installed, or dynamically loaded — may determine whether it passes through all filtering layers or bypasses some.
+
+**Be cautious when assigning weaker models to sub-tasks.** Orchestrators cannot reliably predict sub-task complexity. Routing "simple" tasks to a cheaper model is a false economy when the complexity assessment itself requires the judgment of a capable model.
+
+**Mode checks happen at call time, not at definition time.** The orchestration mode gates do not remove tools from the schema; they reject calls when invoked under the wrong mode. This means the tool appears available but will fail. Design error handling around this — do not retry the same call expecting a different result.
+
+## Claude Code Evidence
+
+Claude Code implements all three orchestration patterns as mutually exclusive modes within a single agent runtime. Only one mode can be active per session — if coordinator mode is active, forking is disabled, and vice versa. This is a deliberate simplification that eliminates ownership ambiguity at the cost of flexibility.
+
+**Coordinator mode as a distinct operational persona.** When coordinator mode is activated, the agent receives an entirely different system prompt that replaces the default. This prompt encodes the phased workflow (research, synthesis, implementation, verification) and the "always synthesize" rule as first-class instructions. The coordinator dispatches workers as async tool calls and receives their results as structured notifications injected into the conversation. The coordinator distinguishes these notifications from real user messages by their markup structure, preventing confusion between human input and worker output.
+
+**Fork as context-sharing with cache optimization.** Claude Code's fork implementation clones the parent's full message history into each child, then appends a synthetic turn where all tool-result slots contain identical placeholder text. Only the final directive block differs per child. This design was chosen specifically to maximize prompt cache hits — the entire shared prefix (system prompt, message history, tool definitions, and placeholder results) is byte-identical across siblings, so the inference provider can serve all children from the same cached prefix. The single-level guard keeps the delegation tool in fork children's tool schemas (preserving byte-identical tool definitions) but rejects any fork attempt at invocation time with a clear error message.
+
+**Swarm as flat peer topology.** Claude Code's team system assigns each peer a name and runs it in a dedicated process. Peers coordinate through a shared task list rather than through message-passing or peer spawning. The runtime enforces the flat roster constraint with an explicit rejection message when a teammate attempts to create another teammate. In-process teammates face additional lifecycle restrictions — they cannot spawn background agents because their execution is coupled to the leader process — while process-isolated teammates manage their own background work independently.
+
+**Tool filtering as defense in depth.** Claude Code applies multiple layers of tool filtering depending on agent type. All sub-agents face a base disallow-list. Custom agents (those defined by users rather than built into the runtime) face an additional restriction layer. Asynchronous agents are restricted to an explicit allow-list rather than the full filtered pool. Extension-provided tools bypass all filtering — a deliberate design choice reflecting that extensions are user-installed and trusted. This layered approach means each worker operates with the minimum tool surface required for its role.
+
+**Model selection as a coordinator responsibility.** Claude Code's coordinator design guidance recommends against overriding the default model for individual workers, based on the observation that orchestrators cannot reliably predict sub-task complexity. Specifying a weaker model for "simple" tasks is treated as a false economy.
+
+**Continue-vs-spawn as an explicit decision point.** The coordinator pattern surfaces the continue-or-spawn choice as a first-class decision in the orchestration flow. The coordinator can send a follow-up message to an existing worker (preserving its accumulated context) or spawn a fresh worker (starting from a clean slate). Claude Code's design guidance is explicit: continue when the existing context directly overlaps the next task, spawn fresh when it does not — especially for verification, where the implementation worker's context carries assumptions that would compromise independent review.