aether-colony 3.1.4 → 3.1.15

package/.opencode/commands/ant/plan.md

@@ -3,11 +3,33 @@ 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)
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+Parse `$normalized_args`:
+- 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`
 
@@ -32,18 +54,35 @@ No colony initialized. Run /ant:init "<goal>" first.
 ```
 Stop here.
 
-**Auto-Recovery Header (Session Start):**
-If `goal` exists and state is valid, output a brief context line:
-```
-🔄 Resuming: Phase {current_phase} - {phase_name}
-```
-This helps recover context after session clears. Continue immediately (non-blocking).
+### Step 1.5: Load State and Show Resumption Context
+
+Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+
+If successful and goal is not null:
+1. Extract current_phase from state
+2. Get phase name from plan.phases[current_phase - 1].name (or "(unnamed)")
+3. Display brief resumption context:
+   ```
+   🔄 Resuming: Phase X - Name
+   ```
+
+If .aether/HANDOFF.md exists (detected in load-state output):
+- Display "Resuming from paused session"
+- Read .aether/HANDOFF.md for additional context
+- Remove .aether/HANDOFF.md after display (cleanup)
+
+Run: `bash .aether/aether-utils.sh unload-state` to release lock.
+
+**Error handling:**
+- If E_FILE_NOT_FOUND: "No colony initialized. Run /ant:init first." and stop
+- If validation error: Display error details with recovery suggestion and stop
+- For other errors: Display generic error and suggest /ant:status for diagnostics
 
 ### Step 2: Check Existing Plan
 
 If `plan.phases` has entries (non-empty array), skip to **Step 6** (Display Plan).
 
-Parse `$ARGUMENTS`:
+Parse `$normalized_args`:
 - If contains `--accept`: Set `force_accept = true` (accept current plan regardless of confidence)
 - Otherwise: `force_accept = false`
 
@@ -59,7 +98,7 @@ AETHER COLONY :: PLANNING
 State: PLANNING
 Phase: 0/0 (generating plan)
 Confidence: 0%
-Iteration: 0/50
+Iteration: 0/4
 
 Active Workers:
   [Research] Starting...
@@ -76,9 +115,9 @@ Progress
 
 [                    ] 0%
 
-Target: 95% confidence
+Target: 80% confidence
 
-Iteration: 0/50
+Iteration: 0/4
 Gaps: (analyzing...)
 ```
 
@@ -87,76 +126,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="general-purpose":
+
+        """
+        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":
+    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="general-purpose":
 
-    --- 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":
+    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="general-purpose":
+    # NOTE: Claude Code uses aether-route-setter; OpenCode uses general-purpose with role injection
 
     """
     You are a Route-Setter Ant in the Aether Colony.
@@ -165,7 +290,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.
@@ -202,7 +327,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:}
@@ -211,18 +339,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:
     {
@@ -254,7 +383,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": ["...", "..."]
     }
     """
@@ -268,64 +397,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 ===
+    # === STALL TRACKING ===
 
-    # 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
-
-    # 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.
+Planning complete after {iteration} iteration(s).
 
-Current confidence: {confidence}%
-Unresolved gaps:
-{list gaps marked needs_human_input}
-
-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
@@ -351,6 +449,12 @@ Ready to build.
 
 ### Step 6: 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:
 
 ```
@@ -406,18 +510,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/.opencode/commands/ant/redirect.md

@@ -7,11 +7,17 @@ You are the **Queen**. Add an AVOID constraint.
 
 ## Instructions
 
-The pattern to avoid is: `$ARGUMENTS`
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+The pattern to avoid is: `$normalized_args`
 
 ### Step 1: Validate
 
-If `$ARGUMENTS` empty -> show usage: `/ant:redirect <pattern to avoid>`, stop.
+If `$normalized_args` 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

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

@@ -7,27 +7,45 @@ You are the **Queen Ant Colony**. Restore state from a paused session.
 
 ## Instructions
 
-### Step 0: Version Check (Non-blocking)
+### Step -1: Normalize Arguments
 
-Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
 
-If the command succeeds and the JSON result contains a non-empty string, display it as a one-line notice. Proceed regardless of outcome.
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
 
-### Step 1: Read State Files
+Parse `$normalized_args`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
 
-Use the Read tool to read these files (in parallel):
-- `.aether/HANDOFF.md`
-- `.aether/data/COLONY_STATE.json`
+### Step 0: Initialize Visual Mode (if enabled)
 
-If `COLONY_STATE.json` has `goal: null`, output:
+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
 ```
-No colony state found. Either:
-  /ant:init "<goal>"     Start a new colony
-  Check .aether/HANDOFF.md for manual recovery
-```
 
-Stop here.
+### Step 0.5: Version Check (Non-blocking)
+
+Run using the Bash tool: `bash .aether/aether-utils.sh version-check 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.
+
+### Step 1: Load State and Validate
+
+Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+
+If successful:
+1. Parse state from result
+2. If goal is null: Show "No colony state found..." message and stop
+3. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
+4. Extract all state fields for display
+
+Keep state loaded (don't unload yet) - we'll need it for the full display.
 
 ### Step 2: Compute Active Signals
 
@@ -51,7 +69,7 @@ Output header:
 ═══════════════════════════════════════════════════ 🚦➡️🐜💨💨
 ```
 
-Read the HANDOFF.md for context about what was happening, then display:
+Read the .aether/HANDOFF.md for context about what was happening, then display:
 
 ```
 +=====================================================+
@@ -71,33 +89,40 @@ ACTIVE PHEROMONES
 
   If no active signals: (no active pheromones)
 
-WORKERS
-
-  If ALL workers have "idle" status, display:
-    All 6 workers idle -- colony ready
-
-  Otherwise, group by status with caste name:
-    Active:
-      builder: currently executing
-    Idle:
-      colonizer  route-setter  watcher  scout  architect
-
 PHASE PROGRESS
   Phase <id>: <name> [<status>]
   (list all phases from plan.phases)
 
 CONTEXT FROM HANDOFF
-  <summarize what was happening from HANDOFF.md>
+  <summarize what was happening from .aether/HANDOFF.md>
 
 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>`
 - If state is `PLANNING` -> note that planning was interrupted, suggest `/ant:plan`
 - Otherwise -> suggest `/ant:status` for full overview
 
+### Step 6: Clear Paused State and Cleanup
+
+Use Write tool to update COLONY_STATE.json:
+- Remove or set to false: `"paused": false`
+- Remove: `"paused_at"` field
+- Update last_updated timestamp
+- Add event: `{timestamp, type: "colony_resumed", worker: "resume", details: "Session resumed"}`
+
+Use Bash tool to remove HANDOFF.md: `rm -f .aether/HANDOFF.md`
+
+Run: `bash .aether/aether-utils.sh unload-state` to release lock.
+
 ---
 
 ## Auto-Recovery Pattern Reference