docs: add Mission system design — goal-oriented autonomous threads

Missions replace routines with evolving, knowledge-accumulating autonomous agents. Unlike routines (fixed prompt, stateless), Missions: - Generate prompts from accumulated Project knowledge (lessons, playbooks, issues from prior threads) - Adapt approach when something fails repeatedly - Track progress toward a goal with success criteria - Self-manage: pause when stuck, complete when goal achieved Architecture: MissionManager with cron ticker spawns threads via ThreadManager. Meta-prompt built from mission goal + Project MemoryDocs via RetrievalEngine. Reflection feeds back automatically. 6-step implementation plan: cron trigger, meta-prompt builder, bridge wiring, CodeAct tools, progress tracking, persistence. Includes two worked examples: daily tech news briefing (ongoing) and test coverage improvement (goal-driven, self-completing). Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
2026-08-26 15:40:18 +00:00 · 2026-03-24 09:14:30 -07:00
parent 0b0e770774
commit e67f2d686d
1 changed files with 229 additions and 0 deletions
@@ -0,0 +1,229 @@
+# Missions: Goal-Oriented Autonomous Threads
+
+**Date:** 2026-03-24
+**Status:** Design → Implementation
+**Depends on:** Engine v2 Phases 1-6 (all done)
+
+---
+
+## What a Mission Is
+
+A Mission is a **Project with intent** — a persistent goal that spawns threads, accumulates knowledge, adapts its approach, and tracks progress toward completion.
+
+Unlike routines (fixed prompt, stateless, mechanical), Missions evolve:
+- Each thread is informed by all previous threads via Project-scoped MemoryDocs
+- The prompt is generated (not fixed) based on accumulated knowledge
+- The approach changes when something fails
+- The Mission can detect completion
+
+## Core Types
+
+```rust
+pub struct Mission {
+    pub id: MissionId,
+    pub project_id: ProjectId,
+    pub goal: String,
+    pub status: MissionStatus,         // Active, Paused, Completed, Failed
+
+    // Trigger
+    pub cadence: MissionCadence,       // Cron, OnEvent, Manual
+
+    // Evolving strategy
+    pub current_focus: Option<String>, // what the next thread should work on
+    pub approach_history: Vec<String>, // what we've tried
+
+    // Progress
+    pub success_criteria: Option<String>,
+    pub thread_history: Vec<ThreadId>,
+
+    // Budget
+    pub max_threads_per_day: u32,
+    pub max_total_threads: Option<u32>,
+}
+```
+
+Already defined in `crates/ironclaw_engine/src/types/mission.rs`.
+
+## Architecture
+
+```
+MissionManager (runtime/mission.rs)
+  │
+  ├── Cron ticker (tokio interval task)
+  │   └── For each Active mission with Cron cadence:
+  │       check if due → spawn_mission_thread()
+  │
+  ├── Event listener (optional)
+  │   └── Match event patterns → spawn_mission_thread()
+  │
+  └── spawn_mission_thread(mission):
+      1. Load Project's MemoryDocs (lessons, playbooks, issues)
+      2. Generate meta-prompt from goal + focus + docs + approach history
+      3. ThreadManager.spawn_thread_with_history(meta_prompt, ...)
+      4. join_thread() → outcome
+      5. Reflection runs automatically (ThreadManager handles this)
+      6. Update mission: current_focus, approach_history, thread_history
+      7. Check success criteria → maybe mark Completed
+```
+
+## Meta-Prompt Generation
+
+The key differentiator from routines. Before each thread, the Mission builds a prompt:
+
+```
+Goal: {mission.goal}
+
+## What we know (from prior threads)
+{retrieved lessons, playbooks, issues from Project MemoryDocs}
+
+## Current focus
+{mission.current_focus or "Determine the first step toward the goal"}
+
+## Previous approaches
+{mission.approach_history — what we've tried and what happened}
+
+## Instructions
+Based on the above context, take the next step toward the goal.
+Use tools to gather information, analyze data, or take actions.
+When you've completed this step, call FINAL() with:
+1. What you accomplished
+2. What you recommend as the next focus
+3. Whether the goal has been achieved
+```
+
+The response is parsed to extract:
+- Accomplishment → becomes a Summary doc
+- Next focus → updates `mission.current_focus`
+- Goal achieved → transitions mission to Completed
+
+## Implementation Plan
+
+### Step 1: MissionManager with cron trigger
+
+`crates/ironclaw_engine/src/runtime/mission.rs` — already has types, needs execution logic:
+
+- `MissionManager::new(thread_manager, store)` — holds refs to spawn threads
+- `MissionManager::start_cron_ticker()` — spawns a tokio task that checks missions every 60s
+- `MissionManager::spawn_mission_thread(mission)` — the core: build prompt, spawn thread, process result
+- `MissionManager::create_mission(goal, cadence, project_id)` — creates and stores a mission
+- `MissionManager::pause/resume/cancel_mission(id)` — lifecycle management
+
+### Step 2: Meta-prompt builder
+
+`crates/ironclaw_engine/src/runtime/mission_prompt.rs`:
+
+- Load MemoryDocs from project via RetrievalEngine
+- Build the structured prompt from mission state + docs
+- Parse the thread's FINAL() response to extract next_focus and goal_status
+
+### Step 3: Wire into bridge router
+
+`src/bridge/router.rs`:
+
+- `EngineState` holds `Arc<MissionManager>`
+- On init, load existing missions from store, start cron ticker
+- Unblock `mission_create`, `mission_list`, `mission_pause` tools (or expose as special functions in CodeAct)
+
+### Step 4: Mission tools for CodeAct
+
+The model can create and manage missions from code:
+
+```python
+# Create a mission
+mission_create(
+    goal="Monitor and improve API response times",
+    cadence="0 9 * * *",  # daily at 9am
+    success_criteria="p95 latency under 200ms for 7 days"
+)
+
+# List missions
+missions = mission_list()
+
+# Pause/resume
+mission_pause(id="...")
+mission_resume(id="...")
+```
+
+### Step 5: Progress tracking + adaptation
+
+After each mission thread completes:
+1. Parse FINAL() for next_focus recommendation
+2. If the same error appears 3+ times → change approach (add to approach_history, clear current_focus, let the next thread try fresh)
+3. If success_criteria is met → mark Completed, notify user
+4. If max_threads exceeded → mark Failed, notify user
+
+### Step 6: Mission persistence
+
+Missions stored via `Store::save_mission/load_mission/list_missions` (trait methods already defined). The HybridStore needs to persist missions to workspace (like MemoryDocs) so they survive restarts.
+
+## How This Replaces Routines
+
+| Routine feature | Mission equivalent |
+|---|---|
+| Cron schedule | `MissionCadence::Cron("0 9 * * *")` |
+| Event trigger | `MissionCadence::OnEvent { pattern }` |
+| Manual fire | `MissionCadence::Manual` + `mission_fire(id)` |
+| Fixed prompt | Meta-prompt generated from goal + project docs |
+| Notification on completion | Thread outcome → channel notification |
+| Lightweight execution | Thread with `max_iterations: 1` |
+| Full job execution | Thread with full iteration budget |
+| Guardrails (max concurrent, timeout) | `ThreadConfig` on spawned threads |
+
+The v1 `RoutineEngine` can stay for backward compatibility. New missions use the engine v2 `MissionManager`.
+
+## Example: Daily Tech News Briefing
+
+```python
+mission_create(
+    goal="Deliver a daily tech news briefing covering AI, crypto, and software engineering",
+    cadence="0 8 * * *",
+    success_criteria=None  # ongoing, never "done"
+)
+```
+
+Thread 1 (day 1):
+- Searches for news, summarizes top stories
+- Reflection: Playbook("Use web_search with freshness='pd', then llm_context for details")
+
+Thread 2 (day 2):
+- Uses the Playbook from day 1 (faster, more efficient)
+- Reflection: Lesson("Bloomberg paywalled, use Reuters/AP instead")
+
+Thread 3 (day 3):
+- Avoids Bloomberg (learned), uses Reuters
+- Reflection: Lesson("User prefers bullet points over paragraphs")
+
+Each day the briefing improves because the Mission accumulates knowledge.
+
+## Example: Improve Test Coverage
+
+```python
+mission_create(
+    goal="Increase IronClaw test coverage from 60% to 80%",
+    cadence="0 10 * * 1-5",  # weekdays at 10am
+    success_criteria="coverage >= 80% in cargo tarpaulin report"
+)
+```
+
+Thread 1: Runs `cargo tarpaulin`, identifies uncovered modules
+Thread 2: Writes tests for the most uncovered module
+Thread 3: Runs coverage again, checks progress, picks next module
+Thread N: Coverage hits 80% → Mission Completed
+
+## What Already Exists vs What's New
+
+| Component | Status |
+|---|---|
+| `Mission` type + `MissionCadence` + `MissionStatus` | ✅ Exists |
+| `Store` trait: save/load/list/update missions | ✅ Exists |
+| `MissionManager` struct | ✅ Exists (shell) |
+| `ThreadManager.spawn_thread()` | ✅ Exists |
+| `RetrievalEngine` (project-scoped doc retrieval) | ✅ Exists |
+| Reflection pipeline (produces docs) | ✅ Exists |
+| `HybridStore` persistence for MemoryDocs | ✅ Exists |
+| Cron ticker loop | ❌ NEW |
+| Meta-prompt generation from mission state + docs | ❌ NEW |
+| FINAL() response parsing for next_focus | ❌ NEW |
+| Progress tracking + adaptation | ❌ NEW |
+| Mission persistence to workspace | ❌ NEW (extend HybridStore) |
+| Mission tools for CodeAct | ❌ NEW |