[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AVH7A8225TVCW3GCF38CPD":3,"skill-same:01M7AVH7A8225TVCW3GCF38CPD":61},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M7AVH7A8225TVCW3GCF38CPD","agent-harness-architect",null,"Architect, evaluate, select, and sandbox production-grade AI agent harnesses and runtime loops using 5-part harness architecture, 4-mechanism validation, and 4-layer stack partitioning. Do not use for generic prompt writing or single-turn chat scripts.","SpectreDeath\u002FBrain-Harness","SpectreDeath","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F207463416?v=4","01M7AVGR1D4X8ADT47APKGVH2Z","JL","01M7AVGR2HSGD23BA5DBTJJTVN",0,"MIT","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fagent-harness-architect\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: agent-harness-architect\ndescription: Architect, evaluate, select, and sandbox production-grade AI agent harnesses and runtime loops using 5-part harness architecture, 4-mechanism validation, and 4-layer stack partitioning. Do not use for generic prompt writing or single-turn chat scripts.\n---\n\n# Agent Harness Architect: Runtime Shell & Selection Engine\n\n`agent-harness-architect` is the cognitive and architectural engine for designing, auditing, selecting, and sandboxing production-grade AI agent runtime harnesses. Synthesized from Rudrendu Paul's foundational literature (*What Is an Agent Harness? The Architecture Behind Claude Code, DeepSeek Harness, and Hermes Agent*, freeCodeCamp, 2026), this skill operationalizes the shift from unopinionated agent framework libraries (2023–2025) to opinionated, turnkey agent harnesses (2026).\n\nRather than treating agent execution as an unbounded prompting loop, `agent-harness-architect` enforces the **5-Part Harness Architecture**, verifies the **4 Reliability Mechanisms** popularized by Claude Code and Deep Agents, decouples the **4-Layer Agent Stack** (MCP, Harness, Orchestration, Observability\u002FSandbox), and locks down load-bearing sandbox safety boundaries.\n\nEvery harness audit, design, or selection workflow executes this 5-stage progression:\n\n```\n[1. Failure Mode Bet Matching] → [2. 5-Part Harness Audit] → [3. 4-Mechanism Reliability Gate] → [4. 4-Layer Stack Auditing] → [5. Safety Invariants & Budget Gate]\n```\n\nSee [CARD.md](CARD.md) for the companion summary card, stage matrix, and verification checklist.\nConsult [..\u002Fai-agent-engineer\u002FSKILL.md](..\u002Fai-agent-engineer\u002FSKILL.md) for canonical agent architectural patterns, [..\u002Forca-orchestrator\u002FSKILL.md](..\u002Forca-orchestrator\u002FSKILL.md) for multi-worker Git worktree coordination, and [..\u002Fcrafting-skills\u002FSKILL.md](..\u002Fcrafting-skills\u002FSKILL.md) for skill authoring standards.\n\n---\n\n## 1. Failure Mode Diagnosis & Architectural Bet Matching\n\nDiagnose the team's operational bottleneck and match it against the four competing architectural bets of 2026 harnesses:\n\n1. **Diagnose Primary Operational Bottleneck**:\n   - *Vendor \u002F Model Lock-in*: Team needs to swap foundation models, tools, or sandboxes without rewriting orchestration logic.\n   - *Unreliable Multi-Turn Execution*: Single-agent sessions drift off-task, hallucinate file states, or burn context by turn 25.\n   - *Cross-Session Amnesia*: The agent re-reasons through identical domain workflows every morning from scratch.\n   - *Audit Surface Bloat*: Security\u002Fcompliance teams reject heavyweight runtimes with sprawling dependency trees.\n2. **Select Architectural Bet**:\n   - **Bet 1: Total Runtime Modularity (`deepseek-harness` \u002F `dsh`)**:\n     * Architecture as a configuration file. Every component—model provider, tool catalog, sandbox container, and terminal UI—is a swappable plugin managed by an IoC container (Cordis pattern).\n   - **Bet 2: Fixed Mechanisms, Executed Reliably (`claude-code`, `deep-agents`, `aider`, `cline`)**:\n     * Focus on four locked mechanisms (planning, sandboxed filesystem, subagents, context compression). Ideal for end-to-end coding loops where a reviewable diff or test pass is the unit of work.\n   - **Bet 3: Compounding Memory & Omnichannel Presence (`hermes-agent`)**:\n     * Persistent self-improvement. Successful multi-step solutions are committed to a shareable skill library. The agent operates as a standing assistant accessible via chat platforms (Slack, Discord, Telegram).\n   - **Bet 4: Radical Minimalism (`pi`, `oh-my-pi`)**:\n     * 4 built-in tools (`read_file`, `write_file`, `edit_file`, `run_bash`), radical transparency, and zero framework weight. Extended via typed extensions or Rust-based DAP\u002FLSP engines (`omp`).\n3. **Evaluate Adoption Curve Health**:\n   - Distinguish launch spikes (e.g. 95,000 stars in 2 days) from compounding organic adoption (steady 1-year climb to 91,000+ stars). Prioritize maintainer commitment and sustained retention over vanity metrics.\n\n> **Completion criterion**: Primary operational bottleneck diagnosed, target architectural bet justified, and baseline harness archetype selected.\n\n---\n\n## 2. Core 5-Part Harness Architecture Audit\n\nAudit or scaffold the five architectural components that comprise every production runtime harness:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│              CORE 5-PART HARNESS ARCHITECTURE               │\n├──────────────────────────────┬──────────────────────────────┤\n│ 1. Model Core                │ 2. Tool Router               │\n│ - Unopinionated next-token \u002F │ - Schema dispatch to local   │\n│   tool-call prediction       │   filesystem, bash, or MCP   │\n├──────────────────────────────┼──────────────────────────────┤\n│ 3. Memory & Context Layer    │ 4. Pre-Execution Planning    │\n│ - Context eviction, middle-  │ - Mandatory step commitments │\n│   out compression, offload   │   before modifying state     │\n├──────────────────────────────┴──────────────────────────────┤\n│ 5. Sandbox Execution Boundary                               │\n│ - Restricted filesystem jail, disposable micro-VMs (E2B)    │\n└─────────────────────────────────────────────────────────────┘\n```\n\n1. **Verify the 5-Step Execution Loop**:\n   - *Step 1 (Prompt Assembly)*: Harness compiles user intent, system instructions, and tool schemas.\n   - *Step 2 (Model Prediction)*: Model emits reasoning and structured tool calls.\n   - *Step 3 (Sandbox Tool Execution)*: Harness executes calls inside the sandbox and captures stdout\u002Fstderr.\n   - *Step 4 (Context Append)*: Harness appends observations back into the message trajectory.\n   - *Step 5 (Termination Evaluation)*: Harness evaluates stop conditions (final answer, max turns, cost limits, user interrupt).\n2. **Audit Toy Loop Failure Seams**:\n   - Inspect tool execution for unhandled exceptions that cause model spin.\n   - Ensure the loop does not run bare `subprocess.run(shell=True)` directly on host working directories.\n\n> **Completion criterion**: 5 core harness components verified and mapped; absence of unconstrained toy loops confirmed.\n\n---\n\n## 3. The 4-Mechanism Reliability Gate\n\nEvaluate and enforce the four load-bearing mechanisms identified in Claude Code and LangChain Deep Agents:\n\n1. **Mechanism A: Pre-Execution Planning Tool**:\n   - Mandate that the model formulate and emit a structured execution plan before invoking file-mutating tools.\n   - Enforce plan check-ins when execution deviates or exceeds estimated step bounds.\n2. **Mechanism B: Virtual Filesystem & Isolated Sandbox**:\n   - Confine all file reads, writes, and shell executions to an isolated path jail or disposable container.\n   - Verify that relative path traversals (`..\u002F..`) cannot escape the sandbox boundary.\n3. **Mechanism C: Subagent Delegation**:\n   - Verify capability to spawn isolated sub-agents with dedicated, clean context windows.\n   - Restrict sub-agents to specific bounded sub-tasks; return aggregated summaries to the parent context.\n4. **Mechanism D: Context Compression & Memory Management**:\n   - Implement middleware that monitors conversation token counts against window limits.\n   - Offload large tool observation outputs (e.g. multi-megabyte log files) to storage pointers or apply middle-out compression.\n\n### Diagnostic Reliability Scorecard\n\n| Architectural Axis | Level 0: Toy \u002F Fragile | Level 1: Intermediate | Level 2: Production Gate |\n|---|---|---|---|\n| **Planning Gate** | Direct execution on turn 1 | Ad-hoc textual plan request | Mandatory planning tool; approval gated |\n| **Sandbox Isolation** | Bare host shell execution | Relative path checks (`cwd=\".\u002Fsandbox\"`) | Ephemeral micro-VM (E2B\u002FModal) or Docker |\n| **Subagent Delegation** | Monolithic single context | Inline simulated persona | Child agent spawned in isolated window |\n| **Context Compression**| Raw dump into history | Hard message truncation | Middle-out compression & artifact pointers |\n| **Observability** | Console print statements | Plain local log files | Distributed session tracing (Langfuse\u002FLangSmith)|\n\n> **Completion criterion**: Target harness audited against all 4 mechanisms; Level 2 production criteria satisfied on planning and sandboxing.\n\n---\n\n## 4. 4-Layer Stack Boundary Auditing\n\nAudit architectural boundaries to ensure clean separation across the 4-layer agent stack:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                 THE 4-LAYER AGENT STACK                     │\n├─────────────────────────────────────────────────────────────┤\n│ Layer 4 (Cross-Cutting): Observability & Micro-VM Sandboxes │\n│ - Tracing: Langfuse, LangSmith, Braintrust, Phoenix         │\n│ - Sandboxing: E2B, Modal, Docker                            │\n├─────────────────────────────────────────────────────────────┤\n│ Layer 3: Orchestration Frameworks                           │\n│ - Multi-agent coordination graphs: LangGraph, CrewAI,       │\n│   AG2, Mastra, DSPy                                         │\n├─────────────────────────────────────────────────────────────┤\n│ Layer 2: Agent Harness Loop                                 │\n│ - Opinionated single-agent ReAct shell: Claude Code, dsh,   │\n│   Hermes Agent, Pi, Deep Agents                             │\n├─────────────────────────────────────────────────────────────┤\n│ Layer 1: Protocol Standard (MCP)                            │\n│ - Model Context Protocol tool servers & unified resources   │\n└─────────────────────────────────────────────────────────────┘\n```\n\n1. **Verify Protocol Decoupling (Layer 1 - MCP)**:\n   - Ensure tool integrations use declarative MCP server configurations rather than hardcoded client branches.\n2. **Enforce Harness-Orchestration Boundary (Layer 2 vs Layer 3)**:\n   - Do not force a single-agent harness loop to handle complex multi-persona DAG choreography.\n   - Delegate stateful, long-running team workflows to Layer 3 orchestrators (LangGraph, Mastra).\n3. **Attach Layer 4 Observability from Day One**:\n   - Mandate session tracing (Langfuse, LangSmith) to capture per-turn token consumption, model latencies, and tool call payloads.\n   - Eliminate unobservable failures at turn 30+ through detailed execution traces.\n\n> **Completion criterion**: 4-layer boundaries verified; tools integrated via MCP; observability hooks wired.\n\n---\n\n## 5. Load-Bearing Safety Invariants & Hard Budget Enforcement\n\nEnforce production runtime safeguards to prevent runaway execution, financial exhaustion, and filesystem corruption:\n\n1. **Jail Path Containment Invariant**:\n   - Tool execution paths must be pinned to explicit sandbox roots. Reject shell execution without verified directory confinement.\n2. **Triple Budget Boundaries**:\n   - *Turn Ceiling*: Configure non-optional `max_turns` (e.g. 15–30 turns) to prevent infinite ReAct loops.\n   - *Financial \u002F Token Budget*: Declare strict per-session token limits or USD expenditure ceilings.\n   - *Wall-Clock Subprocess Timeout*: Enforce synchronous process execution timeouts (\u003C= 120s) on all child bash commands.\n3. **Defensive Error Recovery**:\n   - Wrap tool dispatchers in defensive exception handlers. Capture exit codes, stdout, and stderr.\n   - Provide informative diagnostic error messages to the model instead of crashing or returning empty payloads.\n\n> **Completion criterion**: Hard turn limits, financial budgets, sandbox containment, and defensive error handlers actively enforced.\n\n---\n\n## The Visual Brief Specification\n\nBefore finalizing architectural recommendations or deploying new agent harnesses into production, the architect must generate an interactive HTML Visual Brief:\n\n1. **Target Location**: Write the brief to `%TEMP%\\agent-harness-\u003Ctimestamp>.html` (or platform equivalent).\n2. **Visual Brief Content**:\n   - Dark theme (`#0d1117`) loading Tailwind CSS and Mermaid.js via CDN.\n   - Render the **5-Stage Execution & Selection DAG** illustrating the decision flow across the 4 architectural bets.\n   - Embed the **Diagnostic Reliability Scorecard Table** detailing Level 0 to Level 2 criteria.\n   - Display the **Anti-Pattern Defense Matrix** with concrete mitigation rules.\n3. **Delivery**: Present the clickable file URI to the user for visual inspection.\n\n> **Completion criterion**: Visual brief generated in `%TEMP%`, verified non-empty, and presented as an active clickable link.\n\n---\n\n## Mandatory Checkpoint Gate\n\nTo prevent unreviewed harness migrations, insecure sandbox deployments, or runaway token loops:\n\n1. **Checkpoint Artifact**: Author an `implementation_plan.md` artifact detailing:\n   - Evaluated harness candidates and recommended architectural bet.\n   - Sandbox security boundary specification and path jail configuration.\n   - Hard budget bounds (`max_turns`, token limits, cost caps).\n   - Tracing and observability backend configuration.\n2. **Review Signal**: Set `RequestFeedback: true` in artifact metadata.\n3. **Execution Gate**: **STOP and wait** for explicit human confirmation before deploying new harnesses or executing mutating commands.\n\n> **Completion criterion**: Explicit human confirmation received at the Mandatory Checkpoint gate.\n\n## Micro-Kernel IoC Integration & Headless CLI Dispatch\n\nPer **AGENTS.md Rule 49**, `agent-harness-architect` is elevated from a passive prompt into an authoritative, slotted in-memory domain engine and typed IoC service:\n\n1. **Micro-Kernel IoC Resolution**:\n   ```python\n   from harness.services.agent_harness import AGENT_HARNESS_ARCHITECT_SERVICE_KEY\n\n   service = context.require(AGENT_HARNESS_ARCHITECT_SERVICE_KEY)\n   report = service.audit(target_path=\".\")\n   gate = service.evaluate_reliability()\n   bet = service.classify_bet(bottleneck=\"vendor lock-in\")\n   brief_path = service.visual_brief(target_path=\".\")\n   ```\n2. **Headless Click CLI Commands**:\n   - `harness architect audit [--target \u003Cdir>] [--json]` — 5-part architecture & 4-layer stack audit.\n   - `harness architect score [--config \u003Cpath>] [--json]` — 4-mechanism reliability scorecard (L0–L2).\n   - `harness architect bet [--bottleneck \u003Ctext>]` — Match operational bottleneck to 2026 harness bet.\n   - `harness architect brief [--target \u003Cdir>] [--output \u003Cpath>]` — Interactive HTML review report.\n3. **Domain Engine & Plugin**:\n   - Slotted domain engine: `scripts\u002Fagent_harness_architect.py` (`AgentHarnessArchitectEngine`)\n   - Domain plugin: `plugins\u002Fagent_orchestration\u002Fagent_harness_architect\u002F` (`plugin = AgentHarnessArchitectPlugin()`)\n\n---\n\n## Anti-Patterns\n\n- **The Toy Loop Trap** — Deploying a bare 60-line loop using unconstrained subprocess execution without directory confinement, permission gating, or execution limits.\n- **Unbounded Token Bleed** — Omitting max_turns or cost caps, allowing an autonomous agent to loop indefinitely and burn API budgets.\n- **Silent Tool Error Death Spiral** — Failing to catch tool execution errors or malformed payloads, looping the model back into identical failing states.\n- **Context Flooding Amnesia** — Inlining massive raw tool observations into conversation history without progressive compression or pointer offloading.\n- **Premature Action Drift** — Allowing an agent to mutate code or infrastructure files before formulating and locking a structured execution plan.\n- **Cross-Session Amnesia** — Forcing an agent to re-solve recurring procedural tasks from scratch on every run instead of indexing reusable skills.\n- **Stack Layer Smearing** — Conflating single-agent runtime harness execution with multi-agent orchestration graphs or protocol connectivity.\n","# Agent Harness Architect: Runtime Shell & Selection Engine\n\n`agent-harness-architect` is the cognitive and architectural engine for designing, auditing, selecting, and sandboxing production-grade AI agent runtime harnesses. Synthesized from Rudrendu Paul's foundational literature (*What Is an Agent Harness? The Architecture Behind Claude Code, DeepSeek Harness, and Hermes Agent*, freeCodeCamp, 2026), this skill operationalizes the shift from unopinionated agent framework libraries (2023–2025) to opinionated, turnkey agent harnesses (2026).\n\nRather than treating agent execution as an unbounded prompting loop, `agent-harness-architect` enforces the **5-Part Harness Architecture**, verifies the **4 Reliability Mechanisms** popularized by Claude Code and Deep Agents, decouples the **4-Layer Agent Stack** (MCP, Harness, Orchestration, Observability\u002FSandbox), and locks down load-bearing sandbox safety boundaries.\n\nEvery harness audit, design, or selection workflow executes this 5-stage progression:\n\n```\n[1. Failure Mode Bet Matching] → [2. 5-Part Harness Audit] → [3. 4-Mechanism Reliability Gate] → [4. 4-Layer Stack Auditing] → [5. Safety Invariants & Budget Gate]\n```\n\nSee [CARD.md](CARD.md) for the companion summary card, stage matrix, and verification checklist.\nConsult [..\u002Fai-agent-engineer\u002FSKILL.md](..\u002Fai-agent-engineer\u002FSKILL.md) for canonical agent architectural patterns, [..\u002Forca-orchestrator\u002FSKILL.md](..\u002Forca-orchestrator\u002FSKILL.md) for multi-worker Git worktree coordination, and [..\u002Fcrafting-skills\u002FSKILL.md](..\u002Fcrafting-skills\u002FSKILL.md) for skill authoring standards.\n\n---\n\n## 1. Failure Mode Diagnosis & Architectural Bet Matching\n\nDiagnose the team's operational bottleneck and match it against the four competing architectural bets of 2026 harnesses:\n\n1. **Diagnose Primary Operational Bottleneck**:\n   - *Vendor \u002F Model Lock-in*: Team needs to swap foundation models, tools, or sandboxes without rewriting orchestration logic.\n   - *Unreliable Multi-Turn Execution*: Single-agent sessions drift off-task, hallucinate file states, or burn context by turn 25.\n   - *Cross-Session Amnesia*: The agent re-reasons through identical domain workflows every morning from scratch.\n   - *Audit Surface Bloat*: Security\u002Fcompliance teams reject heavyweight runtimes with sprawling dependency trees.\n2. **Select Architectural Bet**:\n   - **Bet 1: Total Runtime Modularity (`deepseek-harness` \u002F `dsh`)**:\n     * Architecture as a configuration file. Every component—model provider, tool catalog, sandbox container, and terminal UI—is a swappable plugin managed by an IoC container (Cordis pattern).\n   - **Bet 2: Fixed Mechanisms, Executed Reliably (`claude-code`, `deep-agents`, `aider`, `cline`)**:\n     * Focus on four locked mechanisms (planning, sandboxed filesystem, subagents, context compression). Ideal for end-to-end coding loops where a reviewable diff or test pass is the unit of work.\n   - **Bet 3: Compounding Memory & Omnichannel Presence (`hermes-agent`)**:\n     * Persistent self-improvement. Successful multi-step solutions are committed to a shareable skill library. The agent operates as a standing assistant accessible via chat platforms (Slack, Discord, Telegram).\n   - **Bet 4: Radical Minimalism (`pi`, `oh-my-pi`)**:\n     * 4 built-in tools (`read_file`, `write_file`, `edit_file`, `run_bash`), radical transparency, and zero framework weight. Extended via typed extensions or Rust-based DAP\u002FLSP engines (`omp`).\n3. **Evaluate Adoption Curve Health**:\n   - Distinguish launch spikes (e.g. 95,000 stars in 2 days) from compounding organic adoption (steady 1-year climb to 91,000+ stars). Prioritize maintainer commitment and sustained retention over vanity metrics.\n\n> **Completion criterion**: Primary operational bottleneck diagnosed, target architectural bet justified, and baseline harness archetype selected.\n\n---\n\n## 2. Core 5-Part Harness Architecture Audit\n\nAudit or scaffold the five architectural components that comprise every production runtime harness:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│              CORE 5-PART HARNESS ARCHITECTURE               │\n├──────────────────────────────┬──────────────────────────────┤\n│ 1. Model Core                │ 2. Tool Router               │\n│ - Unopinionated next-token \u002F │ - Schema dispatch to local   │\n│   tool-call prediction       │   filesystem, bash, or MCP   │\n├──────────────────────────────┼──────────────────────────────┤\n│ 3. Memory & Context Layer    │ 4. Pre-Execution Planning    │\n│ - Context eviction, middle-  │ - Mandatory step commitments │\n│   out compression, offload   │   before modifying state     │\n├──────────────────────────────┴──────────────────────────────┤\n│ 5. Sandbox Execution Boundary                               │\n│ - Restricted filesystem jail, disposable micro-VMs (E2B)    │\n└─────────────────────────────────────────────────────────────┘\n```\n\n1. **Verify the 5-Step Execution Loop**:\n   - *Step 1 (Prompt Assembly)*: Harness compiles user intent, system instructions, and tool schemas.\n   - *Step 2 (Model Prediction)*: Model emits reasoning and structured tool calls.\n   - *Step 3 (Sandbox Tool Execution)*: Harness executes calls inside the sandbox and captures stdout\u002Fstderr.\n   - *Step 4 (Context Append)*: Harness appends observations back into the message trajectory.\n   - *Step 5 (Termination Evaluation)*: Harness evaluates stop conditions (final answer, max turns, cost limits, user interrupt).\n2. **Audit Toy Loop Failure Seams**:\n   - Inspect tool execution for unhandled exceptions that cause model spin.\n   - Ensure the loop does not run bare `subprocess.run(shell=True)` directly on host working directories.\n\n> **Completion criterion**: 5 core harness components verified and mapped; absence of unconstrained toy loops confirmed.\n\n---\n\n## 3. The 4-Mechanism Reliability Gate\n\nEvaluate and enforce the four load-bearing mechanisms identified in Claude Code and LangChain Deep Agents:\n\n1. **Mechanism A: Pre-Execution Planning Tool**:\n   - Mandate that the model formulate and emit a structured execution plan before invoking file-mutating tools.\n   - Enforce plan check-ins when execution deviates or exceeds estimated step bounds.\n2. **Mechanism B: Virtual Filesystem & Isolated Sandbox**:\n   - Confine all file reads, writes, and shell executions to an isolated path jail or disposable container.\n   - Verify that relative path traversals (`..\u002F..`) cannot escape the sandbox boundary.\n3. **Mechanism C: Subagent Delegation**:\n   - Verify capability to spawn isolated sub-agents with dedicated, clean context windows.\n   - Restrict sub-agents to specific bounded sub-tasks; return aggregated summaries to the parent context.\n4. **Mechanism D: Context Compression & Memory Management**:\n   - Implement middleware that monitors conversation token counts against window limits.\n   - Offload large tool observation outputs (e.g. multi-megabyte log files) to storage pointers or apply middle-out compression.\n\n### Diagnostic Reliability Scorecard\n\n| Architectural Axis | Level 0: Toy \u002F Fragile | Level 1: Intermediate | Level 2: Production Gate |\n|---|---|---|---|\n| **Planning Gate** | Direct execution on turn 1 | Ad-hoc textual plan request | Mandatory planning tool; approval gated |\n| **Sandbox Isolation** | Bare host shell execution | Relative path checks (`cwd=\".\u002Fsandbox\"`) | Ephemeral micro-VM (E2B\u002FModal) or Docker |\n| **Subagent Delegation** | Monolithic single context | Inline simulated persona | Child agent spawned in isolated window |\n| **Context Compression**| Raw dump into history | Hard message truncation | Middle-out compression & artifact pointers |\n| **Observability** | Console print statements | Plain local log files | Distributed session tracing (Langfuse\u002FLangSmith)|\n\n> **Completion criterion**: Target harness audited against all 4 mechanisms; Level 2 production criteria satisfied on planning and sandboxing.\n\n---\n\n## 4. 4-Layer Stack Boundary Auditing\n\nAudit architectural boundaries to ensure clean separation across the 4-layer agent stack:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                 THE 4-LAYER AGENT STACK                     │\n├─────────────────────────────────────────────────────────────┤\n│ Layer 4 (Cross-Cutting): Observability & Micro-VM Sandboxes │\n│ - Tracing: Langfuse, LangSmith, Braintrust, Phoenix         │\n│ - Sandboxing: E2B, Modal, Docker                            │\n├─────────────────────────────────────────────────────────────┤\n│ Layer 3: Orchestration Frameworks                           │\n│ - Multi-agent coordination graphs: LangGraph, CrewAI,       │\n│   AG2, Mastra, DSPy                                         │\n├─────────────────────────────────────────────────────────────┤\n│ Layer 2: Agent Harness Loop                                 │\n│ - Opinionated single-agent ReAct shell: Claude Code, dsh,   │\n│   Hermes Agent, Pi, Deep Agents                             │\n├─────────────────────────────────────────────────────────────┤\n│ Layer 1: Protocol Standard (MCP)                            │\n│ - Model Context Protocol tool servers & unified resources   │\n└─────────────────────────────────────────────────────────────┘\n```\n\n1. **Verify Protocol Decoupling (Layer 1 - MCP)**:\n   - Ensure tool integrations use declarative MCP server configurations rather than hardcoded client branches.\n2. **Enforce Harness-Orchestration Boundary (Layer 2 vs Layer 3)**:\n   - Do not force a single-agent harness loop to handle complex multi-persona DAG choreography.\n   - Delegate stateful, long-running team workflows to Layer 3 orchestrators (LangGraph, Mastra).\n3. **Attach Layer 4 Observability from Day One**:\n   - Mandate session tracing (Langfuse, LangSmith) to capture per-turn token consumption, model latencies, and tool call payloads.\n   - Eliminate unobservable failures at turn 30+ through detailed execution traces.\n\n> **Completion criterion**: 4-layer boundaries verified; tools integrated via MCP; observability hooks wired.\n\n---\n\n## 5. Load-Bearing Safety Invariants & Hard Budget Enforcement\n\nEnforce production runtime safeguards to prevent runaway execution, financial exhaustion, and filesystem corruption:\n\n1. **Jail Path Containment Invariant**:\n   - Tool execution paths must be pinned to explicit sandbox roots. Reject shell execution without verified directory confinement.\n2. **Triple Budget Boundaries**:\n   - *Turn Ceiling*: Configure non-optional `max_turns` (e.g. 15–30 turns) to prevent infinite ReAct loops.\n   - *Financial \u002F Token Budget*: Declare strict per-session token limits or USD expenditure ceilings.\n   - *Wall-Clock Subprocess Timeout*: Enforce synchronous process execution timeouts (\u003C= 120s) on all child bash commands.\n3. **Defensive Error Recovery**:\n   - Wrap tool dispatchers in defensive exception handlers. Capture exit codes, stdout, and stderr.\n   - Provide informative diagnostic error messages to the model instead of crashing or returning empty payloads.\n\n> **Completion criterion**: Hard turn limits, financial budgets, sandbox containment, and defensive error handlers actively enforced.\n\n---\n\n## The Visual Brief Specification\n\nBefore finalizing architectural recommendations or deploying new agent harnesses into production, the architect must generate an interactive HTML Visual Brief:\n\n1. **Target Location**: Write the brief to `%TEMP%\\agent-harness-\u003Ctimestamp>.html` (or platform equivalent).\n2. **Visual Brief Content**:\n   - Dark theme (`#0d1117`) loading Tailwind CSS and Mermaid.js via CDN.\n   - Render the **5-Stage Execution & Selection DAG** illustrating the decision flow across the 4 architectural bets.\n   - Embed the **Diagnostic Reliability Scorecard Table** detailing Level 0 to Level 2 criteria.\n   - Display the **Anti-Pattern Defense Matrix** with concrete mitigation rules.\n3. **Delivery**: Present the clickable file URI to the user for visual inspection.\n\n> **Completion criterion**: Visual brief generated in `%TEMP%`, verified non-empty, and presented as an active clickable link.\n\n---\n\n## Mandatory Checkpoint Gate\n\nTo prevent unreviewed harness migrations, insecure sandbox deployments, or runaway token loops:\n\n1. **Checkpoint Artifact**: Author an `implementation_plan.md` artifact detailing:\n   - Evaluated harness candidates and recommended architectural bet.\n   - Sandbox security boundary specification and path jail configuration.\n   - Hard budget bounds (`max_turns`, token limits, cost caps).\n   - Tracing and observability backend configuration.\n2. **Review Signal**: Set `RequestFeedback: true` in artifact metadata.\n3. **Execution Gate**: **STOP and wait** for explicit human confirmation before deploying new harnesses or executing mutating commands.\n\n> **Completion criterion**: Explicit human confirmation received at the Mandatory Checkpoint gate.\n\n## Micro-Kernel IoC Integration & Headless CLI Dispatch\n\nPer **AGENTS.md Rule 49**, `agent-harness-architect` is elevated from a passive prompt into an authoritative, slotted in-memory domain engine and typed IoC service:\n\n1. **Micro-Kernel IoC Resolution**:\n   ```python\n   from harness.services.agent_harness import AGENT_HARNESS_ARCHITECT_SERVICE_KEY\n\n   service = context.require(AGENT_HARNESS_ARCHITECT_SERVICE_KEY)\n   report = service.audit(target_path=\".\")\n   gate = service.evaluate_reliability()\n   bet = service.classify_bet(bottleneck=\"vendor lock-in\")\n   brief_path = service.visual_brief(target_path=\".\")\n   ```\n2. **Headless Click CLI Commands**:\n   - `harness architect audit [--target \u003Cdir>] [--json]` — 5-part architecture & 4-layer stack audit.\n   - `harness architect score [--config \u003Cpath>] [--json]` — 4-mechanism reliability scorecard (L0–L2).\n   - `harness architect bet [--bottleneck \u003Ctext>]` — Match operational bottleneck to 2026 harness bet.\n   - `harness architect brief [--target \u003Cdir>] [--output \u003Cpath>]` — Interactive HTML review report.\n3. **Domain Engine & Plugin**:\n   - Slotted domain engine: `scripts\u002Fagent_harness_architect.py` (`AgentHarnessArchitectEngine`)\n   - Domain plugin: `plugins\u002Fagent_orchestration\u002Fagent_harness_architect\u002F` (`plugin = AgentHarnessArchitectPlugin()`)\n\n---\n\n## Anti-Patterns\n\n- **The Toy Loop Trap** — Deploying a bare 60-line loop using unconstrained subprocess execution without directory confinement, permission gating, or execution limits.\n- **Unbounded Token Bleed** — Omitting max_turns or cost caps, allowing an autonomous agent to loop indefinitely and burn API budgets.\n- **Silent Tool Error Death Spiral** — Failing to catch tool execution errors or malformed payloads, looping the model back into identical failing states.\n- **Context Flooding Amnesia** — Inlining massive raw tool observations into conversation history without progressive compression or pointer offloading.\n- **Premature Action Drift** — Allowing an agent to mutate code or infrastructure files before formulating and locking a structured execution plan.\n- **Cross-Session Amnesia** — Forcing an agent to re-solve recurring procedural tasks from scratch on every run instead of indexing reusable skills.\n- **Stack Layer Smearing** — Conflating single-agent runtime harness execution with multi-agent orchestration graphs or protocol connectivity.\n",{"name":5,"description":7},"main","eff3b00e36d1d233ad4a4389605c82fbfa0326d3",".agents\u002Fskills\u002Fagent-harness-architect","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness","https:\u002F\u002Fgithub.com\u002FSpectreDeath","I'm here to manage stress so I wouldn't expect earth shattering break throughs I'm just an enthusiast that likes making stuff. ","2026-11-15 05:32:58",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add SpectreDeath\u002FBrain-Harness --skill agent-harness-architect",{"tool":37,"command":38},"bunx","bunx skills add SpectreDeath\u002FBrain-Harness --skill agent-harness-architect",{"tool":40,"command":41},"pnpm","pnpm dlx skills add SpectreDeath\u002FBrain-Harness --skill agent-harness-architect","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fagent-harness-architect\u002FSKILL.md",true,[45,51,55],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"CARD.md","REFERENCE","参考文档",4707,"https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fagent-harness-architect\u002FCARD.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"config.default.yaml",462,"https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fagent-harness-architect\u002Fconfig.default.yaml",{"path":56,"resourceType":57,"resourceTypeDesc":58,"sizeBytes":59,"sourceHtmlUrl":60},"scripts\u002Fagent_harness_architect.py","SCRIPT","脚本",35273,"https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fagent-harness-architect\u002Fscripts\u002Fagent_harness_architect.py",[62,69,76,83,90,97],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7E0W6FR68J2N9CXCZTAQJFX","ui-behavior-primitive-architect","Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA\u002FSSR\u002FRTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fui-behavior-primitive-architect\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7E0VZ7JQNW34G271DENFGYP","trustgraph-ontology-governor","Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Ftrustgraph-ontology-governor\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7E0VQ6Z7R45Q8QAZ4MT39EK","shim-harness-governor","Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fshim-harness-governor\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7E0VC18NMP1QBSRJ3TPQ7MB","graphiti-zep-memory-governor","Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash\u002FLSH entity dedup, RRF\u002FMMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fgraphiti-zep-memory-governor\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M7E0V12ABE1RW3ZRCST8VH5Z","agora-mcp-workbench-architect","Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway\u002Fdispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fagora-mcp-workbench-architect\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":19},"01M7BFYG6QT3484VC57TZ19V7P","skill-eval-assurance-runner","Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fskill-eval-assurance-runner\u002FSKILL.md",[],[]]