aether-colony 3.1.4 → 3.1.15

package/.opencode/commands/ant/chaos.md

@@ -29,13 +29,13 @@ Where builders create with optimism and watchers verify the happy path, you inve
 
 ## Target
 
-The user specifies what to investigate via `$ARGUMENTS`:
+The user specifies what to investigate via `$normalized_args`:
 
 - **File path:** e.g., `src/auth/login.ts` — investigate that specific file
 - **Module name:** e.g., `authentication` — investigate that module/domain
 - **Feature description:** e.g., `user signup flow` — investigate that feature area
 
-**If `$ARGUMENTS` is empty or not provided, display usage and stop:**
+**If `$normalized_args` is empty or not provided, display usage and stop:**
 
 ```
 🎲🐜🔍🐜🎲 CHAOS ANT — Resilience Tester
@@ -60,6 +60,28 @@ Categories tested:
 
 ## Instructions
 
+### 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
+chaos_id="chaos-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$chaos_id"
+bash .aether/aether-utils.sh swarm-display-update "Chaos Ant" "chaos" "excavating" "Probing for weaknesses" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
 ### Step 1: Awaken — Load Context
 
 Read these files in parallel to understand the colony and codebase:
@@ -69,14 +91,14 @@ Read these files in parallel to understand the colony and codebase:
 - `.aether/data/constraints.json` — active constraints and focus areas
 
 **Target identification:**
-- Parse `$ARGUMENTS` to determine the target
+- Parse `$normalized_args` to determine the target
 - If it looks like a file path, verify it exists with Read. If it does not exist, search with Glob for the closest match.
 - If it looks like a module/feature name, use Grep and Glob to locate relevant files
 - Build a list of target files to investigate (aim for 1-5 core files)
 
 **If no relevant files can be found for the target:**
 ```
