agent-harness-design

Agent Harness Design

Core stance:Agent = Model(LLM) + Harness (the operating system that lets the model work in a given environment). Agency comes from model training, not from external code orchestration. A working Agent product must have a complete Harness.

High-level perspective selection table

First split the Agent system into 5main categories(walkinglabs L02 §"What a Harness Actually Is")。Orthogonality statement:The 5 main categories are roughly orthogonal, but a single mechanism can span multiple perspectives at once—when making selections, first choose the main category, then consider cross-axis side effects. Engineering judgments all start from this table.

Perspective	What to look at	Which reference to use	Cross-axis side effects (common overreach)
Instructions / instruction system	AGENTS.md / CLAUDE.md / .cursorrules and other repositories as specification files; rule priority and number of mutable layers	02-checklist.md §10 Skills System + 02-checklist.md §1 Agent Loop	Skills System is also a Tools loading path(load_skill is a tool call);Agent Loop also involves Instructions injection(system prompt assembly)
Tools / tool surface	schema/handler/policy three-in-one, concurrent scheduling, error propagation, MCP integration	02-checklist.md §2 §3 + 03-antipatterns.md L4 L5	Hooks are also Feedback(permission approval feedback);MCP Connectors are also Environment(network dependency management)
Environment / environment	runtime (local / container / Worktree), dependency locks (pyproject.toml / package.json), version pinning (.nvmrc / .python-version), reproducibility	02-checklist.md §1 + 04-production.md §Axis 5 Security and permissions	Boundary with Tools: MCP is both a Tools integration and an Environment dependency
State / state	session transcript, facts that survive restarts, progress files, append-only persistence and head anchor	02-checklist.md §6 Memory System + 03-antipatterns.md	Audit & Hash Chain are also Feedback(alerting);Memory recall is a Feedback loop(query → recall → injection, not a pure State read);Context Compact strictly speaking spans both State + Tools(the four-step pipeline is messages[] state management, and is itself 4 operations)
Feedback	verification commands (test / lint / type-check), Goal/Evaluator separation, independent evaluator	02-checklist.md §5 + 06-loop-engineering.md §Generator/Evaluator	Context Compact is not in this perspective(it is essentially State+Tools);the Memory recall part is in this perspective

Framework-neutral:the two upstream sources (walkinglabs L02 five subsystems / WanLanglin §1.2 three pillars) divide the perspectives differently—walkinglabs emphasizes "which facilities determine the Agent's capability realization rate," while WanLanglin emphasizes "which areas engineering time should be invested in"; this table uses walkinglabs' five subsystems to organize routing, with cited sources in 05-source-synthesis.md。

When to use

Four types of scenarios that trigger this skill:

1. Designing an Agent product/system from scratch—the user says "I want to build an Agent," "help me design the architecture of this Agent," "plan an Agent team"
2. Reviewing/diagnosing an existing Agent design— The user says "How is this Agent designed?", "Why is my Agent unstable?", "What's wrong with this architecture?"
3. Add new mechanisms to an existing Agent— The user says "Add multi-Agent collaboration", "Connect MCP", "Add memory", "Add permission Hooks", "Add context compression"
4. Automation / upgrade to a graph— The user says "Let the Agent run on its own", "I want a Loop, not a single conversation", "Split a single Agent into a multi-Agent team", "Connect cron / webhook / scheduled tasks"

NoApplies to: pure model training/SFT/RLHF, pure prompt engineering (no harness decisions), pure front-end UI design.

Quick start

1. First read references/01-mindset.md for 5 minutes — understand the Model + Harness paradigm and the three fundamental tensions.
2. Based on your scenario, jump to the corresponding section in ## Workflow and implement it step by step.
3. After completion, use references/03-antipatterns.md to self-check, going through all the "❌ Don't do" checklist items.
4. Before launch, use references/04-production.md to run the five-axis check (API / errors / observability / performance / security).
5. If automation / Loop / multi-Agent graphs / selecting a Frontier product paradigm are involved, first read references/06-loop-engineering.md or references/07-graph-engineering.md; for a side-by-side comparison of mainstream product designs, see references/08-frontier-designs.md。

Core paradigm

Agent = Model + Harness. Model is the brain (LLM); Harness is the operating system that lets the brain keep working, use tools, maintain context, deliver files, and accept governance.

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions. But from an engineering perspective, the Harness consists of 14 core mechanisms:

