timmy-home/epics/EPIC-202-claw-agent.md

# EPIC-202: Build Claw-Architecture Agent

**Status:** In Progress  
**Priority:** P0  
**Milestone:** M1: Core Architecture  
**Created:** 2026-03-31  
**Author:** Allegro  

---

## Objective

Create a NEW autonomous agent using architectural patterns from [Claw Code](http://143.198.27.163:3000/Timmy/claw-code), integrated with Gitea for real work dispatch.

## Problem Statement

**Allegro-Primus is IDLE.**
- Gateway running (PID 367883) but zero meaningful output
- No Gitea issues created
- No PRs submitted
- No actual work completed

This agent will **replace** Allegro-Primus with real capabilities.

---

## Claw Patterns to Adopt

### 1. ToolPermissionContext
```python
@dataclass
class ToolPermissionContext:
    deny_tools: set[str]
    deny_prefixes: tuple[str, ...]
    
    def blocks(self, tool_name: str) -> bool:
        return tool_name in self.deny_tools or \
               any(tool_name.startswith(p) for p in self.deny_prefixes)
```

**Why:** Fine-grained tool access control vs Hermes basic approval

### 2. ExecutionRegistry
```python
class ExecutionRegistry:
    def command(self, name: str) -> CommandHandler
    def tool(self, name: str) -> ToolHandler
    def execute(self, context: PermissionContext) -> Result
```

**Why:** Clean routing vs Hermes model-decided routing

### 3. Session Persistence
```python
@dataclass
class RuntimeSession:
    prompt: str
    context: PortContext
    history: HistoryLog
    persisted_path: str
```

**Why:** JSON-based sessions vs SQLite - more portable, inspectable

### 4. Bootstrap Graph
```python
def build_bootstrap_graph() -> Graph:
    # Setup phases
    # Context building  
    # System init messages
```

**Why:** Structured initialization vs ad-hoc setup

---

## Implementation Plan

### Phase 1: Core Architecture (2 days)
- [ ] Create new Hermes profile: `claw-agent`
- [ ] Implement ToolPermissionContext
- [ ] Create ExecutionRegistry
- [ ] Build Session persistence layer

### Phase 2: Gitea Integration (2 days)
- [ ] Gitea client with issue querying
- [ ] Work scheduler for autonomous cycles
- [ ] PR creation and review assistance

### Phase 3: Deployment (1 day)
- [ ] Telegram bot integration
- [ ] Cron scheduling
- [ ] Health monitoring

---

## Success Criteria

| Criteria | How We'll Verify |
|----------|-----------------|
| Receives Telegram tasks | Send test message, agent responds |
| Queries Gitea issues | Agent lists open P0 issues |
| Permission checks work | Blocked tool returns error |
| Session persistence | Restart agent, history intact |
| Progress reports | Agent sends Telegram updates |

---

## Resource Requirements

| Resource | Status |
|----------|--------|
| Gitea API token | ✅ Have |
| Kimi API key | ✅ Have |
| Telegram bot | ⏳ Need @BotFather |
| New profile | ⏳ Will create |

---

## References

- [Claw Code Mirror](http://143.198.27.163:3000/Timmy/claw-code)
- [Claw Issue #1 - Architecture](http://143.198.27.163:3000/Timmy/claw-code/issues/1)
- [Hermes v0.6 Profiles](../docs/profiles.md)

---

## Tickets

- #203: Implement ToolPermissionContext
- #204: Create ExecutionRegistry
- #205: Build Session Persistence
- #206: Gitea Integration
- #207: Telegram Deployment

---

*This epic supersedes Allegro-Primus who has been idle.*