aether-colony 3.1.16 → 5.0.0

package/.claude/commands/ant/lay-eggs.md

@@ -11,12 +11,43 @@ Parse `$ARGUMENTS`:
 - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
 - Otherwise: set `visual_mode = true`
 
+<failure_modes>
+### Plan File Write Failure
+If writing phase plans to COLONY_STATE.json fails:
+- Do not leave partial plan data in state
+- Report what was successfully written vs. what failed
+- Recovery: user can re-run /ant:lay-eggs to regenerate plans
+
+### Goal Parsing Failure
+If the user's goal cannot be parsed into actionable phases:
+- Do not generate placeholder phases
+- Ask user to clarify or simplify the goal
+- Offer examples of well-formed goals
+</failure_modes>
+
+<success_criteria>
+Command is complete when:
+- Phase plan is written to COLONY_STATE.json with tasks and success criteria
+- Plan structure is valid (phases have tasks, tasks have descriptions)
+- User sees the plan and can approve or request changes
+</success_criteria>
+
+<read_only>
+Do not touch during lay-eggs:
+- .aether/dreams/ (user notes)
+- .aether/chambers/ (archived colonies)
+- Source code files (planning only, no implementation)
+- .env* files
+- .claude/settings.json
+</read_only>
+
 ### Step 0: Initialize Visual Mode (if enabled)
 
-If `visual_mode` is true:
+If `visual_mode` is true, run using the Bash tool with description "Initializing colony display...":
 ```bash
-# Generate session ID
+# Generate session ID and persist it for later steps
 layeggs_id="layeggs-$(date +%s)"
+echo "$layeggs_id" > .aether/data/.layeggs_session
 
 # Initialize swarm display
 bash .aether/aether-utils.sh swarm-display-init "$layeggs_id"
@@ -120,21 +151,23 @@ Write `.aether/data/constraints.json`:
 
 ### Step 6: Display Result
 
-**If visual_mode is true, render final swarm display:**
+**If visual_mode is true, render final swarm display** by running using the Bash tool with description "Updating colony display...":
 ```bash
+# Read persisted session ID from Step 0
+layeggs_id=$(cat .aether/data/.layeggs_session 2>/dev/null || echo "layeggs-$(date +%s)")
+
 bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "First eggs laid" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "nursery" 100
-bash .aether/aether-utils.sh swarm-display-render "$layeggs_id"
+bash .aether/aether-utils.sh swarm-display-text "$layeggs_id"
 ```
 
 ```
-🥚 ═══════════════════════════════════════════════════
+🥚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    F I R S T   E G G S   L A I D
-══════════════════════════════════════════════════ 🥚
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🥚
 
 👑 New colony goal:
    "{goal}"
 
-📋 Session: {session_id}
 🏆 Milestone: First Mound (v0.1.0)
 
 {If inherited knowledge:}
@@ -151,3 +184,18 @@ bash .aether/aether-utils.sh swarm-display-render "$layeggs_id"
 Include edge case handling:
 - If no prior knowledge: omit the inheritance section
 - If prior colony had no phases: allow laying eggs without entombment
+
+### Step 7: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+if [ -f .aether/data/COLONY_STATE.json ]; then
+  state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json 2>/dev/null || echo "IDLE")
+  current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+  total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+else
+  state="IDLE"
+  current_phase="0"
+  total_phases="0"
+fi
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"

package/.claude/commands/ant/maturity.md

@@ -9,7 +9,7 @@ You are the **Queen**. Display the colony's maturity journey.
 
 ### Step 1: Detect Current Milestone
 
-Run: `bash .aether/aether-utils.sh milestone-detect`
+Run using the Bash tool with description "Detecting colony milestone...": `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)
@@ -90,3 +90,13 @@ Colony Statistics:
 - 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
+
+### Step 7: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```

package/.claude/commands/ant/migrate-state.md

@@ -114,9 +114,9 @@ Format the JSON with 2-space indentation for readability.
 Output header:
 
 ```
-🚚🐜📦🐜🚚 ═══════════════════════════════════════════════════
+🚚🐜📦🐜🚚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    S T A T E   M I G R A T I O N   C O M P L E T E
-═══════════════════════════════════════════════════ 🚚🐜📦🐜🚚
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚚🐜📦🐜🚚
 ```
 
 Then output a migration summary:
@@ -151,3 +151,15 @@ All commands now use consolidated state format.
 - After v5.1 ships, this command can be removed
 - All 12+ ant commands will be updated to use the new single-file format
 - The backup directory preserves original files for rollback if needed
