chore(setup): initialize project with CLAUDE.md, MCP config, and conductor commands
- CLAUDE.md: full project guidance (architecture, MMA workflow, beads task lifecycle, code conventions, policy rules, commit guidelines) - .mcp.json: manual-slop-tools MCP server registration (26+ dev tools) - .claude/settings.json: Claude Code project settings - .claude/settings.local.json: MCP server permissions - .claude/commands/: 9 conductor slash commands (conductor-setup, conductor-status, conductor-implement, conductor-new-track, conductor-verify, mma-tier1 through tier4)
This commit is contained in:
209
CLAUDE.md
Normal file
209
CLAUDE.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# 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>
|
||||
```
|
||||
Reference in New Issue
Block a user