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:

  # 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.

# 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:

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 closed                         # 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

   cd C:\projects\rook; uv run pytest --cov=src/rook --cov-report=term-missing
   

7. Commit:

   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 closed

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:

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:

git notes add -m "<task id> — <files changed> — <why>" <commit_sha>