aether-colony 3.1.4 → 3.1.15

package/.opencode/commands/ant/feedback.md

@@ -7,10 +7,16 @@ You are the **Queen**. Emit a FEEDBACK signal.
 
 ## Instructions
 
-The feedback message 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 feedback message is: `$normalized_args`
 
 ### Step 1: Validate
-If `$ARGUMENTS` empty -> show usage: `/ant:feedback <message>`, stop.
+If `$normalized_args` empty -> show usage: `/ant:feedback <message>`, stop.
 If content > 500 chars -> "Signal content too long (max 500 chars)", stop.
 
 ### Step 2: Read + Update State

package/.opencode/commands/ant/flag.md

@@ -7,11 +7,17 @@ You are the **Queen**. Create a project-specific flag.
 
 ## Instructions
 
-The flag 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 flag is: `$normalized_args`
 
 ### Step 1: Parse Arguments
 
-Parse `$ARGUMENTS` for:
+Parse `$normalized_args` for:
 - `--type` or `-t`: blocker | issue | note (default: issue)
 - `--phase` or `-p`: phase number (optional)
 - Remaining text: the flag title/description
@@ -21,7 +27,7 @@ Examples:
 - `/ant:flag --type blocker "API rate limit hit"` → blocker type
 - `/ant:flag -t note -p 3 "Consider refactoring later"` → note for phase 3
 
-If `$ARGUMENTS` is empty:
+If `$normalized_args` is empty:
 ```
 Usage: /ant:flag "<description>" [--type blocker|issue|note] [--phase N]
 

package/.opencode/commands/ant/flags.md

@@ -7,11 +7,17 @@ You are the **Queen**. Display project flags.
 
 ## Instructions
 
-Arguments: `$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.
+
+Arguments: `$normalized_args`
 
 ### Step 1: Parse Arguments
 
-Parse `$ARGUMENTS` for:
+Parse `$normalized_args` for:
 - `--all` or `-a`: Show resolved flags too
 - `--type` or `-t`: Filter by type (blocker|issue|note)
 - `--phase` or `-p`: Filter by phase number

package/.opencode/commands/ant/focus.md

@@ -7,11 +7,17 @@ You are the **Queen**. Add a FOCUS constraint.
 
 ## Instructions
 
-The focus area 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 focus area is: `$normalized_args`
 
 ### Step 1: Validate
 
-If `$ARGUMENTS` empty -> show usage: `/ant:focus <area>`, stop.
+If `$normalized_args` empty -> show usage: `/ant:focus <area>`, stop.
 If content > 500 chars -> "Focus content too long (max 500 chars)", stop.
 
 ### Step 2: Read + Update Constraints

package/.opencode/commands/ant/help.md

@@ -109,4 +109,16 @@ HOW IT WORKS
     activity.log        Timestamped worker activity
     spawn-tree.txt      Worker spawn hierarchy
     constraints.json    Focus/redirect pheromone data
+
+OPENCODE USERS
+
+  Argument syntax: OpenCode handles multi-word arguments differently than Claude.
+  Wrap text arguments in quotes for reliable parsing:
+
+    ✅ /ant:init "Build a REST API"
+    ✅ /ant:plan "authentication system"
+    ✅ /ant:focus "database layer"
+
+  Without quotes, only the first word may be captured. This is now handled
+  automatically by the normalize-args utility, but quoting is recommended.
 ```

package/.opencode/commands/ant/init.md

@@ -7,9 +7,33 @@ You are the **Queen Ant Colony**. Initialize the colony with the Queen's intenti
 
 ## Instructions
 
-The user's goal is: `$ARGUMENTS`
+### Step -1: Normalize Arguments
 
-### Step 0: Version Check (Non-blocking)
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode.
+
+The user's goal is: `$normalized_args`
+
+Parse `$normalized_args`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+Note: Use `$normalized_args` instead of `$ARGUMENTS` throughout this command.
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+init_id="init-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$init_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Colony initialization" "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`
 
@@ -17,7 +41,7 @@ If the command succeeds and the JSON result contains a non-empty string, display
 
 ### Step 1: Validate Input
 
