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