Files / Config

CLAUDE.md

# CLAUDE.md - OpenClaw/Fakker Workspace

Project guidance for Claude Code in this repo. Telegraph style. Authoritative; overrides external skill defaults.

## Architecture

- **Fakker (OpenClaw)** = orchestrator brain. Decides, routes, delegates, owns workflow logic.
- **Mission Control** = state board, visibility layer, API, dashboard, audit log. Records reality; does not decide.
- **Workers/agents** = self-report state back to Mission Control via bridge/CLI/API. They own their work, not the board.
- Mission Control must NOT grow into an independent orchestrator. No autonomous scheduling, no decision logic, no worker dispatch from inside Mission Control. If a feature looks like brain work, push it back to Fakker.
- Do not copy code from `builderz-labs/mission-control` or any external orchestration framework. Patterns only, never code.
- No large framework. No heavy abstraction layers. Python standard library + existing repo patterns.
- State lives in `data/mission-control.sqlite3`. Markdown files are human summaries, not source of truth.

## Mission Control Responsibilities

- Persist projects, agents, tasks, runs, events, workflows, artifacts, decisions, approvals.
- Expose read APIs: list tasks, show task, task history, board summary, dashboard state.
- Expose controlled write APIs: create/move/assign task, append event, start/finish run, update agent status.
- Emit append-only audit events on every state change.
- Stay deterministic and side-effect free outside SQLite writes.

Not Mission Control's job: spawning workers, picking next task, retrying failed runs, sending notifications, calling external services.

## Worker Reporting Rules

Workers MUST report own state back via:
- `python3 -m mission_control.cli ...` for CLI access
- `mission_control.bridge` for in-process Python access
- FastAPI endpoints in `mission_control.api` for HTTP access

Required reports:
- On task pickup: `update-agent-status` (mode, current_task_id) + `move-task` to in-progress status
- On progress: `append-event` with type/message/data
- On blocker: `move-task` with `--blocker` text
- On finish: `finish-run` with status, result, verification-notes
- On failure: `finish-run --status failed` + `move-task` back to blocked/pending

Worker must NOT:
- Edit `MISSION_CONTROL.md` or related markdown directly for live state
- Write raw SQL to `data/mission-control.sqlite3`
- Skip events; every status transition needs an event row

## Git Checkpoint Rules

- Commit after each milestone or coherent change set. Small commits, grouped logically.
- Conventional-ish messages, concise, lowercase imperative.
- Stage intended files only; never `git add -A` blindly.
- No force push, no rebase on shared branches, no destructive ops without explicit ask.
- Branch is `master` here. Push only on request.
- After completing a milestone: commit, run verification, then report.

## Verification Commands

Standard verification (run in workspace root):

```bash
python3 -m compileall mission_control tests
python3 -m unittest discover -s tests
python3 -m mission_control.cli init
python3 -m mission_control.cli dashboard
```

Also see `.claude/commands/verify.md`.

Run subset for touched code; run full set before any commit that touches `mission_control/` or `tests/`.

## Safety Rules

- Never commit secrets, credentials, tokens, real phone numbers, or live config.
- Never delete `data/mission-control.sqlite3`. Use `python3 -m mission_control.cli backup` first.
- No `rm -rf`, `git reset --hard`, `git clean -f`, or `git push --force` without explicit user ask.
- Destructive SQL (DROP, TRUNCATE, DELETE without WHERE) requires explicit user confirmation.
- New routes/endpoints stay local-only until web UI dispatch milestone explicitly authorizes exposure.
- Confirm before installing new Python deps; prefer stdlib.
- Stop and ask if a task implies giving Mission Control orchestration authority.

## Installed Skills Guidance

External skills exist for reference only. They do NOT override this repo's architecture.

- **FastAPI skills / claude-api / context7 FastAPI lookups**: route pattern reference only. Use for endpoint signatures, dependency injection idioms, response model shape. Do not import recommended packages or restructure `mission_control.api` to match a skill's template.
- **Workflow / orchestration / ralph-loop / agent-framework skills**: consult for state-transition ideas, status enum naming, retry semantics. Do not adopt their dispatch loops, queue runners, or scheduler classes. Brain logic stays in Fakker.
- **frontend-design**: use only when explicitly building the web UI dispatch milestone. Keep generated UI dependency-free where possible.
- **code-review / caveman-review / review**: ok for diff review.
- **caveman / cavecrew / caveman-commit**: communication/compression style only.
- **skill-creator / claude-md-management**: meta tooling; do not let them rewrite this CLAUDE.md without user ask.
- **find-skills**: discovery only.

Rule: if a skill suggests adding a framework, scheduler, queue runner, ORM layer, or large abstraction, stop and ask. Default answer is no.

## File Map

- `mission_control/` — Python package (db, service, bridge, api, cli)
- `tests/` — unittest suite
- `data/mission-control.sqlite3` — live state
- `.claude/commands/` — slash command prompts
- `MISSION_CONTROL.md` — human dashboard summary
- `MISSION_CONTROL_DB.md` — schema doc
- `AGENT_ROSTER.md`, `TASKS.md`, `INBOX.md`, `TRIAGE_RULES.md` — workflow docs