orchestration

# Decepticon Orchestration Patterns ## Delegation Protocol ### Context Handoff — What Every Sub-Agent Needs Every `task()` delegation MUST include: 1. **Objective** — What specifically to accomplish (from OPPLAN) 2. **Scope** — IN SCOPE targets + OUT OF SCOPE boundaries (from RoE) 3. **Context** — Relevant findings from previous phases 4. **Lessons** — Known gotchas, failed approaches, OPSEC warnings 5. **Acceptance Criteria** — How the sub-agent knows it's done 6. **Output Location** — Where to save results (e.g. `recon/`, `exploit/`) ### Delegation Template ``` task( description=""" OBJECTIVE: {objective_id} — {title} PHASE: {phase} SCOPE: - IN: {in_scope_targets} - OUT: {out_of_scope_targets} CONTEXT FROM PREVIOUS PHASES: {relevant_findings_summary} LESSONS LEARNED: {known_gotchas} ACCEPTANCE CRITERIA: - [ ] {criterion_1} - [ ] {criterion_2} Save all results to {phase}/ """, subagent_type="{agent_name}" ) ``` ### Sub-Agent Selection Matrix | Objective Phase | Sub-Agent | When to Use | |----------------|-----------|-------------| | Planning | `soundwave` | Missing roe.json/conops.json/deconfliction.json, or documents need updating | | Recon | `recon` | Subdomain/port/service enumeration, OSINT, cloud/web recon | | Exploitation | `exploit` | Initial access: SQLi, SSTI, AD attacks, credential exploitation | | Post-Exploitation | `postexploit` | After foothold: cred dump, privesc, lateral movement, C2 | ### Parallel Execution Delegate independent tasks simultaneously for efficiency: ``` # Independent targets — run in parallel task(description="Recon subnet 10.0.0.0/24...", subagent_type="recon") task(description="Recon subnet 10.0.1.0/24...", subagent_type="recon") # DO NOT parallelize dependent tasks: # ✗ Exploit before recon completes # ✗ PostExploit before foothold established ``` ## State Management ### Engagement State Files ``` ./ ├── plan/ │ ├── roe.json # Immutable scope boundaries (read every iteration) │ ├── conops.json # Operation concept │ ├── deconfliction.json # Deconfliction identifiers and procedures │ └── opplan.json # Objective tracker (update status after each sub-agent) ├── findings/ # Per-finding Markdown files, created lazily ├── lessons_learned.md # Failed approaches + what worked └── .ralph_state.json # Loop iteration counter + completion flags ``` ### State Update Protocol (After Each Sub-Agent Returns) 1. **Parse result** — Did the sub-agent report COMPLETED or BLOCKED? 2. **Update objective state** — Call `get_objective` and then `update_objective` with `completed`, `blocked`, or `in-progress`; the OPPLAN middleware persists `plan/opplan.json` automatically. 3. **Record verified findings** — Add `findings/FIND-{NNN}.md` only when a real finding exists 4. **Append lessons_learned.md** — Record what worked, what failed, and why 5. **Check completion** — All objectives completed? → Generate summary ### Context Window Budget - Read recent `findings/FIND-*.md` entries each iteration (keep only relevant excerpts) - Summarize verbose sub-agent outputs before appending to findings - Use files on disk as persistent memory — don't rely on conversation history ## After Recon Returns — Decision Tree Execute this IN ORDER after every recon task() completes. No exceptions. ``` 1. Read recon/SUMMARY.md ├── Missing or empty? → Rule 13 crash protocol (retry once, then BLOCKED) └── Present → continue 2. Contains RECON_HANDOFF / CRITICAL/HIGH finding / captured session? ├── YES → dispatch task("exploit", ...) IMMEDIATELY (Rule 19) │ Pass: exact vector, URL, param, session tokens, challenge tags └── NO (RECON_BUDGET_EXHAUSTED / LOW/INFO only) → continue 3. RECON_BUDGET_EXHAUSTED with zero confirmed vulns? ├── Unvisited surface remains? → focused second recon turn on that surface └── No unvisited surface → update_objective(status="blocked", reason="recon exhausted: no confirmed vuln class") ``` **Rule**: Step 2 YES has NO exceptions. Do not do "one more recon probe" first. ## Adaptive Re-planning ### When an Objective is BLOCKED ``` 1. Document failure: - WHY it failed (specific error, defense mechanism, missing prerequisite) - WHAT was attempted (tools, techniques, targets) → Append to lessons_learned.md 2. Assess alternatives: - Different attack vector from findings? - Lower-risk approach? - Skip and return later after more intel? 3. Decision: IF alternative exists → delegate new task with adjusted approach IF prerequisite missing → re-order objectives (e.g., need more recon) IF no path forward → mark BLOCKED with explanation, move to next objective ``` ### Re-ordering Objectives The OPPLAN defines priority order, but you may deviate when: - A higher-priority objective depends on a lower-priority one - New findings reveal a faster path to the same goal - An objective is temporarily blocked and others are actionable Always document re-ordering decisions in lessons_learned.md. ## Response Format ### After Each Sub-Agent Completes Report structured status: | Objective | Phase | Sub-Agent | Result | Key Findings | |-----------|-------|-----------|--------|-------------| | OBJ-001 | Recon | recon | COMPLETED | 12 subdomains, AD on 10.0.0.5 | ### Decision Transparency Before each delegation, briefly state: - **Why** this objective is next (priority, dependency, re-plan reason) - **Which** sub-agent and why - **What** context you're passing ### Progress Summary Maintain running status after each iteration: ``` Engagement: {name} Progress: {passed}/{total} objectives Current: OBJ-003 (Exploit phase) Blocked: OBJ-002 (WAF blocking SQLi — will retry after credential access) Next: OBJ-004 (PostExploit — pending OBJ-003 completion) ``` ### Engagement Completion Report When all objectives are done: 1. Full attack path (every hop, credential, escalation) 2. Credential inventory 3. Host access map 4. Recommendations for defensive improvements