1. Agent Loop — while True + tool_use + tool_result, the loop stays constant
2. Tool Registry / Dispatch — single source of truth, adding tools doesn't change the loop
3. Deferred Tool Loading — tools list the catalog first, schemas expanded on demand
4. Permission / Hooks — three-state gate (allow/ask/deny) + 4 event extension points
5. Context Compact — four-step compression pipeline (persist→trim→replace→summarize)
6. Memory System — cross-session knowledge, three layers of ownership: workspace / user / remote
7. SubAgent / Team — context isolation + persistent teammates + shared blackboard
8. Task System — file-persisted task graph + blocking + atomic claiming
9. MCP Connectors — external tool namespaces merged into the tool pool
10. Skills System — SKILL.md catalog + on-demand full-text loading
11. Audit & Hash Chain — append-only evidence stream + tamper-proof chain
12. Session & Runtime — UI doesn't run the agent, session is recoverable, runtime is rebuildable
13. Multi-Provider Adapter — protocol differences normalized, Loop only sees neutral types
14. Event-Driven Bus — two pipelines: subscription (read-only) vs decision (can act)

For the complete mechanism table and "why / where / how to verify", see references/02-checklist.md。

Workflow

Scenario A: Design an Agent system from scratch

1. Define the target domain and boundaries— What does this Agent solve? What doesn't it solve? (single-domain vs general-purpose)

   16-step session lifecycle(refer to walkinglabs root README §"The Agent Session Lifecycle", not in L02): every Agent session from start to finish follows this pipeline; in engineering, each step corresponds to a different mechanism in 02-checklist.

   Step names are conceptually labeled by this skill: the original walkinglabs description is action-based (Agent reads X / Agent runs Y),structure(4 phases × N steps) is consistent with upstream, butspecific step names(Bootstrap / Verify / Model turn, etc.) are this skill's conceptual abstraction of the original 16 steps, not walkinglabs' original wording. When citing, read according to this table; for hands-on practice, return to the original README.

   START (1-5):
     [1] Bootstrap
     [2] Verify
     [3] Open session
     [4] Load context
     [5] Seed plan/todos
   
   SELECT (6-7):
     [6] Listen
     [7] Gate
   
   EXECUTE (8-11):
     [8] Model turn
     [9] Tool dispatch
     [10] Hooks (post-tool)
     [11] Append messages
   
   WRAP UP (12-16):
     [12] Settle
     [13] Audit
     [14] Compact
     [15] Continue
     [16] End session
   

   Corresponds to ## Quick start Step 5 of: Quick Start 1-5 corresponds to START 1-5 (mindset and boundaries); Workflow scenario A steps 2-8 correspond to SELECT 6-7 + EXECUTE 8-11 (tools/memory/permissions/context/audit); pre-launch 04-production corresponds to WRAP UP 12-16 (observability/performance/security).

2. Choose Loop form——single process vs Sidecar (Sidecar suits desktop/server); CLI vs TUI vs Web vs GUI

3. Design Tool Registry——internal tools (read-only→write→network→execute), Skills, MCP three layers unified, unified naming

4. Define Memory boundaries——workspace (project facts)/ user (preferences)/ remote (profile) three layers, clear ownership

5. Design permission gate——DENY never prompts; ASK goes through user approval; ALLOW is executable by default

6. Design context budget——max tool output limit, compaction threshold, Skills lazy loading

7. Design audit——JSONL append-only + SHA256 hash chain + head anchor (prevents tail deletion)

8. Draw a one-page diagram of "why it is designed this way"——six-layer architecture (UI / Agent / tools / extensions / memory / governance) with clear responsibilities

Verify:scripts/verify.py(e.g., learn-workbuddy paradigm) + offline mock runs through + real key runs through demo suite

Scenario B: Review/diagnose an existing Agent design

1. Run through the anti-pattern checklist references/03-antipatterns.md——All 30 items checked(actually 30: paradigm layer 6 + Loop layer 8 + context layer 5 + multi-Agent layer 4 + operations layer 5 + Graph layer 2), red-flagged items are the problems
2. Check whether Loop is constant——while True Has it been rewritten? Are there if-else branches inserted in the loop body?
3. Check whether Tool Registry is a single source of truth——are schema/handler/policy separated? Are there three definitions?
4. Check whether permissions are three-stage——are decide / resolve / run separated? Is there any possibility of DENY being overridden?
5. Check the four-step context pipeline——are persist / trim / replace / summarize all implemented? Is the order correct?
6. Check whether the audit chain has a head anchor——a hash chain alone is not enough; prevent "tail deletion"
7. Check whether multi-Agent communication is isolated——do sub-Agents pollute the main window? Does Team communication have boundaries?

