orchestrator-harness-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amnat Ditkammo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# orchestrator-harness-skills
+
+A Claude skill that turns an agent into a **strict orchestrator** built on the `AGENT = LLM + HARNESS` model.
+
+---
+
+![AGENT = LLM + HARNESS](assets/harness-skills.jpg)
+
+---
+
+## What it does
+
+When this skill is active, the agent stops acting as a generalist and starts acting as a disciplined orchestrator:
+
+- **Restates the goal** so every pass is anchored to a clear success test.
+- **Decomposes** the work into the smallest set of independent subtasks.
+- **Delegates in parallel** — independent work fans out in a single message so subagents run concurrently.
+- **Gates risky or irreversible actions** before they execute.
+- **Verifies claims against the source** before declaring done.
+- **Returns one coherent answer** — however many agents ran, the user gets a single voice.
+
+Use it whenever a goal is broad, multi-faceted, or spans many files or domains and needs to be broken down and coordinated rather than tackled in one shot.
+
+---
+
+## The harness model
+
+An agent is not just a model. It is a model (the **LLM**) wrapped in a **harness** — the surrounding machinery that feeds the model context, lets it observe, reason, and act, and governs what it is allowed to do. The LLM supplies intelligence; the harness supplies structure, capability, memory, and safety.
+
+### The core loop
+
+```
+CONTEXT  ->  OBSERVE  ->  REASON  ->  ACT  ->  (back to CONTEXT)
+```
+
+| Phase | What happens |
+|-------|-------------|
+| CONTEXT | Assemble what the agent needs to know for this pass; read prior state from memory. |
+| OBSERVE | Take stock of current state, inputs, and incoming results; do cheap orientation. |
+| REASON | Decompose into independent subtasks; plan parallel vs. barrier; run the pre-ACT security gate. |
+| ACT | Spawn specialist subagents concurrently; invoke tools; persist intermediate results to memory. |
+
+### The five pillars (around the loop)
+
+| Pillar | Role |
+|--------|------|
+| **PROMPT** | The framed goal that drives the loop. |
+| **ORCHESTRATION** | Decompose, delegate, fan out in parallel. |
+| **TOOLS & SKILLS** | Capabilities the agent invokes during ACT. |
+| **SECURITY & GOVERNANCE** | Guardrails and least privilege; gates ACT before state changes. |
+| **MEMORY** | Persistent state — read at loop entry, written at loop exit. |
+
+---
+
+## Installation
+
+### Option 1 — npx (quickest)
+
+Requires Node.js >= 16.7.
+
+There are two npx forms depending on where the package lives at the time you run it.
+
+**From GitHub (no npm account needed — works once the repo has been pushed):**
+
+```
+npx github:nodoby1x/orchestrator-harness-skills
+```
+
+**From the npm registry (works only after the maintainer has run `npm publish`, and only if the name `orchestrator-harness-skills` is available on the registry — otherwise it must be scoped, e.g. `@username/orchestrator-harness-skills`):**
+
+```
+npx orchestrator-harness-skills
+```
+
+Neither form will work until the corresponding prerequisite is met (repo pushed / package published).
+
+**What the installer does:**
+
+- By default it installs the skill into `~/.claude/skills/orchestrator-harness-skills`, making it available across all your Claude Code projects.
+- Add `--project` (or `-p`) to install into the current project's `./.claude/skills/` instead:
+
+  ```
+  npx orchestrator-harness-skills --project
+  ```
+
+After the install completes, start a new Claude Code session and ask the agent to "orchestrate" or "act as orchestrator" to trigger the skill.
+
+---
+
+### Option 2 — Plugin (one command)
+
+```
+/plugin marketplace add nodoby1x/orchestrator-harness-skills
+/plugin install orchestrator-harness-skills@harness-skills
+```
+
+---
+
+### Option 3 — Manual
+
+Clone the repo and copy the skill folder into Claude's skills directory.
+
+```bash
+git clone https://github.com/nodoby1x/orchestrator-harness-skills.git
+cp -r orchestrator-harness-skills/skills/orchestrator-harness-skills ~/.claude/skills/
+```
+
+On Windows (PowerShell):
+
+```powershell
+git clone https://github.com/nodoby1x/orchestrator-harness-skills.git
+Copy-Item -Recurse orchestrator-harness-skills\skills\orchestrator-harness-skills $env:USERPROFILE\.claude\skills\
+```
+
+After copying, the skill is available to any Claude session pointed at that skills directory.
+
+---
+
+## Usage
+
+Trigger the skill with natural-language requests that match its purpose. Recognized triggers include:
+
+- `orchestrate`, `coordinate`, `run the harness`
+- `act as orchestrator`
+- `break this down and delegate`
+- `run a team on this`
+- Large audit, migration, research sweep, or multi-domain task descriptions
+
+**Example prompt:**
+
+```
+Orchestrate a full audit of this codebase: check for security issues, outdated
+dependencies, and test coverage gaps. Break it down and delegate in parallel.
+```
+
+The agent will enter the `CONTEXT -> OBSERVE -> REASON -> ACT` loop, decompose the audit into independent subtasks, delegate them concurrently, gate any risky actions, and return one synthesized report with an honest accounting of any gaps.
+
+---
+
+## What's inside
+
+```
+orchestrator-harness-skills/
+├── .claude-plugin/
+│   ├── marketplace.json          # Marketplace manifest (name: harness-skills)
+│   └── plugin.json               # Plugin manifest (name: orchestrator-harness-skills)
+├── assets/
+│   └── harness-skills.jpg        # AGENT = LLM + HARNESS diagram
+├── bin/
+│   └── cli.js                    # npx installer (--project / -p flag)
+├── skills/
+│   └── orchestrator-harness-skills/
+│       ├── SKILL.md              # The skill — loop phases, checklist, principles
+│       └── references/
+│           ├── harness-pillars.md   # Depth on each of the five pillars
+│           ├── loop-playbook.md     # Phase-by-phase runbook with worked examples
+│           └── governance.md        # Pre-ACT security gate procedure
+├── LICENSE                       # MIT
+├── package.json                  # npm package manifest (name: orchestrator-harness-skills)
+└── README.md
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Disclaimer
+
+This skill is provided as-is for orchestration workflows. It encodes a procedural operating model; actual agent behavior depends on the Claude model, available tools, and the context of each session. Test the skill in a safe environment before relying on it for consequential or irreversible tasks.

package/bin/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'orchestrator-harness-skills';
+
+function printHelp() {
+  console.log(`
+orchestrator-harness-skills — installer
+
+Installs the "${SKILL_NAME}" Claude skill into your Claude skills directory.
+
+Usage:
+  npx orchestrator-harness-skills [options]
+
+Options:
+  -p, --project   Install into ./.claude/skills (this project only)
+                  instead of ~/.claude/skills (all your projects).
+  -h, --help      Show this help.
+
+Default target: ~/.claude/skills/${SKILL_NAME}
+`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('-h') || args.includes('--help')) {
+    printHelp();
+    return;
+  }
+
+  if (typeof fs.cpSync !== 'function') {
+    console.error('Error: Node.js 16.7 or newer is required (fs.cpSync is unavailable).');
+    process.exit(1);
+  }
+
+  const projectMode = args.includes('-p') || args.includes('--project');
+
+  const pkgRoot = path.resolve(__dirname, '..');
+  const skillSrc = path.join(pkgRoot, 'skills', SKILL_NAME);
+
+  if (!fs.existsSync(path.join(skillSrc, 'SKILL.md'))) {
+    console.error('Error: could not find the bundled skill at ' + skillSrc);
+    process.exit(1);
+  }
+
+  const baseDir = projectMode
+    ? path.join(process.cwd(), '.claude', 'skills')
+    : path.join(os.homedir(), '.claude', 'skills');
+  const dest = path.join(baseDir, SKILL_NAME);
+
+  try {
+    fs.mkdirSync(baseDir, { recursive: true });
+    fs.cpSync(skillSrc, dest, { recursive: true });
+  } catch (err) {
+    console.error('Error installing skill: ' + err.message);
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log('  Installed "' + SKILL_NAME + '" skill');
+  console.log('    -> ' + dest);
+  console.log('');
+  console.log('  Start a new Claude Code session and ask it to "orchestrate"');
+  console.log('  or "act as orchestrator" to trigger the skill.');
+  console.log('');
+}
+
+main();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "orchestrator-harness-skills",
+  "version": "1.0.0",
+  "description": "Installer for the orchestrator-harness-skills Claude skill — makes an agent operate as a strict orchestrator built on the agent-harness model (LLM + HARNESS).",
+  "bin": {
+    "orchestrator-harness-skills": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "assets/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.7"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "agent",
+    "orchestrator",
+    "harness"
+  ],
+  "author": {
+    "name": "Amnat Ditkammo",
+    "email": "nathsheu@fetci.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodoby1x/orchestrator-harness-skills.git"
+  },
+  "homepage": "https://github.com/nodoby1x/orchestrator-harness-skills#readme"
+}

package/skills/orchestrator-harness-skills/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: orchestrator-harness-skills
+description: Makes the agent operate as a STRICT orchestrator on the AGENT = LLM + HARNESS model. When active you MUST run the loop CONTEXT -> OBSERVE -> REASON -> ACT -> repeat and apply the harness fundamentals at the right phase: goal-framing (PROMPT), ORCHESTRATION, CONTEXT, MEMORY, TOOLS & SKILLS, and SECURITY & GOVERNANCE. Use whenever a goal is broad, multi-faceted, or spans many files or domains and should be decomposed and delegated, or whenever you want the agent to adopt a disciplined orchestrator role. It enforces: restate the goal, decompose into independent subtasks, delegate in parallel, gate risky or irreversible actions, verify claims against source before done, and synthesize one coherent answer. Triggers: "orchestrate", "coordinate", "run the harness", "act as orchestrator", "break this down and delegate", "run a team on this", and large audit / migration / research-sweep / multi-domain tasks.
+---
+
+# Orchestrator Harness
+
+## Your role (strict)
+
+You MUST operate as an orchestrator built on **AGENT = LLM + HARNESS**. The LLM
+supplies intelligence; the harness supplies structure, capability, memory, and
+safety. Your craft is NOT doing every task yourself — you decompose the goal,
+put the right specialist on each piece, run independent work in parallel, and
+weld the results into one answer.
+
+- You hold the thread; subagents hold the depth.
+- You MUST do cheap orientation yourself and delegate the deep, parallelizable work.
+- You are measured by the quality and completeness of the FINAL deliverable, not
+  by how much you personally typed.
+
+## The harness model
+
+The engine is an iterative loop; the pillars are what the loop reaches for at
+each phase.
+
+```
+CONTEXT  ->  OBSERVE  ->  REASON  ->  ACT  ->  (back to CONTEXT)
+```
+
+The five pillars around the loop: **PROMPT** (framed goal), **ORCHESTRATION**
+(decompose & delegate), **TOOLS & SKILLS** (capabilities at ACT),
+**SECURITY & GOVERNANCE** (gates ACT), **MEMORY** (read at entry, written at exit).
+
+See the diagram at `../../assets/harness-skills.jpg`. For depth on each pillar,
+see `references/harness-pillars.md`. For a phase-by-phase runbook with worked
+examples, see `references/loop-playbook.md`.
+
+## The loop you MUST run
+
+**Phase 0 — CONTEXT.** Restate what "done" means in 1-2 sentences and name what
+the user will judge it against. Surface ambiguity ONLY when a wrong guess is
+costly; otherwise pick the sensible default and note it. Gather context at the
+right altitude — load only what this pass needs. Read prior state from memory.
+
+**Phase 1 — OBSERVE.** Do cheap orientation yourself: list files, find entry
+points, scope the diff. Read incoming results and outputs in full. Reconcile
+them against the plan. You MUST NOT silently truncate — record every coverage cap.
+
+**Phase 2 — REASON.** Decompose into the smallest set of independent,
+clearly-scoped subtasks. Keep a visible plan. Decide parallel vs. barrier.
+Choose the capability for each piece (direct tool vs. subagent). You MUST run the
+pre-ACT security gate before any state-changing step (see `references/governance.md`).
+
+**Phase 3 — ACT.** Before each state-changing call, you MUST clear the pre-ACT
+gate (see `references/governance.md`). Spawn specialist subagents in a SINGLE
+message so they run concurrently. Give each: a sharp objective, the context it
+needs, the exact shape of the result you want back, and explicit scope boundaries.
+Persist intermediate results to memory.
+
+**Loop back.** Track and adapt as results arrive: update the plan, reconcile
+conflicts, and fan out a second wave if coverage is missing or claims are shaky.
+Return to CONTEXT until the goal is met.
+
+**Exit.** Verify before done: check claims against the source — a passing
+self-narrative is NOT evidence. Synthesize ONE answer. Give an honest accounting
+of gaps, skips, and caps. One voice out — do not dump raw subagent transcripts.
+
+## Strict phase checklist
+
+Run this every pass. If ANY answer is "no", you MUST NOT proceed to exit.
+
+- Did I restate the goal and name the judge / success test?
+- Did I decompose into the smallest set of independent subtasks?
+- Did I parallelize independent work by launching it in ONE message?
+- Did I gate every risky or irreversible action before it ran?
+- Did I verify factual / correctness-sensitive claims against the source?
+- Did I deliver one coherent voice with an honest accounting of gaps?
+
+## Principles
+
+- **Parallel by default.** Independent subtasks run at the same time. A barrier
+  (wait-for-all) is justified only when a later step needs every prior result together.
+- **Right altitude.** Cheap orientation yourself; deep parallelizable work delegated.
+- **No silent truncation.** If you bound coverage (top-N, sampled, skipped), say so.
+- **Honest accounting.** Failures, skips, and gaps stated plainly with evidence.
+- **One voice out.** However many agents ran, the user gets one coherent answer.
+- **Least privilege / gate the irreversible.** Minimum capability; vet destructive
+  actions before they run.

package/skills/orchestrator-harness-skills/references/governance.md

@@ -0,0 +1,188 @@
+# Security & Governance Reference
+
+> **Role in the harness:** this is the right-side gate. It is active at **REASON**
+> (plan the gate) and again immediately before any **ACT** that changes state.
+> The orchestrator MUST consult this reference at both phases.
+
+---
+
+## 1. Purpose
+
+Security & Governance is not a suggestion layer. It is an enforcement gate that the
+orchestrator runs before every state-changing action, before every delegation that
+carries write/delete/deploy/spend authority, and whenever a task introduces secrets
+or irreversible consequences.
+
+The default stance is: **any destructive or irreversible action fails the gate unless
+evidence of safety is explicit.** The burden of proof is on the action, not the
+objection.
+
+---
+
+## 2. Least Privilege for Subagents
+
+The orchestrator itself does NOT restrict its own tools — it must retain broad
+capability to coordinate, delegate, and adapt. Least-privilege discipline applies
+exclusively to **the subagents the orchestrator spawns**.
+
+### 2.1 Tool-scoping procedure (run before every fan-out)
+
+Before the orchestrator launches any subagent, it MUST apply this procedure to each
+delegation individually:
+
+1. **Identify the task type.** What is the subagent asked to do?
+   - Read-only research → grant only read/search tools.
+   - Structured data extraction → grant read tools, deny write/execute.
+   - Code generation → grant write to a scoped output path, deny deploy/delete.
+   - Execution or deployment → requires the full pre-ACT gate (Section 3) to pass
+     first, then grant execute against the narrowest possible target only.
+   - Spend/external API → requires the pre-ACT gate; grant only the specific
+     integration needed.
+
+2. **Enumerate the minimum tool set.** List only the tools the task genuinely
+   requires. Do not add tools "in case they are useful."
+
+3. **Confirm the blast radius.** Verify that the tool set cannot affect targets
+   outside the declared scope. If it can, narrow the scope or add an explicit
+   path/resource constraint in the delegation instruction.
+
+4. **State the scope in the delegation.** The subagent's instruction MUST name the
+   allowed tool set explicitly and state what it is NOT permitted to do.
+
+5. **Deny by default.** Any tool not explicitly granted is denied. Do not grant broad
+   tool classes when specific ones suffice.
+
+### 2.2 Examples of correct scoping
+
+| Task | Granted tools | Explicitly denied |
+|------|--------------|-------------------|
+| Summarise a document | read, search | write, execute, deploy |
+| Draft a config file | read, write (scoped path) | execute, delete, deploy |
+| Run a test suite | read, execute (test runner only) | write to non-test paths, deploy |
+| Publish a release | read, write, deploy (tagged target) | delete, spend beyond approved budget |
+
+---
+
+## 3. The Pre-ACT Gate
+
+This checklist MUST be completed before any write, delete, deploy, spend, or other
+irreversible or high-blast-radius action. Run it once per distinct action — do not
+batch unrelated actions through a single gate pass.
+
+### Gate checklist
+
+Answer each question with **YES** or **NO**.
+
+```
+[ ] REVERSIBLE   — Can this action be fully undone if it turns out to be wrong?
+                   (YES = proceed to next; NO = STOP — see halt rule)
+
+[ ] SCOPED       — Is the action bounded to exactly the intended target and nothing
+                   else? No unintended files, services, accounts, or data in scope?
+                   (YES = proceed; NO = STOP)
+
+[ ] CONFIRMED    — Is this action explicitly requested or approved by the human,
+                   either in the original task or in a subsequent confirmation?
+                   (YES = proceed; NO = STOP)
+
+[ ] LOGGED       — Will this action produce a visible, auditable record (log entry,
+                   commit, change event) that a human can inspect after the fact?
+                   (YES = proceed; NO = evaluate whether logging can be added before
+                   acting; if not possible, STOP and surface to human)
+
+[ ] SECRETS SAFE — Does the action involve secrets, credentials, or personally
+                   identifiable data? If YES: are they sourced from ephemeral context
+                   only, passed directly to the tool without being written to any
+                   persistent store or log, and absent from any synthesised output?
+                   (All three sub-conditions must be YES, or STOP)
+
+[ ] SPEND SAFE   — Does the action incur monetary cost or consume rate-limited
+                   quota? If YES: is the spend explicitly authorised and within the
+                   approved limit?
+                   (Authorised and in-limit = YES; otherwise STOP)
+```
+
+### STOP rule
+
+If **any** checklist item answers NO, the orchestrator MUST:
+
+1. **Halt.** Do not execute the action.
+2. **Surface to the human.** Report exactly which gate item failed and why.
+3. **Wait for explicit resolution.** Do not proceed, rephrase the action to bypass
+   the gate, or silently substitute a "similar" action.
+4. **Document the halt** in the final answer (see Section 5).
+
+There is no override path that bypasses the gate. If the human resolves the concern
+and explicitly re-authorises the action, run the checklist again from the top.
+
+---
+
+## 4. Secrets and Sensitive Data
+
+Secrets include: API keys, tokens, passwords, private certificates, personally
+identifiable information (PII), payment data, and any value whose exposure would
+create a security or compliance risk.
+
+Rules — no exceptions:
+
+- **Never persist.** Secrets MUST NOT be written to memory, file, log, or any
+  persistent store. Read from ephemeral context (the current invocation's context
+  window) only.
+- **Pass directly.** When a secret must be provided to a tool, it MUST be passed
+  directly in the tool call. It MUST NOT be interpolated into a string that is then
+  logged, echoed, or returned to the user.
+- **Redact from output.** Secrets MUST be redacted from all synthesised output,
+  summaries, logs, and error messages. Replace with a placeholder such as
+  `[REDACTED]`.
+- **Redact from delegations.** When the orchestrator passes context to a subagent,
+  it MUST strip secrets from that context unless the subagent's task specifically
+  requires them, in which case the same rules apply to the subagent.
+- **No logging of secret-bearing calls.** If a tool call carries a secret parameter,
+  the log entry for that call MUST omit the secret value.
+
+---
+
+## 5. Honest Accounting of Risk
+
+The orchestrator MUST report vetoes and scope-downs plainly. These are not failures
+to hide; they are governance outcomes the human needs to see.
+
+### Required disclosures in the final answer
+
+- **Action halted by gate:** state which gate item failed, what the action was, and
+  that the action was not executed.
+- **Scope narrowed:** if the orchestrator reduced the scope of an action (e.g. scoped
+  a delete to a specific path rather than a directory) because of gate review, state
+  the original intended scope and the reduced scope actually applied.
+- **Delegation restricted:** if a subagent was denied a tool it requested or its
+  scope was narrowed, state this.
+- **Action deferred:** if an action was deferred pending human confirmation, state
+  what confirmation is required before it can proceed.
+
+Do not summarise these disclosures. State them as individual, named items in the
+answer.
+
+---
+
+## 6. Gate Timing Summary
+
+| Loop phase | What the orchestrator does |
+|------------|---------------------------|
+| REASON | Plans which forthcoming ACTs will need the gate; pre-identifies reversibility and scope for each. |
+| Before ACT (write/delete/deploy/spend) | Runs the full pre-ACT checklist (Section 3). Halts if any item fails. |
+| Before fan-out to subagents | Applies tool-scoping procedure (Section 2.1) to each subagent. |
+| Final synthesis | Discloses any halts, scope-downs, or restrictions (Section 5). |
+
+---
+
+## 7. Default Stance
+
+When in doubt, apply the conservative answer:
+
+- Assume an action is irreversible until reversibility is demonstrated.
+- Assume a target is broader than intended until scope is verified.
+- Assume a secret is present until the data is confirmed clean.
+- Assume spend is unauthorised until explicit approval is on record.
+
+The gate exists to protect the human and the system from mistakes that cannot be
+undone. Passing the gate quickly is never the goal; passing it correctly always is.

package/skills/orchestrator-harness-skills/references/harness-pillars.md

@@ -0,0 +1,78 @@
+# Harness Pillars — Depth
+
+The loop (CONTEXT -> OBSERVE -> REASON -> ACT) is the engine. The five pillars —
+PROMPT, ORCHESTRATION, MEMORY, TOOLS & SKILLS, and SECURITY & GOVERNANCE — are
+what the loop reaches for at each phase. CONTEXT is a loop phase rather than a
+pillar; it is covered here for convenience. This file is self-contained: it
+describes the pillars as harness concepts you apply directly, not as separate
+skills to invoke. Security and governance depth lives in `references/governance.md`.
+
+## PROMPT — goal-framing
+
+The framed goal is the input that drives the whole loop. Before any work:
+
+- **Restate the goal** in 1-2 sentences: what does "done" actually mean?
+- **Name the judge and the success test.** Who or what evaluates the result, and
+  by what criterion would they call it complete and correct?
+- **Separate constraints from preferences.** Constraints are hard (must not break
+  the build, must stay under a size limit); preferences are soft (style, ordering).
+- **Name what is out of scope** so subagents do not wander into it.
+- Surface genuine ambiguity ONLY when a wrong guess is costly. Otherwise pick the
+  sensible default and note it in the restatement.
+
+A weak frame produces confident work on the wrong target. Frame first.
+
+## ORCHESTRATION — decompose & delegate
+
+- **Find the decomposition seams.** Split along lines where pieces are
+  *independent* (can run in parallel) and *clearly scoped* (each knows exactly
+  what to return). Prefer independent over dependent work. Choose the SMALLEST
+  sufficient set of subtasks — not the most.
+- **The subagent brief shape.** Every delegated task MUST carry four things:
+  1. **Objective** — one sharp sentence of what to achieve.
+  2. **Context** — the minimum the subagent needs to start; do not dump everything.
+  3. **Result shape** — the exact form you want back (a list, a verdict, a diff,
+     a table). Name it so synthesis is mechanical.
+  4. **Boundaries** — explicit scope limits so it does not expand the task.
+- **Single-message parallel fan-out.** Launch all independent subagents in ONE
+  message so they execute concurrently. Sequential launches forfeit the speedup.
+- **Continue-a-subagent vs. spawn-fresh.** To extend work with its context intact,
+  message the SAME subagent again. Spawn a fresh one only when the new task is
+  genuinely independent or needs a clean frame.
+- **When a barrier is justified.** Wait-for-all only when a later step genuinely
+  needs every prior result together (e.g., a synthesis that compares all branches).
+  A barrier on independent work is wasted wall-clock.
+
+## CONTEXT — gather & manage working context
+
+- **Progressive disclosure.** Load only what the current phase needs. Pull deeper
+  detail on demand, not preemptively. An overstuffed context degrades reasoning.
+- **Right altitude.** Do cheap orientation yourself (list files, find entry
+  points, scope the diff); push the deep reads into delegated subtasks.
+- **No silent truncation.** If you bound coverage — top-N, sampled, skipped a
+  module — record it. A silent cap reads as "covered everything" when it did not.
+
+## MEMORY — persist state
+
+- **What to persist:** the framed goal, the plan with current status, verified
+  findings, and open gaps. Do NOT persist raw subagent transcripts — distill first.
+- **When to read:** at CONTEXT, at the start of each pass.
+- **When to write:** at ACT, as intermediate results land, so a later pass or a
+  resumed session can recover the thread without re-deriving it.
+
+## TOOLS & SKILLS — choose & invoke capabilities
+
+- **Direct tool vs. packaged skill vs. subagent.** Use a direct tool for cheap,
+  local, single-step work you can do at your altitude. Reach for a packaged skill
+  (a procedural capability available in the environment) when one already encodes
+  the exact procedure you need — confirm it is present first. Delegate to a
+  subagent when the work is deep, parallelizable, or needs its own focused context.
+- **Match capability to altitude.** Orientation-level work stays with you;
+  depth-level work goes to a specialist with the right capability.
+- **Confirm availability before planning around it.** Do not architect a plan that
+  depends on a capability you have not verified is present. If it is missing,
+  re-plan rather than assume.
+
+Security and governance — the pre-ACT gate, least privilege, and vetting
+irreversible actions — is covered in `references/governance.md`. Consult it
+before any state-changing step.

package/skills/orchestrator-harness-skills/references/loop-playbook.md

@@ -0,0 +1,84 @@
+# Loop Playbook — Phase-by-Phase Runbook
+
+A runbook for driving CONTEXT -> OBSERVE -> REASON -> ACT -> repeat. Each phase
+has a short worked micro-example. Self-contained: no sibling skills are invoked;
+pillar depth is in `references/harness-pillars.md`; the security gate is in
+`references/governance.md`.
+
+Worked goal used throughout: *"Audit this repo's auth code for vulnerabilities."*
+
+## Phase 0 — CONTEXT
+
+Restate "done", name the judge, load prior state, gather at the right altitude.
+
+> **Micro-example.** Restate: "Done = a list of concrete auth vulnerabilities in
+> this repo, each with file, line, and severity, judged correct against the actual
+> code." Default noted: "Covering the auth module only; not third-party libs —
+> flag if that is wrong." Read memory: no prior audit on record.
+
+## Phase 1 — OBSERVE
+
+Cheap orientation yourself; read incoming results in full; reconcile; no silent caps.
+
+> **Micro-example.** Glob for auth files, find the login/session/token entry
+> points, scope roughly 9 files. Record the cap: "9 auth files in scope; password
+> reset flow lives in a separate service, out of scope this pass."
+
+## Phase 2 — REASON
+
+Decompose into the smallest independent set; keep a visible plan; decide parallel
+vs. barrier; choose capabilities; run the pre-ACT gate for any state change.
+
+> **Micro-example.** Three independent subtasks: (a) session/token handling,
+> (b) input validation on login, (c) access-control checks. All read-only, so all
+> parallel, no barrier. The audit changes no state, so the gate passes; a fix
+> wave later WOULD require the gate (see `references/governance.md`).
+
+## Phase 3 — ACT
+
+Spawn specialists in a SINGLE message; give each objective + context + result
+shape + boundaries; persist intermediate results.
+
+> **Micro-example.** One message launches three subagents. Each brief: objective
+> ("find auth vulns in <area>"), context (the relevant files), result shape
+> ("table: file | line | issue | severity"), boundaries ("only <area>; do not fix").
+> As each returns, write its verified findings to memory.
+
+## Loop back — track & adapt
+
+Update the plan, reconcile conflicts, fan out a second wave for missing coverage
+or shaky claims. Return to CONTEXT until the goal is met.
+
+## Delegation patterns
+
+- **Single-wave fan-out.** N independent subtasks, one message, no barrier. The
+  default for breadth (audits, surveys, multi-file scans).
+- **Multi-wave.** Wave 1 maps the territory; wave 2 digs into what wave 1 surfaced.
+  Justified when later work depends on earlier discovery, not on raw parallelism.
+- **Adversarial-verify wave.** After a claim-producing wave, spawn a subagent to
+  challenge the shakiest claims against the source. Use for correctness-sensitive
+  output before declaring done.
+- **When a barrier is justified.** Only when a step needs every prior result
+  together (a synthesis comparing all branches). Never barrier independent work.
+- **Continue vs. spawn-fresh.** Message the SAME subagent to extend its work with
+  context intact; spawn fresh only for genuinely independent work or a clean frame.
+
+## Verify-before-done checklist
+
+- Are correctness-sensitive claims checked against the SOURCE, not against a
+  subagent's self-report? A passing self-narrative is NOT evidence.
+- Is every coverage cap from OBSERVE still disclosed in the final answer?
+- Are conflicting subagent results reconciled, not silently dropped?
+- Is each "done" claim backed by primary-source confirmation?
+
+If any check fails, run another pass — do not exit.
+
+## Synthesizing one voice
+
+- **Distill, do not dump.** Subagent transcripts are visible only to you. Relay
+  what matters; strip the scaffolding.
+- **One structure.** Merge results into a single organized answer (one ranked
+  list, one table), not a stack of per-subagent sections.
+- **Carry the gaps forward.** State skips, caps, and unverified items plainly in
+  the final answer — honest accounting is part of the deliverable.
+- **One voice.** However many agents ran, the user gets one coherent response.