docs: add comprehensive implementation plan for BrokeCrew
This commit is contained in:
parent
edab67dbbc
commit
b8b85f18d3
1 changed files with 474 additions and 0 deletions
474
docs/superpowers/plans/2026-09-26-brokecrew.md
Normal file
474
docs/superpowers/plans/2026-09-26-brokecrew.md
Normal file
|
|
@ -0,0 +1,474 @@
|
|||
# BrokeCrew Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Build `brokecrew`, a high-performance, async-first Rust CLI and core library enabling users to interact with a resilient multi-persona AI team backed by OpenRouter models with two-stage routing, automatic candidate fallbacks, budget tracking, and typed multi-agent pipelines.
|
||||
|
||||
**Architecture:** A dual-target crate (`src/lib.rs` + `src/main.rs`). `lib.rs` encapsulates all domain types, OpenRouter client with SSE streaming, live registry caching, rate-limit budgeting, two-stage routing, and multi-agent pipelines with zero UI/terminal coupling. `main.rs` is a thin entrypoint providing `clap` argument parsing, `indicatif` spinners, `owo-colors` terminal output, and OS keyring integration.
|
||||
|
||||
**Tech Stack:** Rust 2021 edition, `tokio` (async runtime), `reqwest` (HTTP client with connection pooling & json), `tokio-util` / `futures-util` (SSE streaming), `clap` (CLI parser with derive), `serde` & `toml` & `serde_json` (serialization), `keyring` (OS credential store), `indicatif` (terminal progress/spinners), `owo-colors` (terminal colors), `tracing` & `tracing-subscriber` (structured logging), `wiremock` (integration testing).
|
||||
|
||||
**Spec:** [docs/superpowers/specs/2026-09-26-brokecrew-design.md](file:///home/oiupoyt/projects/brokecrew/docs/superpowers/specs/2026-09-26-brokecrew-design.md)
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Must compile on stable Rust with zero warnings under `cargo clippy --all-targets -- -D warnings`.
|
||||
- No API keys ever printed in logs, debug representations, error messages, or terminal outputs.
|
||||
- `main.rs` must remain a thin entrypoint; no persona, registry, router, or budget logic may leak into `main.rs`.
|
||||
- Network calls must never `.unwrap()` or panic; all failures mapped cleanly into typed `ClientError` variants.
|
||||
- Dual-licensed under MIT OR Apache-2.0.
|
||||
|
||||
## Review Focus
|
||||
|
||||
1. **Invalid API Key (HTTP 401)**: Must fail fast with `ClientError::Unauthorized` without uselessly cycling through remaining candidate models.
|
||||
2. **Exhausted Credits (HTTP 402)**: Must abort immediately with `ClientError::PaymentRequired` without retrying free candidates.
|
||||
3. **Stage B Router Hallucination**: If the small LLM router outputs unparseable text or an unknown persona, system must smoothly fall back to `default_persona` (e.g. `general`).
|
||||
4. **Candidate Rate Limiting (HTTP 429)**: Candidate cascade must catch rate limits, log the fallback event with model IDs, and invoke the next viable candidate seamlessly.
|
||||
5. **Total Cascade Failure**: If all candidates in a persona's fallback list fail or are unlisted, an aggregated error must report every attempt cleanly without panicking.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Crate Scaffolding, Governance & Default Config
|
||||
|
||||
**Files:**
|
||||
- Create: `Cargo.toml`
|
||||
- Create: `LICENSE-MIT`
|
||||
- Create: `LICENSE-APACHE`
|
||||
- Create: `CODEOWNERS`
|
||||
- Create: `CONTRIBUTING.md`
|
||||
- Create: `CHANGELOG.md`
|
||||
- Create: `README.md`
|
||||
- Create: `.github/workflows/ci.yml`
|
||||
- Create: `config/personas.example.toml`
|
||||
- Create: `src/lib.rs`
|
||||
- Create: `src/main.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: Compilable Rust package with `brokecrew` library and binary targets.
|
||||
|
||||
- [ ] **Step 1: Create Cargo.toml with dependencies**
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "brokecrew"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
authors = ["oiupoyt <oiupoyt.cat@gmail.com>"]
|
||||
description = "A Rust-native multi-model AI team CLI with resilient OpenRouter fallback routing"
|
||||
license = "MIT OR Apache-2.0"
|
||||
readme = "README.md"
|
||||
repository = "https://github.com/brokecrew/brokecrew"
|
||||
keywords = ["cli", "llm", "openrouter", "multi-agent", "ai"]
|
||||
categories = ["command-line-utilities", "development-tools"]
|
||||
|
||||
[dependencies]
|
||||
tokio = { version = "1.40", features = ["full"] }
|
||||
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "stream"] }
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
serde_json = "1.0"
|
||||
toml = "0.8"
|
||||
clap = { version = "4.5", features = ["derive", "env"] }
|
||||
tracing = "0.1"
|
||||
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
|
||||
thiserror = "1.0"
|
||||
async-trait = "0.1"
|
||||
futures-util = "0.3"
|
||||
keyring = { version = "3.0", features = ["linux-native"] }
|
||||
indicatif = "0.17"
|
||||
owo-colors = "4.1"
|
||||
regex = "1.10"
|
||||
chrono = { version = "0.4", features = ["serde"] }
|
||||
dirs = "5.0"
|
||||
tempfile = "3.12"
|
||||
|
||||
[dev-dependencies]
|
||||
wiremock = "0.6"
|
||||
tokio-test = "0.4"
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create initial src/lib.rs and src/main.rs**
|
||||
|
||||
Create minimal placeholder library and binary to ensure baseline compilation.
|
||||
|
||||
- [ ] **Step 3: Create licenses, governance, CI workflow, and personas.example.toml**
|
||||
|
||||
Add `LICENSE-MIT`, `LICENSE-APACHE`, `CODEOWNERS`, `CONTRIBUTING.md`, `CHANGELOG.md`, `README.md`, `.github/workflows/ci.yml`, and `config/personas.example.toml` matching the spec.
|
||||
|
||||
- [ ] **Step 4: Verify build and test compilation**
|
||||
|
||||
Run: `cargo check` and `cargo test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add Cargo.toml src/ LICENSE* CODEOWNERS CONTRIBUTING.md CHANGELOG.md README.md .github/ config/
|
||||
git commit -m "chore: scaffold project structure, licenses, CI and default config"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Core Domain Models & Fallback Resolution (`persona.rs`)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/persona.rs`
|
||||
- Modify: `src/lib.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `Tier`, `ModelCandidate`, `Persona`, `DispatchResult`, `ModelAttempt`, `PersonaRegistry`, and fallback candidate selection logic.
|
||||
|
||||
- [ ] **Step 1: Write failing unit test for candidate fallback selection**
|
||||
|
||||
Test that candidate selection properly skips stealth models when `allow_stealth` is false, prioritizes paid tier when escalated, and returns candidates in declared priority order.
|
||||
|
||||
- [ ] **Step 2: Run test to verify failure**
|
||||
|
||||
Run: `cargo test --lib persona`
|
||||
Expected: FAIL with missing types.
|
||||
|
||||
- [ ] **Step 3: Implement persona domain types and candidate selector**
|
||||
|
||||
Implement `Tier`, `ModelCandidate`, `Persona`, `DispatchResult`, `ModelAttempt`, `PersonaRegistry::get_eligible_candidates(&self, persona_name: &str, allow_stealth: bool, require_paid: bool)`.
|
||||
|
||||
- [ ] **Step 4: Run tests to verify pass**
|
||||
|
||||
Run: `cargo test --lib persona`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/persona.rs src/lib.rs
|
||||
git commit -m "feat: implement persona domain models and candidate resolution"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Free-Tier Budget Awareness & Rate Limiter (`budget.rs`)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/budget.rs`
|
||||
- Modify: `src/lib.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `BudgetTracker`, `BudgetStatus`, `CreditTier`, rolling window check (20 req/min), daily quota check (50 or 1,000 req/day), atomic persistence to disk.
|
||||
|
||||
- [ ] **Step 1: Write failing tests for rolling window and daily rollover**
|
||||
|
||||
Write tests covering:
|
||||
- Permitting requests up to 20 per minute; rejecting or returning delay on 21st.
|
||||
- Accurately reporting remaining daily budget.
|
||||
- Warning when exceeding 80% daily quota threshold.
|
||||
- Persisting state and reloading from JSON.
|
||||
|
||||
- [ ] **Step 2: Run test to verify failure**
|
||||
|
||||
Run: `cargo test --lib budget`
|
||||
Expected: FAIL with module not found.
|
||||
|
||||
- [ ] **Step 3: Implement BudgetTracker with atomic persistence**
|
||||
|
||||
Implement `BudgetTracker` using a sliding timestamp queue for the 60-second window, UTC date tracking for daily counts, and atomic writes via `tempfile`.
|
||||
|
||||
- [ ] **Step 4: Run tests to verify pass**
|
||||
|
||||
Run: `cargo test --lib budget`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/budget.rs src/lib.rs
|
||||
git commit -m "feat: implement account-wide budget tracker and rate limiter"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Model Client & SSE Streaming Engine (`client.rs`)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/client.rs`
|
||||
- Modify: `src/lib.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `ModelClient` trait, `ClientError`, `OpenRouterClient`, `complete()`, `complete_stream()`, SSE event parser.
|
||||
- Consumes: `tokio::sync::mpsc::Sender<String>` for streaming deltas.
|
||||
|
||||
- [ ] **Step 1: Write failing tests for SSE chunk parsing and error status mapping**
|
||||
|
||||
Unit test the SSE stream line parser to ensure `data: {"choices":[{"delta":{"content":"foo"}}]}` parses correctly, `data: [DONE]` signals completion, 401 maps to `Unauthorized`, 402 maps to `PaymentRequired`, and 429 extracts `Retry-After`.
|
||||
|
||||
- [ ] **Step 2: Run test to verify failure**
|
||||
|
||||
Run: `cargo test --lib client`
|
||||
Expected: FAIL with missing module.
|
||||
|
||||
- [ ] **Step 3: Implement ModelClient and OpenRouterClient**
|
||||
|
||||
Implement `OpenRouterClient` with custom headers (`HTTP-Referer`, `X-Title`, `Authorization: Bearer <key>`), request timeouts, SSE stream consumption, and robust `ClientError` mapping. Implement custom `Debug` to ensure API keys are never printed.
|
||||
|
||||
- [ ] **Step 4: Run tests to verify pass**
|
||||
|
||||
Run: `cargo test --lib client`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/client.rs src/lib.rs
|
||||
git commit -m "feat: implement OpenRouter HTTP client with SSE streaming"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Live Model Registry & Cache (`registry.rs`)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/registry.rs`
|
||||
- Modify: `src/lib.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `ModelInfo`, `ModelPricing`, `ModelRegistry`, `fetch_models()`, `is_model_available()`, `start_background_sync()`.
|
||||
|
||||
- [ ] **Step 1: Write failing test for ModelRegistry catalog parsing & filtering**
|
||||
|
||||
Test deserializing OpenRouter `/v1/models` JSON response, caching models in memory, and verifying model availability.
|
||||
|
||||
- [ ] **Step 2: Run test to verify failure**
|
||||
|
||||
Run: `cargo test --lib registry`
|
||||
Expected: FAIL with missing module.
|
||||
|
||||
- [ ] **Step 3: Implement ModelRegistry**
|
||||
|
||||
Implement `ModelRegistry` holding `Arc<RwLock<HashMap<String, ModelInfo>>>`, background sync with configurable duration, and helper to filter candidate lists based on live availability.
|
||||
|
||||
- [ ] **Step 4: Run tests to verify pass**
|
||||
|
||||
Run: `cargo test --lib registry`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/registry.rs src/lib.rs
|
||||
git commit -m "feat: implement live model registry cache and background sync"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Two-Stage Router & Complexity Escalation (`router/`)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/router/mod.rs`
|
||||
- Create: `src/router/keyword.rs`
|
||||
- Create: `src/router/llm.rs`
|
||||
- Modify: `src/lib.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `Router`, `RouteDecision`, Stage A `KeywordRouter::classify`, Stage B `LlmRouter::classify`, Stage C `estimate_complexity()`.
|
||||
|
||||
- [ ] **Step 1: Write failing table-driven unit tests for Stage A keyword routing**
|
||||
|
||||
Test matching keywords against personas ("build me a website" -> `coder`, "audit this code" -> `reviewer`, "hello how are you" -> `None`).
|
||||
|
||||
- [ ] **Step 2: Write failing unit tests for Stage B LLM fallback & Stage C escalation**
|
||||
|
||||
Test router output sanitization (valid persona accepted, unparseable output falls back to `default_persona`), and complexity score calculation triggering paid tier flag.
|
||||
|
||||
- [ ] **Step 3: Run tests to verify failure**
|
||||
|
||||
Run: `cargo test --lib router`
|
||||
Expected: FAIL.
|
||||
|
||||
- [ ] **Step 4: Implement KeywordRouter, LlmRouter, and combined Router**
|
||||
|
||||
Implement word-boundary regex matching in `keyword.rs`, single-token LLM dispatch with fallback in `llm.rs`, and complexity evaluation.
|
||||
|
||||
- [ ] **Step 5: Run tests to verify pass**
|
||||
|
||||
Run: `cargo test --lib router`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/router/ src/lib.rs
|
||||
git commit -m "feat: implement two-stage router with keyword filter and complexity escalation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Multi-Agent Handoff Pipeline (`pipeline.rs`)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/pipeline.rs`
|
||||
- Modify: `src/lib.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `PipelineStep`, `PipelineConfig`, `PipelineExecutor`, `PipelineEvent` (`StepStart`, `Chunk`, `StepDone`), `execute_pipeline()`.
|
||||
|
||||
- [ ] **Step 1: Write failing test for sequential pipeline execution**
|
||||
|
||||
Test pipeline passing step 1 output into step 2 context when `pass_previous_output = true`, emitting proper lifecycle events.
|
||||
|
||||
- [ ] **Step 2: Run test to verify failure**
|
||||
|
||||
Run: `cargo test --lib pipeline`
|
||||
Expected: FAIL.
|
||||
|
||||
- [ ] **Step 3: Implement PipelineExecutor**
|
||||
|
||||
Implement sequential execution of pipeline steps using candidate fallback per step, streaming deltas via event channel.
|
||||
|
||||
- [ ] **Step 4: Run tests to verify pass**
|
||||
|
||||
Run: `cargo test --lib pipeline`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/pipeline.rs src/lib.rs
|
||||
git commit -m "feat: implement multi-agent handoff pipeline engine"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Configuration Loader & Keyring Credential Storage (`config.rs`)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/config.rs`
|
||||
- Modify: `src/lib.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `AppConfig`, `load_config()`, `get_api_key()`, `save_api_key_to_keyring()`.
|
||||
- Resolves key priority: CLI argument -> `OPENROUTER_API_KEY` env -> OS Keyring -> `config.toml`.
|
||||
|
||||
- [ ] **Step 1: Write unit tests for configuration loading and key resolution priority**
|
||||
|
||||
Test fallback hierarchy from CLI argument to environment variable to config file.
|
||||
|
||||
- [ ] **Step 2: Run test to verify failure**
|
||||
|
||||
Run: `cargo test --lib config`
|
||||
Expected: FAIL.
|
||||
|
||||
- [ ] **Step 3: Implement config loading and keyring storage**
|
||||
|
||||
Support default configuration directory (`~/.config/brokecrew/`), loading `personas.toml`, loading `config.toml`, storing and retrieving key via `keyring` crate with safe fallback when headless/keyring unavailable.
|
||||
|
||||
- [ ] **Step 4: Run tests to verify pass**
|
||||
|
||||
Run: `cargo test --lib config`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/config.rs src/lib.rs
|
||||
git commit -m "feat: implement config loading and OS keyring credential storage"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 9: CLI UX, Terminal Presentation & Subcommands (`cli.rs`, `main.rs`)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/cli.rs`
|
||||
- Modify: `src/main.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Subcommands:
|
||||
- `brokecrew chat [PROMPT] [--persona <NAME>] [--pipeline <NAME>] [--allow-stealth] [--escalate]`
|
||||
- `brokecrew config set-key`
|
||||
- `brokecrew personas list`
|
||||
- `brokecrew status`
|
||||
- Features: `indicatif` spinner during TTFT, `owo-colors` distinct persona styling, real-time SSE chunk streaming, `--json-logs` structured logging toggle.
|
||||
|
||||
- [ ] **Step 1: Implement clap CLI hierarchy in src/cli.rs**
|
||||
|
||||
Define `Cli`, `Commands`, flags (`--json-logs`, `--allow-stealth`, `--escalate`, `--config-file`, `--api-key`).
|
||||
|
||||
- [ ] **Step 2: Implement subcommand handlers in src/main.rs**
|
||||
|
||||
Connect CLI args to library calls:
|
||||
- `chat`: Route prompt, display persona badge with unique color, stream response, display fallback notices if any candidate failed.
|
||||
- `config set-key`: Prompt securely for key and save to keyring.
|
||||
- `personas list`: Pretty-print personas, candidates, triggers, and pipelines.
|
||||
- `status`: Show live registry statistics and daily/minute budget usage.
|
||||
|
||||
- [ ] **Step 3: Verify CLI commands with cargo run**
|
||||
|
||||
Run: `cargo run -- --help`, `cargo run -- personas list`, `cargo run -- status`
|
||||
Expected: Formatted terminal output.
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add src/cli.rs src/main.rs
|
||||
git commit -m "feat: implement clap CLI subcommands and terminal UX"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 10: Integration Tests, Fallback Simulation & WireMock (`tests/`)
|
||||
|
||||
**Files:**
|
||||
- Create: `tests/router_tests.rs`
|
||||
- Create: `tests/fallback_tests.rs`
|
||||
- Create: `tests/wiremock_client.rs`
|
||||
|
||||
**Interfaces:**
|
||||
- Verifies:
|
||||
- Full candidate fallback cascade on 429/503 errors.
|
||||
- WireMock SSE stream ingestion and status code handling.
|
||||
- Table-driven router classification.
|
||||
- Budget tracker integration.
|
||||
|
||||
- [ ] **Step 1: Implement router_tests.rs**
|
||||
|
||||
Add comprehensive table-driven tests for prompt routing and edge cases.
|
||||
|
||||
- [ ] **Step 2: Implement fallback_tests.rs**
|
||||
|
||||
Implement mock `ModelClient` simulating failures on top candidates to verify seamless candidate fallback and audit logs.
|
||||
|
||||
- [ ] **Step 3: Implement wiremock_client.rs**
|
||||
|
||||
Implement WireMock HTTP tests verifying SSE streaming, 401 fast failure, 402 payment required handling, and `/v1/models` catalog parsing.
|
||||
|
||||
- [ ] **Step 4: Run the complete test suite and clippy**
|
||||
|
||||
Run: `cargo test` and `cargo clippy --all-targets -- -D warnings`
|
||||
Expected: 100% tests PASS and zero clippy warnings.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add tests/
|
||||
git commit -m "test: add comprehensive integration tests and WireMock test harness"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 11: Final Polish, Verification & Documentation
|
||||
|
||||
**Files:**
|
||||
- Modify: `README.md`
|
||||
- Verify: Acceptance criteria checklist
|
||||
|
||||
- [ ] **Step 1: Complete README.md**
|
||||
|
||||
Include quickstart guide, install command, architecture diagram, persona configuration tutorial, and "Why BrokeCrew vs LiteLLM/RouteLLM" comparison.
|
||||
|
||||
- [ ] **Step 2: End-to-end verification**
|
||||
|
||||
Run `cargo check`, `cargo clippy --all-targets -- -D warnings`, `cargo test`, and run CLI subcommands locally.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add README.md
|
||||
git commit -m "docs: complete comprehensive README and user documentation"
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue