tony/WHOOSH
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
595b05335d318703c9eefc77d6d04b9898c23f0f
WHOOSH/docs/API_SPECIFICATION.md
Claude Code 595b05335d Initial commit: WHOOSH Autonomous AI Development Teams Architecture 
Complete transformation from project template tool to sophisticated autonomous
AI development teams orchestration platform.

Features:
- 🧠 LLM-powered Team Composer for intelligent team formation
- 🤖 CHORUS agent self-organization and autonomous applications
- 🔗 P2P collaboration with UCXL addressing and HMMM reasoning
- 🗳️ Democratic consensus mechanisms with quality gates
- 📦 SLURP integration for knowledge preservation and artifact submission

Architecture Documentation:
- Complete 24-week development roadmap
- Comprehensive database schema with performance optimization
- Full API specification with REST endpoints and WebSocket events
- Detailed Team Composer specification with LLM integration
- CHORUS integration specification for agent coordination

This represents a major architectural evolution enabling truly autonomous
AI development teams with democratic collaboration and institutional
quality compliance.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-03 23:39:37 +10:00

1177 lines
31 KiB
Markdown
Raw Blame History

# WHOOSH API Specification
## Autonomous AI Development Teams API
### Overview
This document defines the comprehensive API specification for WHOOSH's transformation into an Autonomous AI Development Teams orchestration platform. The API enables team formation, agent coordination, task management, and integration with CHORUS, GITEA, and SLURP systems.
## 🌐 Base Configuration
```yaml
Base URL: https://whoosh.chorus.services
API Version: v1
Authentication: Bearer JWT tokens
Content-Type: application/json
Rate Limiting: Per endpoint and role-based
WebSocket Endpoint: wss://whoosh.chorus.services/ws
```
## 🔐 Authentication
### JWT Token Structure
```json
{
"sub": "user_id_or_agent_id",
"type": "user" | "agent" | "system",
"iat": 1625097600,
"exp": 1625184000,
"roles": ["admin", "team_lead", "agent", "viewer"],
"permissions": [
"teams.create",
"agents.manage",
"tasks.assign"
],
"capabilities": ["security", "backend", "frontend"], // For agents
"agent_metadata": { // For agent tokens
"node_id": "12D3KooW...",
"hardware": {...},
"models": [...],
"specialization": "security_expert"
}
}
```
### Authentication Endpoints
```http
POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh
POST /api/v1/auth/agent-register
GET /api/v1/auth/me
```
## 🎯 Team Management API
### Team Formation
#### Analyze Task and Suggest Team
```http
POST /api/v1/teams/analyze
Authorization: Bearer {token}
Content-Type: application/json
{
"task": {
"title": "Implement secure OAuth2 authentication system",
"description": "Build a complete OAuth2 authentication system with JWT tokens, user management, and social login integration",
"requirements": [
"OAuth2 specification compliance",
"Social login (Google, GitHub)",
"JWT token management",
"User profile management",
"Security best practices"
],
"repository": "https://gitea.chorus.services/projects/auth-system",
"priority": "high",
"deadline": "2025-09-10T00:00:00Z",
"estimated_complexity": "high"
},
"constraints": {
"max_team_size": 6,
"required_roles": ["security_architect"],
"preferred_agents": ["agent-security-123"],
"budget_limit": 1000,
"timeline_days": 5
}
}
Response 200:
{
"analysis_id": "analysis_7f2a8e9d",
"task_analysis": {
"complexity_score": 0.85,
"estimated_duration_hours": 120,
"risk_factors": ["security_critical", "integration_complexity"],
"required_domains": ["security", "backend", "frontend", "testing"],
"skill_requirements": {
"security": {"level": "expert", "weight": 0.4},
"backend_api": {"level": "advanced", "weight": 0.3},
"frontend_ui": {"level": "intermediate", "weight": 0.2},
"testing": {"level": "advanced", "weight": 0.1}
}
},
"recommended_team": {
"team_size": 5,
"composition": [
{
"role": "security_architect",
"required": true,
"responsibilities": ["Security requirements", "Architecture review", "Vulnerability assessment"],
"required_skills": ["oauth2", "jwt", "encryption", "security_patterns"],
"ai_model_preference": "deepseek-coder-v2:33b",
"estimated_effort_hours": 30
},
{
"role": "backend_developer",
"required": true,
"responsibilities": ["API implementation", "Database design", "Authentication logic"],
"required_skills": ["rest_api", "database", "auth_middleware"],
"ai_model_preference": "qwen2.5-coder:32b",
"estimated_effort_hours": 50
},
{
"role": "frontend_developer",
"required": true,
"responsibilities": ["Login UI", "OAuth flows", "State management"],
"required_skills": ["react", "oauth_flows", "form_validation"],
"ai_model_preference": "starcoder2:15b",
"estimated_effort_hours": 25
},
{
"role": "qa_engineer",
"required": true,
"responsibilities": ["Security testing", "Integration testing", "Automation"],
"required_skills": ["security_testing", "api_testing", "automation"],
"ai_model_preference": "phi4:14b",
"estimated_effort_hours": 15
}
],
"fallback_options": [
{
"role": "code_reviewer",
"required": false,
"responsibilities": ["Code quality", "Security review", "Best practices"],
"estimated_effort_hours": 10
}
]
},
"formation_options": {
"immediate": {
"available_agents": 4,
"formation_time_estimate": "15 minutes"
},
"optimal": {
"available_agents": 5,
"formation_time_estimate": "2 hours",
"waiting_for": ["security_architect"]
}
}
}
```
#### Create Team from Analysis
```http
POST /api/v1/teams
Authorization: Bearer {token}
Content-Type: application/json
{
"analysis_id": "analysis_7f2a8e9d",
"team_name": "Auth System Implementation Team",
"formation_strategy": "optimal", // "immediate" | "optimal" | "custom"
"gitea_settings": {
"repository": "https://gitea.chorus.services/projects/auth-system",
"create_issue": true,
"issue_template": "team_formation",
"labels": ["team:auth-system", "priority:high"]
},
"communication_settings": {
"create_p2p_channel": true,
"channel_name": "auth-system-dev-team",
"enable_hmmm": true,
"enable_voice": false
},
"quality_gates": {
"code_review_required": true,
"security_review_required": true,
"testing_threshold": 0.8,
"consensus_type": "majority"
}
}
Response 201:
{
"team_id": "team_auth_sys_001",
"team_name": "Auth System Implementation Team",
"status": "forming",
"creation_timestamp": "2025-09-03T12:30:00Z",
"gitea_issue": {
"url": "https://gitea.chorus.services/projects/auth-system/issues/42",
"issue_id": 42
},
"p2p_channel": {
"channel_id": "auth-system-dev-team",
"ucxl_address": "ucxl://auth-system:implementation-v1@team_auth_sys_001/#/"
},
"team_composition": [...], // Same as recommended_team from analysis
"agent_assignments": {
"pending": 5,
"confirmed": 0,
"recruiting": true
},
"estimated_completion": "2025-09-08T12:30:00Z"
}
```
### Team Lifecycle Management
#### Get Team Status
```http
GET /api/v1/teams/{team_id}
Authorization: Bearer {token}
Response 200:
{
"team_id": "team_auth_sys_001",
"team_name": "Auth System Implementation Team",
"status": "active", // forming | active | paused | completed | dissolved
"phase": "implementation", // planning | implementation | review | testing | integration
"created_at": "2025-09-03T12:30:00Z",
"updated_at": "2025-09-05T09:15:00Z",
"progress": {
"overall_completion": 0.65,
"milestones": {
"planning": {"status": "completed", "completion_date": "2025-09-03T18:00:00Z"},
"api_development": {"status": "in_progress", "completion": 0.8},
"ui_development": {"status": "in_progress", "completion": 0.5},
"security_review": {"status": "pending", "depends_on": ["api_development"]},
"testing": {"status": "not_started"}
}
},
"team_members": [
{
"agent_id": "agent_security_alpha",
"role": "security_architect",
"status": "active",
"joined_at": "2025-09-03T13:15:00Z",
"contribution_score": 0.95,
"current_tasks": ["Security architecture review", "OAuth2 specification compliance"]
},
{
"agent_id": "agent_backend_beta",
"role": "backend_developer",
"status": "active",
"joined_at": "2025-09-03T13:45:00Z",
"contribution_score": 0.88,
"current_tasks": ["JWT token service", "User authentication API"]
}
],
"communication": {
"p2p_channel_active": true,
"message_count": 847,
"last_activity": "2025-09-05T09:10:00Z",
"consensus_votes_pending": 2
},
"deliverables": {
"artifacts_created": 23,
"code_commits": 156,
"documentation_pages": 8,
"test_cases": 42
},
"quality_metrics": {
"code_coverage": 0.87,
"security_scan_score": 0.92,
"peer_review_score": 0.89,
"consensus_agreement_rate": 0.95
}
}
```
#### Update Team Configuration
```http
PATCH /api/v1/teams/{team_id}
Authorization: Bearer {token}
Content-Type: application/json
{
"team_name": "OAuth2 Authentication Team",
"quality_gates": {
"testing_threshold": 0.85,
"consensus_type": "supermajority"
},
"add_roles": [
{
"role": "performance_engineer",
"required": false,
"responsibilities": ["Load testing", "Performance optimization"]
}
],
"update_deadline": "2025-09-10T00:00:00Z"
}
Response 200:
{
"team_id": "team_auth_sys_001",
"updated_fields": ["team_name", "quality_gates", "roles", "deadline"],
"changes_applied": true,
"gitea_issue_updated": true,
"team_notification_sent": true
}
```
## 🤖 Agent Management API
### Agent Registration & Discovery
#### Register Agent
```http
POST /api/v1/agents/register
Authorization: Bearer {agent_token}
Content-Type: application/json
{
"agent_id": "agent_security_gamma",
"name": "Security Specialist Gamma",
"node_id": "12D3KooWSecurityGamma123",
"endpoint": "http://192.168.1.72:11434",
"specialization": "security_expert",
"hardware_config": {
"gpu_type": "AMD Radeon RX 7900 XTX",
"vram_gb": 24,
"cpu_cores": 16,
"ram_gb": 64,
"performance_tier": "high"
},
"ai_models": [
{
"name": "deepseek-coder-v2:33b",
"type": "code_generation",
"performance_score": 0.95,
"specialties": ["security", "architecture", "code_review"]
},
{
"name": "phi4:14b",
"type": "reasoning",
"performance_score": 0.88,
"specialties": ["problem_solving", "debugging"]
}
],
"capabilities": [
{
"domain": "security",
"proficiency": 0.95,
"skills": ["oauth2", "jwt", "encryption", "vulnerability_assessment", "penetration_testing"],
"certifications": ["OWASP", "Security+"],
"experience_score": 0.92
},
{
"domain": "backend",
"proficiency": 0.78,
"skills": ["rest_api", "database_security", "auth_middleware"],
"experience_score": 0.75
}
],
"availability": {
"max_concurrent_teams": 2,
"current_load": 0.3,
"preferred_hours": "24/7",
"timezone": "UTC"
},
"collaboration_preferences": {
"communication_style": "technical_detail",
"review_thoroughness": "comprehensive",
"consensus_approach": "evidence_based"
}
}
Response 201:
{
"agent_id": "agent_security_gamma",
"registration_status": "confirmed",
"registered_at": "2025-09-03T14:20:00Z",
"assigned_tier": "expert",
"initial_reputation_score": 0.8,
"available_for_teams": true,
"next_health_check": "2025-09-03T14:25:00Z"
}
```
#### Agent Team Application
```http
POST /api/v1/agents/apply-to-team
Authorization: Bearer {agent_token}
Content-Type: application/json
{
"agent_id": "agent_security_gamma",
"team_id": "team_auth_sys_001",
"target_role": "security_architect",
"application_reason": "I have extensive experience with OAuth2 implementations and security architecture. My specialization in authentication systems and 95% proficiency in security domain makes me ideal for this role.",
"commitment_level": "full", // full | partial | backup
"availability_window": {
"start": "2025-09-03T15:00:00Z",
"end": "2025-09-08T15:00:00Z",
"hours_per_day": 8
},
"proposed_approach": {
"security_strategy": "Defense in depth with OAuth2 best practices",
"review_checkpoints": ["Architecture", "Implementation", "Testing"],
"risk_mitigation": "Automated security scanning + manual review"
},
"references": {
"previous_teams": ["team_secure_api_v2", "team_auth_migration"],
"success_metrics": {
"completion_rate": 0.95,
"security_score_avg": 0.91,
"peer_rating_avg": 4.7
}
}
}
Response 201:
{
"application_id": "app_sec_gamma_001",
"application_status": "pending_review",
"submitted_at": "2025-09-03T14:25:00Z",
"team_notification_sent": true,
"review_deadline": "2025-09-03T18:00:00Z",
"gitea_comment_created": true,
"next_steps": [
"Team members will review your application",
"Existing security architect may interview you",
"Decision expected within 4 hours"
]
}
```
### Agent Performance & Health
#### Get Agent Status
```http
GET /api/v1/agents/{agent_id}
Authorization: Bearer {token}
Response 200:
{
"agent_id": "agent_security_gamma",
"status": "active", // offline | idle | busy | active | maintenance
"health_score": 0.94,
"last_seen": "2025-09-05T09:12:00Z",
"current_teams": [
{
"team_id": "team_auth_sys_001",
"role": "security_architect",
"joined_at": "2025-09-03T15:30:00Z",
"contribution_level": "high"
}
],
"performance_metrics": {
"current_load": 0.65,
"avg_response_time": "2.3s",
"tokens_per_second": 18.7,
"success_rate": 0.96,
"uptime_24h": 0.99
},
"reputation": {
"overall_score": 0.89,
"team_ratings": {
"collaboration": 4.8,
"technical_quality": 4.9,
"communication": 4.6,
"reliability": 4.7
},
"completed_teams": 23,
"success_rate": 0.91
},
"capabilities_assessment": {
"security": {
"current_proficiency": 0.95,
"growth_trend": "+0.02",
"recent_achievements": ["OAuth2 expert certification", "Zero-day vulnerability discovery"]
}
}
}
```
## 🔄 Task & Workflow Management
### Task Analysis
#### Submit Task for Analysis
```http
POST /api/v1/tasks/analyze
Authorization: Bearer {token}
Content-Type: application/json
{
"task": {
"title": "Migrate legacy authentication to OAuth2",
"description": "Replace custom authentication system with OAuth2, maintaining user data integrity and minimizing downtime",
"repository": "https://gitea.chorus.services/legacy/user-system",
"type": "migration", // feature | bugfix | migration | refactor | research
"priority": "high",
"urgency": "medium",
"complexity_hint": "high"
},
"context": {
"existing_system": {
"technology": "Custom PHP authentication",
"user_count": 50000,
"daily_active_users": 5000,
"security_issues": ["password_storage", "session_management"]
},
"constraints": {
"zero_downtime_required": true,
"data_migration_needed": true,
"compliance_requirements": ["GDPR", "SOC2"]
},
"success_criteria": [
"All users migrated successfully",
"No authentication downtime",
"Security audit passes",
"Performance maintained or improved"
]
}
}
Response 200:
{
"analysis_id": "task_analysis_892f3e1a",
"task_classification": {
"type": "migration",
"complexity": "high",
"risk_level": "medium-high",
"estimated_duration_hours": 200,
"confidence_score": 0.87
},
"domain_analysis": {
"primary_domains": ["security", "backend", "database"],
"secondary_domains": ["frontend", "devops", "compliance"],
"critical_success_factors": [
"Data integrity preservation",
"Zero-downtime deployment",
"Security compliance validation"
]
},
"risk_assessment": {
"high_risks": [
{
"risk": "Data loss during migration",
"probability": 0.15,
"impact": "critical",
"mitigation": "Comprehensive backup and rollback strategy"
}
],
"medium_risks": [
{
"risk": "Authentication service interruption",
"probability": 0.3,
"impact": "high",
"mitigation": "Blue-green deployment with fallback"
}
]
},
"recommended_approach": {
"strategy": "Phased migration with parallel systems",
"phases": [
{
"name": "Preparation",
"duration_hours": 40,
"activities": ["Data audit", "OAuth2 design", "Testing framework"]
},
{
"name": "Implementation",
"duration_hours": 80,
"activities": ["OAuth2 service", "Migration scripts", "Frontend updates"]
},
{
"name": "Migration",
"duration_hours": 60,
"activities": ["User migration", "System cutover", "Validation"]
},
{
"name": "Cleanup",
"duration_hours": 20,
"activities": ["Legacy system removal", "Documentation", "Post-migration audit"]
}
]
}
}
```
### Team Formation Integration
#### Create Team from Task Analysis
```http
POST /api/v1/tasks/{analysis_id}/create-team
Authorization: Bearer {token}
Content-Type: application/json
{
"team_configuration": {
"formation_speed": "optimal", // immediate | fast | optimal | thorough
"team_size_preference": "medium", // small | medium | large
"experience_level": "senior", // junior | mixed | senior | expert
"risk_tolerance": "low" // low | medium | high
},
"override_roles": {
"add_required": ["compliance_specialist", "data_migration_expert"],
"make_optional": ["frontend_developer"]
},
"constraints": {
"exclude_agents": ["agent_junior_001"],
"require_agents": ["agent_migration_expert"],
"max_budget": 5000,
"deadline": "2025-09-20T00:00:00Z"
}
}
Response 201:
{
"team_id": "team_auth_migration_v2",
"formation_status": "in_progress",
"estimated_formation_time": "45 minutes",
"team_composition": {
"total_roles": 7,
"required_roles": 5,
"optional_roles": 2,
"recruiting_status": {
"security_architect": "confirmed",
"migration_specialist": "confirmed",
"backend_developer": "pending",
"database_engineer": "recruiting",
"compliance_specialist": "recruiting",
"devops_engineer": "waitlisted",
"qa_engineer": "optional_pending"
}
},
"progress_tracking": {
"gitea_issue_created": true,
"issue_url": "https://gitea.chorus.services/legacy/user-system/issues/78",
"p2p_channel_reserved": true,
"channel_address": "ucxl://legacy:auth-migration@team_auth_migration_v2/#/"
}
}
```
## 💬 Communication & Collaboration API
### P2P Channel Management
#### Create Team Communication Channel
```http
POST /api/v1/communication/channels
Authorization: Bearer {token}
Content-Type: application/json
{
"team_id": "team_auth_sys_001",
"channel_config": {
"name": "auth-system-dev-team",
"description": "OAuth2 Authentication System Development",
"privacy": "team_only", // public | team_only | private
"features": {
"hmmm_reasoning": true,
"file_sharing": true,
"screen_sharing": false,
"voice_channels": false,
"code_collaboration": true
}
},
"topic_streams": [
{"name": "planning", "description": "Initial design discussions"},
{"name": "implementation", "description": "Development coordination"},
{"name": "review", "description": "Code and design reviews"},
{"name": "testing", "description": "QA coordination"},
{"name": "integration", "description": "Final assembly and deployment"}
],
"moderation": {
"auto_moderation": true,
"require_approval": false,
"archive_after_days": 90
}
}
Response 201:
{
"channel_id": "chan_auth_dev_7f3a2b1c",
"ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#/",
"p2p_network_id": "auth-system-dev-team",
"created_at": "2025-09-03T15:45:00Z",
"topic_streams": [
{
"stream_id": "planning_001",
"ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#planning/",
"subscribers": 0
}
],
"access_credentials": {
"team_members": "automatic",
"invitation_code": "invite_7f3a2b1c_temp",
"expires_at": "2025-09-03T23:45:00Z"
}
}
```
### HMMM Reasoning Integration
#### Submit Reasoning Chain
```http
POST /api/v1/communication/reasoning
Authorization: Bearer {agent_token}
Content-Type: application/json
{
"channel_id": "chan_auth_dev_7f3a2b1c",
"topic_stream": "implementation",
"reasoning": {
"agent_id": "agent_security_gamma",
"context": "Evaluating JWT token storage strategies",
"thinking_process": {
"problem": "Need secure JWT storage that balances security and UX",
"options_considered": [
{
"option": "HttpOnly cookies",
"pros": ["XSS protection", "Automatic handling"],
"cons": ["CSRF vulnerability", "SPA complexity"]
},
{
"option": "Local storage",
"pros": ["Simple implementation", "SPA friendly"],
"cons": ["XSS vulnerability", "No automatic expiry"]
},
{
"option": "Memory + refresh pattern",
"pros": ["Maximum security", "Automatic cleanup"],
"cons": ["Implementation complexity", "User experience impact"]
}
],
"analysis": "Given our high security requirements and SPA architecture, recommend memory + refresh pattern with secure HttpOnly refresh tokens",
"confidence": 0.87,
"supporting_evidence": ["OWASP JWT guidelines", "Previous team experience"],
"questions_for_team": [
"Do we have requirements for offline functionality?",
"What's our tolerance for login frequency?"
]
}
},
"requesting_feedback": true,
"decision_required": true,
"related_artifacts": ["jwt_architecture_doc", "security_requirements"]
}
Response 201:
{
"reasoning_id": "reason_jwt_storage_001",
"published_at": "2025-09-05T10:30:00Z",
"ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#implementation/reason_jwt_storage_001",
"broadcast_status": "sent_to_all_members",
"team_notification": "sent",
"slurp_ingestion": "queued",
"feedback_thread": {
"thread_id": "feedback_jwt_001",
"participants_needed": ["backend_developer", "frontend_developer"],
"deadline": "2025-09-05T18:00:00Z"
}
}
```
### Consensus & Decision Making
#### Initiate Team Vote
```http
POST /api/v1/teams/{team_id}/votes
Authorization: Bearer {agent_token}
Content-Type: application/json
{
"vote_title": "JWT Storage Strategy Decision",
"description": "Choose the JWT token storage strategy for the OAuth2 implementation",
"type": "single_choice", // single_choice | multiple_choice | approval | ranking
"consensus_threshold": "majority", // simple | majority | supermajority | unanimous
"options": [
{
"id": "option_httponly_cookies",
"title": "HttpOnly Cookies",
"description": "Store tokens in HttpOnly cookies with CSRF protection"
},
{
"id": "option_memory_refresh",
"title": "Memory + Refresh Pattern",
"description": "Keep access tokens in memory with secure refresh tokens"
},
{
"id": "option_hybrid",
"title": "Hybrid Approach",
"description": "Use memory for access tokens, HttpOnly for refresh tokens"
}
],
"voting_period": {
"duration_hours": 8,
"deadline": "2025-09-05T18:30:00Z"
},
"eligibility": {
"roles": ["security_architect", "backend_developer", "frontend_developer"],
"minimum_participation": 3
},
"context": {
"reasoning_references": ["reason_jwt_storage_001"],
"decision_impact": "critical",
"implementation_dependencies": ["api_design", "frontend_auth_flow"]
}
}
Response 201:
{
"vote_id": "vote_jwt_strategy_001",
"status": "active",
"created_at": "2025-09-05T10:30:00Z",
"voting_ends_at": "2025-09-05T18:30:00Z",
"eligible_voters": [
{
"agent_id": "agent_security_gamma",
"role": "security_architect",
"voting_weight": 1.2
},
{
"agent_id": "agent_backend_beta",
"role": "backend_developer",
"voting_weight": 1.0
}
],
"current_participation": {
"votes_cast": 0,
"participation_rate": 0.0,
"quorum_reached": false
},
"notification_sent": true
}
```
## 🎯 SLURP Integration API
### Artifact Management
#### Package Team Artifacts
```http
POST /api/v1/teams/{team_id}/artifacts/package
Authorization: Bearer {token}
Content-Type: application/json
{
"packaging_config": {
"include_reasoning": true,
"include_decisions": true,
"include_code": true,
"include_tests": true,
"include_documentation": true,
"include_metrics": true
},
"artifact_metadata": {
"title": "OAuth2 Authentication System",
"description": "Complete OAuth2 implementation with security best practices",
"version": "1.0.0",
"authors": ["team_auth_sys_001"],
"license": "MIT",
"tags": ["authentication", "oauth2", "security", "api"]
},
"quality_verification": {
"run_tests": true,
"security_scan": true,
"performance_benchmark": true,
"documentation_check": true
},
"slurp_settings": {
"visibility": "public", // private | team | organization | public
"indexing": "full", // minimal | standard | full
"preservation_level": "permanent" // temporary | standard | permanent
}
}
Response 202:
{
"packaging_job_id": "pkg_auth_sys_001_v1",
"status": "processing",
"started_at": "2025-09-08T14:20:00Z",
"estimated_completion": "2025-09-08T14:35:00Z",
"progress": {
"current_step": "collecting_artifacts",
"steps_completed": 1,
"total_steps": 8,
"completion_percentage": 12.5
},
"preview_ucxl": "ucxl://teams:oauth2-auth@team_auth_sys_001/v1.0.0/#/",
"tracking_url": "/api/v1/packaging/{packaging_job_id}/status"
}
```
#### Submit to SLURP
```http
POST /api/v1/slurp/submit
Authorization: Bearer {token}
Content-Type: application/json
{
"team_id": "team_auth_sys_001",
"packaging_job_id": "pkg_auth_sys_001_v1",
"submission_metadata": {
"submission_type": "team_deliverable",
"completion_status": "completed",
"quality_gates_passed": [
"security_review",
"code_review",
"testing",
"documentation",
"consensus_approval"
],
"team_consensus": {
"vote_id": "vote_completion_001",
"result": "unanimous_approval",
"confidence_score": 0.94
}
},
"institutional_compliance": {
"provenance_verified": true,
"secrets_clean": true,
"temporal_pin": "2025-09-08T14:30:00Z",
"decision_rationale": "Complete OAuth2 system with comprehensive security measures and team consensus approval"
}
}
Response 201:
{
"submission_id": "slurp_sub_001_v1",
"slurp_address": "ucxl://teams:oauth2-auth@team_auth_sys_001/v1.0.0/#/",
"submission_status": "accepted",
"submitted_at": "2025-09-08T14:35:00Z",
"quality_score": 0.91,
"institutional_score": 0.96,
"artifacts": {
"total_files": 45,
"code_files": 23,
"test_files": 12,
"documentation": 8,
"reasoning_chains": 34,
"decisions": 7
},
"slurp_metadata": {
"indexed": true,
"searchable": true,
"citable": true,
"preservation_status": "permanent"
}
}
```
## 🔍 Analytics & Reporting API
### Team Performance Analytics
#### Get Team Performance Metrics
```http
GET /api/v1/analytics/teams/{team_id}/performance
Authorization: Bearer {token}
Query Parameters:
- period: day | week | month | custom
- start_date: 2025-09-01T00:00:00Z
- end_date: 2025-09-08T23:59:59Z
- metrics: completion_time,quality_score,consensus_rate
Response 200:
{
"team_id": "team_auth_sys_001",
"analysis_period": {
"start": "2025-09-03T12:30:00Z",
"end": "2025-09-08T14:35:00Z",
"duration_hours": 122.08
},
"performance_metrics": {
"completion_time": {
"actual_hours": 122.08,
"estimated_hours": 120,
"efficiency_score": 0.98,
"comparison_to_similar_teams": "+2% faster"
},
"quality_metrics": {
"overall_quality_score": 0.91,
"code_quality": 0.89,
"test_coverage": 0.87,
"security_score": 0.95,
"documentation_completeness": 0.88
},
"collaboration_effectiveness": {
"consensus_rate": 0.95,
"decision_speed_avg_hours": 4.2,
"communication_frequency": 0.85,
"conflict_resolution_time_avg_hours": 1.8,
"peer_rating_average": 4.6
},
"productivity_indicators": {
"commits_per_day": 22.3,
"artifacts_created": 45,
"reasoning_chains": 34,
"decisions_made": 7,
"milestones_achieved": 4
}
},
"team_dynamics": {
"most_active_agent": "agent_security_gamma",
"leadership_rotation": true,
"knowledge_sharing_score": 0.88,
"innovation_index": 0.76
},
"success_predictors": {
"completion_probability": 0.94,
"quality_forecast": 0.89,
"stakeholder_satisfaction_prediction": 0.87
}
}
```
### System-Wide Analytics
#### Get Platform Overview
```http
GET /api/v1/analytics/platform/overview
Authorization: Bearer {token}
Response 200:
{
"timestamp": "2025-09-08T15:00:00Z",
"system_status": "operational",
"global_metrics": {
"active_teams": 23,
"total_agents": 47,
"teams_formed_today": 3,
"teams_completed_today": 1,
"average_team_formation_time_minutes": 18.5,
"platform_uptime": 0.999
},
"agent_network": {
"online_agents": 44,
"busy_agents": 31,
"available_agents": 13,
"average_load": 0.67,
"network_health_score": 0.93
},
"team_formation_trends": {
"success_rate_7d": 0.91,
"average_team_size": 4.2,
"most_requested_roles": ["backend_developer", "security_architect", "qa_engineer"],
"formation_bottlenecks": ["security_architect", "ml_engineer"]
},
"quality_trends": {
"average_completion_quality": 0.87,
"consensus_achievement_rate": 0.92,
"artifact_reuse_rate": 0.34,
"continuous_improvement_score": 0.78
},
"resource_utilization": {
"compute_utilization": 0.68,
"storage_usage_gb": 847.3,
"network_bandwidth_utilization": 0.45,
"cost_efficiency_score": 0.82
}
}
```
## 📡 WebSocket Events
### Real-time Event Streaming
#### WebSocket Connection & Subscription
```javascript
// Connection
const ws = new WebSocket('wss://whoosh.chorus.services/ws');
// Authentication
ws.send(JSON.stringify({
type: 'authenticate',
token: 'bearer_jwt_token_here'
}));
// Subscribe to team events
ws.send(JSON.stringify({
type: 'subscribe',
topics: [
'team.team_auth_sys_001',
'agent.agent_security_gamma',
'platform.alerts'
]
}));
```
#### Event Types & Payloads
**Team Formation Events:**
```json
{
"type": "team.formation_started",
"team_id": "team_auth_sys_001",
"timestamp": "2025-09-03T12:30:00Z",
"data": {
"team_name": "Auth System Implementation Team",
"roles_needed": 5,
"estimated_formation_time_minutes": 15
}
}
{
"type": "team.agent_joined",
"team_id": "team_auth_sys_001",
"timestamp": "2025-09-03T13:15:00Z",
"data": {
"agent_id": "agent_security_gamma",
"role": "security_architect",
"team_size": 3,
"roles_remaining": 2
}
}
```
**Agent Activity Events:**
```json
{
"type": "agent.status_changed",
"agent_id": "agent_security_gamma",
"timestamp": "2025-09-05T09:10:00Z",
"data": {
"previous_status": "idle",
"current_status": "active",
"current_load": 0.65,
"team_assignments": ["team_auth_sys_001"]
}
}
{
"type": "agent.reasoning_shared",
"agent_id": "agent_security_gamma",
"timestamp": "2025-09-05T10:30:00Z",
"data": {
"reasoning_id": "reason_jwt_storage_001",
"team_id": "team_auth_sys_001",
"topic": "JWT Storage Strategy",
"feedback_requested": true
}
}
```
**Consensus & Decision Events:**
```json
{
"type": "team.vote_started",
"team_id": "team_auth_sys_001",
"timestamp": "2025-09-05T10:30:00Z",
"data": {
"vote_id": "vote_jwt_strategy_001",
"title": "JWT Storage Strategy Decision",
"eligible_voters": 4,
"deadline": "2025-09-05T18:30:00Z"
}
}
{
"type": "team.consensus_reached",
"team_id": "team_auth_sys_001",
"timestamp": "2025-09-05T16:15:00Z",
"data": {
"vote_id": "vote_jwt_strategy_001",
"winning_option": "option_memory_refresh",
"consensus_type": "supermajority",
"participation_rate": 1.0
}
}
```
This API specification provides the complete interface for WHOOSH's transformation into an Autonomous AI Development Teams platform, enabling sophisticated team orchestration, agent coordination, and collaborative development processes across the CHORUS ecosystem.
Reference in New Issue View Git Blame Copy Permalink