From 1f853a39334cc80bb7a27142076c64ad0214c037 Mon Sep 17 00:00:00 2001
From: soryu <soryu@soryu.co>
Date: Thu, 15 Jan 2026 11:34:06 +0000
Subject: Advance stages of a contract

---
 makima/src/daemon/task/manager.rs | 49 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

(limited to 'makima/src/daemon/task')

diff --git a/makima/src/daemon/task/manager.rs b/makima/src/daemon/task/manager.rs
index e6a4e29..4ccedb2 100644
--- a/makima/src/daemon/task/manager.rs
+++ b/makima/src/daemon/task/manager.rs
@@ -708,10 +708,13 @@ makima supervisor checkpoint "Checkpoint message"
 makima supervisor checkpoints [task_id]
 ```
 
-### Contract
+### Contract & Phase Management
 ```bash
-# Get contract status
+# Get contract status (including current phase)
 makima supervisor status
+
+# Advance to the next phase (specify, plan, execute, review)
+makima supervisor advance-phase <phase>
 ```
 
 ### User Feedback
@@ -759,6 +762,48 @@ The ask command will block until the user responds (or timeout). Use this to:
 ### For "Specification" contracts (Research → Specify → Plan → Execute → Review):
 Progress through each phase, spawning tasks as needed and asking for user feedback.
 
+## Phase Management Commands
+
+Check contract status (including current phase):
+```bash
+makima supervisor status
+```
+
+Advance to the next phase:
+```bash
+makima supervisor advance-phase <phase>
+```
+
+Valid phases: `specify`, `plan`, `execute`, `review`
+
+## When to Advance Phases
+
+**IMPORTANT**: You MUST advance the contract phase as you complete work in each phase!
+
+### Simple Contracts (Plan → Execute)
+- **Plan → Execute**: When you understand the plan and are ready to spawn tasks
+- **Complete contract**: When all tasks are done/merged and PR is created
+
+### Specification Contracts (Research → Specify → Plan → Execute → Review)
+- **Research → Specify**: When requirements are understood
+- **Specify → Plan**: When specifications are written
+- **Plan → Execute**: When implementation plan is ready
+- **Execute → Review**: When all tasks are done/merged
+- **Complete contract**: After review is done and PR is created
+
+## Phase Advancement Workflow
+
+1. Complete work for current phase (spawn tasks, wait, merge)
+2. Check status: `makima supervisor status`
+3. Ask user for confirmation (recommended):
+   ```bash
+   makima supervisor ask "Ready to advance to execute phase?" --choices "Yes,Not yet"
+   ```
+4. Advance: `makima supervisor advance-phase execute`
+5. Continue with next phase work
+
+**DO NOT forget to advance phases!** The user needs to see the contract progressing.
+
 ## Key Points
 
 1. **Create a makima branch first** - use `branch "makima/{name}"` for the contract's work
-- 
cgit v1.2.3