Agent Harness

Production-grade Agent Harness combining execution discipline, knowledge compounding, and product thinking into a single adaptive workflow. Use when: (1) building features or fixing bugs with AI agents, (2) user says 'build', 'plan', 'spec', 'review', 'ship', 'debug', (3) managing multi-step or multi-agent tasks, (4) need structured engineering workflow with quality gates. Provides: task complexity auto-grading (simple/medium/complex), anti-rationalization guards, concurrent subagent scheduling (≤4 hard limit), tool-chain continuity enforcement, context budget management, verification protocols, and experience compounding. Triggers: 'agent harness', 'engineering workflow', 'build protocol', 'multi-agent task', 'coding discipline', 'subagent orchestration'.

A unified engineering harness combining execution discipline, knowledge compounding, and product thinking. Born from ~450k characters of real-world AI textbook writing + 15+ production incidents.

GAIA benchmark shows scaffold design = 30pp+ performance boost — same model, HAL scaffold 74.6% vs bare model ~44%. The harness is the multiplier.

Core Philosophy

Agent = Model + Harness. The model provides capability; the harness provides discipline.

Three layers, one workflow:

1. Challenge — Is this the right thing to build?
2. Execute — Build it with engineering rigor
3. Compound — Learn from what happened

Task Complexity Auto-Grading

Before starting any task, assess complexity. This determines which workflow steps to run.

🟢 Simple (bug fix, config change, small tweak)

• Skip spec/plan → Direct edit → Verify → Done

🟡 Medium (new feature, module, integration)

• Plan → Build incrementally → Test → Review → Done

🔴 Complex (architecture change, multi-module, new system)

• Full pipeline: Challenge → Spec → Plan → Build → Test → Review → Ship

When unsure, start at 🟡. Upgrade to 🔴 if you discover hidden complexity. Never downgrade mid-task.

Layer 1: Challenge (🔴 Complex tasks only)

Before writing any code, answer these questions:

1. Problem validity — Is the user solving a real problem?
2. Simplest approach — Is there a simpler way?
3. Scope clarity — Can you explain "done" in one sentence?
4. Risk assessment — What's the worst outcome if this goes wrong?

Output: A one-paragraph problem statement the user confirms before proceeding.

Layer 2: Execute

Spec (🟡🔴 only)

• Goal: One sentence describing the outcome
• Interface: Inputs, outputs, API contracts
• Constraints: What you will NOT do
• Acceptance criteria: How to verify it works (must be testable)

Plan (🟡🔴 only)

Break the spec into atomic tasks:

• Each task modifies ≤3 files
• Each task has a clear verification step
• Tasks ordered by dependency (independent tasks can parallelize)

Build

Execute tasks incrementally. After each task:

1. Verify the task works (run it, test it, check the output)
2. Checkpoint progress to file
3. Only then move to the next task

Critical rules:

• Never modify code you haven't read first
• Don't add features beyond what was asked
• Don't refactor "while you're at it"
• If tests fail, report honestly — don't claim success

Verify

Every deliverable must have evidence, not just "looks good":

Deliverable type	Required evidence
Code change	Tests pass (show output)
Config change	Restart + verify (show status)
File generation	wc -l + grep key content
API integration	Show actual response
Documentation	Spot-check 3 claims for accuracy

🔴 Reading is not verification. Run it.

Review (🟡🔴 only)

Self-review from 5 dimensions:

1. Correctness — Does it do what was asked?
2. Edge cases — Empty input, huge input, concurrent access?
3. Security — Injection points, leaked secrets, missing auth?
4. Performance — Will it work at 10x scale?
5. Maintainability — Will someone understand this in 6 months?

Ship (🔴 only)

Pre-ship checklist:

• All tests pass
• Rollback plan exists (undo in <5 min?)
• Feature flag or gradual rollout if risky
• Monitoring covers the new code path

Layer 3: Compound

After completing any task, spend 30 seconds on:

1. What broke? — Errors, retries, unexpected behavior? → Record the specific lesson
2. What was slow? — Bottlenecks? → Note them
3. What would you do differently? — Better approach with hindsight?

Only record specific, actionable lessons. Not generic advice.

Good: "Bedrock throttles at >4 concurrent requests. Use model rotation or serial execution." Bad: "Remember to handle API limits properly."

Anti-Rationalization Table

