CHORUS/HAP_ACTION_PLAN.md

# CHORUS Human Agent Portal (HAP) — Implementation Action Plan

**Goal:**  
Transform the existing CHORUS autonomous agent system into a dual-binary architecture supporting both autonomous agents and human agent portals using shared P2P infrastructure.

---

## 🔍 Current State Analysis

### ✅ What We Have
CHORUS currently implements a **comprehensive P2P autonomous agent system** with:

- **P2P Infrastructure**: libp2p mesh with mDNS discovery
- **Agent Identity**: Crypto-based agent records (`pkg/agentid/`)
- **Messaging**: HMMM collaborative reasoning integration
- **Storage**: DHT with role-based Age encryption
- **Addressing**: UCXL context resolution system (`pkg/ucxl/`)
- **Coordination**: SLURP task distribution (`pkg/slurp/`)
- **Configuration**: Role-based agent definitions
- **Web Interface**: Setup and configuration UI

### ⚠️ What's Missing
- **Multi-binary architecture** (currently single `main.go`)
- **Human interface layer** for message composition and interaction
- **HAP-specific workflows** (templated forms, prompts, context browsing)

---

## 📋 Implementation Phases

### Phase 1: Structural Reorganization (HIGH PRIORITY)
**Goal**: Split monolithic binary into shared runtime + dual binaries

#### Tasks:
- [ ] **1.1** Create `cmd/agent/main.go` (move existing `main.go`)
- [ ] **1.2** Create `cmd/hap/main.go` (new human portal entry point)
- [ ] **1.3** Extract shared initialization to `internal/common/runtime/`
- [ ] **1.4** Update `Makefile` to build both `CHORUS-agent` and `CHORUS-hap` binaries
- [ ] **1.5** Test autonomous agent functionality remains identical

**Key Changes:**
```
/cmd/
  /agent/main.go     # Existing autonomous agent logic
  /hap/main.go       # New human agent portal
/internal/common/
  /runtime/          # Shared P2P, config, services initialization
    agent.go
    config.go
    services.go
```

**Success Criteria:**
- Both binaries compile successfully
- `CHORUS-agent` maintains all current functionality
- `CHORUS-hap` can join P2P mesh as peer

### Phase 2: HAP Interface Implementation (MEDIUM PRIORITY)
**Goal**: Create human-friendly interaction layer

#### Tasks:
- [ ] **2.1** Implement basic terminal interface in `internal/hapui/terminal.go`
- [ ] **2.2** Create message composition templates for HMMM messages
- [ ] **2.3** Add context browsing interface for UCXL addresses
- [ ] **2.4** Implement justification prompts and metadata helpers
- [ ] **2.5** Test human agent can send/receive HMMM messages

**Key Components:**
```
/internal/hapui/
  forms.go          # Templated message composition
  terminal.go       # Terminal-based human interface
  context.go        # UCXL context browsing helpers
  prompts.go        # Justification and metadata prompts
```

**Success Criteria:**
- Human can compose and send HMMM messages via terminal
- Context browsing works for UCXL addresses
- HAP appears as valid agent to autonomous peers

### Phase 3: Enhanced Human Workflows (MEDIUM PRIORITY)  
**Goal**: Add sophisticated human agent features

#### Tasks:
- [ ] **3.1** Implement patch creation and submission workflows
- [ ] **3.2** Add time-travel diff support (`~~`, `^^` operators)
- [ ] **3.3** Create collaborative editing interfaces
- [ ] **3.4** Add decision tracking and approval workflows
- [ ] **3.5** Implement web bridge for browser-based HAP interface

**Advanced Features:**
- Patch preview before submission to DHT
- Approval chains for architectural decisions
- Real-time collaboration on UCXL contexts
- WebSocket bridge to web UI for rich interface

**Success Criteria:**
- Humans can create and submit patches via HAP
- Approval workflows integrate with existing SLURP coordination
- Web interface provides richer interaction than terminal

### Phase 4: Integration & Optimization (LOW PRIORITY)
**Goal**: Polish and optimize the dual-agent system

#### Tasks:
- [ ] **4.1** Enhance `AgentID` structure to match HAP plan specification
- [ ] **4.2** Optimize resource usage for dual-binary deployment
- [ ] **4.3** Add comprehensive testing for human/machine agent interactions
- [ ] **4.4** Document HAP usage patterns and workflows
- [ ] **4.5** Create deployment guides for mixed agent teams

