aether-colony 3.1.1 → 3.1.3

package/.claude/commands/ant/build.md

@@ -277,14 +277,36 @@ CONSTRAINTS: (none)
    The `archaeology_context` will be injected into builder prompts in Step 5.1 (see below).
    If this step was skipped (no existing files modified), the archaeology section is omitted from builder prompts.
 
-### Step 5: Analyze Tasks and Plan Spawns
+### Step 5: Initialize Swarm Display and Analyze Tasks
 
 **YOU (the Queen) will spawn workers directly. Do NOT delegate to a single Prime Worker.**
 
-Log phase start:
+**Initialize visual swarm tracking:**
 ```bash
+# Generate unique build ID
+build_id="build-$(date +%s)"
+
+# Initialize swarm display for this build
+bash .aether/aether-utils.sh swarm-display-init "$build_id"
+
+# Log phase start
 bash .aether/aether-utils.sh activity-log "EXECUTING" "Queen" "Phase {id}: {name} - Queen dispatching workers"
+
+# Display animated header
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Phase {id}: {name}" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 10 "fungus_garden" 0
+```
+
+**Show real-time display header:**
 ```
+🔨🐜 COLONY BUILD INITIATED 🐜🔨
+═══════════════════════════════════════════════════
+Phase {id}: {name}
+Build ID: {build_id}
+
+Launching swarm display... (visual tracking enabled)
+```
+
+Analyze the phase tasks:
 
 Analyze the phase tasks:
 
@@ -330,9 +352,10 @@ Total: {N} Builders + 1 Watcher + 1 Chaos = {N+2} spawns
 
 For each Wave 1 task, use Task tool with `subagent_type="general"` and `run_in_background: true`:
 
-Log each spawn:
+Log each spawn and update swarm display:
 ```bash
 bash .aether/aether-utils.sh spawn-log "Queen" "builder" "{ant_name}" "{task_description}"
+bash .aether/aether-utils.sh swarm-display-update "{ant_name}" "builder" "excavating" "{task_description}" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 10
 ```
 
 **Builder Worker Prompt Template:**
@@ -402,9 +425,12 @@ DO NOT spawn for work you can complete in < 10 tool calls.
 Before spawning:
   1. Check: bash .aether/aether-utils.sh spawn-can-spawn {depth}
   2. Generate name: bash .aether/aether-utils.sh generate-ant-name "{caste}"
-  3. Log: bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
-  4. Use Task tool with subagent_type="general"
-  5. After completion: bash .aether/aether-utils.sh spawn-complete "{child_name}" "{status}" "{summary}"
+  3. Log spawn: bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
+  4. Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "excavating" "{task}" "{your_name}" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 10
+  5. Use Task tool with subagent_type="general"
+  6. After completion:
+     - Log completion: bash .aether/aether-utils.sh spawn-complete "{child_name}" "{status}" "{summary}"
+     - Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "completed" "{task}" "{your_name}" '{"read":5,"grep":3,"edit":2,"bash":1}' 100 "fungus_garden" 100
 
 Full spawn format: .aether/workers.md section "Spawning Sub-Workers"
 
@@ -440,11 +466,15 @@ For each spawned worker, call TaskOutput with `block: true` to wait for completi
 
 Store all results for synthesis in Step 5.6.
 
-For each completed worker, log:
+For each completed worker, log and update swarm display:
 ```bash
 bash .aether/aether-utils.sh spawn-complete "{ant_name}" "completed" "{summary}"
+bash .aether/aether-utils.sh swarm-display-update "{ant_name}" "builder" "completed" "{task_description}" "Queen" '{"read":5,"grep":3,"edit":2,"bash":1}' 100 "fungus_garden" 100
 ```
 
+**Update swarm display with accumulated tool usage:**
+As workers complete, accumulate their actual tool usage (Read, Grep, Edit, Bash counts from their activity logs) and update the swarm display to show live progress.
+
 **Only proceed to Step 5.3 after ALL Wave 1 TaskOutput calls have returned.**
 
 ### Step 5.3: Spawn Wave 2+ Workers (Sequential Waves)