-🎲 Chaos Ant cannot locate target: $ARGUMENTS
+🎲 Chaos Ant cannot locate target: $normalized_args
    Searched for matching files and modules but found nothing.
    Please provide a valid file path, module name, or feature description.
 ```
@@ -206,6 +228,12 @@ For each scenario, produce a finding in this format. Display each to the termina
 
 ### Step 5: Produce the Chaos Report
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Chaos Ant" "chaos" "completed" "Resilience test complete" "Colony" '{"read":8,"grep":4,"edit":0,"bash":3}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$chaos_id"
+```
+
 After all 5 scenarios, compile the structured report:
 
 ```

package/.opencode/commands/ant/colonize.md

@@ -1,12 +1,45 @@
 ---
 name: ant:colonize
-description: "🔍🐜🗺️🐜🔍 Analyze codebase and prepare for colony work"
+description: "📊🐜🗺️🐜📊 Survey territory with 4 parallel scouts for comprehensive colony intelligence"
 ---
 
-You are the **Queen**. Perform initial codebase analysis.
+You are the **Queen**. Dispatch Surveyor Ants to map the territory.
+
+The arguments are: `$normalized_args`
+
+**Parse arguments:**
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
 
 ## Instructions
 
+### 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.
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+colonize_id="colonize-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$colonize_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "dispatching" "Surveying territory" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
+Display header:
+```
+📊🐜🗺️🐜📊 ═══════════════════════════════════════════════
+         C O L O N I Z E  —  T e r r i t o r y  S u r v e y
+═══════════════════════════════════════════════ 📊🐜🗺️🐜📊
+
+Queen dispatching Surveyor Ants...
+```
+
 ### Step 1: Validate
 
 Read `.aether/data/COLONY_STATE.json`.
@@ -15,15 +48,15 @@ Read `.aether/data/COLONY_STATE.json`.
 1. Create `.aether/data/` directory if it does not exist.
 2. Write a minimal COLONY_STATE.json:
    `{"version": "3.0", "goal": null, "state": "IDLE", "current_phase": 0, "session_id": null, "initialized_at": null, "build_started_at": null, "plan": {"generated_at": null, "confidence": null, "phases": []}, "memory": {"phase_learnings": [], "decisions": [], "instincts": []}, "errors": {"records": [], "flagged_patterns": []}, "signals": [], "graveyards": [], "events": []}`
-3. Output: "No colony state found. Bootstrapping minimal state for codebase analysis."
+3. Output: "No colony state found. Bootstrapping minimal state for territory survey."
 
-**If the file exists:** continue (colonize works with or without a goal).
+**If the file exists:** continue.
 
 **If `plan.phases` is not empty:** output "Colony already has phases. Use /ant:continue.", stop.
 
-### Step 2: Surface Scan
+### Step 2: Quick Surface Scan (for session context)
 
-Use Glob to find key files (read up to 20 total).
+Use Glob to find key files (read up to 20 total) to provide context for the survey.
 
 **Package manifests:**
 - package.json, Cargo.toml, pyproject.toml, go.mod, Gemfile, pom.xml, build.gradle
@@ -37,107 +70,119 @@ Use Glob to find key files (read up to 20 total).
 **Config:**
 - tsconfig.json, .eslintrc.*, jest.config.*, vite.config.*, webpack.config.*
 
-Read found files. Extract:
-- Tech stack (language, framework, key dependencies)
+Read found files. Extract basic info:
+- Tech stack (language, framework)
 - Entry points (main files)
-- Key directories (src/, lib/, tests/, etc.)
-- File counts per top-level directory
-
-### Step 2.5: Command Detection
-
-Detect build, test, type-check, and lint commands from two sources. Track each command with its source attribution (`claude_md` or `heuristic`).
-
-**Source 1 — CLAUDE.md (priority):**
-
-Read `CLAUDE.md` in the project root. If it does not exist, skip to Source 2.
-Scan for commands under headings matching: `Commands`, `Scripts`, `Development`, `Build`, `Testing`, `Lint`, or similar.
-Also extract inline code blocks containing patterns like `npm`, `npx`, `yarn`, `pnpm`, `cargo`, `go`, `pytest`, `make`, `gradle`, `mvn`.
-For each command found, store: `{ label, command, source: "claude_md" }`.
-
-**Source 2 — Heuristic from package manifests:**
-
-Using the manifests found in Step 2, infer commands with this table:
+- Key directories
 
-| Manifest | Field/Pattern | Label | Command |
-|---|---|---|---|
-| package.json | `scripts.test` | test | `npm test` |
-| package.json | `scripts.build` | build | `npm run build` |
-| package.json | `scripts.lint` | lint | `npm run lint` |
-| package.json | `scripts.typecheck` or `scripts.type-check` | typecheck | `npm run typecheck` |
-| Cargo.toml | (exists) | test | `cargo test` |
-| Cargo.toml | (exists) | build | `cargo build` |
-| Cargo.toml | `clippy` in deps | lint | `cargo clippy` |
-| pyproject.toml | `[tool.pytest]` or pytest in deps | test | `pytest` |
-| pyproject.toml | `[tool.ruff]` or ruff in deps | lint | `ruff check .` |
-| pyproject.toml | `[tool.mypy]` or mypy in deps | typecheck | `mypy .` |
-| go.mod | (exists) | test | `go test ./...` |
-| go.mod | (exists) | build | `go build ./...` |
+### Step 3: Dispatch Surveyor Ants (Parallel)
 
-For each inferred command, only store it if no command with the same label was already found from CLAUDE.md (CLAUDE.md wins per-label). Store as: `{ label, command, source: "heuristic" }`.
-
-If neither source yields any commands, set the detected commands list to empty.
+Create the survey directory:
+```bash
+mkdir -p .aether/data/survey
+```
 
-### Step 3: Write CODEBASE.md
+Generate unique names for the 4 Surveyor Ants and log their dispatch:
+```bash
+bash .aether/aether-utils.sh generate-ant-name "surveyor"
+bash .aether/aether-utils.sh generate-ant-name "surveyor"
+bash .aether/aether-utils.sh generate-ant-name "surveyor"
+bash .aether/aether-utils.sh generate-ant-name "surveyor"
+```
 
-Create `.planning/CODEBASE.md` (ensure `.planning/` exists first):
+Log the dispatch:
+```bash
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{provisions_name}" "Mapping provisions and trails"
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{nest_name}" "Mapping nest structure"
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{disciplines_name}" "Mapping disciplines and sentinels"
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{pathogens_name}" "Identifying pathogens"
+```
 
-```markdown
-# Codebase Overview
+**Spawn 4 Surveyor Ants in parallel using the Task tool:**
 
-**Stack:** <language> + <framework>
-**Entry:** <main entry points>
+Each Task should use `subagent_type="aether-surveyor-{focus}"`:
+1. `aether-surveyor-provisions` — Maps PROVISIONS.md and TRAILS.md
+2. `aether-surveyor-nest` — Maps BLUEPRINT.md and CHAMBERS.md
+3. `aether-surveyor-disciplines` — Maps DISCIPLINES.md and SENTINEL-PROTOCOLS.md
+4. `aether-surveyor-pathogens` — Maps PATHOGENS.md
 
