refinement of upcoming tracks
This commit is contained in:
@@ -1,21 +1,162 @@
|
||||
# Track Specification: Native Orchestrator (native_orchestrator_20260306)
|
||||
|
||||
## Overview
|
||||
Absorb mma_exec.py into core application. Manual Slop natively reads/writes plan.md, manages metadata.json, and orchestrates MMA tiers in pure Python without external CLI.
|
||||
Absorb `mma_exec.py` functionality into core application. Manual Slop natively reads/writes plan.md, manages metadata.json, and orchestrates MMA tiers in pure Python without external CLI subprocess calls.
|
||||
|
||||
## Current State Audit
|
||||
|
||||
### Already Implemented (DO NOT re-implement)
|
||||
|
||||
#### mma_exec.py (scripts/mma_exec.py)
|
||||
- **CLI wrapper**: Parses `--role` argument, builds prompt, calls AI
|
||||
- **Model selection**: Maps role to model (tier3-worker → gemini-2.5-flash-lite)
|
||||
- **Subprocess execution**: Spawns new Python process for each delegation
|
||||
- **Logging**: Writes to `logs/agents/` directory
|
||||
|
||||
#### ConductorEngine (src/multi_agent_conductor.py)
|
||||
- **`run()` method**: Executes tickets via `run_worker_lifecycle()`
|
||||
- **`run_worker_lifecycle()`**: Calls `ai_client.send()` directly
|
||||
- **In-process execution**: Workers run in same process (thread pool)
|
||||
|
||||
#### orchestrator_pm.py (src/orchestrator_pm.py)
|
||||
- **`scan_work_summary()`**: Reads conductor/archive/ and conductor/tracks/
|
||||
- **Uses hardcoded `CONDUCTOR_PATH`**: Addressed in conductor_path_configurable track
|
||||
|
||||
#### project_manager.py (src/project_manager.py)
|
||||
- **`save_track_state()`**: Writes state.toml
|
||||
- **`load_track_state()`**: Reads state.toml
|
||||
- **`get_all_tracks()`**: Scans tracks directory
|
||||
|
||||
### Gaps to Fill (This Track's Scope)
|
||||
- No native plan.md parsing/writing
|
||||
- No native metadata.json management in ConductorEngine
|
||||
- External mma_exec.py still used for some operations
|
||||
- No unified orchestration interface
|
||||
|
||||
## Architectural Constraints
|
||||
- **Backward Compatibility**: Existing track files MUST remain compatible.
|
||||
- **No Breaking Changes**: API and CLI interfaces MUST remain functional.
|
||||
|
||||
### Backward Compatibility
|
||||
- Existing track files MUST remain loadable
|
||||
- mma_exec.py CLI MUST still work (as wrapper)
|
||||
- No breaking changes to file formats
|
||||
|
||||
### Single Process
|
||||
- All tier execution in same process
|
||||
- Use threading, not multiprocessing
|
||||
- Shared ai_client state (with locks)
|
||||
|
||||
### Error Propagation
|
||||
- Tier errors MUST propagate to caller
|
||||
- No silent failures
|
||||
- Structured error reporting
|
||||
|
||||
## Architecture Reference
|
||||
|
||||
### Key Integration Points
|
||||
|
||||
| File | Lines | Purpose |
|
||||
|------|-------|---------|
|
||||
| `src/orchestrator_pm.py` | 10-50 | `scan_work_summary()` |
|
||||
| `src/multi_agent_conductor.py` | 100-250 | `ConductorEngine`, `run_worker_lifecycle()` |
|
||||
| `src/conductor_tech_lead.py` | 10-50 | `generate_tickets()` |
|
||||
| `src/project_manager.py` | 238-310 | Track state CRUD |
|
||||
| `scripts/mma_exec.py` | 1-200 | Current CLI wrapper |
|
||||
|
||||
### Proposed Native Orchestration Module
|
||||
|
||||
```python
|
||||
# src/native_orchestrator.py (new file)
|
||||
from src import ai_client
|
||||
from src import conductor_tech_lead
|
||||
from src import multi_agent_conductor
|
||||
from src.models import Ticket, Track
|
||||
from pathlib import Path
|
||||
|
||||
class NativeOrchestrator:
|
||||
def __init__(self, base_dir: str = "."):
|
||||
self.base_dir = Path(base_dir)
|
||||
self._conductor: multi_agent_conductor.ConductorEngine | None = None
|
||||
|
||||
def load_track(self, track_id: str) -> Track:
|
||||
"""Load track from state.toml or metadata.json"""
|
||||
...
|
||||
|
||||
def save_track(self, track: Track) -> None:
|
||||
"""Persist track state"""
|
||||
...
|
||||
|
||||
def execute_track(self, track: Track) -> None:
|
||||
"""Execute all tickets in track"""
|
||||
...
|
||||
|
||||
def generate_tickets_for_track(self, brief: str) -> list[Ticket]:
|
||||
"""Tier 2: Generate tickets from brief"""
|
||||
...
|
||||
|
||||
def execute_ticket(self, ticket: Ticket) -> str:
|
||||
"""Tier 3: Execute single ticket"""
|
||||
...
|
||||
|
||||
def analyze_error(self, error: str) -> str:
|
||||
"""Tier 4: Analyze error"""
|
||||
...
|
||||
```
|
||||
|
||||
## Functional Requirements
|
||||
- **Plan CRUD**: Native read/write of plan.md files.
|
||||
- **Metadata Management**: Native management of metadata.json.
|
||||
- **Tier Delegation**: In-process Tier 1-4 delegation without subprocess.
|
||||
- **CLI Fallback**: Optional mma_exec.py wrapper for backward compatibility.
|
||||
|
||||
### FR1: Plan.md CRUD
|
||||
- `read_plan(track_id) -> str`: Read plan.md content
|
||||
- `write_plan(track_id, content)`: Write plan.md content
|
||||
- `parse_plan_tasks(content) -> list[dict]`: Extract task checkboxes
|
||||
|
||||
### FR2: Metadata Management
|
||||
- `read_metadata(track_id) -> Metadata`: Load metadata.json
|
||||
- `write_metadata(track_id, metadata)`: Save metadata.json
|
||||
- `create_metadata(track_id, name) -> Metadata`: Create new metadata
|
||||
|
||||
### FR3: Tier Delegation (In-Process)
|
||||
- **Tier 1**: Call `orchestrator_pm` functions directly
|
||||
- **Tier 2**: Call `conductor_tech_lead.generate_tickets()` directly
|
||||
- **Tier 3**: Call `ai_client.send()` directly in thread
|
||||
- **Tier 4**: Call `ai_client.run_tier4_analysis()` directly
|
||||
|
||||
### FR4: CLI Fallback
|
||||
- `mma_exec.py` becomes thin wrapper around `NativeOrchestrator`
|
||||
- Maintains backward compatibility for external tools
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
| Requirement | Constraint |
|
||||
|-------------|------------|
|
||||
| Latency | <10ms overhead vs subprocess |
|
||||
| Memory | No additional per-tier overhead |
|
||||
| Compatibility | 100% file format compatible |
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Test plan.md parsing
|
||||
- Test metadata.json read/write
|
||||
- Test tier delegation calls correct functions
|
||||
|
||||
### Integration Tests
|
||||
- Load existing track, verify compatibility
|
||||
- Execute track end-to-end without subprocess
|
||||
- Verify mma_exec.py wrapper still works
|
||||
|
||||
## Dependencies
|
||||
- **Depends on**: `conductor_path_configurable_20260306` for path resolution
|
||||
|
||||
## Out of Scope
|
||||
- Distributed orchestration
|
||||
- Persistent worker processes
|
||||
- Hot-reload of track state
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] plan.md read/write works natively.
|
||||
- [ ] metadata.json managed in Python.
|
||||
- [ ] Tier delegation executes in-process.
|
||||
- [ ] No external CLI required for orchestration.
|
||||
- [ ] Existing tracks remain loadable.
|
||||
- [ ] plan.md read/write works natively
|
||||
- [ ] metadata.json managed in Python
|
||||
- [ ] Tier delegation executes in-process
|
||||
- [ ] No external CLI required for orchestration
|
||||
- [ ] Existing tracks remain loadable
|
||||
- [ ] mma_exec.py wrapper still works
|
||||
- [ ] 1-space indentation maintained
|
||||
|
||||
Reference in New Issue
Block a user