**Refinements:**
- Performance optimization for shared P2P layer
- Memory usage optimization when running both binaries
- Enhanced logging and monitoring for human activities
- Integration with existing health monitoring system

---

## 🧱 Architecture Alignment

### Current vs Planned Structure

| Component | Current Status | HAP Plan Status | Action Required |
|-----------|----------------|-----------------|-----------------|
| **Multi-binary** | ❌ Single `main.go` | Required | **Phase 1** restructure |
| **Agent Identity** | ✅ `pkg/agentid/` | ✅ Compatible | Minor enhancement |
| **HMMM Messages** | ✅ Integrated | ✅ Complete | None |
| **UCXL Context** | ✅ Full implementation | ✅ Complete | None |
| **DHT Storage** | ✅ Encrypted, distributed | ✅ Complete | None |
| **PubSub Comms** | ✅ Role-based topics | ✅ Complete | None |
| **HAP Interface** | ❌ Not implemented | Required | **Phase 2-3** |

### Shared Runtime Components
Both `chorus-agent` and `chorus-hap` will share:

- **P2P networking** and peer discovery
- **Agent identity** and cryptographic signing
- **HMMM message** validation and routing
- **UCXL address** resolution and context storage
- **DHT operations** for distributed state
- **Configuration system** and role definitions

**Only the execution loop and UI modality differ between binaries.**

---

## 🔧 Implementation Strategy

### Incremental Migration Approach
1. **Preserve existing functionality** - autonomous agents continue working
2. **Add HAP alongside** existing system rather than replacing
3. **Test continuously** - both binaries must interoperate correctly
4. **Gradual enhancement** - start with basic HAP, add features incrementally

### Key Principles
- **Backward compatibility**: Existing CHORUS deployments unaffected
- **Shared protocols**: Human and machine agents are indistinguishable on P2P mesh
- **Common codebase**: Maximum code reuse between binaries
- **Incremental delivery**: Each phase delivers working functionality

### Risk Mitigation
- **Comprehensive testing** after each phase
- **Feature flags** to enable/disable HAP features during development
- **Rollback capability** to single binary if needed
- **Documentation** of breaking changes and migration steps

---

## 📈 Success Metrics

### Phase 1 Success
- [ ] `make build` produces both `chorus-agent` and `chorus-hap` binaries
- [ ] Existing autonomous agent functionality unchanged
- [ ] Both binaries can join same P2P mesh

### Phase 2 Success  
- [ ] Human can send HMMM messages via HAP terminal interface
- [ ] HAP appears as valid agent to autonomous peers
- [ ] Message composition templates functional

### Phase 3 Success
- [ ] Patch submission workflows complete
- [ ] Web interface provides rich HAP experience
- [ ] Human/machine agent collaboration demonstrated

### Overall Success
- [ ] Mixed teams of human and autonomous agents collaborate seamlessly
- [ ] HAP provides superior human experience compared to direct protocol interaction
- [ ] System maintains all existing performance and reliability characteristics

---

## 🎯 Next Steps

### Immediate Actions (This Sprint)
1. **Create cmd/ structure** and move main.go to cmd/agent/
2. **Stub cmd/hap/main.go** with basic P2P initialization
3. **Extract common runtime** to internal/common/
4. **Update Makefile** for dual binary builds
5. **Test agent binary** maintains existing functionality

### Short Term (Next 2-4 weeks)
1. **Implement basic HAP terminal interface**
2. **Add HMMM message composition**
3. **Test human agent P2P participation**
4. **Document HAP usage patterns**

### Medium Term (1-2 months)
1. **Add web bridge for browser interface**  
2. **Implement patch workflows**
3. **Add collaborative features**
4. **Optimize performance**

---

## 📚 Resources & References

- **Original HAP Plan**: `archive/chorus_hap_dev_plan.md`
- **Current Architecture**: `pkg/` directory structure
- **P2P Infrastructure**: `p2p/`, `pubsub/`, `pkg/dht/`
- **Agent Identity**: `pkg/agentid/`, `pkg/crypto/`
- **Messaging**: `pkg/hmmm_adapter/`, HMMM integration
- **Context System**: `pkg/ucxl/`, `pkg/ucxi/`
- **Configuration**: `pkg/config/`, role definitions

The current CHORUS implementation provides an excellent foundation for the HAP vision. The primary challenge is architectural restructuring rather than building new functionality from scratch.