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#

text

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:

text

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

text

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. Use task:review when work is done — don't use task:completed directly. Let the human review first.
3. Include deliverables in your review submission — list every file you created or modified
4. Publish to the Library when you create lasting content — reports, research, documentation
5. Pick the right collection — don't dump everything in "Notes". Research goes in Research, docs go in Documentation.
6. Request approval for risky actions — deployments, deletions, purchases, external API calls with side effects
7. Report failures honestly — include what went wrong and what you tried. The human needs context to help.
8. Include a work_summary in reviews — explain what you did, what choices you made, and what the human should focus on when reviewing.

---

Quick Reference#

EventWhen to Usetask:startedYou begin working on an assigned tasktask:progressYou want to report incremental progress (0-100%)task:reviewWork is done, ready for human reviewtask:completedTask is approved and fully donetask:failedSomething went wrong, task can't be completedlibrary:publishYou produced a document worth keepinglibrary:updateYou revised an existing Library documentapproval:neededYou need human permission before proceedingrequest:submitYou identified new work that should be donesession:createdYour session just startedsession:endedYour session is closing, report token usageagent:idleYou have no more tasksagent:errorYou hit a system-level error

---

Events You Will RECEIVE from Mission Control#

Mission Control sends events back to you when a human makes a decision. These arrive as messages in your session with type: "mc:event". When you receive one, act on it.

mc:review_approved#

Your work was approved. The task is now "done". Look for the next task.

Fields: taskId, taskTitle, projectId, projectName, round, qualityScore, notes, nextAction

What to do: Check if the project has more tasks in "todo" stage. If so, pick the next one and start it.

mc:changes_requested#

Your work needs revisions. The task has been moved back to "doing". Read the feedback and fix the issues.

Fields: taskId, taskTitle, round, feedback, currentStage

What to do: Read the feedback field carefully. It contains the human's specific concerns. Revise your work, then resubmit with task:review.

mc:review_rejected#

Your work was rejected. The task is back in "todo" and may be reassigned.

Fields: taskId, taskTitle, round, reason, currentStage

What to do: Read the reason. If you can address it, pick the task back up. If not, move on to other work.

mc:approval_granted#

A workflow gate you requested was approved. Resume your paused work.

Fields: approvalId, approvalType, title, resumeToken, entityType, entityId, notes, nextAction

What to do: If resumeToken is present, use it to resume the paused workflow. If nextAction is "resume_workflow", continue from where you stopped.

mc:approval_denied#

A workflow gate you requested was denied.

Fields: approvalId, approvalType, title, entityType, entityId, reason, nextAction

What to do: Read the reason. You may need to take a different approach or abandon the action.

mc:project_kickoff#

A new project was created (from an approved request or directly). You are the owner agent. Start planning.

Fields: projectId, projectName, description, priority, fromRequest, requestTitle, hint

What to do: Break the project down into tasks. Create them via POST /api/tasks with project_id set. Put tasks in "backlog" or "todo" stage. Then start working on the highest-priority one.

mc:task_assigned#

A task was assigned to you.

Fields: taskId, taskTitle, projectId, priority, currentStage, previousAgent, nextAction

What to do: If currentStage is "todo", start when ready. If "doing", continue work immediately.

mc:task_resume#

A task you own was moved back to "doing" (e.g., after changes requested).

Fields: taskId, taskTitle, fromStage, toStage, movedBy, nextAction

What to do: Resume work on this task. Check if there's review feedback in the task metadata.

mc:task_queued#

A task you own was moved to "todo" — it's queued and ready for you to pick up.

Fields: taskId, taskTitle, fromStage, movedBy, nextAction

What to do: This task is available for you to start. When you're ready, send task:started and begin work.

mc:project_activated#

A project you own was activated. Start working on its tasks.

Fields: projectId, projectName, hint

What to do: Check the hint field for the API endpoint to find available tasks. Start with the highest priority one.

mc:project_paused#

A project you own was paused. Stop work on its tasks.

Fields: projectId, projectName, reason

What to do: Stop working on tasks from this project. Focus on other projects or report idle.

mc:project_completed#

All tasks in a project are done.

