feat(tasks): implement task management system with CRUD operations

- Added a new SQL migration to create the `tasks` table with relevant fields and indexes.
- Introduced task management tools for creating, listing, and updating tasks within the system.
- Enhanced the API to support task operations, including endpoints for task creation, retrieval, updating, and deletion.
- Updated documentation to include new task tools and their usage.
- Integrated task management into the agent's workflow, allowing for better task tracking and execution.

Author: jamiepine

migrations/20260219000001_tasks.sql

@@ -0,0 +1,26 @@
+CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,
+    agent_id TEXT NOT NULL,
+    task_number INTEGER NOT NULL,
+    title TEXT NOT NULL,
+    description TEXT,
+    status TEXT NOT NULL DEFAULT 'backlog',
+    priority TEXT NOT NULL DEFAULT 'medium',
+    subtasks TEXT,
+    metadata TEXT,
+    source_memory_id TEXT,
+    worker_id TEXT,
+    created_by TEXT NOT NULL,
+    approved_at TIMESTAMP,
+    approved_by TEXT,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    completed_at TIMESTAMP,
+    UNIQUE(agent_id, task_number)
+);
+
+CREATE INDEX IF NOT EXISTS idx_tasks_agent ON tasks(agent_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+CREATE INDEX IF NOT EXISTS idx_tasks_number ON tasks(agent_id, task_number);
+CREATE INDEX IF NOT EXISTS idx_tasks_source_memory ON tasks(source_memory_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_worker ON tasks(worker_id);

prompts/en/branch.md.j2

@@ -22,6 +22,7 @@ Depending on why the channel branched, you might:
 - **Process complex input** — The user said something that requires analysis. Break it down, think through it, return your understanding.
 - **Spawn a worker** — If the user wants something done *now*, spawn a worker for it. Set a status so the channel knows what's happening. Return a summary of what you kicked off.
 - **Save for later** — If the user mentions something they want to do but not right now ("I need to update the tests at some point", "remind me to check the deploy tomorrow"), save it as a **todo** memory instead of spawning a worker. The difference is timing intent: immediate action = worker, future action = todo.
+- **Manage the task board** — For task commands (approve, list, pick up, update progress), use task tools from this branch. Channels do not manage task state directly.
 
 ## Tools
 
@@ -37,6 +38,15 @@ Forget a memory by ID. Use this when the user wants something removed, or when y
 ### spawn_worker
 If the user wants something done now and it needs execution tools (shell, file, exec), spawn a worker. Give it a specific task description with enough context to work independently. The worker won't have the conversation history — it only knows what you tell it. If the user is describing something for later rather than requesting immediate action, save a **todo** memory instead.
 
+### task_list
+List tasks on the board (optionally by status/priority) before making state changes when you need to verify references.
+
+### task_create
+Create structured tasks when the user asks to add planned work to the board.
+
+### task_update
+Update task status, priority, subtasks, metadata, or assigned worker. For "pick up #N", move `ready -> in_progress`, spawn a worker, then bind the worker ID to the task.
+
 ## Rules
 
 1. Be concise. The channel is going to read your conclusion and use it in a conversation. Don't write an essay. Return the signal, not the process.

prompts/en/tools/branch_description.md.j2

@@ -1 +1 @@
-Fork a branch to think independently. The branch gets a clone of your current conversation history and has access to memory_recall, memory_save, and memory_delete tools. It runs independently and returns a conclusion.
+Fork a branch to think independently. The branch gets a clone of your current conversation history and can use memory tools, task tools (task_create/task_list/task_update), and spawn_worker for execution handoff. It runs independently and returns a conclusion.

prompts/en/tools/task_create_description.md.j2

@@ -0,0 +1 @@
+Create a structured task on the board. Use this when a user asks to add work, capture explicit backlog items, or formalize something actionable. Prefer short titles and concrete subtasks.

prompts/en/tools/task_list_description.md.j2

@@ -0,0 +1 @@
+List tasks from the board, optionally filtered by status or priority. Use this before task updates when you need to verify a task number or current state.

prompts/en/tools/task_update_description.md.j2

@@ -0,0 +1 @@
+Update an existing task by task number. You can change status, priority, title, description, subtasks, or metadata. For worker processes, only update the task assigned to that worker.

src/agent/channel.rs

@@ -1069,6 +1069,9 @@ async fn spawn_branch(
     };
 
     let tool_server = crate::tools::create_branch_tool_server(
+        Some(state.clone()),
+        state.deps.agent_id.clone(),
+        state.deps.task_store.clone(),
         state.deps.memory_search.clone(),
         state.conversation_logger.clone(),
         state.channel_store.clone(),

src/agent/cortex.rs

@@ -13,7 +13,9 @@ use crate::error::Result;
 use crate::llm::SpacebotModel;
 use crate::memory::search::{SearchConfig, SearchMode, SearchSort};
 use crate::memory::types::{Association, MemoryType, RelationType};
+use crate::tasks::{TaskStatus, UpdateTaskInput};
 use crate::{AgentDeps, ProcessEvent, ProcessType};
+use crate::agent::worker::Worker;
 use crate::hooks::CortexHook;
 
 use rig::agent::AgentBuilder;
@@ -721,6 +723,181 @@ pub fn spawn_association_loop(deps: AgentDeps, logger: CortexLogger) -> tokio::t
     })
 }
 