-If `$ARGUMENTS` is empty or blank, output:
+If `$normalized_args` is empty or blank, output:
 
 ```
 Aether Colony
@@ -175,7 +199,16 @@ bash .aether/aether-utils.sh validate-state colony
 
 This validates COLONY_STATE.json structure. If validation fails, output a warning.
 
-### Step 5.5: Register Repo (Silent)
+### Step 5.5: Detect Nestmates
+
+Run using Bash tool: `node -e "const nl = require('./bin/lib/nestmate-loader'); console.log(JSON.stringify(nl.findNestmates(process.cwd())))"`
+
+If nestmates are found:
+1. Display: `Nestmates found: N related colonies`
+2. List each nestmate with name and truncated goal
+3. Check for shared TO-DOs or cross-project dependencies
+
+### Step 5.6: Register Repo (Silent)
 
 Attempt to register this repo in the global hub. Both steps are silent on failure — registry is not required for the colony to work.
 
@@ -193,6 +226,12 @@ If either command fails, proceed silently. These are optional bookkeeping.
 
 ### Step 6: Display Result
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Colony initialized" "Colony" '{"read":5,"grep":2,"edit":3,"bash":2}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$init_id"
+```
+
 Output this header:
 
 ```
@@ -216,6 +255,12 @@ Then output the result:
    {N} instinct(s) | {N} learning(s)
 {End if}
 
+{If nestmates found in Step 5.5:}
+🏘️ Nest Context: {N} sibling colonies detected
+   Context from related projects will be automatically considered
+   during planning and execution.
+{End if}
+
 🐜 The colony awaits your command:
 
    /ant:plan      📋 Generate project plan

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

@@ -7,9 +7,31 @@ You are the **Queen**. Begin a new colony, preserving pheromones.
 
 ## 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
+layeggs_id="layeggs-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$layeggs_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Laying first eggs" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 0
+```
+
 ### Step 1: Validate Input
 
-- If `$ARGUMENTS` is empty:
+- If `$normalized_args` is empty:
   ```
   Usage: /ant:lay-eggs "<new colony goal>"
 
@@ -54,7 +76,7 @@ Generate new state following RESEARCH.md Pattern 2 (State Reset with Pheromone P
 - memory.instincts (high confidence only)
 
 **Fields to reset:**
-- goal: new goal from $ARGUMENTS
+- goal: new goal from $normalized_args
 - state: "READY"
 - current_phase: 0
 - session_id: new session_{unix_timestamp}_{random}
@@ -86,6 +108,12 @@ Write `.aether/data/constraints.json`:
 
 ### Step 6: Display Result
 
+**If visual_mode is true, render final swarm display:**
+```bash
+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"
+```
+
 ```
 🥚 ═══════════════════════════════════════════════════
    F I R S T   E G G S   L A I D

package/.opencode/commands/ant/oracle.md

@@ -5,7 +5,7 @@ description: "🔮🐜🧠🐜🔮 Oracle Ant - deep research agent using RALF i
 
 You are the **Oracle Ant** command handler. You configure and launch a deep research loop that runs autonomously in a separate process.
 
-The user's input is: `$ARGUMENTS`
+The user's input is: `$normalized_args`
 
 ## Non-Invasive Guarantee
 
@@ -13,13 +13,45 @@ Oracle NEVER touches COLONY_STATE.json, constraints.json, activity.log, or any c
 
 ## 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 and Route
 
-Parse `$ARGUMENTS` to determine the action:
+Parse `$normalized_args` to determine the action:
+
+1. Check for flags:
+   - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+   - Otherwise: set `visual_mode = true`
+   - Remove flags from arguments before routing
 
-1. **If `$ARGUMENTS` is exactly `stop`** — go to **Step 0b: Stop Oracle**
-2. **If `$ARGUMENTS` is exactly `status`** — go to **Step 0c: Show Status**
-3. **Otherwise** — go to **Step 1: Research Wizard**
+2. **If remaining arguments is exactly `stop`** — go to **Step 0b: Stop Oracle**
+3. **If remaining arguments is exactly `status`** — go to **Step 0c: Show Status**
+4. **Otherwise** — go to **Step 0.5: Initialize Visual Mode** then **Step 1: Research Wizard**
+
+### Step 0.5: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+oracle_id="oracle-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$oracle_id"
+bash .aether/aether-utils.sh swarm-display-update "Oracle" "oracle" "researching" "Deep research in progress" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
+Display visual header:
+```
+🔮🐜🧠🐜🔮 ═══════════════════════════════════════════════
+          O R A C L E  —  R e s e a r c h  M o d e
+═══════════════════════════════════════════════ 🔮🐜🧠🐜🔮
+
+Oracle peering into the depths...
+```
 
 ---
 
@@ -99,13 +131,13 @@ Output the header:
 ═══════════════════════════════════════════════════ 🔮🐜🧠🐜🔮
 ```
 
-**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.
+**If `$normalized_args` is not empty and not a subcommand**, use it as the initial topic suggestion. Otherwise, the topic will be asked in Question 1.
 
 Now ask questions using AskUserQuestion. Ask them one at a time so each answer can inform the next question.
 
 **Question 1: Research Topic**
 
-If `$ARGUMENTS` already contains a topic, skip this question and use that as the topic.
+If `$normalized_args` already contains a topic, skip this question and use that as the topic.
 
 Otherwise ask:
 

package/.opencode/commands/ant/organize.md

@@ -5,10 +5,16 @@ description: "🧹🐜🏛️🐜🧹 Run codebase hygiene report - archivist an
 
 You are the **Queen Ant Colony**. Spawn an archivist to analyze codebase hygiene.
 
-> **Note:** `$ARGUMENTS` is unused. Future extensions could accept a path scope argument.
+> **Note:** `$normalized_args` is unused. Future extensions could accept a path scope argument.
 
 ## 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 1: Read State
 
 Use the Read tool to read these files (in parallel):
@@ -48,7 +54,8 @@ If no active signals after filtering:
 
 Read `.aether/workers.md` and extract the `## Architect` section.
 
