Agent Harness

A unified engineering harness that combines execution discipline, knowledge compounding, and product thinking. Born from 45万字 of real-world AI textbook writing + 9 production incidents.

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? (from Gstack)
2. Execute — Build it with engineering rigor (from Superpower)
3. Compound — Learn from what happened (from CE)

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
• Example: "fix the typo in line 42", "update the API endpoint"

🟡 Medium (new feature, module, integration)

• Plan → Build incrementally → Test → Review → Done
• Example: "add user authentication", "integrate payment API"

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

• Full pipeline: Challenge → Spec → Plan → Build → Test → Review → Ship
• Example: "redesign the database schema", "build a multi-agent orchestrator"

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. If any answer is "no" or uncertain, pause and discuss with the user.

1. Problem validity — Is the user solving a real problem or building a solution looking for a problem?
2. Simplest approach — Is there a simpler way that doesn't require building this?
3. Scope clarity — Can you explain what "done" looks like in one sentence?
4. Risk assessment — What's the worst thing that happens if this goes wrong?

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

Layer 2: Execute

Spec (🟡🔴 only)

Define what you're building before you build it:

• Goal: One sentence describing the outcome
• Interface: Inputs, outputs, API contracts
• Constraints: What you will NOT do (equally important as what you will 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 are ordered by dependency (independent tasks can parallelize)
• Estimate: simple tasks ~5min, medium ~15min, complex ~30min

Build

Execute tasks incrementally. After each task:

1. Verify the task works (run it, test it, check the output)
2. Commit or checkpoint the progress
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":

Review (🟡🔴 only)

Self-review from 5 dimensions:

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

Ship (🔴 only)

Pre-ship checklist:

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

Layer 3: Compound

After completing any task (regardless of complexity), spend 30 seconds on:

1. What broke? — Any errors, retries, unexpected behavior? → Record the specific lesson
2. What was slow? — Any step that took longer than expected? → Note the bottleneck
3. What would you do differently? — With hindsight, was there a better approach?

Only record specific, actionable lessons. Not generic advice like "be more careful".

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

Anti-Rationalization Table

When you catch yourself thinking any of these, stop and follow the rebuttal:

Concurrent Subagent Scheduling

When delegating to subagents:

Concurrency limits:

• ≤2 subagents parallel to same API endpoint

• 2? Serialize or distribute across regions/models

• 4+ parallel = 75% failure rate (tested). Don't do it.

Task delegation rules:

• Task instructions must be self-contained (don't say "go read file X")
• Include content directly in the instruction, not file references
• Each subagent writes to its own independent file
• Subagents never communicate directly — everything goes through coordinator

Failure handling:

• Don't blindly retry. First classify: Design failure? Alignment failure? Verification failure?
• Check sessions_history for the actual error, don't guess
• See references/mast-failure-taxonomy.md for the full classification framework

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: Is this correct? Complete? Well-formed?
4. Core principle: "The implementer is an LLM. Verify independently. 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 a step 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.

Quick Reference

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