-**Structure:**
-- <dir>/ (<count> files)
-- ...
+**Prompt for each surveyor:**
+```
+You are Surveyor Ant {name}. Explore this codebase and write your survey documents.
 
-**Key Dependencies:**
-- <dep1>: <purpose>
-- <dep2>: <purpose>
-- ...
+Focus: {provisions|nest|disciplines|pathogens}
 
-## Commands
-<for each detected command from Step 2.5>
-- **<label>**: `<command>` (<source: claude_md | heuristic>)
-<if no commands detected>
-No build system detected.
-</if>
+The surface scan found:
+- Language: {language}
+- Framework: {framework}
+- Key directories: {dirs}
 
-**Test Location:** <tests/ or __tests__/ or similar>
+Write your documents to `.aether/data/survey/` following your agent template.
+Return only confirmation when complete — do not include document contents.
+```
 
-**Notes:**
-- <any notable patterns or conventions observed>
+Collect confirmations from all 4 surveyors. Each should return:
+- Document name(s) written
+- Line count(s)
+- Brief status
+
+### Step 4: Verify Survey Completeness
+
+Check that all 7 documents were created:
+```bash
+ls .aether/data/survey/PROVISIONS.md 2>/dev/null && echo "PROVISIONS: OK" || echo "PROVISIONS: MISSING"
+ls .aether/data/survey/TRAILS.md 2>/dev/null && echo "TRAILS: OK" || echo "TRAILS: MISSING"
+ls .aether/data/survey/BLUEPRINT.md 2>/dev/null && echo "BLUEPRINT: OK" || echo "BLUEPRINT: MISSING"
+ls .aether/data/survey/CHAMBERS.md 2>/dev/null && echo "CHAMBERS: OK" || echo "CHAMBERS: MISSING"
+ls .aether/data/survey/DISCIPLINES.md 2>/dev/null && echo "DISCIPLINES: OK" || echo "DISCIPLINES: MISSING"
+ls .aether/data/survey/SENTINEL-PROTOCOLS.md 2>/dev/null && echo "SENTINEL: OK" || echo "SENTINEL: MISSING"
+ls .aether/data/survey/PATHOGENS.md 2>/dev/null && echo "PATHOGENS: OK" || echo "PATHOGENS: MISSING"
 ```
 
-Keep output under 50 lines. Focus on what's relevant to the colony goal (if set), or provide a general codebase overview.
+If any documents are missing, note which ones in the output.
 
-### Step 4: Update State
+### Step 5: Update State
 
 Read `.aether/data/COLONY_STATE.json`. Update:
 - Set `state` to `"IDLE"` (ready for planning)
+- Set `territory_surveyed` to `"<ISO-8601 UTC>"`
 
 Write Event: Append to the `events` array as pipe-delimited string:
-`"<ISO-8601 UTC>|codebase_colonized|colonize|Codebase analyzed: <primary language/framework>"`
+`"<ISO-8601 UTC>|territory_surveyed|colonize|Territory surveyed: 7 documents"`
 
 If the `events` array exceeds 100 entries, remove the oldest entries to keep only 100.
 
 Write the updated COLONY_STATE.json.
 
-### Step 5: Confirm
+### Step 6: Confirm
 
 Output header:
 
 ```
-🔍🐜🗺️🐜🔍 ═══════════════════════════════════════════════════
-   C O D E B A S E   A N A L Y S I S
-═══════════════════════════════════════════════════ 🔍🐜🗺️🐜🔍
+📊🐜🗺️🐜📊 ═══════════════════════════════════════════════════
+   T E R R I T O R Y   S U R V E Y   C O M P L E T E
+═══════════════════════════════════════════════════ 📊🐜🗺️🐜📊
 ```
 
 Then output:
 
 ```
-Codebase analysis complete.
-See: .planning/CODEBASE.md
+🗺️ Colony territory has been surveyed.
+
+Survey Reports:
+  📦 PROVISIONS.md         — Tech stack & dependencies
+  🛤️  TRAILS.md             — External integrations
+  📐 BLUEPRINT.md          — Architecture patterns
+  🏠 CHAMBERS.md           — Directory structure
+  📜 DISCIPLINES.md        — Coding conventions
+  🛡️  SENTINEL-PROTOCOLS.md — Testing patterns
+  ⚠️  PATHOGENS.md          — Tech debt & concerns
+
+Location: .aether/data/survey/
+
+{If any docs missing:}
+⚠️  Missing: {list missing documents}
+{/if}
 
 Stack: <language> + <framework>
 Entry: <main entry point>
@@ -151,26 +196,7 @@ Next:
 
 {If goal is not null:}
 Next:
-  /ant:plan              Generate project plan
+  /ant:plan              Generate project plan (will load relevant survey docs)
   /ant:focus "<area>"    Inject focus before planning
   /ant:redirect "<pat>"  Inject constraint before planning
 ```
