aether-colony 5.1.0 → 5.3.0

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

@@ -0,0 +1,203 @@
+<!-- Generated from .aether/commands/pause-colony.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:pause-colony
+description: "💾🐜⏸️🐜💾 Pause colony work and create handoff document for resuming later"
+---
+
+### 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.
+
+You are the **Queen Ant Colony**. Save current state for session handoff.
+
+## Instructions
+
+Parse `$normalized_args`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 1: Read State
+
+Use the Read tool to read `.aether/data/COLONY_STATE.json`.
+
+If `goal` is null, output `No colony initialized. Nothing to pause.` and stop.
+
+### 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 3: Build Handoff Summary
+
+Gather context for the handoff from `COLONY_STATE.json`:
+- `goal` from top level
+- `state` and `current_phase` from top level
+- `workers` object
+- Active signals from `pheromone-read` output (with current decayed strengths from Step 2)
+- Phase progress from `plan.phases` (how many complete, current phase tasks)
+- What was in progress or pending
+
+### Step 4: Write Handoff
+
+Use the Write tool to update `.aether/HANDOFF.md` with a session handoff section at the top. The format:
+
+```markdown
+# Colony Session Paused
+
+## Quick Resume
+Run `/ant:resume-colony` in a new session.
+
+## State at Pause
+- Goal: "<goal>"
+- State: <state>
+- Current Phase: <phase_number> — <phase_name>
+- Session: <session_id>
+- Paused: <ISO-8601 timestamp>
+
+## Active Pheromones
+- <TYPE> (strength <current>): "<content>"
+(list each non-expired signal)
+
+## Phase Progress
+(for each phase, show status)
+- Phase <id>: <name> [<status>]
+
+## Current Phase Tasks
+(list tasks in the current phase with their statuses)
+- [<icon>] <task_id>: <description>
+
+## What Was Happening
+<brief description of what the colony was doing>
+
+## Next Steps on Resume
+<what should happen next>
+```
+
+### 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.**
+
+Before displaying the pause confirmation, check if the user has uncommitted work worth preserving.
+
+1. **Check for uncommitted changes:**
+```bash
+git status --porcelain 2>/dev/null
+```
+If the output is empty (nothing to commit) or the command fails (not a git repo), skip this step silently and continue to Step 5.
+
+2. **Check for double-prompting:**
+Read `last_commit_suggestion_phase` from COLONY_STATE.json (already loaded in Step 1).
+If `last_commit_suggestion_phase` equals the current phase, skip this step silently — the user was already prompted at POST-ADVANCE. Continue to Step 5.
+
+3. **Generate the commit message:**
+```bash
+bash .aether/aether-utils.sh generate-commit-message "pause" {current_phase} "{phase_name}"
+```
+Parse the returned JSON to extract `message` and `files_changed`.
+
+4. **Check files changed:**
+```bash
+git diff --stat HEAD 2>/dev/null | tail -5
+```
+
+5. **Display the suggestion:**
+```
+──────────────────────────────────────────────────
+Commit Suggestion
+──────────────────────────────────────────────────
+
+  Message:  {generated_message}
+  Files:    {files_changed} files changed
+  Preview:  {first 5 lines of git diff --stat}
+
+──────────────────────────────────────────────────
+```
+
+6. **Use AskUserQuestion:**
+```
+Commit your work before pausing?
+
+1. Yes, commit with this message
+2. Yes, but let me write the message
+3. No, I'll commit later
+```
+
+7. **If option 1 ("Yes, commit with this message"):**
+```bash
+git add -A && git commit -m "{generated_message}"
+```
+Display: `Committed: {generated_message} ({files_changed} files)`
+
+8. **If option 2 ("Yes, but let me write the message"):**
+Use AskUserQuestion to get the user's custom commit message, then:
+```bash
+git add -A && git commit -m "{custom_message}"
+```
+Display: `Committed: {custom_message} ({files_changed} files)`
+
+9. **If option 3 ("No, I'll commit later"):**
+Display: `Skipped. Your changes are saved on disk but not committed.`
+
+10. **Record the suggestion to prevent double-prompting:**
+Set `last_commit_suggestion_phase` to `{current_phase}` in COLONY_STATE.json (add the field at the top level if it does not exist).
+
+**Error handling:** If any git command fails (not a repo, merge conflict, pre-commit hook rejection), display the error output and continue to Step 5. The commit suggestion is advisory only — it never blocks the pause flow.
+
+Continue to Step 5.
+
+### Step 5: Display Confirmation
+
+Output header:
+
+```
+💾🐜⏸️🐜💾 ═══════════════════════════════════════════════════
+   C O L O N Y   P A U S E D
+═══════════════════════════════════════════════════ 💾🐜⏸️🐜💾
+```
+
+Then output:
++=====================================================+
+|  AETHER COLONY :: PAUSED                             |
++=====================================================+
+
+  Goal: "<goal>"
+  Phase: <current_phase> — <phase_name>
+  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/.aether/commands/opencode/phase.md

