| name | pilot-hypertree-execution |
| description | Standing planning doctrine for the port-daddy pilot: every plan is executed as a hypertree of context clusters. Structure phase before content phase, cluster-to-agent assignment by file-disjointness, spawn discipline capped at the merge-queue digest bound, and manager-driven orchestration with worktree isolation and pointer-based digests. Activate whenever the pilot (or any planner lane) decomposes work into parallel agents: 'plan this wave', 'partition this work', 'how many agents', 'hypertree execution'. NOT for the partitioning algorithms themselves (use agent-context-partitioner), single-node prompt construction (use skillful-node-prompt), or token accounting mechanics (use context-economics-for-agent-swarms).
|
| license | FSL-1.1-MIT |
| allowed-tools | Read,Bash,Grep,Glob,Edit,Write |
| metadata | {"category":"Agent & Orchestration","tags":["hypertree","planning-doctrine","context-clusters","pilot","orchestration","spawn-discipline","waves","dag"],"pairs-with":["manager-driven-team-orchestrator","dag-isolation-manager","dag-parallel-executor","skillful-node-prompt","agent-context-partitioner","context-economics-for-agent-swarms","hypertree-planning"],"provenance":{"kind":"first-party","owners":["port-daddy"]}} |
| io-contract | {"kind":"deliverable","produces":[{"kind":"design-doc","description":"A wave plan: hypertree outline with context clusters, typed edges, agent assignments with K justified against the spawn-discipline bound, and merge-gated wave boundaries","format":"markdown"}]} |
Pilot Hypertree Execution
The Doctrine
Operator directive (2026-08-22): port-daddy's planning always does hypertree
context-cluster execution — the pilot working as manager-driven-team-orchestrator
dag-isolation-manager + dag-parallel-executor, with per-node prompts per
skillful-node-prompt.
This is not one option among several. It is the standing rule for how the pilot
(and any planner lane) turns an objective into running agents. The reasoning is
the HyperTree Planning result (see the hypertree-planning skill, arriving via
its own import PR): complex work fails from structural mismatch between problem
complexity and reasoning organization, not from insufficient effort. A 60-step
sequential chain accumulates error; a hypertree of independent branches reduces
effective depth and lets independent branches run in parallel. The doctrine
binds that insight to port-daddy's concrete execution machinery.
When to Use
- The pilot receives an objective that will take more than one agent or more
than one sitting.
- Any planner lane is about to decompose work into tasks, waves, or PRs.
- An operator asks "how should we split this?" or "how many agents?"
NOT for: choosing the clustering algorithm (use agent-context-partitioner),
writing the per-node prompt text (use skillful-node-prompt), or pricing token
spend (use context-economics-for-agent-swarms). This skill is the doctrine
that sequences those skills; they carry the mechanics.
Rule 1 — Structure Phase Before Content Phase
Build the hypertree outline before committing to any detail. Two distinct
phases, never interleaved:
- Structure phase: produce the hypertree skeleton. The root is the
objective. Top-level branches are context clusters (defined below). No
implementation decisions are made here — only decomposition decisions.
- Content phase: fill in leaf detail (specific edits, specific tests,
specific PRs) inside each branch, guided by the outline.
Why the separation matters: premature detail commitment (picking the fix before
picking the partition) causes cascading revisions when the structure turns out
wrong, and the outline is itself the coordination protocol — each branch knows
its scope from its parent cut, so no central message-passing is needed for
branches to stay out of each other's way.
Context clusters, causal closure, typed edges
Top-level branches are context clusters: groups of tasks chosen to
. The unit of sharing is concrete:
files and subsystems. Two tasks that edit the same file, or reason over the
same subsystem's invariants, belong in the same cluster. Two tasks whose file
sets are disjoint belong in different clusters. (This is the min-cut framing
from : the optimal partition minimizes mutual
information across the cut, and file overlap is the cheap, honest proxy.)