+/// Spawn a background loop that picks up ready tasks when idle.
+pub fn spawn_ready_task_loop(deps: AgentDeps, logger: CortexLogger) -> tokio::task::JoinHandle<()> {
+    tokio::spawn(async move {
+        if let Err(error) = run_ready_task_loop(&deps, &logger).await {
+            tracing::error!(%error, "cortex ready-task loop exited with error");
+        }
+    })
+}
+
+async fn run_ready_task_loop(deps: &AgentDeps, logger: &CortexLogger) -> anyhow::Result<()> {
+    tracing::info!("cortex ready-task loop started");
+
+    // Let startup settle before first pickup attempt.
+    tokio::time::sleep(Duration::from_secs(10)).await;
+
+    loop {
+        let interval = (**deps.runtime_config.cortex.load()).tick_interval_secs;
+        tokio::time::sleep(Duration::from_secs(interval.max(5))).await;
+
+        if let Err(error) = pickup_one_ready_task(deps, logger).await {
+            tracing::warn!(%error, "ready-task pickup pass failed");
+        }
+    }
+}
+
+async fn pickup_one_ready_task(deps: &AgentDeps, logger: &CortexLogger) -> anyhow::Result<()> {
+    let Some(task) = deps.task_store.claim_next_ready(&deps.agent_id).await? else {
+        return Ok(());
+    };
+
+    logger.log(
+        "task_pickup_started",
+        &format!("Picked up ready task #{}", task.task_number),
+        Some(serde_json::json!({
+            "task_number": task.task_number,
+            "title": task.title,
+        })),
+    );
+
+    let prompt_engine = deps.runtime_config.prompts.load();
+    let worker_system_prompt = prompt_engine
+        .render_worker_prompt(
+            &deps.runtime_config.instance_dir.display().to_string(),
+            &deps.runtime_config.workspace_dir.display().to_string(),
+        )
+        .expect("failed to render worker prompt");
+
+    let mut task_prompt = format!("Execute task #{}: {}", task.task_number, task.title);
+    if let Some(description) = &task.description {
+        task_prompt.push_str("\n\nDescription:\n");
+        task_prompt.push_str(description);
+    }
+    if !task.subtasks.is_empty() {
+        task_prompt.push_str("\n\nSubtasks:\n");
+        for (index, subtask) in task.subtasks.iter().enumerate() {
+            let marker = if subtask.completed { "[x]" } else { "[ ]" };
+            task_prompt.push_str(&format!("{}. {} {}\n", index + 1, marker, subtask.title));
+        }
+    }
+
+    let screenshot_dir = deps.runtime_config.workspace_dir.join(".spacebot").join("screenshots");
+    let logs_dir = deps.runtime_config.workspace_dir.join(".spacebot").join("logs");
+    let _ = std::fs::create_dir_all(&screenshot_dir);
+    let _ = std::fs::create_dir_all(&logs_dir);
+
+    let browser_config = (**deps.runtime_config.browser_config.load()).clone();
+    let brave_search_key = (**deps.runtime_config.brave_search_key.load()).clone();
+    let worker = Worker::new(
+        None,
+        task_prompt,
+        worker_system_prompt,
+        deps.clone(),
+        browser_config,
+        screenshot_dir,
+        brave_search_key,
+        logs_dir,
+    );
+
+    let worker_id = worker.id;
+    deps.task_store
+        .update(
+            &deps.agent_id,
+            task.task_number,
+            UpdateTaskInput {
+                worker_id: Some(worker_id.to_string()),
+                ..Default::default()
+            },
+        )
+        .await?;
+
+    let _ = deps.event_tx.send(ProcessEvent::WorkerStarted {
+        agent_id: deps.agent_id.clone(),
+        worker_id,
+        channel_id: None,
+        task: format!("task #{}: {}", task.task_number, task.title),
+    });
+
+    let task_store = deps.task_store.clone();
+    let agent_id = deps.agent_id.to_string();
+    let event_tx = deps.event_tx.clone();
+    let logger = logger.clone();
+    tokio::spawn(async move {
+        match worker.run().await {
+            Ok(result_text) => {
+                if let Err(error) = task_store
+                    .update(
+                        &agent_id,
+                        task.task_number,
+                        UpdateTaskInput {
+                            status: Some(TaskStatus::Done),
+                            ..Default::default()
+                        },
+                    )
+                    .await
+                {
+                    tracing::warn!(%error, task_number = task.task_number, "failed to mark picked-up task done");
+                }
+
+                logger.log(
+                    "task_pickup_completed",
+                    &format!("Completed picked-up task #{}", task.task_number),
+                    Some(serde_json::json!({
+                        "task_number": task.task_number,
+                        "worker_id": worker_id.to_string(),
+                    })),
+                );
+
+                let _ = event_tx.send(ProcessEvent::WorkerComplete {
+                    agent_id: Arc::from(agent_id.as_str()),
+                    worker_id,
+                    channel_id: None,
+                    result: result_text,
+                    notify: true,
+                });
+            }
+            Err(error) => {
+                if let Err(update_error) = task_store
+                    .update(
+                        &agent_id,
+                        task.task_number,
+                        UpdateTaskInput {
+                            status: Some(TaskStatus::Ready),
+                            clear_worker_id: true,
+                            ..Default::default()
+                        },
+                    )
+                    .await
+                {
+                    tracing::warn!(%update_error, task_number = task.task_number, "failed to return task to ready after failure");
+                }
+
+                logger.log(
+                    "task_pickup_failed",
+                    &format!("Picked-up task #{} failed: {error}", task.task_number),
+                    Some(serde_json::json!({
+                        "task_number": task.task_number,
+                        "worker_id": worker_id.to_string(),
+                        "error": error.to_string(),
+                    })),
+                );
+
+                let _ = event_tx.send(ProcessEvent::WorkerComplete {
+                    agent_id: Arc::from(agent_id.as_str()),
+                    worker_id,
+                    channel_id: None,
+                    result: format!("Worker failed: {error}"),
+                    notify: true,
+                });
+            }
+        }
+    });
+
+    Ok(())
+}
+
 async fn run_association_loop(deps: &AgentDeps, logger: &CortexLogger) -> anyhow::Result<()> {
     tracing::info!("cortex association loop started");
 

src/agent/ingestion.rs

@@ -473,6 +473,9 @@ async fn process_chunk(
         crate::conversation::history::ConversationLogger::new(deps.sqlite_pool.clone());
     let channel_store = crate::conversation::ChannelStore::new(deps.sqlite_pool.clone());
     let tool_server: ToolServerHandle = crate::tools::create_branch_tool_server(
+        None,
+        deps.agent_id.clone(),
+        deps.task_store.clone(),
         deps.memory_search.clone(),
         conversation_logger,
         channel_store,

src/agent/worker.rs

@@ -174,6 +174,7 @@ impl Worker {
             self.deps.agent_id.clone(),
             self.id,
             self.channel_id.clone(),
+            self.deps.task_store.clone(),
             self.deps.event_tx.clone(),
             self.browser_config.clone(),
             self.screenshot_dir.clone(),