@@ -0,0 +1,113 @@
+<!-- Generated from .aether/commands/phase.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:phase
+description: "📝🐜📍🐜📝 Show phase details - Queen reviews phase status, tasks, and caste assignment"
+---
+
+### 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.
+
+You are the **Queen Ant Colony**. Display phase details from the project plan.
+
+## Instructions
+
+The argument is: `$normalized_args`
+
+### Step 1: Read State
+
+Use the Read tool to read `.aether/data/COLONY_STATE.json`.
+
+If `goal` is null, output `No colony initialized. Run /ant:init first.` and stop.
+
+If `plan.phases` is an empty array, output `No project plan. Run /ant:plan first.` and stop.
+
+### Step 2: Determine What to Show
+
+- 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
+
+Find the phase by ID in `plan.phases`.
+
+**Calculate next phase ID:**
+- Let `total_phases` = length of `plan.phases` array
+- If current phase ID < total_phases, then `next_id` = current phase ID + 1
+- If current phase ID >= total_phases (viewing last phase), omit the "View next phase" suggestion
+
+Output this header:
+
+
+
+```
+📝🐜📍🐜📝 ═══════════════════════════════════════════════════
+   P H A S E   {id}   D E T A I L S
+═══════════════════════════════════════════════════ 📝🐜📍🐜📝
+
+
+Then display:
+
+```
+📍 Phase <id>: <name>
+📊 Status: <status>
+
+   <description>
+
+🐜 Tasks:
+   {status_icon} <task_id>: <description>
+      ↳ depends on: <deps or "none">
+
+✅ Success Criteria:
+   • <criterion>
+
+───────────────────────────────────────────────────
+
+
+🐜 Next Steps:
+
+───────────────────────────────────────────────────
+   /ant:build <id>       🔨 Phase <id>: <phase_name>
+   /ant:phase <next_id>  📋 Phase <next_id>: <next_phase_name> (only if not last phase)
+   /ant:status           📊 Colony status
+```
+
+
+
+Status icons: `[ ]` pending, `[~]` in_progress, `[✓]` completed
+
+### Step 3b: List View
+
+Output this header:
+
+
+
+```
+📝🐜📍🐜📝 ═══════════════════════════════════════════════════
+   A L L   P H A S E S
+═══════════════════════════════════════════════════ 📝🐜📍🐜📝
+
+
+For each phase in `plan.phases`, display:
+```
+[{id}] {name} [{status}]
+   {short_description}
+```
+
+Display phases grouped by status:
+```
+✓ Completed
+   [{id}] {name}
+~ In Progress
+   [{id}] {name}
+[ ] Pending
+   [{id}] {name}
+```
+
+Display completion progress:
+```
+📊 Overall: {completed_count}/{total_count} phases complete
+```

package/.aether/commands/opencode/pheromones.md

