3.4 KiB
3.4 KiB
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
- Document Claw Code architecture analysis
- 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"