Files / Config

MISSION_CONTROL_SPEC.md

# MISSION_CONTROL_SPEC.md - Mission Control System Spec

## Purpose And Scope

Mission Control is the operating system for Khaled's OpenClaw orchestration setup. It should support Fakker as the main orchestrator, future agents and subagents, backend work, frontend work, infra/DevOps, QA/testing, automation, integrations, backoffice workflows, server/process monitoring, outputs, reports, and live status.

OpenClaw / Fakker is the core orchestration system. Paperclip is external/protected and stays out of the core unless Khaled explicitly activates it.

## Docs Layer Vs Live State Layer

| Layer | Purpose | Examples |
| --- | --- | --- |
| Documentation | Human-readable intent, rules, decisions, procedures, and command contracts. | `MISSION_CONTROL.md`, `PROJECTS.md`, `TASKS.md`, `DECISIONS.md`, `RUNBOOKS.md`, `OUTPUTS.md`, `COMMANDS.md` |
| Live state | Machine-readable current state and telemetry. | agents, tasks, workflows, cron jobs, heartbeats, integrations, outputs, usage, costs |
| Event history | Append-only timeline of state changes and observations. | JSONL events for inbox, tasks, agents, heartbeats, outputs, usage, costs |

Markdown explains what should happen. Structured data records what is happening now.

## Desired Vs Observed State

| State Type | Meaning |
| --- | --- |
| Desired state | What should exist, be active, be scheduled, be protected, or be delivered. |
| Observed state | What is actually happening now based on tools, checks, jobs, and reports. |
| Status evaluation | Whether observed state matches desired state. |

Example: desired state says a daily status routine should run; observed state says the last heartbeat was 30 hours ago; health should be `stale`.

## Health Levels

| Level | Meaning |
| --- | --- |
| `healthy` | Observed state matches desired state. |
| `warning` | Working, but needs attention soon. |
| `failed` | Expected behavior failed or is unavailable. |
| `stale` | No fresh signal inside the expected window. |
| `unknown` | No reliable observation exists yet. |

## Data Model

| Entity | Tracks |
| --- | --- |
| Agents | id, name, role, status, model, mode, session, current task, last seen, tokens, estimated cost |
| Subagents | parent agent, role, scope, assignment, status, model, result output |
| Tasks | id, title, domain, lifecycle status, priority, owner, repo/path, branch, blocker, dependencies, test status, expected output |
| Workflows | id, name, status, steps, dependencies, current step, owner, expected output |
| Routines / Cron / Heartbeats | schedule, desired state, last run, next run, result, health, failure count |
| Integrations | name, type, purpose, status, health, boundary, credential reference, last check |
| Outputs | type, trigger, owner, status, generated location, generated time |
| Usage / Cost | model, agent, task, input tokens, output tokens, total tokens, estimated cost, currency, time window |
| Inbox | raw intake count, untriaged count, triaged count, urgent count, newest items |

Delivery domains are `backend`, `frontend`, `infra/DevOps`, `QA/testing`, `automation`, `integration`, and `backoffice`.

Delivery modes are `Planning`, `Building`, `Debugging`, `Reviewing`, `Reporting`, and `Monitoring`.

## Event Log

Use JSONL first because it is append-friendly, easy to inspect, and easy to migrate later.

Events should include inbox item creation, task triage/splitting/assignment/blocking/review/done/archive, agent status changes, heartbeat results, cron runs, errors, outputs generated, workflow changes, model usage, token/cost records, and integration health changes.

Minimum event fields: `timestamp`, `type`, `source`, `entity_type`, `entity_id`, `status`, `message`, and optional `data`.

## Privacy And Security Rules

- Never store secrets.
- Store credential references only, such as `telegram_bot`, not actual tokens.
- Redact tokens, keys, cookies, auth headers, and private URLs in logs.
- Keep external/protected projects out of live state unless explicitly activated.
- Paperclip remains external/protected unless Khaled explicitly activates it.
- Real runtime event logs should likely be gitignored.
- Example files must use synthetic safe data only.

## Inbox / Triage / Assignment Layer

Mission Control needs an intake layer before work becomes tracked delivery.

| Stage | Meaning |
| --- | --- |
| Raw inbox item | Unstructured idea, bug, task, project note, request, or backoffice need. |
| Triage | Fakker reviews clarity, urgency, scope, project, domain, and risk. |
| Classification | Classify as task, bug, project note, decision candidate, automation idea, backoffice item, research item, support/debug item, or archive. |
| Split | Break broad items into smaller deliverable tasks when needed. |
| Priority | Assign `urgent`, `high`, `medium`, `low`, or `someday`. |
| Assignment | Assign to Fakker, subagent role, automation, or Human:Khaled. |
| Expected output | Every assigned task gets a clear deliverable. |
| Tracking | Active, assigned, blocked, and review items appear in Mission Control. |
| Review / done / archive | Completed work moves through review, done, and archive. |

