| name | oort-cascade |
| description | Use when facing complex tasks that need multiple specialized agents working in sequence or parallel — task decomposition, role assignment, dependency DAGs, revision loops, and quality validation |
| allowed-tools | Agent Read Grep Glob |
OORT Cascade
Task-Oriented Orchestrated Relay Topology. When a task is too complex for a single pass, decompose it into specialized roles, wire them into a dependency graph, execute in parallel waves, and validate output quality before delivering.
This is orchestration methodology, not a framework or library. Apply it by structuring how you use the Agent tool, subagents, and parallel execution within Claude Code.
When to Use
- Multi-step tasks that produce a deliverable (report, codebase, design, campaign)
- Tasks requiring different specializations (research + build + validate)
- Work where quality matters enough to justify a validation pass
- Requests with explicit multi-department scope ("research X, then build Y, then review Z")
- Tasks where getting it wrong is expensive (proposals, client deliverables, production code)
When NOT to Use
- Simple lookups, single-action commands, quick questions
- Tasks under ~40 words that have a clear single-step answer
- Pure factual retrieval (just answer the question)
- Tasks where speed matters more than quality (quick drafts, brainstorming)
- Anything you can do well in a single focused pass -- cascading adds overhead
Threshold rule: If you can deliver a high-quality result in one pass, do that. Cascade only when decomposition genuinely improves the outcome.
The 4 Layers
OORT has four layers. You will use layers 1-3 directly. Layer 4 is about output formatting.
| Layer | Purpose | What You Do |
|---|
| 1. Task Cascade | Decompose request into parallel specialized roles | Break the task into a DAG of roles |
| 2. Meta-Prompting | Generate tailored instructions per role | Write specific prompts for each subagent |
| 3. Handoff Protocol | Structured data transfer between roles | Pass findings as structured data, not prose |
| 4. Output Formatting | Format result for the target audience | Deliver in the format the user requested |
Task Decomposition
When you receive a complex task, follow this sequence:
Step 1: Identify the Deliverable
What does the user want produced? A report? A codebase? A plan? A refactored module? Name it concretely.
Step 2: Map Required Capabilities
What skills and knowledge are needed? List them:
- Does it need research or external information gathering?
- Does it need building/creating/writing?
- Does it need validation or quality checking?
- Does it need documentation or archival?
- Does it need specialized domain expertise?
Step 3: Assign Roles
Each capability maps to a role. The four core roles are:
| Role | Responsibility | Delivers |
|---|
| Researcher | Gather data, context, background info | Bullet-point findings with sources |
| Builder | Create the main deliverable | The artifact (code, document, design) |
| Validator | Quality-check the output, score 0-10 | Score + actionable feedback |
| Documenter | Archive results, update project docs | Structured summary for memory |
Add specialist roles only when they provide clear value:
- Analyst -- when raw data needs interpretation before the builder can use it
- Architect -- when structural decisions precede implementation
- Reviewer -- when domain-specific review differs from general validation
- Editor -- when tone/style polish is a distinct concern from content accuracy
Step 4: Define the Dependency DAG
Which roles need output from others? Independent roles run in parallel.
Wave 1 (parallel): Researcher, Analyst
Wave 2 (needs W1): Builder
Wave 3 (needs W2): Validator
Wave 4 (needs W3): Documenter
Step 5: Execute in Waves
Use the Agent tool to dispatch subagents. Independent roles within a wave run in parallel. Dependent roles wait for their inputs.
Decomposition Rules
- Minimum viable cascade: Builder + Validator. Every cascade needs at least these two.
- Add Researcher only if external information, codebase exploration, or context gathering is required.
- Add Documenter only if the results need to be archived or project docs need updating.
- Add specialists only when they provide clear value over combining responsibilities.
- Max 6 roles per cascade. Beyond 6, you get diminishing returns and coordination overhead.
- Lean is better. Fewer roles = faster execution, less handoff noise, lower cost.
Meta-Prompting: Tailored Instructions Per Role
Every role gets a purpose-built prompt. Never dispatch a subagent with generic instructions.
Template
You are the {ROLE} on a team completing: {TASK}
YOUR SPECIFIC RESPONSIBILITY:
{What this role must deliver -- concrete and measurable}
DELIVERABLE FORMAT:
{Exact structure of expected output}
CONTEXT FROM PREVIOUS ROLES:
{Handoff data from dependencies -- key findings, data points, artifacts}
QUALITY CRITERIA:
{What "good" looks like for this specific output}
CONSTRAINTS:
- Scope: {boundaries of this role's work}
- Length: {target size of output}
- Audience: {who will consume this output}
Role-Specific Guidance
Researcher prompts should specify:
- Focus areas and specific questions to answer
- Where to look (codebase paths, file types, documentation)
- Output format: bullet points with citations, not prose
Builder prompts should specify:
- Exact deliverable specification
- Style, tone, and structural requirements
- Reference materials from upstream roles
- Output: the actual artifact
Validator prompts should specify:
- Scoring rubric (accuracy, completeness, quality, format)
- Specific items to check against the original request
- Output: structured score + issues + revision feedback
Documenter prompts should specify:
- What to document and where
- Format and structure expectations
- Output: structured summary ready for project docs
Worked Example
Task: "Refactor the auth module to use JWT tokens instead of session cookies"
- Researcher prompt: "Survey the current auth implementation. Identify all files using session cookies, all endpoints that check auth state, and all tests covering auth. Output: file list, dependency map, risk areas as bullet points."
- Builder prompt: "Using the researcher's file list and dependency map, refactor auth from session cookies to JWT. Implement token generation, validation middleware, refresh flow. Preserve all existing test coverage."
- Validator prompt: "Review the JWT refactor against: (1) all original auth tests still pass, (2) no session cookie references remain, (3) token refresh handles edge cases, (4) no security regressions. Score 0-10 on accuracy, completeness, quality, format."
Handoff Protocol
Roles pass structured data downstream -- not prose paragraphs. See handoff-protocol.md for the full specification.
Key rules:
- Max 500 tokens per handoff (forces conciseness)
- Use bullet points, not paragraphs
- Include raw data and numbers, not just interpretations
- Every claim needs a source or confidence qualifier
- When merging multiple upstream handoffs, synthesize -- do not duplicate
Anti-patterns:
- "The researcher found many interesting things about the topic" (vague, useless)
- Passing entire previous outputs as handoffs (bloated, unfocused)
- Omitting source references (downstream roles cannot verify)
Quality Gates and Validation
Every cascade includes validation. See quality-gates.md for the full scoring system.
Functional Testing (Not Just Scoring)
The validator must use the output like a user would, not just read and rate it. Scoring without execution catches surface problems; functional testing catches real ones.
| Output Type | Functional Test |
|---|
| Code | Run it. Execute tests. Check imports resolve. Verify the build passes. |
| API endpoints | Call them. Send real requests. Check response shapes and status codes. |
| Web UI / frontend | Load it in a browser (Playwright, puppeteer). Click through flows. Screenshot results. |
| Documents / reports | Check all claims are sourced. Verify data points against inputs. |
| Config / infrastructure | Dry-run or validate syntax (terraform validate, docker compose config). |
| 3D models | Check mesh integrity, verify printability constraints. |
Tune the validator to skepticism. Models praise their own work — a separate validator context with instructions to find problems catches what self-review misses. The validator prompt should say "find what's wrong" not "check if it's good."
Validator prompt pattern:
"Your job is to BREAK this, not approve it.
Run the code. Hit the endpoints. Click the buttons.
Score based on what actually works, not what looks right."
The Builder-Validator Loop
Builder produces output
|
Validator RUNS functional tests (not just reads)
|
Score >= 7? --> Accept, continue pipeline
Score < 7? --> Send feedback to Builder with specific issues
|
Builder revises addressing ALL listed issues
|
Validator re-tests (functional, not just re-reads)
|
Accept (max 2 revision loops to prevent infinite cycles)
Scoring Rubric
Rate every output on these four dimensions (0-10 each):
| Dimension | What to Check |
|---|
| Accuracy | Are facts correct? Claims supported? Code functional? |
| Completeness | Does it address every part of the request? |
| Quality | Is it well-structured, polished, professional? |
| Format | Does it match the requested output format? |
Overall score = average of dimensions, rounded.
Score Thresholds
| Score | Action |
|---|
| 9-10 | Ship immediately |
| 7-8 | Ship with minor notes |
| 5-6 | Revise if time allows |
| 3-4 | Must revise before shipping |
| 0-2 | Restart the role from scratch |
Revision Rules
- Max 2 revision loops per role (prevents infinite cycles)
- Each revision must address ALL listed issues
- Track score progression -- it should improve each iteration
- If score does not improve after revision, accept and note the quality gap to the user
Self-Validation Checklist
Before returning ANY output from any role, verify:
Red Flags Table
| If you notice... | The problem is... | Fix it by... |
|---|
| A role's output is >2000 tokens | Scope creep or missing constraints | Tightening the meta-prompt with explicit length limits |
| Validator always scores 9-10 | Rubber-stamp validation | Adding specific checkpoints to the validator prompt |
| Builder ignores researcher findings | Weak handoff | Restructuring handoff as explicit requirements, not background info |
| Cascade has 7+ roles | Over-decomposition | Merging roles with overlapping responsibilities |
| Revision loop hits max without improving | Fundamental approach problem | Restarting the role with a different strategy |
| Handoff is prose paragraphs | Handoff protocol violation | Converting to structured KEY_FINDINGS / DATA_POINTS format |
| User's request was simple but you cascaded | Over-engineering | Handling it directly in a single pass |
Cascade vs. Direct: Decision Guide
Ask yourself these questions:
- Does this need multiple distinct skills? (research AND build AND validate) -- If yes, cascade.
- Is the deliverable complex enough to benefit from a validation pass? -- If yes, at least Builder + Validator.
- Would I naturally break this into phases if doing it myself? -- If yes, those phases are your roles.
- Can I do this well in a single focused pass? -- If yes, skip the cascade entirely.
Putting It All Together
Here is the full execution flow for a cascade:
1. Receive complex task
2. Identify deliverable and required capabilities
3. Assign roles (min: Builder + Validator, max: 6)
4. Build dependency DAG and group into waves
5. Write meta-prompts for each role (tailored, not generic)
6. Execute Wave 1 (parallel where possible)
7. Collect outputs, build structured handoffs
8. Execute Wave 2 with handoff context
9. ... continue through all waves ...
10. Validator scores final output
11. If score < 7 and revisions remain, loop back to Builder
12. Deliver final output to user
The power of OORT is not in the framework -- it is in the discipline of decomposition, structured handoffs, and closed-loop validation. Apply the pattern; skip the ceremony when the task does not warrant it.
Subagent Dispatch Guardrails
Opus 4.6 has a strong native tendency to spawn subagents. Combined with OORT's cascade pattern, this can cause over-spawning — subagents spawning subagents, coordination overhead exceeding the work itself.
Use subagents (cascade) when:
- Tasks can genuinely run in parallel with no shared state
- Different specializations are required (research vs build vs validate)
- The deliverable benefits from isolated contexts (independent perspectives)
- Work is substantial enough that coordination overhead is worth it
Work directly (no cascade) when:
- A single grep, file read, or lookup answers the question
- The task is a sequential chain where each step needs the previous result immediately
- Single-file edits or small focused changes
- The task takes less than 2 minutes of focused work
- You already have the context you need — don't delegate understanding
Anti-patterns to avoid:
- Spawning a Researcher subagent when you could just grep the codebase yourself
- Creating a Validator subagent for a 10-line code change — just run the tests directly
- Cascading a task that has one obvious approach — cascading adds overhead, not quality
- Nesting cascades — if a subagent needs its own cascade, the decomposition is wrong