-
-### Step 5.5: Suggest Commands for CLAUDE.md
-
-Skip if all commands came from `claude_md` or none were detected. This is **non-blocking** -- do not edit CLAUDE.md automatically.
-
-For heuristic-sourced commands only, output:
-
-```
-💡 Detected commands not yet in CLAUDE.md. Consider adding:
-```
-
-Then a fenced code block the user can copy-paste into CLAUDE.md:
-
-```markdown
-## Commands
-- <label>: `<command>`
-```
-
-Then: `Paste the above into your project's CLAUDE.md to skip heuristic detection next time.`

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

@@ -7,7 +7,29 @@ You are the **Queen Ant Colony**. Reconcile completed work and advance to the ne
 
 ## 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
+continue_id="continue-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$continue_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Phase continuation" "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`
 
@@ -30,12 +52,29 @@ Extract: `goal`, `state`, `current_phase`, `plan.phases`, `errors`, `memory`, `e
 - If `goal: null` -> output "No colony initialized. Run /ant:init first." and stop.
 - If `plan.phases` is empty -> output "No project plan. Run /ant:plan first." and stop.
 
-**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
 
 **Completion Detection:**
 
@@ -65,8 +104,8 @@ Resolve each command (build, test, types, lint) using this priority chain. Stop
 **Priority 1 — CLAUDE.md (System Context):**
 Check the CLAUDE.md instructions already loaded in your system context for explicit build, test, type-check, or lint commands. These are authoritative and override all other sources.
 
-**Priority 2 — .planning/CODEBASE.md `## Commands`:**
-Read `.planning/CODEBASE.md` and look for the `## Commands` section. Use any commands listed there for slots not yet filled by Priority 1.
+**Priority 2 — codebase.md `## Commands`:**
+Read `.aether/data/codebase.md` and look for the `## Commands` section. Use any commands listed there for slots not yet filled by Priority 1.
 
 **Priority 3 — Fallback Heuristic Table:**
 For any commands still unresolved, check for these files in order, use first match:
@@ -632,6 +671,49 @@ Update COLONY_STATE.json:
 
 Write COLONY_STATE.json.
 
+### Step 2.3: Update Handoff Document
+
+After advancing the phase, update the handoff document with the new current state:
+
+```bash
+# Determine if there's a next phase
+next_phase_id=$((current_phase + 1))
+has_next_phase=$(jq --arg next "$next_phase_id" '.plan.phases | map(select(.id == ($next | tonumber))) | length' .aether/data/COLONY_STATE.json)
+
+# Write updated handoff
+cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
+# Colony Session — Phase Advanced
+
+## Quick Resume
+Run `/ant:build {next_phase_id}` to start working on the current phase.
+
+## State at Advancement
+- Goal: "$(jq -r '.goal' .aether/data/COLONY_STATE.json)"
+- Completed Phase: {completed_phase_id} — {completed_phase_name}
+- Current Phase: {next_phase_id} — {next_phase_name}
+- State: READY
+- Updated: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+## What Was Completed
+- Phase {completed_phase_id} marked as completed
+- Learnings extracted: {learning_count}
+- Instincts updated: {instinct_count}
+
+## Current Phase Tasks
+$(jq -r '.plan.phases[] | select(.id == next_phase_id) | .tasks[] | "- [ ] \(.id): \(.description)"' .aether/data/COLONY_STATE.json)
+
+## Next Steps
+- Build current phase: `/ant:build {next_phase_id}`
+- Review phase details: `/ant:phase {next_phase_id}`
+- Pause colony: `/ant:pause-colony`
+
+## Session Note
+Phase advanced successfully. Colony is READY to build Phase {next_phase_id}.
+HANDOFF_EOF
+```
+
+This handoff reflects the post-advancement state, allowing seamless resumption even if the session is lost.
+
 ### Step 2.4: Update Changelog
 
 **Append a changelog entry for the completed phase.**
