--- name: agent-composer description: Reads the current work context and plans the optimal agent dispatch. Clarifies direction with 1-2 questions when unclear; infers and proceeds immediately when execution path is unclear. Runs an automatic recording gate after each Wave completes. Triggered by "compose agents", "which agent should I use?", "run in parallel", or "agent-composer". user-invocable: true allowed-tools: ["Read", "Bash", "Glob", "Grep", "Agent", "Skill"] model-note: session-inherit — Sonnet base is first-class (sonnet_floor_doctrine.md); depth-critical judged steps route to dispatch (opus agent / cross-family sidecar, consent-gated), never a substrate requirement --- # agent-composer — Agent Composition Layer A coordinator skill that reads the work context and decides "which agents to dispatch, when, and in what order." Selects the optimal combination from the FH skill pool and either outputs a fan-out plan or executes it directly. ## Triggers - `/agent-composer` - "Which agent should I use?", "Pick one automatically", "Compose the agents" - "Set up the agents", "Decide which agents to use" - "Split the work and run in parallel", "Process with multiple agents" - "Build the dispatch plan", "Run in parallel splits" - When the task is complex or spans multiple projects ## Core Principles - **Compose only**: Does not perform work directly. Outputs the dispatch plan and executes after user approval. - **Parallel first**: When 2+ tasks are independent, propose parallel fan-out instead of sequential. - **Minimal composition**: Only the agents needed. Over-provisioning agents creates inefficiency. - **Coordinator ≠ executor**: Only collects results (fan-in) and presents an integrated report. --- ## Step 0. Context Collection Identify 4 items from the request: task type · scope · constraints · natural-language goal → skill mapping. Check `LOCAL_SKILL_REGISTRY.md` for project-local skills; check `.mcp.json` or `CLAUDE.md` for external plugins. > **Detail**: See `SKILL_detail.md §Step-0` — NL pattern mapping table, cross-install detection, registry lookup format — read when auto-mapping an ambiguous request. --- ## Step 0.2 — Capability Fit Analysis > **Schema**: `knowledge/shared/harness-core/tpa_schema.md` — `artifact_type` enum determines `role_match` lookup domain for scoring. > Runs before dispatching agents. **Skip if user specifies exact agents by name.** For each subtask in the composition plan: 1. **Read agent registry**: `.claude/agents/*.md` + installed plugin agents Extract: `role` · `allowed_tools` · `writes` · `declared_capabilities` 2. **Score capability fit**: `[subtask_type]` × `[agent capabilities]` → `fit_score` (0.0–1.0) 3. **GAP**: `fit_score < 0.5` for a required-weight subtask → query `/plugin-recommender`: "agent for [subtask_type] in [context]" → includes Codex marketplace + Claude Code marketplace (not just FH native) → user: **install** / **skip** / **use general-purpose fallback** ### Capability Fit Scoring Table | Subtask type | Strong fit signal | Weak fit signal | |---|---|---| | Adversarial review | `subagent_type="challenger"`, artifact_type match | general-purpose only | | Phantom detection | `phantom-quench` | general-purpose only | | Persona simulation | `hub-persona-auditor`, deep-insight persona | general-purpose only | | Code generation | `writes: true` + code tools | `writes: false` or no code tools | | Audit-only | `writes: false` (safe) | `writes: true` (risky for audit) | ### Author-Exposure Table — a review pass, not a second executor The table above picks **who does the subtask**. This one adds a different question at a different stage: **what failure is the author structurally exposed to, now that the work is claimed done?** It never replaces capability fit and never selects the agent that performs the work — it adds a **review pass** before the work is released. A doc-writing subtask scores no "adversarial review" fit, yet its author is blind to cold-entry failure, and capability fit never surfaces that. **Materiality gate — run this pass only when the work product is material.** At least one of: public or otherwise irreversible surface · affects users other than the author · carries external claims, numbers, or citations · introduces new behavior · touches security, data, deletion, or permissions. Internal notes, wording fixes, and one-line edits do **not** trigger it — an unbounded trigger just trains the pass into being skipped. | Failure the author cannot self-detect | Review mechanism | Type | |---|---|---| | Cold entry — first contact breaks (missing install step, undefined term, no success signal) | `beginner` | agent | | Everyday-use friction invisible to the designer | `main-player` | agent | | Currency vs the outside field (needs external citation, not assertion) | `expert` | agent | | Self-verification only fails in the optimistic direction | `challenger` + `auto-decorrelation` | agent + pipeline | | Rebuilding something that already exists | `fact-checker` · `asset-placement-gate` | agent · skill | | Numbers/citations living in the artifact without grounding | `phantom-quench` | skill | | **Exposure unclear** (material, but no row above fits) | `challenger` | agent — default, not a skip | The `Type` column matters for the capability-fit checks above: `writes`/tooling scoring applies to **agent** rows only; skill and pipeline rows are invoked, not scored. **Behavioral rule — no silent skip, and "no row applies" is not an exit.** Name the row before the agent. If you believe none applies, you must (a) state which rows you considered, (b) give a one-line reason each is excluded, and (c) fall through to the **Exposure-unclear** row — the default is `challenger`, never nothing. (Origin: 2026-07-21 — four dispatches in one session were chosen by orchestrator judgment alone. They were right; that is luck, not a mechanism. In the same session one `beginner` dispatch blocked a public-repo merge on 4 findings the author had not seen.) **Behavioral rule — the lens does not hold the verdict.** A review pass returns `evidence`, `risk`, and a `recommended decision` only. It may **not** emit a terminal `block`/`approve`; the orchestrator declares the outcome, on its own stated grounds, and approval on an irreversible surface stays with the human regardless of what the lens returned. **Row-growth criterion (anti-case-crafting).** A new row is admissible only if the failure type has been **observed more than once**, is **not coverable by an existing row**, and names a *verifiable exposure axis* rather than a job title or a favorite tool. If rows keep accreting, that is the signal to fold the table into a smaller set of principled axes — not to keep appending. **Behavioral rule**: A `writes: false` agent (e.g. fact-checker, hub-persona-auditor) must NOT be assigned a task requiring edits. Capability fit scoring catches this statically before dispatch. **Behavioral rule**: Degraded composition — when any required-weight role is filled with general-purpose fallback, output `⚠️ degraded: [role]` in the composition plan. Do not silently use general-purpose for a specialized role. > **Detail**: See `SKILL_detail.md §CapabilityFit` — scoring procedure, agent registry reading, plugin-recommender query format, worked examples — read when executing Step 0.2. --- ## Step 0-a. Clarification Protocol > Execution condition: Only when direction or goal is unclear (skip → go directly to Step 0-b if clear) **Core principle**: Only ask when what the person must provide (direction · insight · decision) is unclear. Execution method · agent selection · recording location → infer and proceed — do not ask. ### Direction vs. Execution Decision Table | Request type | Classification | Action | |---|---|---| | "Do X" — target and completion criteria are clear | Clear | Immediately enter Step 0-b | | "Improve X" — improvement dimension unclear | Direction unclear | Ask for clarification | | "Something feels off" — diagnosis target unclear | Execution unclear → infer | Auto-dispatch harness-doctor | | "Wrap up / harvest this session" — trigger is clear | Clear | Run harvest-loop based on recent work ("run the pipeline" itself is ceded to pipeline-conductor — route end-to-end sweeps there, not here) | | No request — session context exists | Execution unclear → infer | Auto-compose based on CATALOG/MEMORY, then confirm | > **Detail**: See `SKILL_detail.md §Clarification` — 2-question format, 4-question structured confirmation, meta-prompting intervention — read when direction ambiguity requires a clarification block. --- ## Step 0-b. Wave 0 — Reconnaissance Dispatch (Mandatory Before New Tasks) > Execution condition: For cross-project tasks or when scope is unclear. Skip for single-project tasks with clear scope. This orchestrator does not read files or understand structure directly — **even reconnaissance work is dispatched as agents.** All tasks including new assets → fact-checker (A) mandatory in Wave 0. > **Detail**: See `SKILL_detail.md §Wave-0` — self-contained brief requirements, deferred ToolSearch pre-requisite pattern — read when writing a recon agent brief. --- ## Step 1. Agent Mapping Default composition table by task type. > **Note**: This table lists known installed agents. Capability fit scoring in Step 0.2 overrides static mapping when `.claude/registry/agent_cards.json` (repo-relative — there is no bare `agent_cards.json` at the repo root) has more current data. > **Call method distinction**: `(S)` = Skill tool call / `(A)` = Background dispatch via Agent tool | Task type | Default composition | Parallel | |---|---|:---:| | **[Wave 0] Recon (all tasks)** | Recon agent (A) — file/structure understanding. Direct orchestrator execution forbidden | — | | **[Wave 0] All tasks including new assets** | fact-checker (A) — proactive duplicate/stale validation | — | | Meta-simulation quality validation | sim-conductor (S) — challenger + beginner + main-player | ✅ Parallel | | Field pattern harvest | field-harvest (S) | — | | Harness structural diagnosis | harness-doctor (S) | — | | New asset placement decision | asset-placement-gate (S) | — | | External user entry point audit | hub-persona-auditor (A) | — | | Naming/innovation scan | persona-innovator (A) | — | | Cross-project simultaneous work | N field agents (A) | ✅ Parallel | | Three-Doctor Loop | harness-doctor (S) + context-doctor (S) + sim-conductor (S) | ✅ Parallel | | Pre-PR code review | sim-conductor D-code 3 personas (S) | ✅ Parallel | | Learning cross-validation | verify-bidirectional (S) | — | | Ecosystem synergy exploration | cross-ecosystem-synergy-detection (S) | — | | Plugin recommendation | plugin-recommender (S) | — | | Install conflict diagnosis | install-doctor (S) | — | | Onboarding install | install-wizard (S) — ⚠️ interactive; `--dry-run` for bg parallel | — | | Hub PR review | harness-pr-reviewer (S) — requires PR number first | — | | **Decision-maker approval review** | apex-review (S) — CTO/tech lead/QA lead personas + HTML deck | — | | **Project local skills** | LOCAL_SKILL_REGISTRY lookup → relevant project skill (A/S) | Per project | --- ## Step 2. Composition Plan Output ``` agent-composer — Composition Plan ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Task: {task summary} Composition: {N} agents | Parallel: {Y/N} | Estimated time: ~{N} min Wave 0 (Recon): [R] Recon agent — {file/structure understanding goal} Wave 1 (Parallel): [A] {agent name} — {role in 1 line} [B] {agent name} — {role in 1 line} Wave 2 (after Wave 1 completes): [D] {agent name} — {executed after result integration} fan-in: integrate results after Wave completes → output report ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Execute? (Y: run all / E: edit then run / N: cancel) ``` Optionally name the composition's shape in the plan header (`Composition pattern: {name}`) so the operator recognizes the structure at a glance — a recognition aid, not a routing input. > **Detail**: See `SKILL_detail.md §Composition-Pattern-Labels` — the six revfactory-vocabulary labels > (Pipeline / Fan-out-in / Expert Pool / Producer-Reviewer / Supervisor / Hierarchical) mapped to the > existing FH constructs they name — read when labeling a plan header. --- ## Step 2.5 — Model Routing Decision (complexity_routing) ### Routing Rules 1. No `complexity_routing` in skill frontmatter → use `model:` field as-is 2. `complexity_routing` present + any `escalate_when` condition matches → use `high` model 3. No conditions match → use `base` model Include 1-line routing audit in composition plan output: `[Model routing] harness-doctor: cold_start → opus` ### Default Architecture | Mode | Orchestrator | Executor | When | |---|---|---|---| | **Base** | sonnet | sonnet | Default — all tasks | | **Amplified** | opus | sonnet | `EXECUTION_TIER: full/max` · plan mode · `cross_project` + `high_stakes` both detected | **Simplification guard**: Single-Wave, single-project tasks → Sonnet sufficient. Do not escalate. > **Detail**: See `SKILL_detail.md §Model-Routing` — escalation condition evaluation table, amplified audit log format. --- ## Step 2.7 — Destructive Action Gate After scanning the composition plan, if any of the following types are found, mark with 🚨 and output a separate warning before Step 3. | Type | Examples | |---|---| | External send | git push/force, PR create/merge, Slack/wiki upload | | File/data destruction | rm -rf, DB DROP/DELETE, file overwrite, branch delete | | Production impact | Service deploy, migration, permission/config changes | If 🚨 items exist, insert before the standard Y/E/N in Step 3: ``` ⚠️ Irreversible operations are included: - [type] [specific operation] Do you want to proceed? (yes / no) ``` `no` → remove that operation or cancel entirely. Safe remaining operations can continue. **Named residual — the plan is gated per step, never as a chain.** A composition whose steps each pass can still be harmful as a whole (skills that each soften one signal until it disappears). No check here reads the chain as one unit. The 🚨 table above flags a step only by its own type, so a harmless-looking step that shapes what a later irreversible step acts on is not flagged. Detail: `knowledge/shared/harness-core/capability_composition_contract.md §3`. --- ## Step 3. Approval → Execution - **Y**: Execute immediately. Generate Context Cards (Step 3-a), then dispatch parallel agents in a single message. - **E**: User modifies plan then re-confirms. - **N**: Cancel. > **Detail**: See `SKILL_detail.md §Worktree-Isolation` — Step 3.1 parallel proposal mode with git worktree isolation — read when 2+ agents write to overlapping files. ### Step 3-runtime. Dispatch Runtime Selection Use the runtime available in the current session: | Runtime | Dispatch mechanism | |---|---| | Claude Code | `Agent(...)` for agents, slash/skill invocation for skills | | Codex-primary | `FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --agent {agent}` or `--skill {skill}` | | Generic shell | `FH_BACKEND=auto npx --package @chrono-meta/fh-gate fh-run ...` | When using `fh-run`, pass each agent's Context Card through `--prompt` and pass target files with repeated `--file` arguments. The fan-in obligation is unchanged: collect each adapter output, then synthesize one integrated report before proceeding to the next wave. ### Step 3-a. Context Card Injection (required for 2+ parallel agents) Sub-agents are spawned in isolation — they cannot see the live conversation. Inject a Context Card into each agent prompt before dispatch to prevent context blindness (duplicate work, stale direction, missing constraints). **N≤2 (standard)**: ``` [Session Context Card] Purpose: {session goal} Completed: {done items + file paths — agent must know to avoid duplication} This agent's task: {specific task for this agent} Note: {constraints / history the agent must know} ``` **N≥3 (Registry mode — DACS-inspired, arXiv:2604.07911)**: ``` [Session Context Card] Purpose: {session goal} Completed: {done items + file paths} This agent's task: {specific task} Note: {constraints} [Agent Registry] Agent-1 ({role}): {≤1 sentence — what it's doing, key files} Agent-2 ({role}): {≤1 sentence} ... (all agents except this one) ``` Total Registry ≤200 tokens. Each agent receives its own full card + compressed view of all other agents. **Coordination-overhead budget** (apply before each Wave): | Rule | Constraint | |---|---| | **Per-wave fan-out cap** | ≤4 agents per dispatch wave. Above 4: decompose hierarchically (supervisor → sub-waves), not flat fan-out | | **Capability-aware routing** | Match each subtask to agent's `role` + `allowed_tools` + `writes`. Never dispatch a `writes: false` audit agent (e.g., fact-checker, hub-persona-auditor) for a task requiring edits | Rationale: orchestrator-worker coordination adds ~+285% token overhead at N≥5 flat fan-out (DACS, arXiv:2604.07911). Sub-waves amortize this. **Focus Mode** (N≥3, on-demand only): When an agent signals `"Need full context from Agent-X to proceed"` → re-dispatch that agent with Agent-X's full Context Card + Registry-compressed view of others. Use only when genuinely needed — adds one round-trip. **Omit card**: Simple read-only lookup agents with no context dependency may skip injection. --- ## Step 3.5 — Inter-Wave Adaptation Check (Runtime Adaptation) After Wave N completes, before Wave N+1, evaluate: **① Premise Reversal** — Does Wave N result reverse a Wave N+1 premise? → revise plan, confirm with user **② Repeated Failure** — Same agent failed 2+ times? → exclude + suggest replacement **③ Early-Harvest Trigger** — 3+ new patterns discovered? → propose mini-harvest before Wave N+1 **Simplification guard**: Skip for simple tasks with only one Wave (Wave 0 + Wave 1). > **Detail**: See `SKILL_detail.md §Wave-Adaptation` — adaptation check output format. --- ## Step 4. fan-in — Result Integration > **M/S/R tier criteria**: M = blocks external user entry / structural conflict / immediate action required · S = feature degradation / address within next session · R = improvement value / backlog Each agent finding must satisfy the **loom fan-in contract** (3 fields minimum): `tier | location | fix suggestion`. Results not meeting this format → mark "format non-compliant" and re-request or skip. Integrate results into M/S/R tiers → output completion report: ``` agent-composer — Complete ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Executed: {N} | Time: ~{N} min | Parallel gain: {N}x vs sequential M: {N} items → [action suggestion] S: {N} items → backlog R: {N} items → backlog ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` > **Detail**: See `SKILL_detail.md §fan-in-Contract` — per-row format spec, format non-compliant handling. --- ## Step 4-b. State Transition Gate After fan-in report, evaluate conditions and auto-suggest the next Wave: | Condition | Wave suggestion | |---|---| | ① M-tier > 0 | **Wave next-M**: fact-checker (A) → harness-pr-reviewer (S) | | ② persona-innovator naming candidates > 0 | **Wave next-I**: delegate to user + asset-placement-gate (S) | | ③ External absorption signal High > 0 | **Wave next-E**: persona-innovator Mode E (A) + meta-prompt-builder (S) | | ⑤ Design conflict / 2+ conflicting suggestions | **Wave next-D**: deliberation (S) — verdict folds back into Step 4-b | | ④ All 0 | **End**: "backlog only, defer to next session" | Naming/direction/deliberation decisions: auto-execution forbidden — user confirmation required. --- ## Step 4-c. Auto-Recording Gate | Condition | Auto action | |---|---| | 2+ new files created or 3+ existing files changed, **or M-tier resolved** | harvest-loop lightweight mode (field-harvest → contention → verify-bidirectional) | | Architecture/direction decision made | "Record this decision? [1-line summary]" — save after confirmation | | None of the above | Fall back to field-harvest proposal | Auto-recording allowed scope: file change lists + execution results. Decision content and naming require confirmation. > **Detail**: See `SKILL_detail.md §Auto-Recording` — Wave execution recording format, harvest-loop lightweight mode pipeline, human decision gate. --- ## Step 5. Wave 4 — Final Judgment Gate Execute after all Waves 0~3 complete. Auto-skip for simple exploration or planning tasks. ### Judgment Logic ``` IF M-tier == 0 AND S-tier < 3: → PASS (merge approved) ELIF M-tier >= 1: → BLOCK (immediate fix required) ELSE: # M-tier == 0 AND S-tier >= 3 → PASS (S-tier allows backlog — not a merge block reason) ``` | Judgment | Auto-proposal | |---|---| | **PASS** | field-harvest proposal: "Are there patterns to harvest from this Wave?" | | **BLOCK** | Fix M-tier items → suggest re-entry into Wave 1 | > **Detail**: See `SKILL_detail.md §Wave4` — entry conditions, judgment output format, auto-proposal format. --- ## Phase Guard Pattern (Stage Entry Gate) | Dependency | Rule | |---|---| | Wave 0 (recon) not complete | Cannot enter Wave 1 | | Wave 2 (fan-in) not complete | Cannot enter Wave 4 | | State transition (Step 4-b) not complete | Cannot enter Wave next-M/I/E/D | Maximize parallel fan-out among independent agents; dependent stages wait for prior Wave completion. --- ## Step 6. Round Wrap + Proactive Next Step Execute after Wave 4 PASS + Step 4-c recording complete. 3-line completion summary → up to 3 next-round suggestions → fh_signal persistence confirmation. **Proactive suggestion priority** (suggest only 1): | Situation detected | Suggestion | |---|---| | 2+ FH files modified | `harness-doctor` auto-run (after user confirmation) | | New skill/plugin added | `cross-ecosystem-synergy-detection` | | Important artifact completed | `steel-quench` | | No frontier-digest today + large session | `frontier-digest` | | None | "ready for next session" | **Anti-redundancy guard**: if this composition was invoked **by** goal-quench (detect `.claude/goal-quench.active` present with `mode: pro|max`), suppress any suggestion that points back to `/goal-quench` — goal-quench is already the caller, so re-suggesting it is a redundant, confusing loop. Return control to goal-quench instead. See Cross-reference below. > **Detail**: See `SKILL_detail.md §Round-Wrap` — 6-1 completion summary format, 6-2 next round suggestions format, 6-3 fh_signal persistence format. --- ## Execution Tier | Tier | Tokens | Scope | |:---:|:---:|---| | **light** | ~5K | Wave 0 + Wave 1 single → output → end | | **standard** | ~15K | Wave 0 + Wave 1 multi → fan-in → one proactive suggestion | | **full** | ~30K | + Wave N state transition → conditional lightweight harvest | | **max** | ~60K+ | + Three-Doctor Loop → full harvest-loop → next Wave follow-up | Configure via `EXECUTION_TIER: standard` in CLAUDE.md. Temporary override: "use light mode" / "run at max". --- ## Simplification Guard - Single-agent tasks → guide user to call that skill directly (skip agent-composer) - Risk of two agents editing the same file in the same Wave → recommend Wave separation ### Fan-out Scale Tiers | Tier | Count | Behavior | |---|---|---| | **Small** | 2–4 | Dispatch immediately (within per-wave cap) | | **Medium** | 5–16 | Decompose into sub-waves of ≤4; confirm scale before dispatch | | **Large** | 17+ | Worktree isolation mandatory + explicit user approval required | --- ## Done When ``` All stages Step 0~6 complete + Wave composition plan finalized + execution complete + fan-in loom complete: M-tier 0 AND S-tier < 3 → PASS or user has confirmed Wave end + When deliberation was invoked: wait for verdict before closing Wave N+1; verdict folds back into Step 4-b fan-in result set + Auto-recording gate (Step 4-c) complete — confirmed by the RECORD ARTIFACT (harvest output file exists on disk + harvest-loop typed `Verdict:` line read), never by a completion notice alone (completed-notice ≠ completion — return-path audit 2026-08-10) ``` > **Sprint Contract**: Done When must be in an externally verifiable contract format — "criteria a third party can confirm," not "when it feels done." (Anthropic official validation 2025) --- ## Identity agent-composer is the FH **coordinator** above specialist agents — decides "which agent combination is optimal." Also acts as **Curator**: detects stale/duplicate agents and proposes merge candidates. | Human domain | System domain | |---|---| | What to build, why (direction + insight) | Which agents and how (composition + ordering) | | Final adoption decision | Pipeline execution + result aggregation | | Naming/framing | Recording + quality gates | If unclear item is in human domain → ask. System domain → infer and proceed. (Brain/Hands decoupling: agent-composer is Brain-only. Brain = goal parsing → Wave construction → gate decisions.) --- ## Cross-reference — goal-quench (upstream caller) `goal-quench`'s **pro / max** modes invoke agent-composer for goal decomposition (goal-quench Phase 1.5 Step B). The relationship is one-directional and the entry points differ by intent: | User intent | Entry point | agent-composer's role | |---|---|---| | "Compose/dispatch agents for this work" | `/agent-composer` directly | Primary — composes and runs the Wave plan | | "Run a large/budget-gated `/goal` safely" | `/goal-quench --pro` / `--max` | Sub-step — receives the task in compose-only mode, returns a sub-goal Wave plan, hands control back to goal-quench | **Routing note**: when a user frames a large or token-sensitive `/goal` run, prefer `/goal-quench` as the entry point — it wraps this skill with budget + quality gates that a bare agent-composer run does not provide. agent-composer does **not** re-invoke goal-quench (that is the caller); the Step 6 anti-redundancy guard enforces this.