aether-colony 3.1.5 → 3.1.16

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

@@ -3,11 +3,27 @@ name: ant:plan
 description: "📊🐜🗺️🐜📊 Show project plan or generate project-specific phases"
 ---
 
-You are the **Queen**. Orchestrate iterative research and planning until 95% confidence.
+You are the **Queen**. Orchestrate research and planning until 80% confidence (maximum 4 iterations).
 
 ## Instructions
 
-### Step 0: Version Check (Non-blocking)
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# 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
+```
+
+### Step 0.5: Version Check (Non-blocking)
 
 Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
 
@@ -76,7 +92,7 @@ AETHER COLONY :: PLANNING
 State: PLANNING
 Phase: 0/0 (generating plan)
 Confidence: 0%
-Iteration: 0/50
+Iteration: 0/4
 
 Active Workers:
   [Research] Starting...
@@ -93,9 +109,9 @@ Progress
 
 [                    ] 0%
 
-Target: 95% confidence
+Target: 80% confidence
 
-Iteration: 0/50
+Iteration: 0/4
 Gaps: (analyzing...)
 ```
 
@@ -104,76 +120,162 @@ Log start:
 bash .aether/aether-utils.sh activity-log "PLAN_START" "queen" "Iterative planning loop initiated for goal"
 ```
 
-### Step 4: Iterative Research/Planning Loop
+### Step 3.5: Load Territory Survey
+
+Check if territory survey exists before research:
+
+```bash
+ls .aether/data/survey/*.md 2>/dev/null
+```
+
+**If survey exists:**
+1. **Always read PATHOGENS.md first** — understand known concerns before planning
+2. Read other relevant docs based on goal keywords:
+
+| Goal Contains | Additional Documents |
+|---------------|---------------------|
+| UI, frontend, component, page | DISCIPLINES.md, CHAMBERS.md |
+| API, backend, endpoint | BLUEPRINT.md, DISCIPLINES.md |
+| database, schema, model | BLUEPRINT.md, PROVISIONS.md |
+| test, spec | SENTINEL-PROTOCOLS.md, DISCIPLINES.md |
+| integration, external | TRAILS.md, PROVISIONS.md |
+| refactor, cleanup | PATHOGENS.md, BLUEPRINT.md |
+
+**Inject survey context into scout and planner prompts:**
+- Include key patterns from DISCIPLINES.md
+- Reference architecture from BLUEPRINT.md
+- Note tech stack from PROVISIONS.md
+- Flag concerns from PATHOGENS.md
+
+**Display:**
+```
+🗺️ Territory survey loaded — incorporating context into planning
+```
+
+**If no survey:** Continue without survey context (scouts will do fresh exploration)
+
+### Step 4: Research and Planning Loop
 
 Initialize tracking:
 - `iteration = 0`
 - `confidence = 0`
 - `gaps = []` (list of knowledge gaps)
-- `stuck_counts = {}` (gap_id -> count of iterations without progress)
 - `plan_draft = null`
 - `last_confidence = 0`
 - `stall_count = 0` (consecutive iterations with < 5% improvement)
 
-**Loop (max 50 iterations):**
+**Loop (max 4 iterations, 2 agents per iteration: 1 scout + 1 planner):**
 
 ```
-while iteration < 50 AND confidence < 95:
+while iteration < 4 AND confidence < 80:
     iteration += 1
 
-    # === RESEARCH PHASE ===
+    # === AUTO-BREAK CHECKS (no user prompt needed) ===
+    if iteration > 1:
+        if confidence >= 80:
+            Log: "Confidence threshold reached ({confidence}%), finalizing plan"
+            break
+        if stall_count >= 2:
+            Log: "Planning stalled at {confidence}%, finalizing current plan"
+            break
+
+    # === RESEARCH PHASE (always runs — 1 scout per iteration) ===
+
+    if iteration == 1:
+
+        # Broad exploration on first pass
+        Spawn Research Scout via Task tool with subagent_type="aether-scout":
+
+        """
+        You are a Scout Ant in the Aether Colony.
+
+        --- MISSION ---
+        Research the codebase to understand what exists and how it works.
+
+        Goal: "{goal}"
+        Iteration: {iteration}/4
+
+        --- EXPLORATION AREAS ---
+        Cover ALL of these in a single pass:
+        1. Core architecture, entry points, and main modules
+        2. Business logic and domain models
+        3. Testing patterns and quality practices
+        4. Configuration, dependencies, and infrastructure
+        5. Edge cases, error handling, and validation
+
+        --- TOOLS ---
+        Use: Glob, Grep, Read, WebSearch, WebFetch
+        Do NOT use: Task, Write, Edit
+
+        --- OUTPUT CONSTRAINTS ---
+        Maximum 5 findings (prioritize by impact on the goal).
+        Maximum 2 sentences per finding.
+        Maximum 3 knowledge gaps identified.
+
+        --- OUTPUT FORMAT ---
+        Return JSON:
+        {
+          "findings": [
+            {"area": "...", "discovery": "...", "source": "file or search"}
+          ],
+          "gaps_remaining": [
+            {"id": "gap_N", "description": "..."}
+          ],
+          "overall_knowledge_confidence": 0-100
+        }
+        """
 
-    Spawn Research Ant (Scout) via Task tool with subagent_type="general-purpose":
+    else:
 
-    """
-    You are a Scout Ant in the Aether Colony.
+        # Gap-focused research on subsequent passes
+        Spawn Gap-Focused Scout via Task tool with subagent_type="aether-scout":
 
-    --- MISSION ---
-    Research the codebase and domain to fill knowledge gaps for planning.
+        """
+        You are a Scout Ant in the Aether Colony (gap-focused research).
 
-    Goal: "{goal}"
-    Iteration: {iteration}/50
-
-    {if gaps is not empty:}
-    --- SPECIFIC GAPS TO INVESTIGATE ---
-    Focus ONLY on these gaps:
-    {for each gap in gaps:}
-      - {gap.id}: {gap.description}
-    {end for}
-    {else:}
-    --- INITIAL EXPLORATION ---
-    This is iteration 1. Explore:
-    1. Codebase structure (Glob for key files)
-    2. Existing patterns and conventions
-    3. Dependencies and tech stack
-    4. Any existing tests or docs
-    {end if}
+        --- MISSION ---
+        Investigate ONLY these specific knowledge gaps. Do not explore broadly.
 
-    --- TOOLS ---
-    Use: Glob, Grep, Read, WebSearch, WebFetch
-    Do NOT use: Task, Write, Edit
+        Goal: "{goal}"
+        Iteration: {iteration}/4
 
-    --- OUTPUT FORMAT ---
-    Return JSON:
-    {
-      "findings": [
-        {"area": "...", "discovery": "...", "confidence": 0-100}
-      ],
-      "gaps_remaining": [
-        {"id": "gap_N", "description": "..."}
-      ],
-      "gaps_resolved": ["gap_1", "gap_2"],
-      "overall_knowledge_confidence": 0-100
-    }
-    """
+        --- GAPS TO INVESTIGATE ---
+        {for each gap in gaps:}
+          - {gap.id}: {gap.description}
+        {end for}
+
+        --- TOOLS ---
+        Use: Glob, Grep, Read, WebSearch, WebFetch
+        Do NOT use: Task, Write, Edit
 
-    Parse research results. Update gaps list.
+        --- OUTPUT CONSTRAINTS ---
+        Maximum 3 findings (one per gap investigated).
+        Maximum 2 sentences per finding.
+        Only report gaps that are STILL unresolved after your research.
 
-    Log: `bash .aether/aether-utils.sh activity-log "RESEARCH" "scout" "Iteration {iteration}: {summary}"`
+        --- OUTPUT FORMAT ---
+        Return JSON:
+        {
+          "findings": [
+            {"area": "...", "discovery": "...", "source": "file or search"}
+          ],
+          "gaps_remaining": [
+            {"id": "gap_N", "description": "..."}
+          ],
+          "gaps_resolved": ["gap_1", "gap_2"],
+          "overall_knowledge_confidence": 0-100
+        }
+        """
 
-    # === PLANNING PHASE ===
+    # Wait for scout to complete.
+    # Update gaps list from scout results.
 
-    Spawn Planning Ant (Route-Setter) via Task tool with subagent_type="general-purpose":
+    Log: `bash .aether/aether-utils.sh activity-log "RESEARCH" "scout" "Iteration {iteration}: {scout.findings.length} findings, {scout.gaps_remaining.length} gaps"`
+
+    # === PLANNING PHASE (always runs — 1 planner per iteration) ===
+
+    Spawn Planning Ant (Route-Setter) via Task tool with subagent_type="aether-route-setter":
+    # FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are a Route-Setter Ant - creates structured phase plans and analyzes dependencies."
 
     """
     You are a Route-Setter Ant in the Aether Colony.
@@ -182,7 +284,7 @@ while iteration < 50 AND confidence < 95:
     Create or refine a project plan based on research findings.
 
     Goal: "{goal}"
-    Iteration: {iteration}/50
+    Iteration: {iteration}/4
 
     --- PLANNING DISCIPLINE ---
     Read .aether/planning.md for full reference.
@@ -219,7 +321,10 @@ while iteration < 50 AND confidence < 95:
     This enables TRUE EMERGENCE - different approaches based on context.
 
     --- RESEARCH FINDINGS ---
-    {research_results.findings formatted}
+    {scout.findings formatted — compact, max 5 items}
+
+    Remaining Gaps:
+    {gaps formatted — compact, max 3 items}
 
     --- CURRENT PLAN DRAFT ---
     {if plan_draft:}
@@ -228,18 +333,19 @@ while iteration < 50 AND confidence < 95:
     No plan yet. Create initial draft.
     {end if}
 
-    --- REMAINING GAPS ---
-    {gaps_remaining}
-
     --- INSTRUCTIONS ---
     1. If no plan exists, create 3-6 phases with concrete tasks
-    2. Each task must have: exact file paths, steps, expected outputs
-    3. If plan exists, refine based on NEW information only
-    4. Rate confidence across 5 dimensions
-    5. Explain what changed from last iteration
+    2. If plan exists, refine based on NEW information only
+    3. Rate confidence across 5 dimensions
+    4. Keep response concise — no verbose explanations
 
     Do NOT assign castes to tasks - describe the work only.
 
+    --- OUTPUT CONSTRAINTS ---
+    Maximum 6 phases. Maximum 4 tasks per phase.
+    Maximum 2 sentence description per task.
+    Confidence dimensions as single numbers, not paragraphs.
+
     --- OUTPUT FORMAT ---
     Return JSON:
     {
@@ -271,7 +377,7 @@ while iteration < 50 AND confidence < 95:
         "effort": 0-100,
         "overall": 0-100
       },
-      "delta_reasoning": "What NEW information changed the plan",
+      "delta_reasoning": "One sentence: what changed from last iteration",
       "unresolved_gaps": ["...", "..."]
     }
     """
@@ -285,64 +391,33 @@ while iteration < 50 AND confidence < 95:
     Update `.aether/data/watch-status.txt` with current state.
     Update `.aether/data/watch-progress.txt` with progress bar.
 
-    # === ANTI-STUCK CHECKS ===
-
-    # Check 1: Gap stuck detection
-    for each gap in gaps:
-        if gap was in previous iteration's gaps:
-            stuck_counts[gap.id] += 1
-            if stuck_counts[gap.id] >= 3:
-                mark gap as "needs_human_input"
-                remove from active gaps
+    # === STALL TRACKING ===
 
-    # Check 2: Stall detection
     delta = confidence - last_confidence
     if delta < 5:
         stall_count += 1
     else:
         stall_count = 0
 
-    if stall_count >= 3 AND iteration > 5:
-        # Stalled - ask user
-        Display current plan and confidence
-        Ask: "Planning has stalled at {confidence}%. Options:"
-        1. Continue iterating (may not improve)
-        2. Accept current plan
-        3. Provide guidance on: {gaps marked needs_human_input}
-
-        if user chooses "accept" OR force_accept:
-            break loop
-        if user provides guidance:
-            add guidance to gaps as FOCUS constraint
-            reset stall_count
-
-    # Check 3: Diminishing returns
-    if delta < 2 AND iteration > 10:
-        Display: "Approaching local maximum at {confidence}%."
-        Ask: "Continue or accept current plan?"
-        if user accepts:
-            break loop
-
     last_confidence = confidence
 ```
 
-**After loop exits:**
+**After loop exits (auto-finalize, no user prompt needed):**
 
-If `iteration == 50` and `confidence < 95`:
 ```
-Planning reached maximum iterations.
-
-Current confidence: {confidence}%
-Unresolved gaps:
-{list gaps marked needs_human_input}
+Planning complete after {iteration} iteration(s).
 
-Recommendation: {proceed if confidence > 70, else get human input}
+Confidence: {confidence}%
+{if gaps remain:}
+Note: {gaps.length} knowledge gap(s) deferred — these can be resolved during builds.
+{end if}
 ```
-Ask user to accept or provide input.
+
+Proceed directly to Step 5. No user confirmation needed — the plan auto-finalizes.
 
 ### Step 5: Finalize Plan
 
-Once plan is accepted (confidence >= 95 OR user approved):
+Once loop exits (confidence >= 80, max iterations reached, or stall detected):
 
 Read current COLONY_STATE.json, then update:
 - Set `plan.phases` to the final phases array
@@ -366,7 +441,21 @@ Confidence: {confidence}%
 Ready to build.
 ```
 
-### Step 6: Display Plan
+### Step 6: Update Session
+
+Update the session tracking file to enable `/ant:resume` after context clear:
+
+```bash
+bash .aether/aether-utils.sh session-update "/ant:plan" "/ant:build 1" "Plan generated with {confidence}% confidence, {N} phases"
+```
+
+### Step 7: Display Plan
+
+**If visual_mode is true, render final swarm display:**
+```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"
+```
 
 Read `plan.phases` from COLONY_STATE.json and display:
 
@@ -423,18 +512,22 @@ Each dimension rated 0-100%:
 
 **Overall** = weighted average (knowledge 25%, requirements 25%, risks 20%, dependencies 15%, effort 15%)
 
-**Target: 95%** - High confidence plan ready for autonomous execution.
+**Target: 80%** - Sufficient confidence for autonomous execution. Higher confidence is achieved during builds as gaps are resolved.
 
 ---
 
-## Anti-Stuck Safeguards
+## Auto-Termination Safeguards
+
+The planning loop terminates automatically without requiring user input:
+
+1. **Confidence Threshold**: Loop exits when overall confidence reaches 80%
 
-1. **Gap Tracking**: Each gap has a `stuck_count`. After 3 iterations without progress, marked "needs human input"
+2. **Hard Iteration Cap**: Maximum 4 iterations (8 subagents total: 1 scout + 1 planner per iteration)
 
-2. **Stall Detection**: If confidence improves < 5% for 3 consecutive iterations after iteration 5, pause for user decision
+3. **Stall Detection**: If confidence improves < 5% for 2 consecutive iterations, auto-finalize current plan
 
-3. **Diminishing Returns**: If confidence improves < 2% after iteration 10, offer to accept current plan
+4. **Single Scout Research**: One researcher per iteration (broad on iteration 1, gap-focused on 2+) — no parallel Alpha/Beta or synthesis agent
 
-4. **Focused Research**: Research Ant receives SPECIFIC gaps, not open-ended exploration (after iteration 1)
+5. **Compressed Output**: Subagents limited to 5 findings max, 2-sentence summaries, compact JSON
 
-5. **Escape Hatch**: `/ant:plan --accept` accepts current plan regardless of confidence
+6. **Escape Hatch**: `/ant:plan --accept` accepts current plan regardless of confidence

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

@@ -7,7 +7,23 @@ You are the **Queen Ant Colony**. Restore state from a paused session.
 
 ## Instructions
 
-### Step 0: Version Check (Non-blocking)
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+resume_id="resume-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$resume_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Resuming colony" "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`
 
@@ -77,6 +93,12 @@ CONTEXT FROM HANDOFF
 NEXT ACTIONS
 ```
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Colony resumed" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$resume_id"
+```
+
 Route to next action based on state:
 - If state is `READY` and there's a pending phase -> suggest `/ant:build <phase>`
 - If state is `EXECUTING` -> note that a build was interrupted, suggest restarting with `/ant:build <phase>`

package/.claude/commands/ant/resume.md

@@ -0,0 +1,159 @@
+# /ant:resume — Resume Previous Session
+
+Resume work from where you left off after a context clear or new session start.
+
+## When to Use
+
+- After running `/clear` and wanting to continue previous work
+- When opening a new Claude Code session with existing colony state
+- To check what you were working on and pick up where you left off
+
+## What It Does
+
+1. Reads `.aether/data/session.json` to understand previous activity
+2. Reads `COLONY_STATE.json` to verify colony status
+3. Checks `TO-DOs.md` for relevant pending work
+4. Presents a summary and asks if you want to resume
+5. If yes: Restores context and suggests next step
+6. If no: Offers to start fresh with `/ant:init`
+
+## Usage
+
+```bash
+/ant:resume
+```
+
+## Session Recovery Flow
+
+### Step 1: Check for Existing Session
+
+```bash
+bash .aether/aether-utils.sh session-read
+```
+
+Check if session exists and whether it's stale (> 24 hours old).
+
+### Step 2: If No Session Found
+
+Display:
+```
+📋 SESSION RESUME
+
+No previous session found.
+
+Would you like to:
+1. Start a new colony with /ant:init
+2. Check status with /ant:status
+3. View existing colonies with /ant:history
+```
+
+Offer to run `/ant:init` to start fresh.
+
+### Step 3: If Session Exists
+
+Read session data and colony state, then present summary:
+
+```
+📋 SESSION RESUME
+
+You were working on: {colony_goal}
+Current Phase: {current_phase} ({current_milestone})
+Last Command: {last_command}
+Last Active: {hours_ago} hours ago
+Suggested Next: {suggested_next}
+
+Active TODOs:
+- {todo1}
+- {todo2}
+
+Would you like to resume this work?
+```
+
+Use `AskUserQuestion` to present options:
+- **Yes, resume** — Continue where you left off
+- **Show details** — See full colony state first
+- **No, start fresh** — Clear session and start new
+
+### Step 4: If User Chooses "Yes, resume"
+
+1. Mark session as resumed:
+   ```bash
+   bash .aether/aether-utils.sh session-mark-resumed
+   ```
+
+2. Present context summary:
+   ```
+   🔄 Resuming Session
+
+   Colony: {goal}
+   Phase: {phase} - {milestone}
+   Context restored.
+
+   Next suggested step: {suggested_next}
+   ```
+
+3. Run the suggested command or present further options based on state.
+
+### Step 5: If User Chooses "Show details"
+
+Display:
+```
+📊 Colony Details
+
+Goal: {goal}
+State: {state}
+Phase: {phase}
+Milestone: {milestone}
+
+Recent Activity (from activity.log):
+{last 5 entries}
+
+Pending TODOs:
+{todos}
+
+[Present Yes/No choice to resume]
+```
+
+### Step 6: If User Chooses "No, start fresh"
+
+1. Clear the session:
+   ```bash
+   bash .aether/aether-utils.sh session-clear
+   ```
+
+2. Offer:
+   ```
+   Session cleared.
+
+   Start fresh with:
+   - /ant:init "your new goal"
+   - /ant:status (to check other colonies)
+   ```
+
+## Integration with Colony Commands
+
+All `/ant:*` commands should update the session after execution:
+
+```bash
+# Example: After /ant:build completes
+bash .aether/aether-utils.sh session-update "/ant:build $phase" "/ant:continue" "Completed phase $phase"
+```
+
+This ensures session.json is always current for resume functionality.
+
+## Session File Location
+
+`.aether/data/session.json`
+
+This file persists across context clears and Claude Code sessions.
+
+## Stale Session Detection
+
+Sessions older than 24 hours are marked "stale":
+- User is warned: "This session is X days old"
+- Given option to resume anyway or start fresh
+- Helps prevent accidentally resuming ancient work
+
+## Implementation
+
+Execute this flow when user runs `/ant:resume`.