@@ -457,6 +487,7 @@ Repeat Step 5.1-5.2 for each subsequent wave, waiting for previous wave to compl
 
 ```bash
 bash .aether/aether-utils.sh spawn-log "Queen" "watcher" "{watcher_name}" "Independent verification"
+bash .aether/aether-utils.sh swarm-display-update "{watcher_name}" "watcher" "observing" "Verification in progress" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 50
 ```
 
 **Watcher Worker Prompt:**
@@ -521,7 +552,9 @@ You are at depth {depth}. You MAY spawn sub-workers for:
 Spawn limits: Depth 1→4, Depth 2→2, Depth 3→0
 
 Before spawning:
-  bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
+  1. Log spawn: bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
+  2. Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "observing" "{task}" "{your_name}" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 50
+  3. After completion: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "completed" "{task}" "{your_name}" '{"read":3,"grep":2,"edit":0,"bash":0}' 100 "nursery" 100
 
 --- CRITICAL ---
 - You did NOT build this code — verify it objectively
@@ -567,6 +600,11 @@ Call TaskOutput with `block: true` using the Watcher's task_id:
 - Parse: verification_passed, issues_found, quality_score, recommendation
 - Store results for synthesis in Step 5.6
 
+**Update swarm display when Watcher completes:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "{watcher_name}" "watcher" "completed" "Verification complete" "Queen" '{"read":3,"grep":2,"edit":0,"bash":1}' 100 "nursery" 100
+```
+
 **Only proceed to Step 5.4.2 after Watcher TaskOutput has returned.**
 
 ### Step 5.4.2: Spawn Chaos Ant for Resilience Testing
@@ -577,6 +615,7 @@ Generate a chaos ant name and log the spawn:
 ```bash
 bash .aether/aether-utils.sh generate-ant-name "chaos"
 bash .aether/aether-utils.sh spawn-log "Queen" "chaos" "{chaos_name}" "Resilience testing of Phase {id} work"
+bash .aether/aether-utils.sh swarm-display-update "{chaos_name}" "chaos" "probing" "Resilience testing" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "refuse_pile" 75
 ```
 
 **Retrieve existing flags for this phase** (to avoid duplicate findings):
@@ -662,9 +701,10 @@ Log the flag:
 bash .aether/aether-utils.sh activity-log "FLAG" "Chaos" "Created blocker: {finding.title}"
 ```
 
-Log chaos ant completion:
+Log chaos ant completion and update swarm display:
 ```bash
 bash .aether/aether-utils.sh spawn-complete "{chaos_name}" "completed" "{summary}"
+bash .aether/aether-utils.sh swarm-display-update "{chaos_name}" "chaos" "completed" "Resilience testing done" "Queen" '{"read":2,"grep":1,"edit":0,"bash":0}' 100 "refuse_pile" 100
 ```
 
 **Only proceed to Step 5.5 after Chaos Ant TaskOutput has returned.**
@@ -830,7 +870,23 @@ Use AskUserQuestion to get approval. Record in events:
 
 **This step runs ONLY after synthesis is complete. All values come from actual worker results.**
 
-Display build summary based on synthesis results AND `verbose_mode` from Step 1:
+**First, render the final swarm display showing all completed workers:**
+```bash
+# Final swarm display update - mark Queen as completed
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Phase {id} complete" "Colony" '{"read":10,"grep":5,"edit":5,"bash":2}' 100 "fungus_garden" 100
+
+# Render the final swarm display
+bash .aether/aether-utils.sh swarm-display-render "$build_id"
+```
+
+The swarm display will show:
+- 🐜 All workers with their caste emojis (🔨 Builder, 👁️ Watcher, 🎲 Chaos)
+- 📖 Tool usage stats (Read, Grep, Edit, Bash counts)
+- 🏠 Chamber activity map (Fungus Garden, Nursery, Refuse Pile)
+- ✅ Progress bars at 100% for completed work
+- 🌈 Color-coded by caste
+
+**Then display build summary based on synthesis results AND `verbose_mode` from Step 1:**
 
 **If verbose_mode = false (compact output, ~12 lines):**
 

