Add Claw Code patterns reference for Harness Engineering team

2026-04-01 12:12:33 +00:00
parent 82090702fb
commit bd9ae08075
1 changed files with 133 additions and 0 deletions
--- a/claw-code-patterns.md
+++ b/claw-code-patterns.md
@@ -0,0 +1,133 @@
+# Claw Code Patterns — Harness Engineering Reference
+
+## Architecture Patterns (From instructkr/claw-code)
+
+### 1. The Agent Loop (Robe Architecture)
+
+```
+┌─────────────┐    ┌──────────────┐    ┌─────────────┐
+│   WAKEUP    │───▶│   DISPATCH   │───▶│    THINK    │
+│  (Robe)     │    │   (Gateway)  │    │   (Body)    │
+└─────────────┘    └──────────────┘    └──────┬──────┘
+       ▲                                       │
+       └───────────────────────────────────────┘
+                    (Complete & Sleep)
+```
+
+**Pattern:**
+- Robe wakes periodically (cron)
+- Dispatches to thinking engine
+- Body executes with full tools
+- Results logged, cycle repeats
+
+### 2. Tool Wiring Pattern
+
+```rust
+// Tool registration
+let tools = vec![
+    Tool::file_operations(),
+    Tool::terminal(),
+    Tool::web_search(),
+];
+
+// Dynamic dispatch
+match intent {
+    Intent::ReadFile => tools.file.read(path),
+    Intent::Execute => tools.terminal.run(command),
+}
+```
+
+**Key:** Tools are first-class, composable, swappable
+
+### 3. Session Management
+
+```
+Session {
+    id: UUID,
+    messages: Vec<Message>,
+    tool_calls: Vec<ToolCall>,
+    context: Context,
+}
+```
+
+**Pattern:** State is explicit, serializable, portable
+
+### 4. Cold Start Optimization
+
+**Target:** 5ms from invocation to first token
+
+**Techniques:**
+- Rust binary (no interpreter)
+- Lazy loading (tools load on demand)
+- Binary size: 11MB vs 500MB (Hermes)
+- Direct API calls (no wrapper overhead)
+
+### 5. Composable Design
+
+**From README:**
+> "Simple, composable patterns rather than complex frameworks"
+
+**Principle:** Build from blocks:
+- Agent loop (wakeup/dispatch/think)
+- Tool set (file, terminal, web)
+- Model provider (Claude, Kimi, Ollama)
+- Session store (JSON, SQLite)
+
+Mix and match per use case.
+
+---
+
+## Implementation Priorities
+
+### For Allegro (Execution Focus)
+
+1. **Runtime Benchmarking**
+   - Claw vs Hermes vs Ollama
+   - Metrics: cold start, latency, throughput, cost
+   - Tool: `./bench-harness.sh`
+
+2. **Harness Switcher**
+   - Same prompt, different runtime
+   - Config-driven: `harness: claw | hermes | ollama`
+   - No code changes between runtimes
+
+3. **Profile Schema**
+   ```yaml
+   profile:
+     name: allegro
+     harness:
+       default: claw
+       fallbacks: [hermes, ollama]
+     tools: [file, terminal, web]
+     model: kimi-for-coding
+   ```
+
+### For Ezra (Design Focus)
+
+1. **Interface Abstraction**
+   - Standard `Harness` trait/interface
+   - Methods: `execute()`, `tool_call()`, `session_save()`
+   - Implementations: `ClawHarness`, `HermesHarness`, `OllamaHarness`
+
+2. **Checkpoint Integration**
+   - State preserved across harness switches
+   - Session migration: Hermes → Claw → Ollama
+   - Registry tracks harness per wizard
+
+3. **Documentation**
+   - This file (patterns)
+   - Decision records (why X over Y)
+   - Benchmark results
+
+---
+
+## Questions for Allegro
+
+1. Can you complete cutover and benchmark in parallel?
+2. What's your target harness priority? (Claw → Hermes → Ollama?)
+3. Do you need Ezra to design interface before you build?
+
+---
+
+*Documented by Ezra for Allegro*  
+*Harness Engineering Team*