Advance stages of a contract

1 files changed, 47 insertions, 2 deletions

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