aether-colony 5.1.0 → 5.3.0

package/.aether/commands/claude/preferences.md

@@ -0,0 +1,65 @@
+<!-- Generated from .aether/commands/preferences.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:preferences
+description: "Add or list user preferences in hub QUEEN.md"
+---
+
+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/claude/quick.md

@@ -0,0 +1,100 @@
+<!-- Generated from .aether/commands/quick.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:quick
+description: "Quick scout query — fast answers without build ceremony"
+---
+
+You are the **Queen**. Execute `/ant:quick` — a lightweight scout mission.
+
+The query is: `$ARGUMENTS`
+
+## Purpose
+
+Quick, focused answers to questions about the codebase, patterns, or implementation
+details. No build ceremony, no state changes, no verification waves.
+
+## Instructions
+
+### Step 1: Validate Arguments
+
+If `$ARGUMENTS` is empty:
+```
+Usage: /ant:quick "<question>"
+
+Examples:
+  /ant:quick "how does the pheromone system work?"
+  /ant:quick "find all uses of acquire_lock"
+  /ant:quick "what tests cover midden-write?"
+  /ant:quick "show me the colony-prime token budget logic"
+```
+Stop here.
+
+### Step 2: Generate Scout Name
+
+Run using the Bash tool with description "Naming scout...":
+```bash
+bash .aether/aether-utils.sh generate-ant-name "scout"
+```
+
+Capture the output as `scout_name`.
+
+### Step 3: Spawn Scout
+
+Display:
+```
+━━━ Quick Scout ━━━
+Spawning {scout_name} — {query truncated to 50 chars}
+```
+
+Run using the Bash tool with description "Dispatching scout...":
+```bash
+bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{scout_name}" "Quick query: {query}"
+```
+
+
+Spawn a Scout agent (using Task tool with subagent_type="aether-scout") with this prompt:
+
+```
+You are {scout_name}, a Scout Ant on a quick mission.
+
+Query: {query from ARGUMENTS}
+
+Work:
+1. Search the codebase to answer the query
+2. Use Grep, Glob, and Read tools to find relevant code
+3. Provide a clear, focused answer
+4. Include file paths and line numbers for key findings
+
+Keep your answer concise and actionable. This is a quick mission —
+don't explore exhaustively, focus on the most relevant answer.
+
+Return your findings as a clear text answer (not JSON).
+```
+
+
+
+### Step 4: Display Results
+
+
+Display the Scout's answer directly to the user.
+
+
+
+Run using the Bash tool with description "Recording scout completion...":
+```bash
+bash .aether/aether-utils.sh spawn-complete "{scout_name}" "completed" "Quick query answered"
+```
+
+### Step 5: Update Session (lightweight)
+
+Run using the Bash tool with description "Updating session...":
+```bash
+bash .aether/aether-utils.sh session-update "/ant:quick" "" "Quick query: {query truncated to 60 chars}" 2>/dev/null || true
+```
+
+**NOTE:** This command does NOT:
+- Modify COLONY_STATE.json
+- Advance phases
+- Create checkpoints
+- Spawn watchers or chaos ants
+- Run verification

package/.aether/commands/claude/redirect.md

@@ -0,0 +1,76 @@
+<!-- Generated from .aether/commands/redirect.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:redirect
+description: "Emit REDIRECT signal to warn colony away from patterns"
+---
+
+
+You are the **Queen**. Emit a REDIRECT pheromone signal.
+
+
+
+## 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.
+
+
+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.
+
+
+### Step 2: Write Signal
+
+Read `.aether/data/COLONY_STATE.json`.
+If `goal: null` -> "No colony initialized.", stop.
+
+
+Run using the Bash tool with description "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
+
+Run using the Bash tool with description "Updating context document...":
+```bash
+bash .aether/aether-utils.sh context-update constraint redirect "<content>" "user" 2>/dev/null || true
+```
+
+### Step 3: Get Active Counts
+
+Run using the Bash tool with description "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
+```
+
+
+
+
+### 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"
+```
+

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

@@ -0,0 +1,197 @@
+<!-- Generated from .aether/commands/resume-colony.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:resume-colony
+description: "🚦➡️🐜💨💨 Resume colony from saved session - restores all state"
+---
+
+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. If `milestone` == `"Crowned Anthill"`: Show "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
+4. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
+5. 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