Your excuse	Why it's wrong	Do this instead
"Too simple to need tests"	40% of P0 incidents come from "too simple" code	Write the test. It takes 2 minutes.
"I already checked, looks fine"	Reading ≠ verifying	Run it. ls, wc -l, grep, actual execution.
"I'll write tests after the feature"	You won't. Test debt only grows.	Write the test NOW.
"This old code looks unused, I'll delete it"	Chesterton's Fence: understand before removing	git blame first. Ask why it exists.
"It should work"	"Should" is not evidence	Provide logs, output, or data.
"Let me refactor while I'm here"	Scope creep.	File a separate TODO for the refactor.
"I'll handle errors later"	Error handling IS the feature in production	Handle errors now.
"The context is too long, I'll skip details"	Skipping details = skipping correctness	Checkpoint to file, compact context, continue with full fidelity.
"I already ran it once, it should still work"	Stateful systems change.	Run it again. Every time.

Concurrent Subagent Scheduling

Hard limits:

• ≤4 subagents parallel (hard limit; check subagents list before spawning)
• System hard ceiling: 8
• 5+? Re-slice into sequential batches first
• Always check current count before spawning: subagents(action=list)

Task delegation rules:

• Instructions must be self-contained (paste content directly, don't reference files)
• Each subagent writes to its own independent output file
• Subagents never communicate directly — everything goes through coordinator
• Use sessions_yield after spawning, not a poll loop

After yield returns — mandatory checks:

1. subagents(action=list) — confirm all spawned subagents ended
2. ls output files — verify files exist with expected mtimes
3. If any subagent missing or no output file → investigate, don't assume success

Why: OpenClaw subagent completion announce has a known race condition. Never rely on announce as the sole signal. Active verification is the backup system.

Failure classification (before retrying):

• Design failure? → Fix the spec first
• Alignment failure? → Clarify the instruction
• Verification failure? → The work was done but not confirmed
• See references/mast-failure-taxonomy.md for full taxonomy

Tool-Chain Continuity (🔴 Critical)

Every tool call return must be followed by one of:

• Next tool call
• Progress message to user
• sessions_yield

Never: respond with "I'll continue..." and then have no tool call.

Pre-tool-return self-check:

• Task complete? No → what's the next tool call?
• Waiting for external input? → Send message explaining + yield
• "Thinking about next step"? → Danger signal. Pick an action NOW.

Context Budget Management

Water level	Mode	Action
< 70%	🟢 Normal	Full mode, observation masking always on
70–85%	🟡 Auto-Concise	No new large files, tool output truncated, subagent instructions <1500 chars
85–95%	🟠 Preservation	No files >100 lines, force checkpoint to memory, delegate reads to subagent
> 95%	🔴 Emergency	Flush state, alert user to /reset, stop accepting new tasks

Observation Masking (apply immediately after consuming any tool output):

• After reading a file and extracting conclusions: don't re-quote the raw content
• After exec output: keep only key lines
• After subagent delivery: extract deliverable + quality verdict, discard process noise

Critical Safety Rules

🔫 Never restart your own process from inside an agent turn.

• ❌ systemctl restart <service>, pkill <process>, gateway restart in cron prompts
• ✅ Use the platform's safe restart tool (e.g., gateway tool's restart action)
• Why: Agent terminal runs inside the gateway process. Restarting the service = SIGKILL yourself.

🔫🔫 Never put restart commands in cron job prompts.

• once job + agent turn + restart = suicide loop: cron fires → agent runs → restart kills agent → turn never completes → scheduler sees incomplete once job → re-fires on next boot → infinite loop
• Restart/self-check logic must live in an external wrapper (systemd ExecStartPost= or standalone systemd-run unit), completely outside the agent process.

Verification Protocol

For important deliverables, use an independent verifier:

1. Verifier does NOT read the original requirements
2. Verifier only reads the output/deliverable
3. Verifier independently assesses: correct? complete? well-formed?
4. Core principle: "The implementer is an LLM. Reading is not verification. Run it."

Checkpoint Protocol

Protect progress against crashes:

1. Write to file after each step — Don't accumulate results in memory
2. Design tasks as idempotent — Re-running produces the same result
3. Only retry the failed step — Don't restart from scratch
4. Progress must be observable — ls shows what's done, not model memory

See references/checkpoint-patterns.md for detailed patterns.

Known Tool Pitfalls

• \n literal in exec/write content: In some platforms, multiline scripts passed as strings get \n treated as literal characters, not newlines. Always use real line breaks. Verify with read after writing.
• Concurrent writes: Multiple subagents writing to the same file = corruption. Each subagent must have its own output file.
• Reading ≠ Verifying: grep and wc -l are faster than read for verification. Use them.

Quick Reference

🟢 Simple:  Edit → Verify → Done
🟡 Medium:  Plan → Build → Test → Review → Done
🔴 Complex: Challenge → Spec → Plan → Build → Test → Review → Ship → Compound

After every tool call: next action or yield. Never stall.