Output format:{机制名} → {状态: ✅ / ⚠️ / ❌} → {问题描述} → {修复建议}

Scenario C: Add a new mechanism to an existing Agent

1. Confirm Loop unchanged——new mechanisms are always injected via dispatch map / hooks / system prompt, never written into the loop body
2. Start from the minimal subset——do not add the full set at once. First add Loop essentials (tools + dispatch), then context (compact), then security (permission)
3. Follow the progressive order:agent_loop → tool_dispatch → permission → hooks → todo_write → subagent → skills → context_compact → memory → task_system → multi_agent → mcp → audit → production_check
4. Run regressions after each mechanism added——run both offline mock + real key sets to ensure old paths do not regress
5. After adding, use references/05-source-synthesis.md to calibrate——what each of the three upstream resources covers, to avoid reinventing the wheel

Scenario D: Automation / upgrade to Loop / multi-Agent graph

1. Determine whether automation is really needed——refer to references/06-loop-engineering.md §when to use / when not to use, only take the Loop engineering path when ≥ 1 "when to use" condition is met and no "when not to use" condition is hit
2. Choose the Loop form— read 06-loop-engineering.md §4 kinds of loops(Goal-driven / Timer-driven / Maker-Checker / Event-driven), match your trigger source
3. Confirm whether a Graph is needed— read references/07-graph-engineering.md §5 evaluation criteria(task complexity / parallel benefit / separable responsibility / review bandwidth / failure fallback),only go with a Graph when ≥ 3 conditions are met
4. Implement the 6 primitives——Automations / Worktrees / Skills / Connectors / Sub-agents / External State(06-loop-engineering.md §6 primitives), none may be missing
5. Self-check the 4 Silent Costs——Verification Debt / Comprehension Rot / Cognitive Surrender / Token Blowout(06-loop-engineering.md §4 Silent Costs), prepare governance actions for each
6. Cross-compare the Frontier— if you need to do selection / draw lessons, read 08-frontier-designs.md the 4 design philosophies of Pi / Claude Code / Codex / DeepSeek and the 12-dimension evaluation framework (use only the framework names; for specific cell data see the original repository)
7. Separate Generator / Evaluator— the Loop kernel must have an independent evaluator, see 06-loop-engineering.md §Generator/Evaluator Separation

Why this scenario is a separate section:06 / 07 the referenced file is already self-consistent, but SKILL.md previously did not provide a step-by-step entry for scenario D. This section closes the loop on the 4 scenario promises of SKILL.md.

Difference from scenario C: scenario C adds a single mechanism (short-term); scenario D upgrades the architecture (day / week scale, involving Loop persistence, Worktree, multi-Agent communication, External State).

Federation (optional integration)

📦 Production rollout: when you want to apply this skill's design philosophy to a real production Pi Coding Agent,pi-coding-agent the specific APIs of v0.83.0+ (createAgentSession / defineTool / pi.on / session.subscribe / SSE streaming) see upstream dg-piagent skill (from the repository root docs/awesome-skills.md entry).This skill stays vendor-neutral— it only covers harness design philosophy and does not bind to an SDK version;dg-piagent maintains the SDK-versioned concrete implementation. During selection, first read this skill to decide which main paths to take, then install dg-piagent to land it on the Pi runtime.

References

Progressive by usage stage, load on demand.

Read first

• references/01-mindset.md — Required: Model + Harness paradigm, the three fundamental tensions (context vs information / autonomy vs safety / cost vs complexity), kernel + overlay Loop, the two event pipelines

On demand

• references/02-checklist.md — list of 14 mechanisms (mechanism / why / which chapter / how to verify), consult this table for both designing from 0 and reviewing
• references/03-antipatterns.md — 30 anti-patterns(paradigm layer 6 + Loop layer 8 + context layer 5 + multi-Agent layer 4 + operations layer 5 + Graph layer 2; each with wrong / right / why it's wrong), must run the self-check after design is complete and after adding new mechanisms
• references/04-production.md — 5 axes of production rollout (API-ization / error handling / observability / performance / safety), must run before launch
• references/06-loop-engineering.md — automated Loop: 6 primitives, 4 silent costs, generator/evaluator separation
• references/07-graph-engineering.md — multi-Agent graph: 4 components, 3 structural failures, orchestration tax
• references/08-frontier-designs.md — cross-comparison and migration checklist of the 4 Frontier products (Pi / Claude Code / Codex / DeepSeek)

Extended

• references/05-source-synthesis.md — the unique contributions of the five upstream resources + mechanism × source mapping table + extended reading pointers (Grove / Anti-Distillation), for cross-calibration