aether-colony 5.0.0 → 5.1.0

package/.aether/commands/preferences.yaml

@@ -0,0 +1,63 @@
+name: "ant:preferences"
+description: "Add or list user preferences in hub QUEEN.md"
+description_opencode: "📝🐜👑🐜📝 Add or list user preferences in hub QUEEN.md"
+body: |
+  You are the **Queen**. Manage user preferences in the hub `~/.aether/QUEEN.md`.
+
+  ## Instructions
+
+  The input is: `{{ARGUMENTS}}`
+
+  ### Step 1: Validate
+
+  If `{{ARGUMENTS}}` empty -> show usage: `/ant:preferences "preference text"` or `/ant:preferences --list`, stop.
+
+  ### Step 2: Route
+
+  - `{{ARGUMENTS}}` is `--list` -> **List mode**
+  - Otherwise -> **Add mode**
+
+  ### List Mode
+
+  Read `~/.aether/QUEEN.md`. If missing -> "No hub QUEEN.md found. Run /ant:init to create one.", stop.
+
+  Find the `## User Preferences` section (with or without emoji). Extract bullet lines (`- ...`) between that heading and the next `---`.
+
+  If user-added bullets exist, output each. Otherwise:
+  ```
+  No user preferences set yet.
+  Add one with: /ant:preferences "your preference"
+  ```
+  Stop.
+
+  ### Add Mode
+
+  Set `PREF` to `{{ARGUMENTS}}` (strip surrounding quotes).
+  If length > 500 chars -> "Preference too long (max 500 chars)", stop.
+
+  Read `~/.aether/QUEEN.md`. If missing -> "No hub QUEEN.md found. Run /ant:init to create one.", stop.
+
+  **If `## User Preferences` section exists** (with or without emoji):
+  1. Remove `*No user preferences recorded yet.*` placeholder if present
+  2. Append `- $PREF` at end of section (before next `---`)
+
+  **If section missing** (migration case):
+  1. Insert before `## Evolution Log` (with or without emoji):
+  ```
+  ## User Preferences
+
+  - $PREF
+
+  ---
+
+  ```
+
+  Update METADATA comment: increment `stats.total_user_prefs` by 1.
+
+  ### Confirm
+
+  Output (2 lines, no banners):
+  ```
+  Preference saved to hub QUEEN.md
+    "$PREF"
+  ```

package/.aether/commands/redirect.yaml

