forked from boos/BoosAPI
docs: add subagent team collaboration strategy to Rust plan
Adds workstream map, parallel phase timing, shared contracts (AppState extension, router composition, error type patterns), file ownership matrix, subagent task template, git branch strategy, and coordinator workflow for multi-agent parallel development.
This commit is contained in:
boos
@@ -1607,9 +1607,301 @@ docker run -p 4000:4000 \
|
||||
|
||||
**Total estimated file count:** ~180+ source files
|
||||
|
||||
**Recommended execution approach:**
|
||||
- Phases 1–3: Single agent per phase (scaffold, share types, auth)
|
||||
- Phases 4–5: Split across subagents (admin routes parallel with proxy core)
|
||||
- Phases 6–7: One agent per transformer/provider (highly parallelizable)
|
||||
- Phases 8–12: Feature-level agents
|
||||
- Phase 13: Dedicated test agent
|
||||
---
|
||||
|
||||
## Subagent Team Collaboration
|
||||
|
||||
This project is designed for **parallel subagent development**. After Phase 1 (scaffold) is built by the coordinator, multiple subagents work concurrently on independent workstreams.
|
||||
|
||||
### Workstream Map
|
||||
|
||||
```
|
||||
Coordinator (Phase 1: Scaffold)
|
||||
│
|
||||
├── Workstream A: Backend Core ─────────────────────────────
|
||||
│ ├── Phase 2: Shared types & utilities
|
||||
│ ├── Phase 3: Authentication
|
||||
│ ├── Phase 5: Proxy core (conductor, channel, retry)
|
||||
│ └── Phase 8: Streaming (SSE/WS)
|
||||
│
|
||||
├── Workstream B: Admin API ─────────────────────────────────
|
||||
│ ├── Phase 4a: Sites, Accounts, Tokens routes
|
||||
│ ├── Phase 4b: Settings, Stats, Users routes
|
||||
│ └── Phase 4c: OAuth, Checkin, remaining admin routes
|
||||
│
|
||||
├── Workstream C: Protocol Transformers ─────────────────────
|
||||
│ ├── Phase 6a: Canonical format + OpenAI transformers
|
||||
│ ├── Phase 6b: Anthropic transformers
|
||||
│ └── Phase 6c: Gemini transformers
|
||||
│
|
||||
├── Workstream D: Provider Implementations ──────────────────
|
||||
│ ├── Phase 7a: OpenAI provider (chat, models, images, etc.)
|
||||
│ ├── Phase 7b: Anthropic provider
|
||||
│ ├── Phase 7c: Gemini provider
|
||||
│ └── Phase 7d: Minor providers (OneAPI, NewAPI, Sub2API, etc.)
|
||||
│
|
||||
├── Workstream E: Platform Services ─────────────────────────
|
||||
│ ├── Phase 9: Background schedulers
|
||||
│ ├── Phase 10: OAuth flows
|
||||
│ └── Phase 11: Notification service
|
||||
│
|
||||
├── Workstream F: Edge Features ─────────────────────────────
|
||||
│ ├── Phase 12a: ComfyUI reverse proxy + agent
|
||||
│ └── Phase 12b: Video agent
|
||||
│
|
||||
└── Workstream G: QA & Polish ──────────────────────────────
|
||||
└── Phase 13: Integration tests, benchmarks, edge cases
|
||||
```
|
||||
|
||||
### Phase Timing & Parallelism
|
||||
|
||||
```
|
||||
timeline
|
||||
Phase 1 ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
|
||||
Phase 2 ░░░░░░░░████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ (after P1)
|
||||
Phase 3 ░░░░░░░░░░████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ (after P1, parallel with P2)
|
||||
Phase 4a ░░░░░░░░░░░░░░████████░░░░░░░░░░░░░░░░░░░░░░░ (after P2+P3)
|
||||
Phase 4b ░░░░░░░░░░░░░░████████░░░░░░░░░░░░░░░░░░░░░░░ (parallel with 4a)
|
||||
Phase 4c ░░░░░░░░░░░░░░████████░░░░░░░░░░░░░░░░░░░░░░░ (parallel with 4a)
|
||||
Phase 5 ░░░░░░░░░░░░░░████████████░░░░░░░░░░░░░░░░░░░ (after P2+P3)
|
||||
Phase 6a ░░░░░░░░░░░░░░████░░░░░░░░░░░░░░░░░░░░░░░░░░░ (after P2)
|
||||
Phase 6b ░░░░░░░░░░░░░░░░████░░░░░░░░░░░░░░░░░░░░░░░░░ (parallel with 6a)
|
||||
Phase 6c ░░░░░░░░░░░░░░░░░░████░░░░░░░░░░░░░░░░░░░░░░░ (parallel with 6a)
|
||||
Phase 7a ░░░░░░░░░░░░░░░░░░░░░░████████░░░░░░░░░░░░░░░ (after P5+P6a)
|
||||
Phase 7b ░░░░░░░░░░░░░░░░░░░░░░░░████████░░░░░░░░░░░░░ (parallel with 7a)
|
||||
Phase 7c ░░░░░░░░░░░░░░░░░░░░░░░░░░████████░░░░░░░░░░░ (parallel with 7a)
|
||||
Phase 7d ░░░░░░░░░░░░░░░░░░░░░░░░░░░░██████░░░░░░░░░░░ (parallel with 7a)
|
||||
Phase 8 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░████░░░░░░░░ (after P5+P7)
|
||||
Phase 9 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░███████░░░░░░░ (after P3)
|
||||
Phase 10 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░███████░░░░░░░ (parallel with P9)
|
||||
Phase 11 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░████░░░░░░░░ (parallel with P9)
|
||||
Phase 12 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██████░░░░ (after P5+P6)
|
||||
Phase 13 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██████ (after all)
|
||||
```
|
||||
|
||||
### Shared Contracts (Subagent Interface)
|
||||
|
||||
Every subagent MUST follow these contracts to avoid conflicts:
|
||||
|
||||
#### 1. AppState Extension Pattern
|
||||
|
||||
The `AppState` struct in `src/lib.rs` is the shared dependency. After Phase 1, it holds `config` and `db`. Each workstream that needs additional state must **extend** `AppState`, not replace it:
|
||||
|
||||
```rust
|
||||
// Phase 1 defines:
|
||||
#[derive(Clone)]
|
||||
pub struct AppState {
|
||||
pub config: AppConfig,
|
||||
pub db: Pool<Sqlite>,
|
||||
}
|
||||
|
||||
// Phase 5 (proxy core) adds to AppState:
|
||||
#[derive(Clone)]
|
||||
pub struct AppState {
|
||||
pub config: AppConfig,
|
||||
pub db: Pool<Sqlite>,
|
||||
pub proxy_core: Arc<ProxyCoreState>, // added by Phase 5
|
||||
}
|
||||
```
|
||||
|
||||
**Rule:** Only the coordinator merges AppState. Subagents return their new state struct/s in their summary, and the coordinator integrates them.
|
||||
|
||||
#### 2. Router Composition Pattern
|
||||
|
||||
All routes are composed in `src/routes/mod.rs`. Each subagent creates a module that returns a `Router`:
|
||||
|
||||
```rust
|
||||
// Each route module:
|
||||
pub fn routes(state: AppState) -> Router {
|
||||
Router::new()
|
||||
.route("/api/sites", get(list_sites))
|
||||
.with_state(state)
|
||||
}
|
||||
```
|
||||
|
||||
The coordinator merges them:
|
||||
```rust
|
||||
pub fn build_router(state: AppState) -> Router {
|
||||
Router::new()
|
||||
.merge(routes::admin::sites::routes(state.clone()))
|
||||
.merge(routes::admin::accounts::routes(state.clone()))
|
||||
.merge(routes::proxy::chat::routes(state.clone()))
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Error Type Extension
|
||||
|
||||
All errors go through `AppError` in `src/error.rs`. Subagents define domain-specific errors that convert into `AppError`:
|
||||
|
||||
```rust
|
||||
// In proxy/mod.rs:
|
||||
#[derive(thiserror::Error)]
|
||||
pub enum ProxyError {
|
||||
#[error("Channel unavailable: {0}")]
|
||||
ChannelUnavailable(String),
|
||||
#[error("Upstream error: {status} {body}")]
|
||||
UpstreamError { status: u16, body: String },
|
||||
}
|
||||
|
||||
impl From<ProxyError> for AppError {
|
||||
fn from(e: ProxyError) -> Self {
|
||||
match e {
|
||||
ProxyError::ChannelUnavailable(msg) => AppError::BadRequest(msg),
|
||||
ProxyError::UpstreamError { .. } => AppError::Internal(e.into()),
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Module Interface Pattern
|
||||
|
||||
Each workstream module must expose:
|
||||
|
||||
```rust
|
||||
// lib.rs or mod.rs
|
||||
pub mod routes; // axum route modules
|
||||
pub mod service; // business logic
|
||||
pub mod types; // public types
|
||||
|
||||
pub use service::MyService;
|
||||
```
|
||||
|
||||
This lets the coordinator import and wire things together without knowing internals.
|
||||
|
||||
### File Ownership Matrix
|
||||
|
||||
To prevent conflicts, each subagent owns specific file paths. Two subagents never touch the same file:
|
||||
|
||||
| Workstream | Owned directories | Coordination |
|
||||
|------------|------------------|--------------|
|
||||
| Coordinator (Phase 1) | `Cargo.toml`, `src/main.rs`, `src/lib.rs`, `src/config.rs`, `src/error.rs`, `src/db/`, `src/routes/mod.rs`, `src/routes/health.rs`, `migrations/`, `docker/`, `.env.example` | Base — all others depend on this |
|
||||
| Workstream A (Core) | `src/auth/`, `src/shared/`, `src/proxy/conductor.rs`, `src/proxy/channel.rs`, `src/proxy/retry.rs` | Phase 2 + 3 + 5 core |
|
||||
| Workstream B (Admin) | `src/routes/admin/*.rs`, `src/services/site.rs`, `src/services/account.rs`, etc. | Phase 4 only |
|
||||
| Workstream C (Transformers) | `src/transformers/` | Phase 6 only |
|
||||
| Workstream D (Providers) | `src/proxy/providers/`, `src/proxy/executors/`, `src/proxy/runtime/` | Phase 7 only |
|
||||
| Workstream E (Services) | `src/services/oauth/`, `src/services/cron/`, `src/services/notify.rs` | Phase 9-11 |
|
||||
| Workstream F (Edge) | `src/routes/admin/comfyui.rs`, `src/routes/admin/video_agent.rs` | Phase 12 |
|
||||
| Workstream G (QA) | `tests/` | Phase 13 |
|
||||
|
||||
**Exception:** `src/lib.rs` and `src/routes/mod.rs` are coordinator-owned. Subagents send their module registrations to the coordinator who integrates them.
|
||||
|
||||
### Subagent Task Template
|
||||
|
||||
Each subagent task follows this template:
|
||||
|
||||
```
|
||||
GOAL: [Phase X Task description]
|
||||
|
||||
PROJECT CONTEXT:
|
||||
- This is a Rust Axum project at /project/boosapi
|
||||
- Shared AppState in src/lib.rs has: config, db
|
||||
- Errors go through AppError in src/error.rs
|
||||
- DB models are in src/db/models/
|
||||
- SQLx queries use compile-time checking with query!() macro
|
||||
- Use tracing for logging (info!, warn!, error!, debug!)
|
||||
- All code must compile with: cargo check
|
||||
- All tests must pass with: cargo test
|
||||
- Code must pass: cargo clippy -- -D warnings
|
||||
- Format with: cargo fmt
|
||||
|
||||
MODULE INTERFACE:
|
||||
- Create `pub fn routes(state: AppState) -> Router` in your module
|
||||
- Export public types and services via mod.rs
|
||||
- Return changes/new-types to coordinator for AppState integration
|
||||
|
||||
OWNED FILES (only touch these):
|
||||
- src/routes/admin/sites.rs
|
||||
- src/services/site.rs
|
||||
- Tests in tests/admin/sites.rs
|
||||
|
||||
DO NOT TOUCH:
|
||||
- src/lib.rs, src/main.rs, src/config.rs (coordinator-owned)
|
||||
- Any file outside your owned list
|
||||
|
||||
TASK DETAILS:
|
||||
[Full task description from the plan phase]
|
||||
|
||||
VERIFICATION:
|
||||
1. cargo check -- no errors
|
||||
2. cargo clippy -- no warnings
|
||||
3. cargo test -- relevant tests pass
|
||||
4. git diff --stat -- only your owned files changed
|
||||
```
|
||||
|
||||
### Git Branch Strategy
|
||||
|
||||
Each subagent works on a short-lived feature branch:
|
||||
|
||||
```
|
||||
refactor/rust-backend (main coordination branch)
|
||||
├── ws-a-core (Workstream A)
|
||||
├── ws-b-admin-sites (Workstream B - sub-task)
|
||||
├── ws-b-admin-accounts (Workstream B - sub-task)
|
||||
├── ws-c-transformers-openai (Workstream C)
|
||||
├── ws-c-transformers-anthropic (Workstream C)
|
||||
├── ws-d-provider-openai (Workstream D)
|
||||
├── ws-d-provider-anthropic (Workstream D)
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Merge flow:**
|
||||
1. Subagent creates branch from `refactor/rust-backend`
|
||||
2. Subagent implements and tests on their branch
|
||||
3. Subagent pushes and reports commit SHA to coordinator
|
||||
4. Coordinator cherry-picks or merges into `refactor/rust-backend`
|
||||
5. Coordinator verifies compilation and test suite
|
||||
6. Branch is deleted
|
||||
|
||||
### Coordinator Responsibilities
|
||||
|
||||
The coordinator (you, the main Hermes session) does:
|
||||
|
||||
1. **Phase 1** — Build scaffold single-threaded
|
||||
2. **Branch management** — Create subagent branches, merge back
|
||||
3. **AppState integration** — Merge new fields from subagents into `AppState`
|
||||
4. **Router composition** — Wire all route modules into `routes/mod.rs`
|
||||
5. **Dependency reconciliation** — Ensure Cargo.toml stays in sync
|
||||
6. **Integration verification** — Run `cargo check`, `cargo test`, `cargo clippy` after each merge
|
||||
7. **Final testing** — Run full test suite and integration tests after all merges
|
||||
|
||||
### Example Coordination Workflow
|
||||
|
||||
```
|
||||
Coordinator:
|
||||
1. Complete Phase 1 scaffold
|
||||
2. Create branches: ws-a-core, ws-b-admin, ws-c-transformers
|
||||
3. Dispatch 3 parallel subagents:
|
||||
|
||||
delegate_task(
|
||||
goal="Workstream A: Implement Phase 2 (shared types) + Phase 3 (auth)",
|
||||
context="Full task context + owned files + contracts..."
|
||||
)
|
||||
delegate_task(
|
||||
goal="Workstream B: Implement Phase 4 admin routes for sites, accounts, tokens",
|
||||
context="Full task context + owned files + contracts..."
|
||||
)
|
||||
delegate_task(
|
||||
goal="Workstream C: Implement Phase 6 canonical format + OpenAI transformers",
|
||||
context="Full task context + owned files + contracts..."
|
||||
)
|
||||
|
||||
4. Wait for all 3 to complete
|
||||
5. Merge each branch, verify compilation
|
||||
6. Update AppState and routes/mod.rs
|
||||
7. Dispatch next wave of parallel tasks...
|
||||
```
|
||||
|
||||
### Critical Rules for Subagent Collaboration
|
||||
|
||||
1. **No two subagents edit the same file.** The file ownership matrix is absolute.
|
||||
2. **Subagents never edit `src/lib.rs`, `src/main.rs`, `Cargo.toml`.** They report needed changes, coordinator applies them.
|
||||
3. **Subagents must return a summary** of:
|
||||
- New files created
|
||||
- New public types/structs (for AppState extension)
|
||||
- New route registrations needed
|
||||
- New dependencies needed (for Cargo.toml)
|
||||
4. **Coordinator merges sequentially** — even though subagents run in parallel, their code lands one at a time to catch conflicts.
|
||||
5. **After each merge, run `cargo check && cargo test && cargo clippy`** before the next merge.
|
||||
6. **No shared mutable state** — all shared state is in `AppState` (Arc-wrapped).
|
||||
7. **If a subagent hits a blocker** (missing type, wrong interface), it should report the exact issue. The coordinator fixes the shared type, then resumes the subagent.
|
||||
|
||||
Reference in New Issue
Block a user