aether-colony 1.1.0

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

@@ -0,0 +1,367 @@
+---
+name: ant:entomb
+description: "⚰️🐜⚰️ Entomb completed colony in chambers"
+---
+
+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`.
+
+If file missing or `goal: null`:
+```
+No colony to entomb. Run /ant:init first.
+```
+Stop here.
+
+### Step 2: Validate Colony Can Be Entombed
+
+Extract: `goal`, `state`, `current_phase`, `plan.phases`, `memory.decisions`, `memory.phase_learnings`.
+
+**Precondition 1: All phases must be completed**
+
+Check if all phases in `plan.phases` have `status: "completed"`:
+```
+all_completed = all(phase.status == "completed" for phase in plan.phases)
+```
+
+If NOT all completed:
+```
+Cannot entomb incomplete colony.
+
+Completed phases: X of Y
+Remaining: {list of incomplete phase names}
+
+Run /ant:continue to complete remaining phases first.
+```
+Stop here.
+
+**Precondition 2: State must not be EXECUTING**
+
+If `state == "EXECUTING"`:
+```
+Colony is still executing. Run /ant:continue to reconcile first.
+```
+Stop here.
+
+**Precondition 3: No critical errors**
+
+Check `errors.records` for any entries with `severity: "critical"`.
+
+If critical errors exist:
+```
+Cannot entomb colony with critical errors.
+
+Critical errors: {count}
+Run /ant:continue to resolve errors first.
+```
+Stop here.
+
+### Step 3: Compute Milestone
+
+Determine milestone based on phases completed:
+- 0 phases: "Fresh Start"
+- 1 phase: "First Mound"
+- 2-4 phases: "Open Chambers"
+- 5+ phases: "Sealed Chambers"
+
+If all phases completed AND user explicitly sealing: "Crowned Anthill"
+
+For entombment, use the computed milestone or extract from state if already set.
+
+### Step 4: User Confirmation
+
+Display:
+```
+🏺 ═══════════════════════════════════════════════════
+   E N T O M B   C O L O N Y
+══════════════════════════════════════════════════ 🏺
+
+Goal: {goal}
+Phases: {completed}/{total} completed
+Milestone: {milestone}
+
+Archive will include:
+  - COLONY_STATE.json
+  - manifest.json (pheromone trails)
+
+This will reset the active colony. Continue? (yes/no)
+```
+
+Wait for explicit "yes" response before proceeding.
+
+If user responds with anything other than "yes", display:
+```
+Entombment cancelled. Colony remains active.
+```
+Stop here.
+
+### Step 4.5: Check XML Tools
+
+XML archiving is required for entombment. Check tool availability before proceeding.
+Uses `command -v xmllint` directly — consistent with seal.md's tool check.
+
+```bash
+if command -v xmllint >/dev/null 2>&1; then
+  xmllint_available=true
+else
+  xmllint_available=false
+fi
+```
+
+**If xmllint is NOT available:**
+
+Ask the user:
+```
+xmllint is not installed — XML archiving requires it.
+
+Install now?
+  - macOS: xcode-select --install (or brew install libxml2)
+  - Linux: apt-get install libxml2-utils
+
+Install xmllint? (yes/no)
+```
+
+Use AskUserQuestion with yes/no options.
+
+If yes:
+- On macOS: Run `xcode-select --install` or `brew install libxml2`
+- On Linux: Run `sudo apt-get install -y libxml2-utils`
+- After install attempt, re-check: `command -v xmllint >/dev/null 2>&1`
+- If still not available after install:
+  ```
+  xmllint installation failed. Cannot entomb without XML archiving.
+  Install xmllint manually and try again.
+  ```
+  Stop here.
+
+If no:
+```
+Entombment requires XML archiving. Install xmllint and try again.
+```
+Stop here.
+
+### Step 5: Create Chamber
+
+Generate chamber name:
+```bash
+sanitized_goal=$(echo "{goal}" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-' | sed 's/^-//;s/-$//' | cut -c1-50)
+timestamp=$(date -u +%Y%m%d-%H%M%S)
+chamber_name="${sanitized_goal}-${timestamp}"
+```
+
+Handle name collision: if directory exists, append counter:
+```bash
+counter=1
+original_name="$chamber_name"
+while [[ -d ".aether/chambers/$chamber_name" ]]; do
+  chamber_name="${original_name}-${counter}"
+  counter=$((counter + 1))
+done
+```
+
+### Step 6: Create Chamber Using Utilities
+
+Extract decisions and learnings as JSON arrays:
+```bash
+decisions_json=$(jq -c '.memory.decisions // []' .aether/data/COLONY_STATE.json)
+learnings_json=$(jq -c '.memory.phase_learnings // []' .aether/data/COLONY_STATE.json)
+phases_completed=$(jq '[.plan.phases[] | select(.status == "completed")] | length' .aether/data/COLONY_STATE.json)
+total_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+version=$(jq -r '.version // "3.0"' .aether/data/COLONY_STATE.json)
+```
+
+Create the chamber:
+```bash
+bash .aether/aether-utils.sh chamber-create \
+  ".aether/chambers/{chamber_name}" \
+  ".aether/data/COLONY_STATE.json" \
+  "{goal}" \
+  {phases_completed} \
+  {total_phases} \
+  "{milestone}" \
+  "{version}" \
+  '{decisions_json}' \
+  '{learnings_json}'
+```
+
+### Step 6.5: Export XML Archive (hard-stop)
+
+Export combined XML archive to the chamber. This is a HARD REQUIREMENT — entomb fails if XML export fails.
+
+```bash
+chamber_dir=".aether/chambers/$chamber_name"
+xml_result=$(bash .aether/aether-utils.sh colony-archive-xml "$chamber_dir/colony-archive.xml" 2>&1)
+xml_ok=$(echo "$xml_result" | jq -r '.ok // false' 2>/dev/null)
+
+if [[ "$xml_ok" != "true" ]]; then
+  # HARD STOP — remove the chamber and abort
+  rm -rf "$chamber_dir"
+  echo "XML archive export failed. Colony NOT entombed."
+  echo ""
+  echo "Error: $(echo "$xml_result" | jq -r '.error // "Unknown error"' 2>/dev/null)"
+  echo ""
+  echo "The chamber has been cleaned up. Fix the XML issue and try again."
+  # Do NOT proceed to state reset or any further steps
+fi
+```
+
+If xml_ok is true, store for display:
+```bash
+xml_pheromone_count=$(echo "$xml_result" | jq -r '.result.pheromone_count // 0' 2>/dev/null)
+xml_archive_line="XML Archive: colony-archive.xml (${xml_pheromone_count} active signals)"
+```
+
+**Critical behavior:** If XML export fails, entomb STOPS. The chamber directory is removed (cleanup). The colony state is NOT reset. The user sees a clear error and can retry after fixing the issue.
+
+### Step 7: Verify Chamber Integrity
+
+Run verification:
+```bash
+bash .aether/aether-utils.sh chamber-verify ".aether/chambers/{chamber_name}"
+```
+
+If verification fails, display error and stop:
+```
+❌ Chamber verification failed.
+
+Error: {verification_error}
+
+The colony has NOT been reset. Please check the chamber directory:
+.aether/chambers/{chamber_name}/
+```
+Stop here.
+
+### Step 8: Reset Colony State
+
+Backup current state:
+```bash
+cp .aether/data/COLONY_STATE.json .aether/data/COLONY_STATE.json.bak
+```
+
+Reset state (including memory fields, already promoted to QUEEN.md):
+```bash
+# Resolve jq template path (hub-first)
+jq_template=""
+for path in \
+  "$HOME/.aether/system/templates/colony-state-reset.jq.template" \
+  ".aether/templates/colony-state-reset.jq.template"; do
+  if [[ -f "$path" ]]; then
+    jq_template="$path"
+    break
+  fi
+done
+
+if [[ -z "$jq_template" ]]; then
+  echo "Template missing: colony-state-reset.jq.template. Run aether update to fix."
+  exit 1
+fi
+
+jq -f "$jq_template" .aether/data/COLONY_STATE.json.bak > .aether/data/COLONY_STATE.json
+```
+
+Verify reset succeeded:
+```bash
+new_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+if [[ "$new_goal" != "null" ]]; then
+  # Restore from backup
+  mv .aether/data/COLONY_STATE.json.bak .aether/data/COLONY_STATE.json
+  echo "Error: State reset failed. Restored from backup."
+  exit 1
+fi
+```
+
+Remove backup after successful reset:
+```bash
+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:
+
+Resolve the handoff template path:
+  Check ~/.aether/system/templates/handoff.template.md first,
+  then .aether/templates/handoff.template.md.
+
+If no template found: output "Template missing: handoff.template.md. Run aether update to fix." and stop.
+
+Read the template file. Fill all {{PLACEHOLDER}} values:
+  - {{CHAMBER_NAME}} → chamber_name
+  - {{GOAL}} → goal
+  - {{PHASES_COMPLETED}} → phases completed count
+  - {{TOTAL_PHASES}} → total phases count
+  - {{MILESTONE}} → milestone
+  - {{ENTOMB_TIMESTAMP}} → current ISO-8601 UTC timestamp
+
+Remove the HTML comment lines at the top of the template.
+Write the result to .aether/HANDOFF.md using the Write tool.
+
+This handoff serves as the record of the entombed colony.
+
+### Step 9: Display Result
+
+```
+🏺 ═══════════════════════════════════════════════════
+   C O L O N Y   E N T O M B E D
+══════════════════════════════════════════════════ 🏺
+
+✅ Colony archived successfully
+
+👑 Goal: {goal}
+📍 Phases: {completed} completed
+🏆 Milestone: {milestone}
+
+📦 Chamber: .aether/chambers/{chamber_name}/
+{xml_archive_line}
+
+🐜 The colony rests. Its learnings are preserved.
+
+💾 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
+
+**Chamber name collision:** Automatically append counter to make unique.
+
+**Missing files during archive:** Note in output but continue with available files.
+
+**State reset failure:** Restore from backup, display error, do not claim success.
+
+**Empty phases array:** Can entomb a colony that was initialized but had no phases planned (treat as 0 of 0 completed).

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

@@ -0,0 +1,80 @@
+---
+name: ant:feedback
+description: "💬🐜🧠🐜💬 Emit FEEDBACK signal to provide guidance to colony"
+---
+
+You are the **Queen**. Emit a FEEDBACK signal.
+
+## 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.
+
+The feedback message is: `$normalized_args`
+
+### Step 1: Validate
+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
+Read `.aether/data/COLONY_STATE.json`.
+If `goal: null` -> "No colony initialized.", stop.
+
+Generate ISO-8601 timestamp.
+
+**Add signal:**
+Append to `signals` array:
+```json
+{
+  "id": "feedback_<timestamp_ms>",
+  "type": "FEEDBACK",
+  "content": "<feedback message>",
+  "priority": "low",
+  "created_at": "<ISO-8601>",
+  "expires_at": "phase_end"
+}
+```
+
+**Create instinct from feedback:**
+User feedback is high-value learning. Append to `memory.instincts`:
+```json
+{
+  "id": "instinct_<timestamp>",
+  "trigger": "<infer from feedback context>",
+  "action": "<the feedback guidance>",
+  "confidence": 0.7,
+  "domain": "<infer: testing|architecture|code-style|debugging|workflow>",
+  "source": "user_feedback",
+  "evidence": ["User feedback: <content>"],
+  "created_at": "<ISO-8601>",
+  "last_applied": null,
+  "applications": 0,
+  "successes": 0
+}
+```
+
+Write COLONY_STATE.json.
+
+### Step 3: Confirm
+
+Output header:
+
+```
+💬🐜🧠🐜💬 ═══════════════════════════════════════════════════
+   F E E D B A C K   S I G N A L
+═══════════════════════════════════════════════════ 💬🐜🧠🐜💬
+```
+
+Then output:
+```
+💬 FEEDBACK signal emitted
+
+   "{content preview}"
+
+🧠 Instinct created: [0.7] <domain>: <action summary>
+
+🐜 The colony will remember this guidance.
+```

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

@@ -0,0 +1,137 @@
+---
+name: ant:flag
+description: "🚩🐜📋🐜🚩 Create a project-specific flag (blocker, issue, or note)"
+---
+
+You are the **Queen**. Create a project-specific flag.
+
+## 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.
+
+The flag is: `$normalized_args`
+
+### Step 1: Parse Arguments
+
+Parse `$normalized_args` for:
+- `--type` or `-t`: blocker | issue | note (default: issue)
+- `--phase` or `-p`: phase number (optional)
+- Remaining text: the flag title/description
+
+Examples:
+- `/ant:flag "Build fails on auth module"` → issue type
+- `/ant:flag --type blocker "API rate limit hit"` → blocker type
+- `/ant:flag -t note -p 3 "Consider refactoring later"` → note for phase 3
+
+If `$normalized_args` is empty:
+```
+Usage: /ant:flag "<description>" [--type blocker|issue|note] [--phase N]
+
+Types:
+  blocker  Critical issue that blocks phase advancement
+  issue    Warning that should be addressed (default)
+  note     Informational for future reference
+
+Examples:
+  /ant:flag "Build fails on auth"
+  /ant:flag --type blocker "Tests hanging"
+  /ant:flag -t note "Consider refactoring"
+```
+Stop here.
+
+### Step 2: Validate Colony
+
+Read `.aether/data/COLONY_STATE.json`.
+If file missing or `goal: null`:
+```
+No colony initialized. Run /ant:init first.
+```
+Stop here.
+
+### Step 3: Create Flag
+
+Run:
+```bash
+bash .aether/aether-utils.sh flag-add "{type}" "{title}" "{description}" "manual" {phase_or_null}
+```
+
+Parse the result for the flag ID.
+
+### Step 4: Confirm
+
+Output header based on flag type:
+
+**For blocker:**
+```
+🚩🐜📋🐜🚩 ═══════════════════════════════════════════════════
+   B L O C K E R   F L A G   C R E A T E D
+═══════════════════════════════════════════════════ 🚩🐜📋🐜🚩
+```
+
+**For issue:**
+```
+🚩🐜📋🐜🚩 ═══════════════════════════════════════════════════
+   I S S U E   F L A G   C R E A T E D
+═══════════════════════════════════════════════════ 🚩🐜📋🐜🚩
+```
+
+**For note:**
+```
+🚩🐜📋🐜🚩 ═══════════════════════════════════════════════════
+   N O T E   F L A G   C R E A T E D
+═══════════════════════════════════════════════════ 🚩🐜📋🐜🚩
+```
+
+Then output based on flag type:
+
+**For blocker:**
+```
+🚫 BLOCKER flag created
+
+   "{title}"
+
+   ID: {flag_id}
+   Phase: {phase or "all"}
+
+⚠️  This will BLOCK phase advancement until resolved.
+   Use /ant:flags to view all flags.
+```
+
+**For issue:**
+```
+⚠️  ISSUE flag created
+
+   "{title}"
+
+   ID: {flag_id}
+   Phase: {phase or "all"}
+
+   Use /ant:flags to view all flags.
+```
+
+**For note:**
+```
+📝 NOTE flag created
+
+   "{title}"
+
+   ID: {flag_id}
+   Phase: {phase or "all"}
+
+   Use /ant:flags to view all flags.
+```
+
+---
+
+## Flag Lifecycle
+
+1. **Created** - Flag is active and visible
+2. **Acknowledged** - Flag noted but continuing (issues/notes only)
+3. **Resolved** - Flag closed with resolution message
+4. **Auto-resolved** - Blockers auto-resolve on build_pass
+
+Blockers CANNOT be acknowledged - they must be resolved before phase advancement.