@@ -0,0 +1,123 @@
+name: "ant:redirect"
+description: "Emit REDIRECT signal to warn colony away from patterns"
+description_opencode: "⚠️🐜🚧🐜⚠️ Emit REDIRECT signal to warn colony away from patterns"
+body: |
+  {{#claude}}
+  You are the **Queen**. Emit a REDIRECT pheromone signal.
+  {{/claude}}
+  {{#opencode}}
+  You are the **Queen**. Add an AVOID constraint.
+  {{/opencode}}
+
+  ## Instructions
+
+  The pattern to avoid is: `{{ARGUMENTS}}`
+
+  ### Step 1: Validate
+
+  If `{{ARGUMENTS}}` empty -> show usage: `/ant:redirect <pattern to avoid>`, stop.
+  If content > 500 chars -> "Redirect content too long (max 500 chars)", stop.
+
+  {{#claude}}
+  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.
+  {{/claude}}
+
+  ### Step 2: Write Signal
+
+  Read `.aether/data/COLONY_STATE.json`.
+  If `goal: null` -> "No colony initialized.", stop.
+
+  {{#claude}}
+  {{TOOL_PREFIX "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>
+  ```
+
+  Parse the returned JSON for the signal ID.
+
+  ### Step 2.5: Update Context Document
+
+  {{TOOL_PREFIX "Updating context document..."}}
+  ```bash
+  bash .aether/aether-utils.sh context-update constraint redirect "<content>" "user" 2>/dev/null || true
+  ```
+
+  ### Step 3: Get Active Counts
+
+  {{TOOL_PREFIX "Counting active signals..."}}
+  ```bash
+  bash .aether/aether-utils.sh pheromone-count
+  ```
+
+  ### Step 4: Confirm
+
+  Output (3-4 lines, no banners):
+  ```
+  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
+  ```
+  {{/claude}}
+  {{#opencode}}
+  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>"
+  }
+  ```
+
+  If `constraints` array exceeds 10 entries, remove the oldest entries to keep only 10.
+
+  Write constraints.json.
+
+  **Write pheromone signal and update context:**
+  ```bash
+  bash .aether/aether-utils.sh pheromone-write REDIRECT "$normalized_args" --strength 0.9 --reason "User warned colony away from pattern" 2>/dev/null || true
+  bash .aether/aether-utils.sh context-update constraint redirect "$normalized_args" "user" 2>/dev/null || true
+  ```
+
+  ### Step 3: Confirm
+
+  Output header:
+
+  ```
+  ⚠️🐜🚧🐜⚠️ ═══════════════════════════════════════════════════
+     R E D I R E C T   S I G N A L
+  ═══════════════════════════════════════════════════ ⚠️🐜🚧🐜⚠️
+  ```
+
+  Then output:
+  ```
+  🚫 REDIRECT signal emitted
+
+     Avoid: "{content preview}"
+
+  🐜 Colony warned away from this pattern.
+  ```
+  {{/opencode}}
+
+  {{#claude}}
+  ### Step 5: 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"
+  ```
+  {{/claude}}

package/.aether/commands/resume-colony.yaml

@@ -0,0 +1,373 @@
+name: "ant:resume-colony"
+description: "🚦➡️🐜💨💨 Resume colony from saved session - restores all state"
+body_claude: |
+  You are the **Queen Ant Colony**. Restore state from a paused session.
+
+  ## Instructions
+
+  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, run using the Bash tool with description "Initializing resume display...":
+  ### Step 0.5: Version Check (Non-blocking)
+
+  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.
+
+  ### Step 1: Load State and Validate
+
+  Run using the Bash tool with description "Restoring colony session...": `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
+
+  Run using the Bash tool with description "Loading active pheromones...":
+  ```bash
+  bash .aether/aether-utils.sh pheromone-read
+  ```
+
+  Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
+  If empty, treat as "no active pheromones."
+
+  ### Step 2.5: Load Survey Context (Advisory)
+
+  Run using the Bash tool with description "Loading survey context...":
+  ```bash
+  survey_docs=$(ls -1 .aether/data/survey/*.md 2>/dev/null | wc -l | tr -d ' ')
+  survey_latest=$(ls -t .aether/data/survey/*.md 2>/dev/null | head -1)
+  if [[ -n "$survey_latest" ]]; then
+    now_epoch=$(date +%s)
+    modified_epoch=$(stat -f %m "$survey_latest" 2>/dev/null || stat -c %Y "$survey_latest" 2>/dev/null || echo 0)
+    survey_age_days=$(( (now_epoch - modified_epoch) / 86400 ))
+  else
+    survey_age_days=-1
+  fi
+  echo "survey_docs=$survey_docs"
+  echo "survey_age_days=$survey_age_days"
+  ```
+
+  Interpretation:
+  - `survey_docs == 0` => survey missing
+  - `survey_age_days > 14` => survey stale
+  - otherwise survey fresh
+
+  ### Step 3: Display Restored State
+
+  **Note:** Other ant commands (`/ant:status`, `/ant:build`, `/ant:plan`, `/ant:continue`) also show brief resumption context automatically. This full resume provides complete state restoration for explicit session recovery.
+
+  Output header:
+
+  ```
+  🚦➡️🐜💨💨 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+     C O L O N Y   R E S U M E D
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚦➡️🐜💨💨
+  ```
+
+  Read the .aether/HANDOFF.md for context about what was happening, then display:
+
+  ```
+  +=====================================================+
+  |  AETHER COLONY :: RESUMED                            |
+  +=====================================================+
+
+    Goal: "<goal>"
+    State: <state>
+    Session: <session_id>
+    Phase: <current_phase>
+
+  ACTIVE PHEROMONES
+    {TYPE padded to 10 chars} [{bar of 20 chars using filled/empty}] {current_strength:.2f}
+      "{content}"
+
+    Where the bar uses round(current_strength * 20) filled characters and spaces for the remainder.
+
+    If no active signals: (no active pheromones)
+
+  PHASE PROGRESS
+    Phase <id>: <name> [<status>]
+    (list all phases from plan.phases)
+
+  SURVEY CONTEXT
+    Docs: <survey_docs>
+    Age: <survey_age_days> days
+    Status: <fresh|stale|missing>
+    Recommendation: <if missing or stale, suggest /ant:colonize --force-resurvey>
+
+  CONTEXT FROM HANDOFF
+    <summarize what was happening from .aether/HANDOFF.md>
+
+  NEXT ACTIONS
+  ```
+
+  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 with description "Cleaning up handoff file..." to remove HANDOFF.md: `rm -f .aether/HANDOFF.md`
+
+  Run using the Bash tool with description "Releasing colony lock...": `bash .aether/aether-utils.sh unload-state` to release lock.
+
+  ### 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"
+  ```
+
+  ---
+
+  ## Auto-Recovery Pattern Reference
+
+  The colony uses a tiered auto-recovery pattern to maintain context across session boundaries:
+
+  ### Format Tiers
+
+  | Context | Format | When Used |
+  |---------|--------|-----------|
+  | Brief | `🔄 Resuming: Phase X - Name` | Action commands (build, plan, continue) |
+  | Extended | Brief + last activity timestamp | Status command |
+  | Full | Complete state with pheromones, workers, context | resume-colony command |
+
+  ### Brief Format (Action Commands)
+
+  Used by `/ant:build`, `/ant:plan`, `/ant:continue`:
+
+  ```
+  🔄 Resuming: Phase <current_phase> - <phase_name>
+  ```
+
+  Provides minimal orientation before executing the command's primary function.
+
+  ### Extended Format (Status Command)
+
+  Used by `/ant:status` Step 1.5:
+
+  ```
+  🔄 Resuming: Phase <current_phase> - <phase_name>
+     Last activity: <last_event_timestamp>
+  ```
+
+  Adds temporal context to help gauge session staleness.
+
+  ### Full Format (Resume-Colony)
+
+  Used by `/ant:resume-colony`:
+
+  - Complete header with ASCII art
+  - Goal, state, session ID, phase
+  - Active pheromones with strength bars
+  - Worker status by caste
+  - Phase progress for all phases
+  - Handoff context summary
+  - Next action routing
+
+  ### Implementation Notes
+
+  1. **State Source:** All formats read from `.aether/data/COLONY_STATE.json`
+  2. **Phase Name:** Extracted from `plan.phases[current_phase - 1].name`
+  3. **Last Activity:** Parsed from the last entry in `events` array
+  4. **Edge Cases:** Handle missing phase names, empty events, phase 0
+
+body_opencode: |
+  You are the **Queen Ant Colony**. Restore state from a paused session.
+
+  ## Instructions
+
+  Parse `$normalized_args`:
+  - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+  - Otherwise: set `visual_mode = true`
+
+  ### 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
+
+  Run using the Bash tool:
+  ```bash
+  bash .aether/aether-utils.sh pheromone-read
+  ```
+
+  Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
+  If empty, treat as "no active pheromones."
+
+  ### Step 2.5: Load Survey Context (Advisory)
+
+  Run:
+  ```bash
+  survey_docs=$(ls -1 .aether/data/survey/*.md 2>/dev/null | wc -l | tr -d ' ')
+  survey_latest=$(ls -t .aether/data/survey/*.md 2>/dev/null | head -1)
+  if [[ -n "$survey_latest" ]]; then
+    now_epoch=$(date +%s)
+    modified_epoch=$(stat -f %m "$survey_latest" 2>/dev/null || stat -c %Y "$survey_latest" 2>/dev/null || echo 0)
+    survey_age_days=$(( (now_epoch - modified_epoch) / 86400 ))
+  else
+    survey_age_days=-1
+  fi
+  echo "survey_docs=$survey_docs"
+  echo "survey_age_days=$survey_age_days"
+  ```
+
+  Interpretation:
+  - `survey_docs == 0` => survey missing
+  - `survey_age_days > 14` => survey stale
+  - otherwise survey fresh
+
+  ### Step 3: Display Restored State
+
+  **Note:** Other ant commands (`/ant:status`, `/ant:build`, `/ant:plan`, `/ant:continue`) also show brief resumption context automatically. This full resume provides complete state restoration for explicit session recovery.
+
+  Output header:
+
+  ```
+  🚦➡️🐜💨💨 ═══════════════════════════════════════════════════
+     C O L O N Y   R E S U M E D
+  ═══════════════════════════════════════════════════ 🚦➡️🐜💨💨
+  ```
+
+  Read the .aether/HANDOFF.md for context about what was happening, then display:
+
+  ```
+  +=====================================================+
+  |  AETHER COLONY :: RESUMED                            |
+  +=====================================================+
+
+    Goal: "<goal>"
+    State: <state>
+    Session: <session_id>
+    Phase: <current_phase>
+
+  ACTIVE PHEROMONES
+    {TYPE padded to 10 chars} [{bar of 20 chars using filled/empty}] {current_strength:.2f}
+      "{content}"
+
+    Where the bar uses round(current_strength * 20) filled characters and spaces for the remainder.
+
+    If no active signals: (no active pheromones)
+
+  PHASE PROGRESS
+    Phase <id>: <name> [<status>]
+    (list all phases from plan.phases)
+
+  SURVEY CONTEXT
+    Docs: <survey_docs>
+    Age: <survey_age_days> days
+    Status: <fresh|stale|missing>
+    Recommendation: <if missing or stale, suggest /ant:colonize --force-resurvey>
+
+  CONTEXT FROM HANDOFF
+    <summarize what was happening from .aether/HANDOFF.md>
+
+  NEXT ACTIONS
+  ```
+
+  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
+
+  The colony uses a tiered auto-recovery pattern to maintain context across session boundaries:
+
+  ### Format Tiers
+
+  | Context | Format | When Used |
+  |---------|--------|-----------|
+  | Brief | `🔄 Resuming: Phase X - Name` | Action commands (build, plan, continue) |
+  | Extended | Brief + last activity timestamp | Status command |
+  | Full | Complete state with pheromones, workers, context | resume-colony command |
+
+  ### Brief Format (Action Commands)
+
+  Used by `/ant:build`, `/ant:plan`, `/ant:continue`:
+
+  ```
+  🔄 Resuming: Phase <current_phase> - <phase_name>
+  ```
+
+  Provides minimal orientation before executing the command's primary function.
+
+  ### Extended Format (Status Command)
+
+  Used by `/ant:status` Step 1.5:
+
+  ```
+  🔄 Resuming: Phase <current_phase> - <phase_name>
+     Last activity: <last_event_timestamp>
+  ```
+
+  Adds temporal context to help gauge session staleness.
+
+  ### Full Format (Resume-Colony)
+
+  Used by `/ant:resume-colony`:
+
+  - Complete header with ASCII art
+  - Goal, state, session ID, phase
+  - Active pheromones with strength bars
+  - Worker status by caste
+  - Phase progress for all phases
+  - Handoff context summary
+  - Next action routing
+
+  ### Implementation Notes
+
+  1. **State Source:** All formats read from `.aether/data/COLONY_STATE.json`
+  2. **Phase Name:** Extracted from `plan.phases[current_phase - 1].name`
+  3. **Last Activity:** Parsed from the last entry in `events` array
+  4. **Edge Cases:** Handle missing phase names, empty events, phase 0
+