package/.claude/commands/ant/continue.md

@@ -736,6 +736,48 @@ Set `last_commit_suggestion_phase` to `{phase_id}` in COLONY_STATE.json (add the
 
 **Error handling:** If any git command fails (not a repo, merge conflict, pre-commit hook rejection), display the error output and continue to the next step. The commit suggestion is advisory only -- it never blocks the flow.
 
+Continue to Step 2.7 (Context Clear Suggestion), then to Step 2.5 (Project Completion) or Step 3 (Display Result).
+
+### Step 2.7: Context Clear Suggestion (Optional)
+
+**This step is non-blocking. Skipping does not affect phase advancement.**
+
+After committing (or skipping commit), suggest clearing context to refresh before the next phase.
+
+1. **Display the suggestion:**
+```
+──────────────────────────────────────────────────
+Context Refresh
+──────────────────────────────────────────────────
+
+State is fully persisted and committed.
+Phase {next_id} is ready to build.
+
+──────────────────────────────────────────────────
+```
+
+2. **Use AskUserQuestion:**
+```
+Clear context now?
+
+1. Yes, clear context then run /ant:build {next_id}
+2. No, continue in current context
+```
+
+3. **If option 1 ("Yes, clear context"):**
+
+   **IMPORTANT:** Claude Code does not support programmatic /clear. Display instructions:
+   ```
+   Please type: /clear
+   
+   Then run: /ant:build {next_id}
+   ```
+   
+   Record the suggestion: Set `context_clear_suggested` to `true` in COLONY_STATE.json.
+
+4. **If option 2 ("No, continue in current context"):**
+   Display: `Continuing in current context. State is saved.`
+
 Continue to Step 2.5 (Project Completion) or Step 3 (Display Result).
 
 ### Step 2.5: Project Completion
@@ -798,7 +840,7 @@ Output:
    /ant:phase {next_id}   📋 Review phase details first
    /ant:focus "<area>"    🎯 Guide colony attention
 
-💾 State persisted — safe to /clear, then run /ant:build {next_id}
+💾 State persisted — context clear suggested above
 ```
 
 **IMPORTANT:** In the "Next Steps" section above, substitute the actual phase number for `{next_id}` (calculated in Step 2 as `current_phase + 1`). For example, if advancing to phase 4, output `/ant:build 4` not `/ant:build {next_id}`.

package/.opencode/commands/ant/build.md

@@ -15,30 +15,74 @@ Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null
 
 If the command succeeds and the JSON result contains a non-empty string, display it as a one-line notice. Proceed regardless of outcome.
 
+### Step 0.6: Verify LiteLLM Proxy
+
+Check that the LiteLLM proxy is running for model routing:
+
+```bash
+curl -s http://localhost:4000/health | grep -q "healthy" && echo "Proxy healthy" || echo "Proxy not running - workers will use default model"
+```
+
+If proxy is not healthy, log a warning but continue (workers will fall back to default routing).
+
+### Step 0.5: Load Colony State
+
+Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+
+If the command fails (non-zero exit or JSON has ok: false):
+1. Parse error JSON
+2. If error code is E_FILE_NOT_FOUND: "No colony initialized. Run /ant:init first." and stop
+3. If validation error: Display error details with recovery suggestion and stop
+4. For other errors: Display generic error and suggest /ant:status for diagnostics
+
+If successful:
+1. Parse the state JSON from result field
+2. Check if goal is null - if so: "No colony initialized. Run /ant:init first." and stop
+3. Extract current_phase and phase name from plan.phases[current_phase - 1].name
+4. Display brief resumption context:
+   ```
+   🔄 Resuming: Phase X - Name
+   ```
+   (If HANDOFF.md exists, this provides orientation before the build proceeds)
+
+After displaying context, run: `bash .aether/aether-utils.sh unload-state` to release the lock.
+
 ### Step 1: Validate + Read State
 
 **Parse $ARGUMENTS:**
 1. Extract the phase number (first argument)
 2. Check remaining arguments for flags:
    - If contains `--verbose` or `-v`: set `verbose_mode = true`
-   - Otherwise: set `verbose_mode = false`
+   - If contains `--model <name>` or `-m <name>`: set `cli_model_override = <name>`
+   - Otherwise: set defaults
 
 If the phase number is empty or not a number:
 
 ```
-Usage: /ant:build <phase_number> [--verbose|-v]
+Usage: /ant:build <phase_number> [--verbose|-v] [--model <model>|-m <model>]
 
 Options:
-  --verbose, -v   Show full completion details (spawn tree, TDD, patterns)
+  --verbose, -v       Show full completion details (spawn tree, TDD, patterns)
+  --model, -m <name>  Override model for this build (one-time)
 
 Examples:
   /ant:build 1              Build Phase 1 (compact output)
   /ant:build 1 --verbose    Build Phase 1 (full details)
   /ant:build 3 -v           Build Phase 3 (full details)
+  /ant:build 1 --model glm-5    Build Phase 1 with glm-5 for all workers
 ```
 
 Stop here.
 
+**Validate CLI model override (if provided):**
+If `cli_model_override` is set:
+1. Validate the model: `bash .aether/aether-utils.sh model-profile validate "$cli_model_override"`
+2. Parse JSON result - if `.result.valid` is false:
+   - Display: `Error: Invalid model "$cli_model_override"`
+   - Display: `Valid models: {list from .result.models}`
+   - Stop here
+3. If valid: Display `Using override model: {model}`
+
 Read `.aether/data/COLONY_STATE.json`.
 
 **Auto-upgrade old state:**
@@ -235,13 +279,33 @@ CONSTRAINTS: (none)
    The `archaeology_context` will be injected into builder prompts in Step 5.1 (see below).
    If this step was skipped (no existing files modified), the archaeology section is omitted from builder prompts.
 
-### Step 5: Analyze Tasks and Plan Spawns
+### Step 5: Initialize Swarm Display and Analyze Tasks
 
 **YOU (the Queen) will spawn workers directly. Do NOT delegate to a single Prime Worker.**
 
-Log phase start:
+**Initialize visual swarm tracking:**
 ```bash
+# Generate unique build ID
+build_id="build-$(date +%s)"
+
+# Initialize swarm display for this build
+bash .aether/aether-utils.sh swarm-display-init "$build_id"
+
+# Log phase start
 bash .aether/aether-utils.sh activity-log "EXECUTING" "Queen" "Phase {id}: {name} - Queen dispatching workers"
+
+# Display animated header
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Phase {id}: {name}" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 10 "fungus_garden" 0
+```
+
+**Show real-time display header:**
+```
+🔨🐜 COLONY BUILD INITIATED 🐜🔨
+═══════════════════════════════════════════════════
+Phase {id}: {name}
+Build ID: {build_id}
+
+Launching swarm display... (visual tracking enabled)
 ```
 
 Analyze the phase tasks:
@@ -288,9 +352,10 @@ Total: {N} Builders + 1 Watcher + 1 Chaos = {N+2} spawns
 
 For each Wave 1 task, use Task tool with `subagent_type="general"` and `run_in_background: true`:
 
-Log each spawn:
+Log each spawn and update swarm display:
 ```bash
 bash .aether/aether-utils.sh spawn-log "Queen" "builder" "{ant_name}" "{task_description}"
+bash .aether/aether-utils.sh swarm-display-update "{ant_name}" "builder" "excavating" "{task_description}" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 10
 ```
 
 **Builder Worker Prompt Template:**
@@ -360,9 +425,12 @@ DO NOT spawn for work you can complete in < 10 tool calls.
 Before spawning:
   1. Check: bash .aether/aether-utils.sh spawn-can-spawn {depth}
   2. Generate name: bash .aether/aether-utils.sh generate-ant-name "{caste}"
-  3. Log: bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
-  4. Use Task tool with subagent_type="general"
-  5. After completion: bash .aether/aether-utils.sh spawn-complete "{child_name}" "{status}" "{summary}"
+  3. Log spawn: bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
+  4. Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "excavating" "{task}" "{your_name}" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 10
+  5. Use Task tool with subagent_type="general"
+  6. After completion:
+     - Log completion: bash .aether/aether-utils.sh spawn-complete "{child_name}" "{status}" "{summary}"
+     - Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "completed" "{task}" "{your_name}" '{"read":5,"grep":3,"edit":2,"bash":1}' 100 "fungus_garden" 100
 
 Full spawn format: .aether/workers.md section "Spawning Sub-Workers"
 
@@ -392,11 +460,15 @@ For each spawned worker, call TaskOutput with `block: true` to wait for completi
 
 Store all results for synthesis in Step 5.6.
 
-For each completed worker, log:
+For each completed worker, log and update swarm display:
 ```bash
 bash .aether/aether-utils.sh spawn-complete "{ant_name}" "completed" "{summary}"
+bash .aether/aether-utils.sh swarm-display-update "{ant_name}" "builder" "completed" "{task_description}" "Queen" '{"read":5,"grep":3,"edit":2,"bash":1}' 100 "fungus_garden" 100
 ```
 
+**Update swarm display with accumulated tool usage:**
+As workers complete, accumulate their actual tool usage (Read, Grep, Edit, Bash counts from their activity logs) and update the swarm display to show live progress.
+
 **Only proceed to Step 5.3 after ALL Wave 1 TaskOutput calls have returned.**
 
 ### Step 5.3: Spawn Wave 2+ Workers (Sequential Waves)
@@ -409,6 +481,7 @@ Repeat Step 5.1-5.2 for each subsequent wave, waiting for previous wave to compl
 
 ```bash
 bash .aether/aether-utils.sh spawn-log "Queen" "watcher" "{watcher_name}" "Independent verification"
+bash .aether/aether-utils.sh swarm-display-update "{watcher_name}" "watcher" "observing" "Verification in progress" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 50
 ```
 
 **Watcher Worker Prompt:**
@@ -468,7 +541,9 @@ You are at depth {depth}. You MAY spawn sub-workers for:
 Spawn limits: Depth 1→4, Depth 2→2, Depth 3→0
 
 Before spawning:
-  bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
+  1. Log spawn: bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
+  2. Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "observing" "{task}" "{your_name}" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 50
+  3. After completion: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "completed" "{task}" "{your_name}" '{"read":3,"grep":2,"edit":0,"bash":0}' 100 "nursery" 100
 
 --- CRITICAL ---
 - You did NOT build this code — verify it objectively
@@ -508,6 +583,11 @@ Call TaskOutput with `block: true` using the Watcher's task_id:
 - Parse: verification_passed, issues_found, quality_score, recommendation
 - Store results for synthesis in Step 5.6
 
+**Update swarm display when Watcher completes:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "{watcher_name}" "watcher" "completed" "Verification complete" "Queen" '{"read":3,"grep":2,"edit":0,"bash":1}' 100 "nursery" 100
+```
+
 **Only proceed to Step 5.4.2 after Watcher TaskOutput has returned.**
 
 ### Step 5.4.2: Spawn Chaos Ant for Resilience Testing
@@ -518,6 +598,7 @@ Generate a chaos ant name and log the spawn:
 ```bash
 bash .aether/aether-utils.sh generate-ant-name "chaos"
 bash .aether/aether-utils.sh spawn-log "Queen" "chaos" "{chaos_name}" "Resilience testing of Phase {id} work"
+bash .aether/aether-utils.sh swarm-display-update "{chaos_name}" "chaos" "probing" "Resilience testing" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "refuse_pile" 75
 ```
 
 **Retrieve existing flags for this phase** (to avoid duplicate findings):
@@ -592,12 +673,16 @@ Log the flag:
 bash .aether/aether-utils.sh activity-log "FLAG" "Chaos" "Created blocker: {finding.title}"
 ```
 
-Log chaos ant completion:
+Log the flag:
 ```bash
-bash .aether/aether-utils.sh spawn-complete "{chaos_name}" "completed" "{summary}"
+bash .aether/aether-utils.sh activity-log "FLAG" "Chaos" "Created blocker: {finding.title}"
 ```
 
-**Only proceed to Step 5.5 after Chaos Ant TaskOutput has returned.**
+Log chaos ant completion and update swarm display:
+```bash
+bash .aether/aether-utils.sh spawn-complete "{chaos_name}" "completed" "{summary}"
+bash .aether/aether-utils.sh swarm-display-update "{chaos_name}" "chaos" "completed" "Resilience testing done" "Queen" '{"read":2,"grep":1,"edit":0,"bash":0}' 100 "refuse_pile" 100
+```
 
 ### Step 5.5: Create Flags for Verification Failures
 
@@ -760,7 +845,23 @@ Use AskUserQuestion to get approval. Record in events:
 
 **This step runs ONLY after synthesis is complete. All values come from actual worker results.**
 
-Display build summary based on synthesis results AND `verbose_mode` from Step 1:
+**First, render the final swarm display showing all completed workers:**
+```bash
+# Final swarm display update - mark Queen as completed
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Phase {id} complete" "Colony" '{"read":10,"grep":5,"edit":5,"bash":2}' 100 "fungus_garden" 100
+
+# Render the final swarm display
+bash .aether/aether-utils.sh swarm-display-render "$build_id"
+```
+
+The swarm display will show:
+- 🐜 All workers with their caste emojis (🔨 Builder, 👁️ Watcher, 🎲 Chaos)
+- 📖 Tool usage stats (Read, Grep, Edit, Bash counts)
+- 🏠 Chamber activity map (Fungus Garden, Nursery, Refuse Pile)
+- ✅ Progress bars at 100% for completed work
+- 🌈 Color-coded by caste
+
+**Then display build summary based on synthesis results AND `verbose_mode` from Step 1:**
 
 **If verbose_mode = false (compact output, ~12 lines):**
 

package/.opencode/commands/ant/continue.md

@@ -719,6 +719,48 @@ Set `last_commit_suggestion_phase` to `{phase_id}` in COLONY_STATE.json (add the
 
 **Error handling:** If any git command fails (not a repo, merge conflict, pre-commit hook rejection), display the error output and continue to the next step. The commit suggestion is advisory only -- it never blocks the flow.
 
+Continue to Step 2.7 (Context Clear Suggestion), then to Step 2.5 (Project Completion) or Step 3 (Display Result).
+
+### Step 2.7: Context Clear Suggestion (Optional)
+
+**This step is non-blocking. Skipping does not affect phase advancement.**
+
+After committing (or skipping commit), suggest clearing context to refresh before the next phase.
+
+1. **Display the suggestion:**
+```
+──────────────────────────────────────────────────
+Context Refresh
+──────────────────────────────────────────────────
+
+State is fully persisted and committed.
+Phase {next_id} is ready to build.
+
+──────────────────────────────────────────────────
+```
+
+2. **Use AskUserQuestion:**
+```
+Clear context now?
+
+1. Yes, clear context then run /ant:build {next_id}
+2. No, continue in current context
+```
+
+3. **If option 1 ("Yes, clear context"):**
+
+   **IMPORTANT:** OpenCode does not support programmatic /clear. Display instructions:
+   ```
+   Please type: /clear
+   
+   Then run: /ant:build {next_id}
+   ```
+   
+   Record the suggestion: Set `context_clear_suggested` to `true` in COLONY_STATE.json.
+
+4. **If option 2 ("No, continue in current context"):**
+   Display: `Continuing in current context. State is saved.`
+
 Continue to Step 2.5 (Project Completion) or Step 3 (Display Result).
 
 ### Step 2.5: Project Completion
@@ -781,7 +823,7 @@ Output:
    /ant:phase {next_id}   📋 Review phase details first
    /ant:focus "<area>"    🎯 Guide colony attention
 
-💾 State persisted — safe to /clear, then run /ant:build {next_id}
+💾 State persisted — context clear suggested above
 ```
 
 **IMPORTANT:** In the "Next Steps" section above, substitute the actual phase number for `{next_id}` (calculated in Step 2 as `current_phase + 1`). For example, if advancing to phase 4, output `/ant:build 4` not `/ant:build {next_id}`.

package/.opencode/commands/ant/maturity.md

@@ -0,0 +1,92 @@
+---
+name: ant:maturity
+description: "👑🐜🏛️🐜👑 View colony maturity journey with ASCII art anthill"
+---
+
+You are the **Queen**. Display the colony's maturity journey.
+
+## Instructions
+
+### Step 1: Detect Current Milestone
+
+Run: `bash .aether/aether-utils.sh milestone-detect`
+
+Parse JSON result to get:
+- `milestone`: Current milestone name (First Mound, Open Chambers, Brood Stable, Ventilated Nest, Sealed Chambers, Crowned Anthill)
+- `version`: Computed version string
+- `phases_completed`: Number of completed phases
+- `total_phases`: Total phases in plan
+
+### Step 2: Read Colony State
+
+Read `.aether/data/COLONY_STATE.json` to get:
+- `goal`: Colony goal
+- `initialized_at`: When colony was started
+
+Calculate colony age from initialized_at to now (in days).
+
+### Step 3: Display Maturity Journey
+
+Display header:
+```
+       .-.
+      (o o)  AETHER COLONY
+      | O |  Maturity Journey
+       `-`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+👑 Goal: {goal (truncated to 50 chars)}
+🏆 Current: {milestone} ({version})
+📍 Progress: {phases_completed} of {total_phases} phases
+📅 Colony Age: {N} days
+```
+
+### Step 4: Show ASCII Art Anthill
+
+Read the ASCII art file for the current milestone:
+- First Mound → `.aether/visualizations/anthill-stages/first-mound.txt`
+- Open Chambers → `.aether/visualizations/anthill-stages/open-chambers.txt`
+- Brood Stable → `.aether/visualizations/anthill-stages/brood-stable.txt`
+- Ventilated Nest → `.aether/visualizations/anthill-stages/ventilated-nest.txt`
+- Sealed Chambers → `.aether/visualizations/anthill-stages/sealed-chambers.txt`
+- Crowned Anthill → `.aether/visualizations/anthill-stages/crowned-anthill.txt`
+
+Display the ASCII art with current milestone highlighted (bold/bright).
+
+### Step 5: Show Journey Progress Bar
+
+Display progress through all milestones:
+
+```
+Journey Progress:
+
+[█░░░░░] First Mound        (0 phases)   - Complete
+[██░░░░] Open Chambers      (1-3 phases) - Complete
+[███░░░] Brood Stable       (4-6 phases) - Complete
+[████░░] Ventilated Nest    (7-10 phases) - Current
+[█████░] Sealed Chambers    (11-14 phases)
+[██████] Crowned Anthill    (15+ phases)
+
+Next: Ventilated Nest → Sealed Chambers
+      Complete {N} more phases to advance
+```
+
+Calculate which milestones are complete vs current vs upcoming based on phases_completed.
+
+### Step 6: Show Colony Statistics
+
+Display summary stats:
+```
+Colony Statistics:
+  🐜 Phases Completed: {phases_completed}
+  📋 Total Phases: {total_phases}
+  📅 Days Active: {colony_age_days}
+  🏆 Current Milestone: {milestone}
+  🎯 Completion: {percent}%
+```
+
+### Edge Cases
+
+- If milestone file doesn't exist: Show error "Milestone visualization not found"
+- If COLONY_STATE.json missing: "No colony initialized. Run /ant:init first."
+- If phases_completed is 0: All milestones show as upcoming except First Mound