WHOOSH/clarification.md

Current Understanding

Based on your clarifications, I now understand that:

• CHORUS is fully featured: All agent functionality, consensus, elections, HMMM protocol, and output generation already exist
• Role parameterization: CHORUS reads prompts from human-roles.yaml based on role identifier parameter
• P2P Network: HMMM protocol runs on existing P2P network infrastructure
• Output formats: DRs and UCXL are well-defined, council determines specifics per-project
• The gap: WHOOSH deploys containers but doesn't properly wire CHORUS execution with parameters

Revised Implementation Plan

Phase 1: Core Parameter Wiring (MVP - Highest Priority)

1.1 Role Identifier Parameter

• Current Issue: CHORUS containers deploy without role identification
• Solution: Modify internal/orchestrator/agent_deployer.go to pass role parameter
• Implementation:
  • Add CHORUS_ROLE environment variable with role identifier (e.g., "systems-analyst")
  • CHORUS will automatically load corresponding prompt from human-roles.yaml

1.2 Design Brief Content Delivery

• Current Issue: CHORUS agents don't receive the Design Brief issue content
• Solution: Extract and pass Design Brief content as task context
• Implementation:
  • Add CHORUS_TASK_CONTEXT environment variable with issue title, body, labels
  • Include repository metadata and project context

1.3 CHORUS Agent Process Verification

• Current Issue: Containers may deploy but not execute CHORUS properly
• Solution: Verify container entrypoint and command configuration
• Implementation:
  • Ensure CHORUS agent starts with correct parameters
  • Verify container image and execution path

Phase 2: Network & Access Integration (Medium Priority)

2.1 P2P Network Configuration

• Current Issue: Council agents need access to HMMM P2P network
• Solution: Ensure proper network configuration for P2P discovery
• Implementation:
  • Verify agents can connect to existing P2P infrastructure
  • Add necessary network policies and service discovery

2.2 Repository Access

• Current Issue: Agents need repository access for cloning and operations
• Solution: Provide repository credentials and context
• Implementation:
  • Mount Gitea token as secret or environment variable
  • Provide CHORUS_REPO_URL with clone URL
  • Add CHORUS_REPO_NAME for context

Phase 3: Lifecycle Management (Lower Priority)

3.1 Council Completion Detection

• Current Issue: No detection when council completes its work
• Solution: Monitor for council outputs and consensus completion
• Implementation:
  • Watch for new Issues with bzzz-task labels created by council
  • Monitor for Pull Requests with scaffolding
  • Add consensus completion signals from CHORUS

3.2 Container Cleanup

• Current Issue: Council containers persist after completion
• Solution: Automatic cleanup when work is done
• Implementation:
  • Remove containers when completion is detected
  • Clean up associated resources and networks
  • Log completion and transition events

Phase 4: Transition to Dynamic Teams (Future)

4.1 Task Team Formation Trigger

• Current Issue: No automatic handoff from council to task teams
• Solution: Detect council outputs and trigger dynamic team formation
• Implementation:
  • Monitor for new bzzz-task issues created by council
  • Trigger existing WHOOSH dynamic team formation
  • Ensure proper context transfer

Key Implementation Focus

Environment Variables for CHORUS Integration

environment: - CHORUS_ROLE=${role_identifier} # e.g., "systems-analyst"
- CHORUS_TASK_CONTEXT=${design_brief} # Issue title, body, labels - CHORUS_REPO_URL=${repository_clone_url} # For repository access - CHORUS_REPO_NAME=${repository_name} # Project context

Expected Workflow (Clarification Needed)

1. WHOOSH Detection: Detects "Design Brief" issue with chorus-entrypoint + bzzz-task labels
2. Council Deployment: Deploys 8 CHORUS containers with role parameters
3. CHORUS Execution: Each agent loads role prompt, receives Design Brief content
4. Council Operation: Agents use HMMM protocol for communication and consensus
5. Output Generation: Council produces DRs as Issues and scaffolding as PRs
6. Completion & Cleanup: WHOOSH detects completion and removes containers
7. Team Formation: New bzzz-task issues trigger dynamic team formation

Questions for Clarification

1. CHORUS Container Configuration

• Question: What is the exact CHORUS container image and entrypoint?
• Context: Need to verify the container is executing CHORUS properly
• Example: Is it anthonyrawlins/chorus:latest with specific command parameters?

2. CHORUS Parameter Format

• Question: What is the exact parameter format CHORUS expects?
• Context: How does CHORUS receive role identifier and task context?
• Example: Environment variables, command line args, config files?

3. P2P Network Access

• Question: How do council agents connect to the existing P2P network?
• Context: What network configuration or service discovery is needed?
• Example: Specific ports, network policies, or discovery mechanisms?

4. Council Completion Signal

• Question: How does CHORUS signal when council work is complete?
• Context: What should WHOOSH monitor to detect completion?
• Example: Specific consensus events, file outputs, or API calls?

5. Repository Access Method

• Question: How should CHORUS agents access the project repository?
• Context: What credentials and access method does CHORUS expect?
• Example: Token in environment variable, mounted secret, or API key?

6. Council Size and Roles

• Question: Should all 8 roles always be deployed, or is it configurable?
• Context: Some projects might need different council compositions
• Example: Small projects might only need 4-5 roles, large ones might need additional specialists?

7. Design Brief Content Format

• Question: What format does CHORUS expect for the Design Brief content?
• Context: How should issue title, body, and metadata be structured?
• Example: JSON object, plain text, or specific format?

Current Implementation Gaps Summary

The main gap is parameter wiring between WHOOSH's council deployment and CHORUS's agent execution. All the complex functionality (consensus, communication, output generation) already exists in CHORUS - we just need to properly configure the containers to execute CHORUS with the right parameters.

This should be a relatively small implementation focused on:

1. Container Configuration: Proper environment variables and execution parameters
2. Content Extraction: Getting Design Brief content from Gitea to CHORUS
3. Network Setup: Ensuring P2P access for council communication
4. Lifecycle Management: Basic completion detection and cleanup

The heavy lifting (agent logic, consensus, outputs) is already done in CHORUS.

Todos ☐ Wire role identifier parameter to CHORUS containers for council agents ☐ Pass Design Brief content as task context to CHORUS agents ☐ Ensure CHORUS agent process starts correctly in deployed containers ☐ Verify P2P network access for council agents ☐ Add completion detection and container cleanup logic