-Spawn via **Task tool** with `subagent_type="general"`:
+Spawn via **Task tool** with `subagent_type="general-purpose"`:
+# NOTE: Claude Code uses aether-architect; OpenCode uses general-purpose with role injection
 
 ```
 --- WORKER SPEC ---
@@ -159,7 +166,6 @@ CONSTRAINTS:
 - Do NOT flag standard framework files (package.json, tsconfig.json, etc.) as orphaned.
 - Do NOT flag .aether/ internal data files as stale (they are managed by the colony).
 - Do NOT flag .claude/ command files as stale (they are the colony's brain).
-- Do NOT flag .planning/ files as stale (they are project management artifacts).
 - Aim for a useful report, not an exhaustive one. 5-15 findings is ideal.
 ```
 

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

@@ -7,6 +7,28 @@ You are the **Queen Ant Colony**. Save current state for session handoff.
 
 ## 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
+pause_id="pause-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$pause_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Pausing colony" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
 ### Step 1: Read State
 
 Use the Read tool to read `.aether/data/COLONY_STATE.json`.
@@ -69,7 +91,18 @@ Run `/ant:resume-colony` in a new session.
 <what should happen next>
 ```
 
-### Step 4.5: Commit Suggestion (Optional)
+### Step 4.5: Set Paused Flag in State
+
+Use Read tool to get current COLONY_STATE.json.
+
+Use Write tool to update COLONY_STATE.json with paused flag:
+- Add field: `"paused": true`
+- Add field: `"paused_at": "<ISO-8601 timestamp>"`
+- Update last_updated timestamp
+
+This flag indicates the colony is in a paused state and will be cleared on resume.
+
+### Step 4.6: Commit Suggestion (Optional)
 
 **This step is non-blocking. Skipping does not affect the pause or any subsequent steps. Failure to commit has zero consequences.**
 
@@ -143,6 +176,12 @@ Continue to Step 5.
 
 ### Step 5: Display Confirmation
 
+**If visual_mode is true, render final swarm 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"
+```
+
 Output header:
 
 ```
@@ -161,7 +200,21 @@ Then output:
   Pheromones: <active_count> active
 
   Handoff saved to .aether/HANDOFF.md
+  Paused state saved to COLONY_STATE.json
 
 To resume in a new session:
   /ant:resume-colony
+
+💾 State persisted — safe to /clear
+
+🐜 What would you like to do next?
+   1. /ant:resume-colony              — Resume work in this session
+   2. /ant:lay-eggs "<new goal>"      — Start a new colony
+   3. /clear                          — Clear context and continue
+
+Use AskUserQuestion with these three options.
+
+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"
 ```

package/.opencode/commands/ant/phase.md

@@ -7,7 +7,13 @@ You are the **Queen Ant Colony**. Display phase details from the project plan.
 
 ## Instructions
 
-The argument 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 argument is: `$normalized_args`
 
 ### Step 1: Read State
 
@@ -19,9 +25,9 @@ If `plan.phases` is an empty array, output `No project plan. Run /ant:plan first
 
 ### Step 2: Determine What to Show
 
-- If `$ARGUMENTS` is empty -> show the current phase (from `current_phase`). If `current_phase` is 0 or beyond the last phase, show phase 1.
-- If `$ARGUMENTS` is a number -> show that specific phase
-- If `$ARGUMENTS` is "list" or "all" -> show all phases in summary
+- If `$normalized_args` is empty -> show the current phase (from `current_phase`). If `current_phase` is 0 or beyond the last phase, show phase 1.
+- If `$normalized_args` is a number -> show that specific phase
+- If `$normalized_args` is "list" or "all" -> show all phases in summary
 
 ### Step 3a: Single Phase View
 
@@ -89,3 +95,29 @@ Legend: [✓] completed  [~] in progress  [ ] pending
 
 🐜 /ant:phase <id> for details
 ```
+
+### Step 4: Update Handoff (Optional)
+
+After displaying phase details, offer to update the handoff document with review notes:
+
+Use AskUserQuestion:
+```
+Update handoff with phase review notes?
+
+1. Yes — add notes about blockers or decisions
+2. No — continue without updating
+```
+
+If option 1 selected:
+Use AskUserQuestion to collect notes, then append to handoff:
+
+```bash
+cat >> .aether/HANDOFF.md << 'HANDOFF_EOF'
+
+## Phase {id} Review Notes
+- Reviewed: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+- Notes: {user_notes}
+HANDOFF_EOF
+```
+
+Display: `Handoff updated with review notes.`