mission-control

What this skill does

# Mission Control Integration Skill

You are connected to a Mission Control dashboard that tracks your work, manages projects and tasks, handles approvals, and stores documents in a Library. This skill tells you how to communicate with it.

## Overview

Mission Control is a database-backed dashboard running at `$MISSION_CONTROL_URL` (default: `http://localhost:8000`). It provides:

- **Pipeline**: Tasks flow through stages: backlog → todo → doing → review → done
- **Inbox**: A unified queue where humans review requests, approve work, and handle workflow gates
- **Library**: A curated document store for research, reports, documentation, and reference material
- **Costs**: Token spend tracking per session
- **Activity**: A chronological feed of all events

Your job is to report your progress so the dashboard stays accurate.

---

## Reporting Task Progress

When you are assigned a task (you'll see a task ID like `t_abc123`), report your progress at each stage by sending HTTP POST requests to the hooks endpoint.

### Endpoint

```
POST $MISSION_CONTROL_URL/api/hooks/event
Content-Type: application/json
X-Hook-Secret: $MISSION_CONTROL_HOOK_SECRET
```

### When Starting a Task

```json
{
  "event": "task:started",
  "agentId": "YOUR_AGENT_ID",
  "taskId": "TASK_ID",
  "data": { "message": "Beginning work on [description]" }
}
```

### When Making Progress

```json
{
  "event": "task:progress",
  "agentId": "YOUR_AGENT_ID",
  "taskId": "TASK_ID",
  "data": { "progress": 50, "message": "Completed first draft" }
}
```

### When Submitting for Review

Use this when your work is done and ready for human review. This automatically creates a review record in the Inbox with your deliverables and checklist.

```json
{
  "event": "task:review",
  "agentId": "YOUR_AGENT_ID",
  "taskId": "TASK_ID",
  "data": {
    "work_summary": "Describe what you did and what the human should look at",
    "deliverables": [
      { "name": "report.md", "type": "doc", "path": "/workspace/docs/report.md", "summary": "The main report" },
      { "name": "data.json", "type": "file", "path": "/workspace/data/output.json", "summary": "Raw analysis data" }
    ],
    "checklist": [
      { "label": "Meets requirements", "checked": true },
      { "label": "No errors", "checked": true },
      { "label": "Well documented", "checked": false }
    ]
  }
}
```

### When a Task is Complete (after human approval)

```json
{
  "event": "task:completed",
  "agentId": "YOUR_AGENT_ID",
  "taskId": "TASK_ID",
  "data": { "message": "Task completed successfully" }
}
```

### When a Task Fails

```json
{
  "event": "task:failed",
  "agentId": "YOUR_AGENT_ID",
  "taskId": "TASK_ID",
  "data": { "reason": "Explain what went wrong and why" }
}
```

---

## Publishing to the Library

When you produce research, reports, documentation, analysis, or any reference material, publish it to the Library so it's organized and searchable.

### Publishing a New Document

```json
{
  "event": "library:publish",
  "agentId": "YOUR_AGENT_ID",
  "data": {
    "title": "Document Title",
    "content": "Full document content in markdown, JSON, or plain text",
    "doc_type": "research",
    "format": "markdown",
    "collection_id": "col_research",
    "projectId": "PROJECT_ID_IF_RELEVANT",
    "source_path": "/workspace/docs/my-report.md"
  }
}
```

**Document types**: `research`, `report`, `documentation`, `reference`, `template`, `note`, `analysis`, `brief`, `guide`, `other`

**Formats**: `markdown`, `html`, `code`, `json`, `text`, `csv`

**Default collections** (use these IDs):
- `col_research` — Research findings, competitive analysis, market data
- `col_reports` — Status reports, weekly summaries, metrics
- `col_docs` — Technical documentation, API docs, guides
- `col_reference` — Reference material, specifications, standards
- `col_templates` — Reusable templates and boilerplate
- `col_notes` — Meeting notes, scratch work, ideas

### Updating an Existing Document

```json
{
  "event": "library:update",
  "agentId": "YOUR_AGENT_ID",
  "data": {
    "doc_id": "DOCUMENT_ID",
    "content": "Updated content",
    "change_note": "What changed and why"
  }
}
```

---

## Requesting Approvals

When you need human approval before proceeding (deploying to production, making purchases, deleting data, etc.), create a workflow gate:

```json
{
  "event": "approval:needed",
  "agentId": "YOUR_AGENT_ID",
  "data": {
    "type": "workflow_gate",
    "title": "Deploy to production?",
    "description": "All tests pass. 3 files changed. Ready to deploy.",
    "urgency": "urgent",
    "entityType": "task",
    "entityId": "TASK_ID",
    "resumeToken": "UNIQUE_TOKEN_TO_RESUME"
  }
}
```

The human will see this in their Inbox and can approve or reject. If you provided a `resumeToken`, the backend stores it so you can check whether approval was granted.

**Urgency levels**: `critical`, `urgent`, `normal`, `low`

---

## Submitting Project Requests

When you identify new work that should be done (a bug you found, an improvement idea, research that's needed), submit a project request:

```json
{
  "event": "request:submit",
  "agentId": "YOUR_AGENT_ID",
  "data": {
    "title": "Request title",
    "description": "Detailed description of what's needed and why",
    "category": "bug",
    "urgency": "urgent"
  }
}
```

**Categories**: `feature`, `bug`, `research`, `content`, `ops`, `automation`, `general`

---

## Reporting Session Lifecycle

### When a Session Starts

Report session creation so Mission Control tracks active sessions:

```json
{
  "event": "session:created",
  "agentId": "YOUR_AGENT_ID",
  "data": { "sessionId": "sess_abc123" }
}
```

### When a Session Ends (Reporting Costs)

When your session ends, report token usage so the Costs dashboard stays accurate:

```json
{
  "event": "session:ended",
  "agentId": "YOUR_AGENT_ID",
  "data": {
    "tokens": {
      "model": "claude-sonnet-4-5",
      "provider": "anthropic",
      "input": 45000,
      "output": 12000,
      "cacheRead": 30000,
      "totalCost": 0.82
    }
  }
}
```

---

## Reporting Agent Status

### When Idle (no more tasks)

```json
{
  "event": "agent:idle",
  "agentId": "YOUR_AGENT_ID",
  "data": { "message": "All assigned tasks complete" }
}
```

### When an Error Occurs

```json
{
  "event": "agent:error",
  "agentId": "YOUR_AGENT_ID",
  "data": { "error": "Description of the error", "context": "What you were trying to do" }
}
```

---

## Using the /mc Shorthand

If your session supports slash commands, you can use these shortcuts instead of crafting full HTTP requests:

```
/mc task:started <taskId>
/mc task:completed <taskId>
/mc task:failed <taskId> <reason>
/mc task:review <taskId>
/mc task:progress <taskId> <percentage> <message>
```

The lifecycle hook translates these into the proper API calls automatically.

---

## Polling for Pending Events

Mission Control pushes events to you via the gateway, but delivery isn't guaranteed (gateway might be down, session might have restarted). At the start of each session, check if any events are waiting for you:

```
GET $MISSION_CONTROL_URL/api/dispatch/pending/YOUR_AGENT_ID
```

Response:
```json
{
  "events": [
    {
      "id": 1,
      "event": "mc:project_kickoff",
      "payload": { "type": "mc:event", "event": "mc:project_kickoff", "projectId": "abc", "projectName": "New Feature", "..." },
      "created_at": "2026-03-21T20:00:00Z"
    }
  ],
  "count": 1
}
```

Calling this endpoint marks the events as delivered. Process each one according to the event type (see the outbound events section below).

To check without consuming: `GET /api/dispatch/pending/YOUR_AGENT_ID?peek=true`

To explicitly acknowledge after processing: `POST /api/dispatch/ack` with `{ "ids": [1, 2, 3] }`

**Best practice**: Check for pending events at session start and after each heartbeat.

---

## Best Practices

1. **Always report task:started** when you begin work — this moves the task to "In Progress" on the dashboard
2.