docs: add comprehensive implementation plan for BrokeCrew

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 <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"
+```