+
+---
+
+## Step 7: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```

package/.claude/commands/ant/oracle.md

@@ -29,7 +29,7 @@ Parse `$ARGUMENTS` to determine the action:
 
 ### Step 0.5: Initialize Visual Mode (if enabled)
 
-If `visual_mode` is true:
+If `visual_mode` is true, run using the Bash tool with description "Initializing oracle display...":
 ```bash
 # Generate session ID
 oracle_id="oracle-$(date +%s)"
@@ -41,9 +41,9 @@ bash .aether/aether-utils.sh swarm-display-update "Oracle" "oracle" "researching
 
 Display visual header:
 ```
-🔮🐜🧠🐜🔮 ═══════════════════════════════════════════════
-          O R A C L E  —  R e s e a r c h  M o d e
-═══════════════════════════════════════════════ 🔮🐜🧠🐜🔮
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔮🐜🧠🐜🔮  O R A C L E  —  R e s e a r c h  M o d e
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Oracle peering into the depths...
 ```
@@ -52,7 +52,7 @@ Oracle peering into the depths...
 
 ### Step 0b: Stop Oracle
 
-Create the stop signal file:
+Create the stop signal file by running using the Bash tool with description "Stopping oracle research...":
 
 ```bash
 mkdir -p .aether/oracle && touch .aether/oracle/.stop
@@ -96,7 +96,7 @@ Output:
 
 ```
 🔮🐜 Oracle Status
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Topic:       {topic from research.json, or "unknown"}
 Confidence:  {target_confidence}%
 Iterations:  {completed} / {max_iterations}
@@ -104,7 +104,7 @@ Started:     {started_at}
 
 Progress:
 {last 50 lines of progress.md}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   /ant:oracle stop     Halt the loop
   /ant:oracle          Start new research
@@ -121,9 +121,9 @@ This is the setup phase. The Oracle asks questions to configure the research bef
 Output the header:
 
 ```
-🔮🐜🧠🐜🔮 ═══════════════════════════════════════════════════
-   O R A C L E   A N T   —   R E S E A R C H   W I Z A R D
-═══════════════════════════════════════════════════ 🔮🐜🧠🐜🔮
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔮🐜🧠🐜🔮  O R A C L E   A N T  —  R E S E A R C H   W I Z A R D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 **If `$ARGUMENTS` is not empty and not a subcommand**, use it as the initial topic suggestion. Otherwise, the topic will be asked in Question 1.
@@ -201,7 +201,7 @@ Capture session start time:
 ORACLE_START=$(date +%s)
 ```
 
-Check for stale files:
+Check for stale files by running using the Bash tool with description "Checking for stale oracle session...":
 ```bash
 stale_check=$(bash .aether/aether-utils.sh session-verify-fresh --command oracle "" "$ORACLE_START")
 has_stale=$(echo "$stale_check" | jq -r '.stale | length')
@@ -228,7 +228,7 @@ fi
 
 ### Step 2: Configure Research
 
-Create the oracle directory structure:
+Create the oracle directory structure by running using the Bash tool with description "Setting up oracle research...":
 
 ```bash
 mkdir -p .aether/oracle/archive .aether/oracle/discoveries
@@ -238,7 +238,7 @@ Generate an ISO-8601 UTC timestamp.
 
 **Archive previous research if it exists:**
 
-Check if `.aether/oracle/progress.md` exists. If it does:
+Check if `.aether/oracle/progress.md` exists. If it does, run using the Bash tool with description "Archiving previous research...":
 
 ```bash
 DATE=$(date +%Y-%m-%d)
@@ -292,7 +292,7 @@ Use the Write tool to write `.aether/oracle/progress.md`:
 
 #### Step 2.5: Verify Oracle Files Are Fresh
 
-Verify that progress.md and research.json were created successfully:
+Verify that progress.md and research.json were created successfully by running using the Bash tool with description "Verifying oracle files...":
 ```bash
 verify_result=$(bash .aether/aether-utils.sh session-verify-fresh --command oracle "" "$ORACLE_START")
 fresh_count=$(echo "$verify_result" | jq -r '.fresh | length')
@@ -329,7 +329,7 @@ Output the research configuration summary:
 
 Now launch the loop. Try tmux first, fall back to manual.
 
-**Try tmux:**
+**Try tmux** by running using the Bash tool with description "Launching oracle in tmux...":
 
 ```bash
 tmux new-session -d -s oracle "cd $(pwd) && bash .aether/oracle/oracle.sh; echo ''; echo '🔮🐜 Oracle loop finished. Press any key to close.'; read -n1" 2>/dev/null && echo "TMUX_OK" || echo "TMUX_FAIL"
