rook/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project: Rook (Jarvis)

A voice-first local AI agent for hands-free PC control, coding, shell execution, Git, browser automation, and CoSy/Forth-APL integration. The robot personality is modeled after **Rook** from Marathon — a military AI speaking through damaged speakers with a scratchy, static-crackle voice.

Policy-enforced throughout: allowlists per operation, human-in-loop confirmation gates before risky actions, backup-before-edit, no destructive commands. Built as a slow-build system — start simple, layer autonomy over time.

## Environment

- **Shell**: The `Bash` tool runs in a mingw sandbox on Windows and produces unreliable/empty output. Use the `run_powershell` MCP tool for ALL shell commands (git, tests, builds). Bash is last-resort only when the MCP server is not running.
- **Python execution**: Always use `uv run python` — never bare `python`
- **Path separators**: Forward slashes work in PowerShell
- **bd commands**: Always use `--json` flag with `bd` when running via `run_powershell` — ANSI output crashes the parser

## Development Tooling

This project is **planned and built using** tools from `C:\projects\manual_slop`:

- **Beads** (`bd` CLI) — git-backed graph issue tracker. Source of truth for what to build. Replaces `plan.md`.
- **manual_slop MCP** (`manual-slop-tools` server, registered in `.mcp.json`) — 26+ tools: `py_get_skeleton`, `py_get_code_outline`, `get_git_diff`, `run_powershell`, `read_file`, etc. Use these instead of raw file reads.
- **manual_slop workers** — invoke for ALL non-trivial coding tasks:
  ```powershell
  # Run from manual_slop so conductor docs are injected; use absolute @paths for rook files
  cd C:\projects\manual_slop
  uv run python scripts/claude_mma_exec.py --role tier3-worker "PROMPT @C:\projects\rook\src\rook\module.py"
  uv run python scripts/claude_mma_exec.py --role tier4-qa "PROMPT @C:\projects\rook\logs\error.log"
  # For complex tasks, use a task file:
  uv run python scripts/claude_mma_exec.py --task-file C:\projects\rook\task.toml
  ```
  Worker logs land in `C:\projects\manual_slop\logs\claude_agents\`.

### MMA Tier Commands

All commands run from `C:\projects\manual_slop`. Use absolute `@` paths for rook source files.

```powershell
# Tier 1 — Strategic/Orchestration (claude-opus-4-6)
cd C:\projects\manual_slop
uv run python scripts\claude_mma_exec.py --role tier1-orchestrator "PROMPT"

# Tier 2 — Tech Lead / Architecture (claude-sonnet-4-6)
uv run python scripts\claude_mma_exec.py --role tier2-tech-lead "PROMPT"

# Tier 3 — Worker: code implementation, test writing (claude-sonnet-4-6)
uv run python scripts\claude_mma_exec.py --role tier3-worker "PROMPT @C:\projects\rook\src\rook\module.py"

# Tier 4 — QA: error analysis, log summarization (claude-haiku-4-5)
uv run python scripts\claude_mma_exec.py --role tier4-qa "PROMPT @C:\projects\rook\logs\error.log"

# Complex tasks via TOML task file
uv run python scripts\claude_mma_exec.py --task-file C:\projects\rook\task.toml