Task lifecycle statuses: `inbox`, `triaged`, `planned`, `assigned`, `active`, `blocked`, `review`, `done`, `archived`.

## Owner Types

| Owner Type | Use For |
| --- | --- |
| `Fakker` | Main orchestration, coordination, docs, and scoped execution. |
| `Subagent:Backend` | Backend implementation or backend investigation. |
| `Subagent:Frontend` | Frontend implementation, UI, UX, and client-side checks. |
| `Subagent:Infra` | Infrastructure, DevOps, process, server, and deployment tasks. |
| `Subagent:QA` | Test planning, verification, regression checks, and bug reproduction. |
| `Subagent:Research` | Focused research, codebase exploration, and option analysis. |
| `Subagent:Backoffice` | Admin workflows, reporting, cleanup, and operational routines. |
| `Automation:<name>` | Scheduled or automated work. |
| `Human:Khaled` | Decisions, approvals, credentials, external actions, or human-only work. |

Owner assignment must include boundaries, expected output, and review criteria.

## Telegram Command Mapping

| Command | Data Source | Behavior |
| --- | --- | --- |
| `status` | Live state first, `MISSION_CONTROL.md` fallback | Summarize health, active work, blockers, and next action. |
| `today` | Live events, daily memory, Mission Control | Summarize today's changes, outputs, blockers, and next action. |
| `next` | Live tasks and blockers | Recommend the highest-value unblocked next action. |
| `projects` | Live state plus `PROJECTS.md` | Summarize active projects and protected boundaries. |
| `blocked` | Live tasks and workflows | Show blocked items, owners, and unblock actions. |
| `inbox` | Inbox state | Show inbox count/items or add a raw item when content is provided. |
| `triage` | Inbox and triage rules | Classify, prioritize, split, assign, or archive inbox items. |
| `assign` | Planned tasks and roster | Assign work to owner/agent/subagent with expected output. |
| `mytasks` | Task owners | Show tasks for Fakker or a requested owner. |
| `review` | Review queue | Show items waiting for review or acceptance. |
| `server` | Integrations, routines, runbooks | Summarize OpenClaw/server health with evidence and next step. |
| `decisions` | `DECISIONS.md` | Show recent durable decisions. |

## Future UI Route

Route: `/mission-control`

Initial version should be read-only. Live refresh can come after the data model is stable. Actions and approvals should wait until the read-only version is trustworthy and audit/permission boundaries are clear.

Suggested layout:

- Top summary: overall health, last updated, stale signals, active mode, daily estimated cost.
- Desired vs observed panel: mismatches by entity.
- Agents panel: agent/subagent status, model, current task, tokens, cost.
- Inbox/triage panel: inbox count, untriaged items, review queue, owner assignment.
- Work board: active, pending, blocked, and review tasks by domain.
- Workflow panel: dependencies, blockers, current step.
- Ops panel: cron jobs, heartbeats, integrations, services.
- Outputs panel: due/generated reports.
- Event stream: recent JSONL-backed events.

## Phased Implementation Plan

| Phase | Goal | Output |
| --- | --- | --- |
| Phase 1: docs/spec | Define architecture, schema, example state, and example events. | Spec files and safe examples. |
| Phase 2: structured data | Introduce structured state as source for commands. | Generated `state/mission-control.json` and `state/events.jsonl`, likely gitignored. |
| Phase 3: live generation | Add collectors for sessions, cron, heartbeat, git/repos, service health, outputs, and usage. | Fresh desired/observed state and event log. |
| Phase 4: web UI/subpage | Serve live state on `/mission-control`. | Read-only dashboard first, live refresh later, actions after stability. |

## MVP Vs Full Version

| Version | Scope |
| --- | --- |
| MVP | Spec, schema, example state, example events, manually updated structured state later, Telegram fallback to markdown. |
| Full | Database-backed event history, API, live web UI, cost charts, workflow dependencies, service monitors, cron/heartbeat telemetry, report archive, approval actions. |

## First Files

| File | Purpose |
| --- | --- |
| `MISSION_CONTROL_SPEC.md` | This system spec. |
| `schemas/mission-control.schema.json` | JSON Schema for the Mission Control state snapshot. |
| `state/mission-control.example.json` | Synthetic safe example state. |
| `state/events.example.jsonl` | Synthetic safe example events. |

Do not create real runtime files until generation exists. Later, `state/mission-control.json` and `state/events.jsonl` should probably be gitignored.