@@ -376,4 +376,12 @@ Stop here.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```
+
 Stop here.

package/.claude/commands/ant/organize.md

@@ -44,12 +44,12 @@ If no active signals after filtering:
   (no active pheromones)
 ```
 
-### Step 3: Spawn Archivist (Architect-Ant)
+### Step 3: Spawn Archivist (Keeper-Ant)
 
-Read `.aether/workers.md` and extract the `## Architect` section.
+Read `.aether/workers.md` and extract the `## Keeper` section.
 
-Spawn via **Task tool** with `subagent_type="aether-architect"`:
-# FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are an Architect Ant - synthesizes knowledge and coordinates documentation."
+Spawn via **Task tool** with `subagent_type="aether-keeper"`:
+# FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are a Keeper Ant - curates knowledge and synthesizes patterns."
 
 ```
 --- WORKER SPEC ---
@@ -116,14 +116,14 @@ Check for configuration that may not be connected:
 Produce your report in this exact structure:
 
 CODEBASE HYGIENE REPORT
-========================
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Project: {goal}
 Scanned: {timestamp}
 Confidence threshold: HIGH findings are actionable, MEDIUM/LOW are informational
 
 HIGH CONFIDENCE FINDINGS
--------------------------
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 {For each HIGH confidence finding:}
   [{category}] {description}
     Evidence: {what data/observation supports this}
@@ -132,7 +132,7 @@ HIGH CONFIDENCE FINDINGS
 {If no HIGH findings: "No high-confidence hygiene issues detected."}
 
 MEDIUM CONFIDENCE OBSERVATIONS
--------------------------------
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 {For each MEDIUM confidence finding:}
   [{category}] {description}
     Evidence: {what data/observation supports this}
@@ -141,14 +141,14 @@ MEDIUM CONFIDENCE OBSERVATIONS
 {If no MEDIUM findings: "No medium-confidence observations."}
 
 LOW CONFIDENCE NOTES
----------------------
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 {For each LOW confidence finding:}
   [{category}] {description}
 
 {If no LOW findings: "No low-confidence notes."}
 
 SUMMARY
---------
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   High: {count} actionable findings
   Medium: {count} observations
   Low: {count} notes
@@ -165,23 +165,22 @@ CONSTRAINTS:
 
 ### Step 4: Display Report
 
-After the architect-ant returns, display header:
+After the keeper-ant returns, display header:
 
 ```
-🧹🐜🏛️🐜🧹 ═══════════════════════════════════════════════════
+🧹🐜🏛️🐜🧹 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    C O D E B A S E   H Y G I E N E   R E P O R T
-═══════════════════════════════════════════════════ 🧹🐜🏛️🐜🧹
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🧹🐜🏛️🐜🧹
 ```
 
-Then display using Bash tool (white -- architect color):
-
-```
-bash -c 'printf "\e[37m+=====================================================+\e[0m\n"'
-bash -c 'printf "\e[37m|  CODEBASE HYGIENE REPORT                            |\e[0m\n"'
-bash -c 'printf "\e[37m+=====================================================+\e[0m\n\n"'
+Then display using Bash tool with description "Displaying hygiene report header...":
+```bash
+bash -c 'printf "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"'
+bash -c 'printf "   C O D E B A S E   H Y G I E N E   R E P O R T\n"'
+bash -c 'printf "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n"'
 ```
 
-Then display the architect-ant's full report verbatim.
+Then display the keeper-ant's full report verbatim.
 
 ### Step 5: Persist Report
 
@@ -203,7 +202,7 @@ Next:
 
 ### Step 6: Log Activity
 
-Use the Bash tool to run:
+Use the Bash tool with description "Logging hygiene activity..." to run:
 ```
 bash .aether/aether-utils.sh activity-log "COMPLETE" "queen" "Hygiene report generated"
 ```
@@ -216,3 +215,13 @@ All state persisted. Safe to /clear context if needed.
   Report: .aether/data/hygiene-report.md
   Resume: /ant:resume-colony
 ```
+
+### Step 7: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```

package/.claude/commands/ant/pause-colony.md

@@ -13,7 +13,7 @@ Parse `$ARGUMENTS`:
 
 ### Step 0: Initialize Visual Mode (if enabled)
 
