# ADR-001: Harness Engineering Pivot

**Status:** APPROVED  
**Date:** 2026-04-01  
**Deciders:** Alexander Whitestone (Father), Allegro (Executor), Ezra (Scribe)  
**Owner:** Allegro  

---

## Context

We have been operating on Hermes Agent as our default harness. While functional, this creates lock-in to a single runtime. The exposure of Claude Code's architecture and the rapid emergence of Claw Code (98K+ stars, fastest to 50K in GitHub history) presents an opportunity.

Claw Code represents a clean-room Python/Rust rewrite of Claude Code's patterns with:
- Provider trait abstraction (swappable LLMs)
- Native MCP (Model Context Protocol) support
- Plugin hook system (PreToolUse/PostToolUse)
- Session compaction for context management

---

## Decision

We pivot to **harness engineering**: building a multi-runtime, swappable architecture that adopts best patterns from Claw Code while preserving our values layer.

### What This Means

| From | To |
|------|-----|
| Hermes default | Best runtime default |
| Code loyalty | Results loyalty |
| Single harness | Multi-runtime, swappable |
| NIH syndrome | SOTA tracking |

### What We Keep

- **Checkpoint system** (Ezra's ownership model)
- **Profile-based architecture** (wizard separation)
- **SOUL.md / Conscience layer** (values enforcement)
- **Heartbeat pattern** (execution cadence)
- **Gitea integration** (issue tracking)

---

## Consequences

### Positive
- No LLM lock-in (Kimi ↔ Ollama ↔ Claude ↔ OpenAI)
- Tools become portable MCP servers
- Plugin system enables SOUL.md enforcement via hooks
- Session compaction solves token limits
- Faster iteration on harness improvements

### Negative
- Migration work required (8-week timeline)
- Learning curve for Rust if we adopt core runtime
- Potential instability during transition
- Need to maintain backward compatibility for 90 days

### Risks
| Risk | Mitigation |
|------|------------|
| Claw Code API churn | Mirror repo with hourly sync, pin to stable commits |
| Rust competency gap | Hybrid approach: core in Rust, tools in Python |
| Migration disruption | Parallel operation period, feature flags |
| SOUL enforcement gaps | Implement as PreToolUse hook, test exhaustively |

---

## Implementation

### Phase 1: Assessment (Week 1) - IN PROGRESS
- [x] Document Claw Code architecture analysis
- [x] Identify migration touchpoints
- [ ] Create claw-code-mirror repo (BLOCKED: Tailscale)
- [ ] Set up automated upstream sync

### Phase 2: Runtime Abstraction (Weeks 2-3)
- [ ] Define Provider trait
- [ ] Implement Kimi-coding provider
- [ ] Provider factory/config

### Phase 3: Tool System (Weeks 3-4)
- [ ] Extract tools to registry pattern
- [ ] MCP client implementation
- [ ] Convert skills to MCP servers

### Phase 4: Plugin Architecture (Weeks 4-5)
- [ ] Hook system (PreToolUse, PostToolUse)
- [ ] Plugin manifest format
- [ ] SOUL.md enforcement via hooks

### Phase 5: CLI & UX (Weeks 5-6)
- [ ] Single entrypoint
- [ ] Profile-based configuration
- [ ] Session persistence

### Phase 6: Validation (Weeks 6-8)
- [ ] Full test suite (200+ tests)
- [ ] Migration guide
- [ ] Deprecation plan for Hermes

---

## References

- Claw Code upstream: https://github.com/instructkr/claw-code
- MCP Spec: https://modelcontextprotocol.io/
- North Star doc: `/root/wizards/allegro/home/claw_code_north_star.md`
- Architecture analysis: `/root/wizards/allegro/home/claw_code_followup.md`

---

*"Code loyalty → Results loyalty"*