# On repeated failure, pass --failure-count to escalate model
uv run python scripts\claude_mma_exec.py --role tier3-worker --failure-count 1 "PROMPT"
```

Worker logs: `C:\projects\manual_slop\logs\claude_agents\`
Delegation log: `C:\projects\manual_slop\logs\claude_mma_delegation.log`

### Beads Task Workflow

Beads replaces `plan.md`. Same discipline, different storage:

```powershell
cd C:\projects\rook
bd ready --json                                        # find unblocked tasks (start here)
bd update <id> --claim                                 # mark in-progress before starting
bd update <id> --status done                           # mark complete after commit + git note
bd create --title "..." --description "..."            # create a new task
bd dep add <id> <depends-on-id>                        # link dependency
bd list --json                                         # list all tasks
```

## Conductor Workflow (MANDATORY)

All work follows this strict lifecycle. **MMA tiered delegation is mandatory — the Conductor (this agent) does NOT write implementation code or tests directly.**

### Per-Task Lifecycle

1. **Select task**: `bd ready --json` → pick lowest-dependency task

2. **Claim**: `bd update <id> --claim` — do this BEFORE any work

3. **Research phase** (mandatory before any file read >50 lines):
   - `py_get_code_outline` or `py_get_skeleton` to map architecture
   - `get_git_diff` to understand recent changes
   - `list_directory` / `py_get_imports` to map dependencies
   - `get_file_summary` to decide if full read is needed
   - Only use `read_file` with line ranges once target areas are identified

4. **Red phase — write failing tests**:
   - **Pre-delegation checkpoint**: `git add` staged progress before spawning worker
   - Delegate to tier3-worker with a **surgical prompt**: WHERE (file:line), WHAT (tests to create), HOW (assertions/fixtures), SAFETY (thread constraints)
   - Apply the worker's output
   - **Run tests and confirm they FAIL** — do not proceed until red is confirmed

5. **Green phase — implement to pass tests**:
   - **Pre-delegation checkpoint**: stage current progress
   - Delegate to tier3-worker with surgical prompt: WHERE (file:line range), WHAT (change), HOW (APIs/patterns to use), SAFETY constraints
   - Apply the worker's output
   - **Run tests and confirm they PASS**

6. **Coverage check**: target >80% for new modules
   ```powershell
   cd C:\projects\rook; uv run pytest --cov=src/rook --cov-report=term-missing
   ```

7. **Commit**:
   ```powershell
   cd C:\projects\rook
   git add <specific files>
   git commit -m "feat(scope): description"
   git log -1 --format="%H"  # get sha
   git notes add -m "<task id> — <summary of changes and why>" <sha>
   ```

8. **Mark done**: `bd update <id> --status done`

### Worker Prompt Rules

- ALWAYS include `"Use exactly 1-space indentation for Python code"` in every worker prompt
- Prompts must specify WHERE/WHAT/HOW/SAFETY — no vague requests
- If a worker fails, retry with `--failure-count 1` (switches to a more capable model)
- For error analysis, spawn tier4-qa rather than reading raw stderr yourself

### Quality Gates (before marking any task done)

- [ ] All tests pass
- [ ] Coverage ≥80% for new code
- [ ] 1-space indentation throughout
- [ ] Type hints on all parameters, return types, module-level globals
- [ ] No hardcoded secrets (env vars only)
- [ ] Git note attached to commit

### Phase Checkpoints

After completing a group of related tasks (a "phase"):
- Create a checkpoint commit: `git commit -m "conductor(checkpoint): end of phase <name>"`
- Treat this as a **context wipe** — consolidate into git notes and move forward from the checkpoint as ground truth

## Tech Stack

- **Language**: Python 3.11+
- **Package manager**: `uv`
- **AI**: Anthropic Claude — `claude-haiku-4-5-20251001` primary, `claude-sonnet-4-6` fallback for complex reasoning
- **Voice In**: Telegram audio notes → STT (OpenClaw-style messaging)
- **Voice Out**: ElevenLabs TTS (Rook voice ID — scratchy/rough robot) with Google TTS as fallback
- **GUI** (ModernCoSy component): Dear PyGui — dockable panels, dark theme
- **CoSy**: subprocess stdin/stdout pipe to `CoSy.bat` / `reva.exe`
- **Testing**: pytest + pytest-cov

## Architecture

### Policy Enforcement

Every capability that touches the filesystem, shell, or Git must:
1. Check the operation against an allowlist for that capability
2. Prompt for confirmation before: file delete, git push, package install, any subprocess outside approved dirs
3. Backup-before-edit for file modifications

Approved working dirs: `~/dev`, `~/logs`, `~/ModernCoSy`.

### Threading

- Main asyncio loop: agent turns, capability execution
- Daemon thread: Telegram message polling
- Cross-thread: `asyncio.run_coroutine_threadsafe()` for Telegram → agent queue
- GUI (Dear PyGui) runs on main thread; asyncio on a background daemon thread

### CoSy Integration

Launch CoSy as a persistent subprocess:
```python
proc = subprocess.Popen(
 ["cmd", "/c", "CoSy.bat"],
 stdin=subprocess.PIPE,
 stdout=subprocess.PIPE,
 stderr=subprocess.STDOUT,
 text=True
)
```
Send expressions via `proc.stdin.write(expr + "\n")`, read from `proc.stdout`. Policies: backup before redefining words, only load from personal vocab dir, no infinite loops.

## Code Conventions

Source: `C:\projects\manual_slop\conductor\product-guidelines.md`

- **Indentation**: exactly **1 space** per level (AI token-optimized — mandatory)
- **Blank lines**: max 1 between top-level defs, 0 within functions
- **Type hints**: required on all parameters, return types, and module-level globals
- **Logging**: aggressive — all agent actions, API payloads, tool calls, and subprocess calls logged with timestamps
- **Dependency minimalism**: prefer stdlib over heavy third-party packages where feasible
- **No `rm -rf`**: prohibited in code and subprocess calls
- **No inline secrets**: env vars only (`ANTHROPIC_API_KEY`, `ELEVENLABS_API_KEY`, `TELEGRAM_BOT_TOKEN`, `GOOGLE_TTS_KEY`)

## Commit Guidelines

```
<type>(<scope>): <description>
```
Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`

After each commit, attach a git note:
```powershell
git notes add -m "<task id> — <files changed> — <why>" <commit_sha>
```