Fields: projectId, projectName

What to do: Acknowledge completion. Consider publishing a summary to the Library.

mc:stall_nudge#

You haven't reported progress in a while. Mission Control wants a status update.

Fields: taskId, taskTitle, stallMinutes, hint

What to do: Send a task:progress event immediately with your current status. If you're stuck, send task:failed with the reason.

---

Outbound Events Quick Reference#

EventMeaningYour Actionmc:review_approvedWork acceptedFind next taskmc:changes_requestedRevisions neededRead feedback, fix, resubmitmc:review_rejectedWork rejectedRead reason, task back to todomc:approval_grantedGate clearedResume paused workflowmc:approval_deniedGate deniedHandle denial, try alternativemc:project_kickoffNew project, you're ownerPlan tasks, break down workmc:task_assignedTask assigned to youStart or continue workmc:task_resumeTask moved back to doingResume workmc:task_queuedTask moved to todoPick up when readymc:project_activatedProject is now activeStart working on tasksmc:project_pausedProject pausedStop work on its tasksmc:project_completedAll tasks doneAcknowledge, maybe publish summarymc:stall_nudgeNo progress reportedSend status update immediately

---

Trigger Contracts — What Happens When a Human Decides#

These are the complete end-to-end chains from a human decision in the dashboard to the expected agent response. If you receive one of these events, you MUST act on it — the human is waiting.

Request Approved → Project Kickoff#

Human action: Approves a request in the Inbox, or clicks "Convert to Project" on a request.

What Mission Control does:

1. Creates a new project in the database (status: active)
2. Links it to the original request
3. Dispatches mc:project_kickoff to the owner agent

Event you receive: mc:project_kickoff

Your required response:

1. Read the description and priority fields

2. Break the project into tasks — send POST $MISSION_CONTROL_URL/api/tasks for each one: json

   {
     "project_id": "PROJECT_ID_FROM_EVENT",
     "title": "Task name",
     "description": "What to do",
     "priority": "high",
     "pipeline_stage": "todo",
     "assigned_agent": "YOUR_AGENT_ID"
   }
   
   

3. Pick the highest-priority task and send task:started to begin work

4. If you can't plan the project (unclear requirements), send a request:submit event asking for clarification

If you don't respond: The project sits empty with zero tasks. The human sees it on the dashboard with 0% progress and no activity.

Project Activated → Start Working#

Human action: Sets a project's status to "active" (either via the Projects page or by approving a request).

What Mission Control does:

1. Updates the project status in the database
2. Dispatches mc:project_activated to the owner agent

Event you receive: mc:project_activated

Your required response:

1. Query available tasks: GET $MISSION_CONTROL_URL/api/tasks?project_id=PROJECT_ID&pipeline_stage=todo
2. If tasks exist, pick the highest-priority one and send task:started
3. If no tasks exist, create them first (same as kickoff flow above)

If you don't respond: The project shows as "active" but with no tasks moving. The stall detector will eventually flag it.

Review Approved → Next Task#

Human action: Approves a review in the Inbox.

What Mission Control does:

1. Moves the task to "done" stage
2. Checks if all project tasks are done (if so, completes the project)
3. Dispatches mc:review_approved to the agent who submitted the review

Event you receive: mc:review_approved

Your required response:

1. Check the nextTaskHint field — it contains the API URL to find the next todo task
2. If there's a next task, send task:started and begin work
3. If no more tasks in the project, send agent:idle
4. Consider publishing a progress report to the Library

If you don't respond: The completed task shows as done, but the next task in the project stays in "todo" with nobody working on it.

Changes Requested → Revise and Resubmit#

Human action: Requests changes on a review.

What Mission Control does:

1. Moves the task back to "doing" stage
2. Stores the feedback in the task metadata
3. Dispatches mc:changes_requested to the agent

Event you receive: mc:changes_requested

Your required response:

1. Read the feedback field — it contains the human's specific concerns
2. Revise your work to address each point
3. Resubmit with task:review including updated deliverables and a new work_summary that explains what you changed

If you don't respond: The task sits in "doing" with review feedback that nobody acts on. The stall detector will flag it.