115 lines
3.4 KiB
Markdown
115 lines
3.4 KiB
Markdown
# 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"*
|