-If `visual_mode` is true:
+If `visual_mode` is true, run using the Bash tool with description "Initializing pause display...":
 ```bash
 # Generate session ID
 pause_id="pause-$(date +%s)"
@@ -178,31 +178,31 @@ Continue to Step 5.
 
 ### Step 4.8: Update Context Document
 
-Log this pause activity to `.aether/CONTEXT.md`:
+Log this pause activity to `.aether/CONTEXT.md` by running using the Bash tool with description "Updating context document...":
 
 ```bash
 bash .aether/aether-utils.sh context-update activity "pause-colony" "Colony paused — handoff created" "—"
 ```
 
-Update safe-to-clear status:
+Update safe-to-clear status by running using the Bash tool with description "Marking safe to clear...":
 ```bash
 bash .aether/aether-utils.sh context-update safe-to-clear "YES" "Colony paused — safe to /clear, run /ant:resume-colony to continue"
 ```
 
 ### Step 5: Display Confirmation
 
-**If visual_mode is true, render final swarm display:**
+**If visual_mode is true, render final swarm display** by running using the Bash tool with description "Updating pause display...":
 ```bash
 bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Colony paused" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "fungus_garden" 100
-bash .aether/aether-utils.sh swarm-display-render "$pause_id"
+bash .aether/aether-utils.sh swarm-display-text "$pause_id"
 ```
 
 Output header:
 
 ```
-💾🐜⏸️🐜💾 ═══════════════════════════════════════════════════
+💾🐜⏸️🐜💾 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    C O L O N Y   P A U S E D
-═══════════════════════════════════════════════════ 💾🐜⏸️🐜💾
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 💾🐜⏸️🐜💾
 ```
 
 Then output:
@@ -235,3 +235,13 @@ If option 1 selected: proceed to run /ant:resume-colony flow
 If option 2 selected: run /ant:lay-eggs flow
 If option 3 selected: display "Run /ant:resume-colony when ready to continue, or /ant:lay-eggs to start fresh"
 ```
+
+### Step 6: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```

package/.claude/commands/ant/phase.md

@@ -35,9 +35,9 @@ Find the phase by ID in `plan.phases`.
 Output this header:
 
 ```
-📝🐜📍🐜📝 ═══════════════════════════════════════════════════
-   P H A S E   {id}   D E T A I L S
-═══════════════════════════════════════════════════ 📝🐜📍🐜📝
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📝🐜📍🐜📝  P H A S E   {id}   D E T A I L S
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 Then display:
@@ -55,13 +55,22 @@ Then display:
 ✅ Success Criteria:
    • <criterion>
 
-─────────────────────────────────────────────────────
-🐜 Next Steps:
+──────────────────────────────────────────────────
+🐜 Next Up
+──────────────────────────────────────────────────
    /ant:build <id>       🔨 Phase <id>: <phase_name>
    /ant:phase <next_id>  📋 Phase <next_id>: <next_phase_name> (only if not last phase)
    /ant:status           📊 Colony status
 ```
 
+After displaying phase details, generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```
+
 Status icons: `[ ]` pending, `[~]` in_progress, `[✓]` completed
 
 ### Step 3b: List View
@@ -69,9 +78,9 @@ Status icons: `[ ]` pending, `[~]` in_progress, `[✓]` completed
 Output this header:
 
 ```
-📝🐜📍🐜📝 ═══════════════════════════════════════════════════
-   A L L   P H A S E S
-═══════════════════════════════════════════════════ 📝🐜📍🐜📝
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📝🐜📍🐜📝  A L L   P H A S E S
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 Then display all phases as a summary:

package/.claude/commands/ant/plan.md

@@ -18,14 +18,13 @@ If `visual_mode` is true:
 # Generate session ID
 plan_id="plan-$(date +%s)"
 
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$plan_id"
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Generating colony plan" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+# Initialize swarm display (consolidated)
+bash .aether/aether-utils.sh swarm-display-init "$plan_id" && bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Generating colony plan" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
 ```
 
 ### Step 0.5: Version Check (Non-blocking)
 
-Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
+Run using the Bash tool with description "Checking colony version...": `bash .aether/aether-utils.sh version-check-cached 2>/dev/null || true`
 
 If the command succeeds and the JSON result contains a non-empty string, display it as a one-line notice. Proceed regardless of outcome.
 
@@ -427,6 +426,11 @@ Read current COLONY_STATE.json, then update:
 
 Write COLONY_STATE.json.
 
+Validate the state file:
+```bash
+bash .aether/aether-utils.sh validate-state colony
+```
+
 Log: `bash .aether/aether-utils.sh activity-log "PLAN_COMPLETE" "queen" "Plan finalized with {confidence}% confidence"`
 
 Update watch-status.txt:
@@ -451,18 +455,17 @@ bash .aether/aether-utils.sh session-update "/ant:plan" "/ant:build 1" "Plan gen
 
 ### Step 7: Display Plan
 
-**If visual_mode is true, render final swarm display:**
+**If visual_mode is true, render final swarm display (consolidated):**
 ```bash
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Plan generated" "Colony" '{"read":8,"grep":4,"edit":2,"bash":1}' 100 "fungus_garden" 100
-bash .aether/aether-utils.sh swarm-display-render "$plan_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Plan generated" "Colony" '{"read":8,"grep":4,"edit":2,"bash":1}' 100 "fungus_garden" 100 && bash .aether/aether-utils.sh swarm-display-text "$plan_id"
 ```
 
 Read `plan.phases` from COLONY_STATE.json and display:
 
 ```
