WHOOSH/README.md

# WHOOSH - Autonomous AI Development Teams

**Orchestration platform for self-organizing AI development teams with democratic consensus and P2P collaboration.**

## 🎯 Overview

WHOOSH has evolved from a simple project template tool into a sophisticated **Autonomous AI Development Teams Architecture** that enables AI agents to form optimal development teams, collaborate through P2P channels, and deliver high-quality solutions through democratic consensus processes.

## 🏗️ Architecture

### Core Components

- **🧠 Team Composer**: LLM-powered task analysis and optimal team formation
- **🤖 Agent Self-Organization**: CHORUS agents autonomously discover and apply to teams
- **🔗 P2P Collaboration**: UCXL addressing with structured reasoning (HMMM) 
- **🗳️ Democratic Consensus**: Voting systems with quality gates and institutional compliance
- **📦 Knowledge Preservation**: Complete context capture for SLURP with provenance tracking

### Integration Ecosystem

```
WHOOSH Team Composer → GITEA Team Issues → CHORUS Agent Discovery → P2P Team Channels → SLURP Artifact Submission
```

## 📋 Development Status

**Current Phase**: Foundation & Planning
- ✅ Comprehensive architecture specifications
- ✅ Database schema design 
- ✅ API specification
- ✅ Team Composer design
- ✅ CHORUS integration specification
- 🚧 Implementation in progress

## 🚀 Quick Start

### Prerequisites

- Python 3.11+
- PostgreSQL 15+
- Redis 7+
- Docker & Docker Compose
- Access to Ollama models or cloud LLM APIs

### Development Setup

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

# Setup Python environment
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

# Setup database
docker-compose up -d postgres redis
python scripts/setup_database.py

# Run development server
python -m whoosh.main
```

## 📚 Documentation

### Architecture & Design
- [📋 Development Plan](docs/DEVELOPMENT_PLAN.md) - Complete 24-week roadmap
- [🗄️ Database Schema](docs/DATABASE_SCHEMA.md) - Comprehensive data architecture
- [🌐 API Specification](docs/API_SPECIFICATION.md) - Complete REST & WebSocket APIs

### Core Systems
- [🧠 Team Composer](docs/TEAM_COMPOSER_SPEC.md) - LLM-powered team formation engine
- [🤖 CHORUS Integration](docs/CHORUS_INTEGRATION_SPEC.md) - Agent self-organization & P2P collaboration
- [📖 Original Vision](docs/Modules/WHOOSH.md) - Autonomous AI development teams concept

## 🔧 Key Features

### Team Formation
- **Intelligent Analysis**: LLM-powered task complexity and skill requirement analysis
- **Optimal Composition**: Dynamic team sizing with role-based agent matching
- **Risk Assessment**: Comprehensive project risk evaluation and mitigation
- **Timeline Planning**: Automated formation scheduling with contingencies

### Agent Coordination  
- **Self-Assessment**: Agents evaluate their own capabilities and availability
- **Opportunity Discovery**: Automated scanning of team formation opportunities
- **Autonomous Applications**: Intelligent team application with value propositions
- **Performance Tracking**: Continuous learning from team outcomes

### Collaboration Systems
- **P2P Channels**: UCXL-addressed team communication channels
- **HMMM Reasoning**: Structured thought processes with evidence and consensus
- **Democratic Voting**: Multiple consensus mechanisms (majority, supermajority, unanimous)
- **Quality Gates**: Institutional compliance with provenance and security validation

### Knowledge Management
- **Context Preservation**: Complete capture of team processes and decisions
- **SLURP Integration**: Automated artifact bundling and submission
- **Decision Rationale**: Comprehensive reasoning chains and consensus records
- **Learning Loop**: Continuous improvement from team performance feedback

## 🛠️ Technology Stack

### Backend
- **Language**: Python 3.11+ with FastAPI
- **Database**: PostgreSQL 15+ with async support
- **Cache**: Redis 7+ for sessions and real-time data
- **LLM Integration**: Ollama + Cloud APIs (OpenAI, Anthropic)
- **P2P**: libp2p for peer-to-peer networking

### Frontend
- **Framework**: React 18 with TypeScript
- **State**: Zustand for complex state management
- **UI**: Tailwind CSS with Headless UI components
- **Real-time**: WebSocket with auto-reconnect
- **Charts**: D3.js for advanced visualizations

### Infrastructure
- **Containers**: Docker with multi-stage builds
- **Orchestration**: Docker Swarm (cluster deployment)
- **Proxy**: Traefik with SSL termination
- **Monitoring**: Prometheus + Grafana
- **CI/CD**: GITEA Actions with automated testing

## 🎯 Roadmap

### Phase 1: Foundation (Weeks 1-4)
- Core infrastructure and Team Composer service
- Database schema implementation
- Basic API endpoints and WebSocket infrastructure

### Phase 2: CHORUS Integration (Weeks 5-8)
- Agent self-organization capabilities
- GITEA team issue integration
- P2P communication infrastructure

### Phase 3: Collaboration Systems (Weeks 9-12)
- Democratic consensus mechanisms
- HMMM reasoning integration
- Team lifecycle management

### Phase 4: SLURP Integration (Weeks 13-16)
- Artifact packaging and submission
- Knowledge preservation systems
- Quality validation pipelines

### Phase 5: Frontend & UX (Weeks 17-20)
- Complete user interface
- Real-time dashboards
- Administrative controls

### Phase 6: Advanced Features (Weeks 21-24)
- Machine learning optimization
- Cloud LLM integration
- Advanced analytics and reporting

## 🤝 Contributing

1. Fork the repository on GITEA
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is part of the CHORUS ecosystem and follows the same licensing terms.

## 🔗 Related Projects

- **[CHORUS](https://gitea.chorus.services/tony/CHORUS)** - Distributed AI agent coordination
- **[KACHING](https://gitea.chorus.services/tony/KACHING)** - License management and billing
- **[SLURP](https://gitea.chorus.services/tony/SLURP)** - Knowledge artifact management
- **[BZZZ](https://gitea.chorus.services/tony/BZZZ)** - Original task coordination (legacy)

---

**WHOOSH** - *Where AI agents become autonomous development teams* 🚀