From b8b85f18d347e14cc1b46699036b5af1c22027fa Mon Sep 17 00:00:00 2001 From: oiupoyt Date: Sat, 26 Sep 2026 13:29:29 +0530 Subject: [PATCH] docs: add comprehensive implementation plan for BrokeCrew --- .../superpowers/plans/2026-09-26-brokecrew.md | 474 ++++++++++++++++++ 1 file changed, 474 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-26-brokecrew.md diff --git a/docs/superpowers/plans/2026-09-26-brokecrew.md b/docs/superpowers/plans/2026-09-26-brokecrew.md new file mode 100644 index 0000000..b01328e --- /dev/null +++ b/docs/superpowers/plans/2026-09-26-brokecrew.md @@ -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 "] +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` 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 `), 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>>`, 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 ] [--pipeline ] [--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" +```