@@ -749,7 +831,7 @@ Clear context now?
 
 3. **If option 1 ("Yes, clear context"):**
 
-   **IMPORTANT:** OpenCode does not support programmatic /clear. Display instructions:
+   **IMPORTANT:** Claude Code does not support programmatic /clear. Display instructions:
    ```
    Please type: /clear
    
@@ -794,6 +876,12 @@ Runs ONLY when all phases complete.
 
 ### Step 3: Display Result
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Phase advanced" "Colony" '{"read":5,"grep":2,"edit":3,"bash":2}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$continue_id"
+```
+
 Output:
 
 ```

package/.opencode/commands/ant/council.md

@@ -7,6 +7,28 @@ You are the **Queen Ant Colony**. Convene the council to clarify user intent and
 
 ## Instructions
 
+### 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
+council_id="council-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$council_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Convening council" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
 ### Step 1: Read Current State
 
 Read `.aether/data/COLONY_STATE.json`.
@@ -223,6 +245,12 @@ Keep max 100 events.
 
 ### Step 8: Display Summary
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Council adjourned" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$council_id"
+```
+
 ```
 📜🐜🏛️🐜📜 COUNCIL ADJOURNED
 

package/.opencode/commands/ant/dream.md

@@ -29,6 +29,30 @@ You wander the codebase like a monk walks a garden — not to fix, not to judge,
 
 ## Instructions
 
+### 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.
+
+### Step 0: Parse Arguments
+
+Parse `$normalized_args`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 0.5: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+dream_id="dream-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$dream_id"
+bash .aether/aether-utils.sh swarm-display-update "Dreamer" "dreamer" "observing" "Wandering the codebase" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 0
+```
+
 ### Step 1: Awaken — Load Context
 
 Read these files in parallel to understand the world you're dreaming about:

package/.opencode/commands/ant/entomb.md

@@ -7,6 +7,28 @@ You are the **Queen**. Archive the completed colony to chambers.
 
 ## Instructions
 
+### 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
+entomb_id="entomb-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$entomb_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Entombing colony" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
 ### Step 1: Read State
 
 Read `.aether/data/COLONY_STATE.json`.
@@ -204,6 +226,44 @@ Remove backup after successful reset:
 rm -f .aether/data/COLONY_STATE.json.bak
 ```
 
+### Step 8.5: Write Final Handoff
+
+After entombing the colony, write the final handoff documenting the archived colony:
+
+```bash
+cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
+# Colony Session — ENTOMBED
+
+## ⚰️ Colony Archived
+**Status:** Entombed in Chambers — Colony work preserved
+
+## Chamber Location
+.aether/chambers/{chamber_name}/
+
+## Colony Summary
+- Goal: "{goal}"
+- Phases: {completed} completed of {total}
+- Milestone: {milestone}
+- Entombed At: {timestamp}
+
+## Chamber Contents
+- colony-state.json — Full colony state
+- manifest.json — Archive metadata
+- activity.log — Colony activity history
+- spawn-tree.txt — Worker spawn records
+- flags.json — Project flags (if existed)
+
+## Session Note
+This colony has been entombed and the active state reset.
+The colony rests. Its learnings are preserved in the chamber.
+
+To start anew: /ant:lay-eggs "<new goal>"
+To explore chambers: /ant:tunnels
+HANDOFF_EOF
+```
+
+This handoff serves as the record of the entombed colony.
+
 ### Step 9: Display Result
 
 ```
@@ -220,7 +280,19 @@ rm -f .aether/data/COLONY_STATE.json.bak
 📦 Chamber: .aether/chambers/{chamber_name}/
 
 🐜 The colony rests. Its learnings are preserved.
-   Run /ant:lay-eggs to begin anew.
+
+💾 State persisted — safe to /clear
+
+🐜 What would you like to do next?
+   1. /ant:lay-eggs "<new goal>"  — Start a new colony
+   2. /ant:tunnels                — Browse archived colonies
+   3. /clear                      — Clear context and continue
+
+Use AskUserQuestion with these three options.
+
+If option 1 selected: proceed to run /ant:lay-eggs flow
+If option 2 selected: run /ant:tunnels
+If option 3 selected: display "Run /ant:lay-eggs to begin anew after clearing"
 ```
 
 ### Edge Cases