WHOOSH/README.md

# WHOOSH - Autonomous AI Development Teams

WHOOSH is the orchestration platform for autonomous AI development teams in the CHORUS ecosystem. It transforms from a simple project template tool into a sophisticated system that enables AI agents to form optimal teams, collaborate democratically, and deliver high-quality solutions through consensus-driven development processes.

## 🎯 MVP Goals

The current MVP focuses on:

1. **Single-Agent Execution**: Process `bzzz-task` labeled issues with single-agent teams
2. **GITEA Integration**: Webhook handling for task discovery and PR management  
3. **Basic Team Management**: Minimal team state tracking and assignment
4. **SLURP Integration**: Artifact submission and retrieval proxy
5. **Docker Swarm Deployment**: Production-ready containerization

## 🏗️ Architecture

### Core Components

- **Go Backend**: HTTP server with chi/echo framework, structured logging with zerolog
- **PostgreSQL Database**: Team, agent, and task state management with migrations
- **GITEA Integration**: Webhook processing and API client for issue management
- **Docker Swarm**: Production deployment with secrets management
- **Redis**: Optional caching and session management

### MVP Workflow

1. GITEA webhook receives issue with `bzzz-task` label
2. WHOOSH parses task information and creates team assignment
3. Single-agent executor processes task (stubbed Team Composer)
4. Results submitted via SLURP proxy for artifact preservation
5. PR creation and status updates back to GITEA

## 🚀 Quick Start

### Local Development

```bash
# Clone repository
git clone https://gitea.chorus.services/tony/WHOOSH.git
cd WHOOSH

# Copy environment configuration
cp .env.example .env
# Edit .env with your configuration

# Start with Docker Compose
docker-compose up -d

# Or run locally
go run ./cmd/whoosh
```

### Production Deployment

```bash
# Setup Docker Swarm secrets
./scripts/setup-secrets.sh

# Deploy to swarm
./scripts/deploy-swarm.sh v0.1.0-mvp
```

## 📋 API Endpoints

### Health & Status
- `GET /health` - Service health check
- `GET /health/ready` - Readiness check with database connection

### Teams (MVP Minimal)
- `GET /api/v1/teams` - List teams
- `POST /api/v1/teams` - Create team (stub)
- `GET /api/v1/teams/{teamID}` - Get team details (stub)
- `PUT /api/v1/teams/{teamID}/status` - Update team status (stub)

### Task Management
- `POST /api/v1/tasks/ingest` - Task ingestion (stub)
- `GET /api/v1/tasks/{taskID}` - Get task details (stub)

### SLURP Integration
- `POST /api/v1/slurp/submit` - Submit artifacts (stub)
- `GET /api/v1/slurp/artifacts/{ucxlAddr}` - Retrieve artifacts (stub)

### CHORUS Integration
- `GET /api/v1/projects/{projectID}/tasks` - List project tasks
- `GET /api/v1/projects/{projectID}/tasks/available` - List available tasks
- `GET /api/v1/projects/{projectID}/repository` - Get project repository info
- `GET /api/v1/projects/{projectID}/tasks/{taskNumber}` - Get specific task
- `POST /api/v1/projects/{projectID}/tasks/{taskNumber}/claim` - Claim task for agent
- `PUT /api/v1/projects/{projectID}/tasks/{taskNumber}/status` - Update task status
- `POST /api/v1/projects/{projectID}/tasks/{taskNumber}/complete` - Complete task
- `POST /api/v1/agents/register` - Register CHORUS agent
- `PUT /api/v1/agents/{agentID}/status` - Update agent status

### Webhooks
- `POST /webhooks/gitea` - GITEA webhook endpoint (implemented)

## 🗄️ Database Schema

### Core Tables (MVP)

- **teams**: Team management and status tracking
- **team_roles**: Available roles (executor, coordinator, reviewer)
- **team_assignments**: Agent-to-team assignments
- **agents**: Minimal agent registry
- **slurp_submissions**: Artifact tracking

## 🔐 Security Features

- **Docker Swarm Secrets**: Sensitive data management
- **SHHH Integration**: Data redaction and encryption
- **JWT Authentication**: Service and user token validation
- **Webhook Signature Validation**: GITEA webhook authenticity
- **Rate Limiting**: API endpoint protection

## 🛠️ Development Commands

```bash
# Build binary
go build ./cmd/whoosh

# Run tests
go test ./...

# Format code
go fmt ./...

# Static analysis
go vet ./...

# Database migrations
migrate -path migrations -database "postgres://..." up
```

## 📊 Monitoring

### Docker Swarm Services

```bash
# Service status
docker service ls --filter label=com.docker.stack.namespace=whoosh

# Service logs
docker service logs -f whoosh_whoosh

# Scale services
docker service scale whoosh_whoosh=3
```

### Health Endpoints

- Health: `https://whoosh.chorus.services/health`
- Ready: `https://whoosh.chorus.services/health/ready`

## 🔄 Future Roadmap

### Post-MVP Features

1. **Team Composer**: LLM-powered task analysis and team formation
2. **P2P Communication**: UCXL addressing and HMMM integration
3. **Agent Self-Organization**: Automatic team application and consensus
4. **Advanced Analytics**: Performance metrics and team effectiveness
5. **Multi-Repository Support**: Cross-project team coordination

### Integration Points

- **CHORUS Agents**: P2P task coordination and execution
- **BZZZ System**: Distributed task management integration  
- **SHHH Encryption**: Secure data handling and transmission
- **UCXL Addressing**: Decentralized resource identification
- **SLURP Storage**: Comprehensive artifact preservation

## 📚 Documentation

- [Development Plan](docs/DEVELOPMENT_PLAN.md) - Comprehensive transformation roadmap
- [Database Schema](docs/DATABASE_SCHEMA.md) - Complete schema documentation
- [API Specification](docs/API_SPECIFICATION.md) - Full API reference
- [Team Composer Spec](docs/TEAM_COMPOSER_SPEC.md) - LLM integration details

## 🤝 Contributing

WHOOSH follows the CHORUS ecosystem development patterns:

1. Branch from `main` for features
2. Implement with comprehensive tests
3. Update version tags for container builds
4. Deploy to staging for validation
5. Create PR with detailed description

## 📄 License

This project is part of the CHORUS ecosystem. All rights reserved.

---

**WHOOSH** - *Where autonomous AI development teams come together* 🎭