# Implementation Plan

## Scope For This Implementation

- Included:
  - Project scaffold (`pyproject.toml`, `src/stoned_ai/`, `tests/`)
  - TTS layer wrapping Arena's Kokoro backend
  - Cleaning engine for AI CLI output noise
  - AI backend abstraction supporting Codex and Gemini CLI backends
  - Web server with SSE delivery
  - Host view (`/host`) with text input, send, voice selection, session control
  - Broadcast view (`/broadcast`) styled for OBS browser source capture
  - WAV audio serving for both views
  - Per-speaker voice assignment (host voice + AI voice)
  - `install.sh` script and `~/.local/bin/stoned-web` link

- Excluded from initial build:
  - Claude API backend (Phase 2)
  - Visual avatar or waveform animation overlay
  - YouTube chat integration
  - Persistent conversation logging (nice to have, not required for launch)
  - Mobile-responsive host view (desktop only for now)

## Phases

### Phase 1: Arena Core Enhancements

- Objective: Update the Arena project to support human speakers and the /broadcast view.
- Files affected (in the Arena project):
  - `src/arena/agents.py` — add `human` runner.
  - `src/arena/web.py` — add `/broadcast` route and UI message input.
  - `src/arena/core.py` — ensure `run_conversation` handles the human backend.
- Risks: Breaking existing AI-vs-AI modes in Arena.
- Exit criteria: Arena can successfully pause a conversation loop to wait for human input from the Web UI.

### Phase 2: Stoned Mode Presets

- Objective: Define the specific prompt envelopes and cleaning rules for the Stoned.AI show.
- Files likely affected:
  - `src/arena/core.py` — add `MODE_STONED` preset.
  - `src/arena/clean.py` — update regex for high-quality show output.
- Exit criteria: Jason can select "Stoned Mode" in Arena and it loads the correct speaker labels and roles.

### Phase 3: OBS Broadcast View

- Objective: Build the read-only, styled broadcast page within Arena.
- Files likely affected:
  - `src/arena/web.py`
- Exit criteria: `/broadcast` is accessible and OBS captures audio/video end-to-end.


### Phase 5: Claude API Backend (Post-Launch)

- Objective: Add a Claude backend using the `anthropic` SDK as an alternative to Codex/Gemini.
- Files likely affected:
  - `src/stoned_ai/ai.py`
  - `pyproject.toml` (add `anthropic` dependency)
- Risks: Requires a valid `ANTHROPIC_API_KEY` environment variable on `svc-ai`. Must not break existing Codex/Gemini backends.
- Exit criteria: The host view offers a Claude model option. A full conversation runs using the Claude API backend.

## Order Of Operations

1. Create `pyproject.toml` and package scaffold.
2. Implement `tts.py` (Kokoro wrapper).
3. Implement `clean.py` (noise stripping for Codex and Gemini).
4. Implement `ai.py` (Codex and Gemini backends).
5. Implement `web.py` — server core, session state, SSE stream, WAV serving.
6. Implement `/host` view in `web.py`.
7. Implement `/broadcast` view in `web.py`.
8. Write `scripts/install.sh`.
9. Smoke test: full end-to-end conversation from host view to broadcast view.
10. Verify OBS browser source audio capture.

## Testing Expectations

- Unit tests: `tts.py` voice listing. `clean.py` noise stripping against fixture strings. `ai.py` CLI argument construction (mock subprocess).
- Integration tests: Full SSE event sequence from host message submit to broadcast card render. Requires a live Codex or Gemini CLI.
- Manual verification: OBS audio capture. Visual broadcast layout on stream. Per-speaker voice differentiation.

## Documentation Expectations

- `README.md` must be updated with usage instructions after Phase 2 is complete.
- `docs/09-PROJECT-STATUS.md` must be updated after each phase completes.
- `docs/06-WORKER-HANDOFF.md` must be updated before handing off to the implementation model.

## Escalation Conditions

- Stop and raise a change request if:
  - `pykokoro` cannot be imported without installing the full Arena package.
  - The Kokoro voice pipeline requires GPU on the current hardware and fails on CPU.
  - OBS cannot capture audio from a browser source pointing at `svc-ai` without additional configuration.
  - The Codex or Gemini CLI output format has changed in a way that breaks the cleaning engine.

## Signature

- Document role: governing
- Created by: Claude (supervisor)
- Created at: 2026-04-12
- Revision status: initial
- Future revision rule: this document may be revised only by the user or by an explicitly authorized supervisor revision