Agent Orchestration 🦞

By Hal Labs — Part of the Hal Stack

Your agents fail because your prompts suck. This skill fixes that.

The Core Problem

You're not prompting. You're praying.

Most prompts are wishes tossed into the void:

CODEBLOCK0

You type something reasonable. The output is mid. You rephrase. Still mid. You add keywords. Somehow worse. You blame the model.

Here's what you don't understand: A language model is a pattern-completion engine. It generates the most statistically probable output given your input.

Vague input → generic output. Not because the model is dumb. Because generic is what's most probable when you give it nothing specific to work with.

The model honored exactly what you asked for. You just didn't realize how little you gave it.

The Core Reframe

A prompt is not a request. A prompt is a contract.

Every contract must answer four non-negotiables:

Miss one, the model fills the gap with assumptions. Assumptions are where hallucinations are born.

The 5-Layer Architecture

Effective prompts share a specific structure. This maps to how models actually process information.

Layer 1: Identity

Who is the model in this conversation?

Not "helpful assistant" but a specific role with specific expertise:

CODEBLOCK1

The model doesn't "become" this identity—it accesses different clusters of training data, different stylistic patterns, different reasoning approaches.

Identity matters. Miss this and you get generic output.

Layer 2: Context

What does the model need to know to do this task exceptionally well?

Context must be:

• - Ordered — Most important first
• Scoped — Only what's relevant
• Labeled — What's rules vs. editable vs. historical

CODEBLOCK2

Without labels, the model treats everything as equally optional. Then it rewrites your core logic halfway through.

Layer 3: Task

What specific action must be taken?

Not "write something about X" but precise instructions:

CODEBLOCK3

The more precisely you define the task, the more precisely the model executes.

Layer 4: Process ⚡

This is where most prompts fail.

You're asking for output. You should be asking for how the output is formed.

❌ Bad:
CODEBLOCK4

✅ Good:
CODEBLOCK5

You don't want answers. You want how the answer is formed.

Think like a director. You're not asking for a scene—you're directing how the scene gets built.

Layer 5: Output

What does "done" actually look like?

If you don't specify, you get whatever format the model defaults to.

CODEBLOCK6

Miss one layer, the structure wobbles. Miss two, it collapses.

Model Selection

Prompt portability is a myth.

Different models are different specialists. You wouldn't give identical instructions to your exec assistant, designer, and backend dev.

Adapt your prompts per model:

• - Some prefer structured natural language
• Some need explicit step sequencing
• Some collapse under verbose prompts
• Some ignore constraints unless repeated
• Some excel at analysis but suck at creativity

The person who writes model-specific prompts will outperform the person with "better ideas" every time.

Constraints Are Instructions

Vagueness isn't flexibility. It's cowardice.

You hedge because being specific feels risky. But the model doesn't read your mind.

Constraints are not limitations. Constraints are instructions.

CODEBLOCK7

Every conversation starts at zero. The model doesn't have accumulated context from working with you. Consistency comes from instruction, not memory.

Canonical Documentation

If you don't have docs, you're gambling.

The rule: Reference docs in your prompts.

CODEBLOCK8

Without explicit anchoring, the model assumes everything is mutable—including your core decisions.

"Good prompting isn't writing better sentences. It's anchoring the model to reality."

The Complete Template

CODEBLOCK9

Ralph Mode

For complex tasks where first attempts often fail:

CODEBLOCK10

When to use:

• - Build tasks with multiple components
• Integration work
• Anything where first-try success is unlikely

Agent Tracking

Every spawned agent gets tracked. No orphans.

Maintain notes/areas/active-agents.md:

CODEBLOCK11

Heartbeat check:

1. Run sessions_list --activeMinutes 120
2. Compare to tracking file
3. Investigate any missing/stalled agents
4. Log completions to LEARNINGS.md

The Learnings Loop

Every agent outcome is data. Capture it.

Maintain LEARNINGS.md:

CODEBLOCK13

Role Library

Build reusable role definitions:

CODEBLOCK14

Quick Reference

The 4 Non-Negotiables

1. 1. Role — Who is the model?
2. Task — What must it do?
3. Constraints — What rules apply?
4. Output — What does done look like?

The 5 Layers

1. 1. Identity — Specific role and expertise
2. Context — Ordered, scoped, labeled
3. Task — Precise objective
4. Process — How to approach (most overlooked!)
5. Output — Exact format specification

Pre-Spawn Checklist

• - [ ] Identity assigned?
• [ ] Context labeled (rules/state/history)?
• [ ] Task specific and measurable?
• [ ] Process described (not just output)?
• [ ] User stories defined?
• [ ] Output format specified?
• [ ] Constraints explicit?
• [ ] Error handling included?
• [ ] Added to tracking file?

The Final Truth

The gap between "AI doesn't work for me" and exceptional results isn't intelligence or access.

One group treats prompting as conversation. The other treats it as engineering a system command.

The model matches your level of rigor.

• - Vague inputs → generic outputs
• Structured inputs → structured outputs
• Clear thinking → clear results

You don't need to be smarter. You need to be clearer.

Clarity is a system, not a talent.