Skill: christianye/obsidian-harness (version 1.0.1)

--- name: agent-harness description: "Production-grade Agent Harness combining execution discipline (Superpower), knowledge compounding (CE), and product thinking (Gstack) 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 development tasks, (4) need structured engineering workflow with quality gates. Provides: task complexity auto-grading (simple/medium/complex), anti-rationalization guards, concurrent subagent scheduling, verification protocols, experience compounding, and product-level requirement validation." --- # 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": | 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 | ### 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: | 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 is complete" | You won't. Test debt only grows. | Write the test NOW, before moving on. | | "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 this while I'm here" | Scope creep. You weren't asked to refactor. | Do only what was requested. File a separate TODO for the refactor. | | "I'll handle errors later" | Error handling IS the feature in production | Handle errors now. Happy path without error handling is a prototype. | | "The context is too long, I'll summarize and skip details" | Skipping details = skipping correctness | Checkpoint to file, compact context, continue with full fidelity. | ## 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](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](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 ```

path: references/checkpoint-patterns.md
content: # Checkpoint Patterns for Agent Systems

## Why Checkpoint?

Agent tasks can fail mid-execution (idle timeout, API throttling, OOM). Without checkpoints, all progress is lost.

## Three Strategies

### 1. File-Level Checkpoint (Simplest, Recommended)

Write output to file after each subtask completes.

```
Task: Write 5 chapters
→ Complete Ch1 → write ch1.md ✅ (checkpoint 1)
→ Complete Ch2 → write ch2.md ✅ (checkpoint 2)
→ Ch3 crashes → Restart: Ch1, Ch2 exist, only redo Ch3
```

Best for: Subagent orchestration. Each subagent writes to its own file. If one fails, only re-dispatch that one.

### 2. State Machine Checkpoint (Medium Complexity)

Model the task as a state machine. Persist state on each transition.

```json
{
  "taskId": "rebuild-v8",
  "currentStep": 9,
  "totalSteps": 14,
  "completedFiles": ["ch1.md", ..., "ch8.md"],
  "lastCheckpoint": "2026-04-08T15:30:00Z"
}
```

Recovery: Read state file, skip completed steps.

Best for: Sequential multi-step pipelines where order matters.

### 3. Event Sourcing (Most Powerful, Most Complex)

Store all state-change events instead of current state. Recovery = replay events.

Best for: Critical business workflows where you need full auditability and replay capability.

## Practical Rules

1. **Write to file after each step** — Don't accumulate in context memory
2. **Design idempotent tasks** — Re-running a step = same result (write to same file = overwrite = safe)
3. **Only retry the failed step** — Not the whole pipeline
4. **Observable progress** — `ls` shows what's done; don't rely on model's "memory"

## Why Not Just Use Context?

Three ways context fails as a checkpoint:
1. **Idle timeout** — Session killed, context gone
2. **Compaction** — Mid-task details may be summarized away
3. **Hallucination** — Model "remembers" doing step 5, but the file was never written

**File system is the only reliable persistence layer.** `ls` doesn't lie.


path: references/mast-failure-taxonomy.md
content: # MAST Failure Taxonomy for Multi-Agent Systems

Classify failures into three categories to determine the correct fix:

## Three Failure Types

| Type | Share | Symptoms | Fix Direction |
|---|---|---|---|
| **Design** | ~40% | Wrong task decomposition, unclear agent boundaries, bad tool selection | Redesign architecture and task splitting |
| **Alignment** | ~35% | Agent understood the task but drifted, wrong output format, creatively bypassed constraints | Improve prompts, add constraints, refine acceptance criteria |
| **Verification** | ~25% | Output looks correct but isn't, missing quality checks, errors amplified downstream | Add Verification Agent, set quality gates |

## Diagnostic Five-Question Protocol

When a multi-agent task fails:

1. **What did the agent believe was happening?** (task understanding) → Alignment issue
2. **What tools were called, in what order?** (execution path) → Design issue
3. **What signal was missing?** (information gap) → Design issue
4. **Which guardrail should have caught this?** (missing protection) → Verification issue
5. **How can we detect this faster next time?** (observability) → All types

## Key Insight

65% of multi-agent failures (Design + Verification) have nothing to do with model capability. Switching to a stronger model won't fix them. Only 35% (Alignment) might benefit from a better model or better prompts.

**Fix the harness first, then consider the model.**


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)