-📊🐜🗺️🐜📊 ═══════════════════════════════════════════════════
+📊🐜🗺️🐜📊 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    C O L O N Y   P L A N
-═══════════════════════════════════════════════════ 📊🐜🗺️🐜📊
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊🐜🗺️🐜📊
 
 👑 Goal: {goal}
 
@@ -496,6 +499,14 @@ Read `plan.phases` from COLONY_STATE.json and display:
 
 Status icons: pending = `[ ]`, in_progress = `[~]`, completed = `[✓]`
 
+After displaying the plan, generate the state-based Next Up block:
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```
+
 ---
 
 ## Confidence Scoring Reference

package/.claude/commands/ant/redirect.md

@@ -1,9 +1,9 @@
 ---
 name: ant:redirect
-description: "⚠️🐜🚧🐜⚠️ Emit REDIRECT signal to warn colony away from patterns"
+description: "Emit REDIRECT signal to warn colony away from patterns"
 ---
 
-You are the **Queen**. Add an AVOID constraint.
+You are the **Queen**. Emit a REDIRECT pheromone signal.
 
 ## Instructions
 
@@ -14,48 +14,45 @@ The pattern to avoid is: `$ARGUMENTS`
 If `$ARGUMENTS` empty -> show usage: `/ant:redirect <pattern to avoid>`, stop.
 If content > 500 chars -> "Redirect content too long (max 500 chars)", stop.
 
-### Step 2: Read + Update Constraints
+Parse optional flags from `$ARGUMENTS`:
+- `--ttl <value>`: signal lifetime (e.g., `2h`, `1d`, `7d`). Default: `phase_end`.
+- Strip flags from content before using it as the pattern.
+
+### Step 2: Write Signal
 
 Read `.aether/data/COLONY_STATE.json`.
 If `goal: null` -> "No colony initialized.", stop.
 
-Read `.aether/data/constraints.json`. If file doesn't exist, create it with:
-```json
-{"version": "1.0", "focus": [], "constraints": []}
-```
-
-Generate constraint ID: `c_<unix_timestamp_ms>`
-
-Append to `constraints` array:
-```json
-{
-  "id": "<generated_id>",
-  "type": "AVOID",
-  "content": "<pattern to avoid>",
-  "source": "user:redirect",
-  "created_at": "<ISO-8601 timestamp>"
-}
+Run using the Bash tool with description "Setting colony redirect...":
+```bash
+bash .aether/aether-utils.sh pheromone-write REDIRECT "<content>" --strength 0.9 --reason "User warned colony away from pattern" --ttl <ttl>
 ```
 
-If `constraints` array exceeds 10 entries, remove the oldest entries to keep only 10.
+Parse the returned JSON for the signal ID.
 
-Write constraints.json.
+### Step 3: Get Active Counts
 
-### Step 3: Confirm
+Run using the Bash tool with description "Counting active signals...":
+```bash
+bash .aether/aether-utils.sh pheromone-count
+```
 
-Output header:
+### Step 4: Confirm
 
+Output (3-4 lines, no banners):
 ```
-⚠️🐜🚧🐜⚠️ ═══════════════════════════════════════════════════
-   R E D I R E C T   S I G N A L
-═══════════════════════════════════════════════════ ⚠️🐜🚧🐜⚠️
-```
-
-Then output:
+REDIRECT signal emitted
+  Avoid: "<content truncated to 60 chars>"
+  Strength: 0.9 | Expires: <phase end or ttl value>
+  Active signals: <focus_count> FOCUS, <redirect_count> REDIRECT, <feedback_count> FEEDBACK
 ```
-🚫 REDIRECT signal emitted
 
-   Avoid: "{content preview}"
+### Step 5: Next Up
 
-🐜 Colony warned away from this pattern.
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
 ```