orchestration

name	orchestration
description	Decepticon orchestrator patterns — delegation, state management, adaptive re-planning, context handoff protocols.
allowed-tools	Read
metadata	{"subdomain":"orchestration","when_to_use":"delegate, orchestrate, next objective, blocked, re-plan, hand off, engagement state, status update, parallel execution","tags":"orchestration, delegation, state-management, re-planning, context-handoff","upstream_ref":"Decepticon orchestrator delegation / re-planning patterns — multi-agent control plane, no direct attack technique"}

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