@@ -0,0 +1,162 @@
+<!-- Generated from .aether/commands/pheromones.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:pheromones
+description: "🎯🐜🚫🐜💬 View and manage active pheromone signals"
+---
+
+### 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.
+
+You are the **Queen**. Display and manage the colony's pheromone signals.
+
+## Instructions
+
+Parse `$normalized_args`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+Extract subcommand from `$normalized_args`:
+- No argument or `all`: Show all active pheromones
+- `focus`: Show only FOCUS signals
+- `redirect`: Show only REDIRECT signals
+- `feedback`: Show only FEEDBACK signals
+- `clear`: Clear expired/inactive signals
+- `expire <id>`: Expire a specific signal by ID
+
+### Step 1: Read Colony State
+
+Read `.aether/data/COLONY_STATE.json`.
+
+If file missing or `goal: null`:
+```
+No colony initialized. Run /ant:init first.
+```
+Stop here.
+
+### Step 2: Handle Subcommands
+
+**If subcommand is `clear`:**
+
+Run using the Bash tool:
+```bash
+# Count signals before
+before_count=$(jq '[.signals[] | select(.active == true)] | length' .aether/data/pheromones.json 2>/dev/null || echo "0")
+
+# Mark expired/inactive signals as inactive
+now=$(date +%s)
+jq --argjson now "$now" '
+  def to_epoch(ts):
+    if ts == null or ts == "" or ts == "phase_end" then null
+    else
+      (ts | split("T")) as $parts |
+      ($parts[0] | split("-")) as $d |
+      ($parts[1] | rtrimstr("Z") | split(":")) as $t |
+      (($d[0] | tonumber) - 1970) * 365 * 86400 +
+      (($d[1] | tonumber) - 1) * 30 * 86400 +
+      (($d[2] | tonumber) - 1) * 86400 +
+      ($t[0] | tonumber) * 3600 +
+      ($t[1] | tonumber) * 60 +
+      ($t[2] | rtrimstr("Z") | tonumber)
+    end;
+
+  def decay_days(t):
+    if t == "FOCUS"    then 30
+    elif t == "REDIRECT" then 60
+    else 90
+    end;
+
+  .signals = [.signals[] |
+    (to_epoch(.created_at)) as $created_epoch |
+    (if $created_epoch != null then ($now - $created_epoch) / 86400 else 0 end) as $elapsed_days |
+    (decay_days(.type)) as $dd |
+    ((.strength // 0.8) * (1 - ($elapsed_days / $dd))) as $eff_raw |
+    (if $eff_raw < 0 then 0 else $eff_raw end) as $eff |
+    if $eff < 0.1 then . + {active: false} else . end
+  ]
+' .aether/data/pheromones.json > .aether/data/pheromones.json.tmp && mv .aether/data/pheromones.json.tmp .aether/data/pheromones.json
+
+# Count signals after
+after_count=$(jq '[.signals[] | select(.active == true)] | length' .aether/data/pheromones.json 2>/dev/null || echo "0")
+cleared=$((before_count - after_count))
+
+echo "before=$before_count after=$after_count cleared=$cleared"
+```
+
+Display:
+```
+🧹 Pheromone Cleanup
+
+   Before: {before_count} active signals
+   After:  {after_count} active signals
+   Cleared: {cleared} expired signal(s)
+
+Run /ant:pheromones to see remaining signals.
+```
+Stop here.
+
+**If subcommand is `expire <id>`:**
+
+Extract the signal ID from arguments.
+Run using the Bash tool:
+```bash
+signal_id="{extracted_id}"
+jq --arg id "$signal_id" '.signals = [.signals[] | if .id == $id then . + {active: false} else . end]' .aether/data/pheromones.json > .aether/data/pheromones.json.tmp && mv .aether/data/pheromones.json.tmp .aether/data/pheromones.json && echo "expired=$signal_id"
+```
+
+Display:
+```
+✓ Signal expired: {signal_id}
+
+Run /ant:pheromones to see remaining signals.
+```
+Stop here.
+
+### Step 3: Display Active Pheromones (default or filter)
+
+Run using the Bash tool with description "Displaying pheromones...":
+```bash
+bash .aether/aether-utils.sh pheromone-display "{subcommand or 'all'}"
+```
+
+The output will be the formatted pheromone table.
+
+### Step 4: Summary and Next Steps
+
+Display guidance:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+💡 Managing Pheromones
+
+   /ant:focus "area"      🎯 Guide attention
+   /ant:redirect "avoid"  🚫 Set hard constraint
+   /ant:feedback "note"   💬 Provide guidance
+   /ant:pheromones clear  🧹 Clear expired signals
+
+🐜 Signals decay over time: FOCUS 30d, REDIRECT 60d, FEEDBACK 90d
+```
+
+### Edge Cases
+
+**No pheromones file:**
+```
+No pheromones active. Colony has no signals.
+
+Inject signals with:
+  /ant:focus "area"    - Guide attention
+  /ant:redirect "avoid" - Set hard constraint
+  /ant:feedback "note"  - Provide guidance
+```
+
+**No active signals of filtered type:**
+```
+No active {type} signals found.
+
+Try: /ant:pheromones (to see all)
+```
+
+**Invalid subcommand:**
+Display help showing valid subcommands.