aether-colony 5.0.0 → 5.2.1

package/.claude/commands/ant/export-signals.md

@@ -0,0 +1,57 @@
+<!-- Generated from .aether/commands/export-signals.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:export-signals
+description: "Export colony pheromone signals to portable XML format"
+---
+
+You are the **Queen**. Export colony pheromone signals to portable XML format.
+
+## Instructions
+
+The optional output path is: `$ARGUMENTS`
+
+### Step 1: Validate
+
+Read `.aether/data/COLONY_STATE.json`.
+If file missing or `goal: null` -> "No colony initialized. Run /ant:init first.", stop.
+
+Parse `$ARGUMENTS`:
+- If a path is provided, use it as the output path.
+- If empty, default to `.aether/exchange/pheromones.xml`.
+
+### Step 2: Export
+
+Run using the Bash tool with description "Exporting pheromone signals to XML...":
+```bash
+bash .aether/aether-utils.sh pheromone-export-xml "<output_path>"
+```
+
+Parse the returned JSON:
+- If `.ok` is `true`: extract `.result.path` and `.result.validated` (if present).
+- If `.ok` is `false`: check `.error` for details. If error mentions `xmllint` or `E_FEATURE_UNAVAILABLE`, display: "XML export requires xmllint. Install with: xcode-select --install (macOS) or apt-get install libxml2-utils (Linux)." Otherwise display the error message and stop.
+
+### Step 3: Confirm
+
+
+Output (3-5 lines, no banners):
+```
+Pheromone signals exported to XML
+  Path: <output_path>
+  Validated: <yes/no based on .result.validated>
+
+Share this file with another colony using /ant:import-signals.
+```
+
+
+
+
+### Step 4: 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/.claude/commands/ant/feedback.md

@@ -1,10 +1,14 @@
+<!-- Generated from .aether/commands/feedback.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:feedback
 description: "Emit FEEDBACK signal to provide guidance to colony"
 ---
 
+
 You are the **Queen**. Emit a FEEDBACK pheromone signal.
 
+
+
 ## Instructions
 
 The feedback message is: `$ARGUMENTS`
@@ -14,15 +18,18 @@ The feedback message is: `$ARGUMENTS`
 If `$ARGUMENTS` empty -> show usage: `/ant:feedback <message>`, stop.
 If content > 500 chars -> "Signal 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 feedback message.
 
+
 ### Step 2: Write Signal and Create Instinct
 
 Read `.aether/data/COLONY_STATE.json`.
 If `goal: null` -> "No colony initialized.", stop.
 
+
 Run using the Bash tool with description "Recording colony feedback...":
 ```bash
 bash .aether/aether-utils.sh pheromone-write FEEDBACK "<content>" --strength 0.7 --reason "User feedback guidance" --ttl <ttl>
@@ -48,6 +55,13 @@ User feedback is high-value learning. Generate ISO-8601 timestamp and append to
 
 Write COLONY_STATE.json.
 
+### 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 feedback "<content>" "user" 2>/dev/null || true
+```
+
 ### Step 3: Get Active Counts
 
 Run using the Bash tool with description "Counting active signals...":
@@ -67,6 +81,9 @@ FEEDBACK signal emitted
 Instinct created: [0.7] <domain>: <action summary>
 ```
 
+
+
+
 ### Step 5: Next Up
 
 Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
@@ -76,3 +93,4 @@ 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/.claude/commands/ant/flag.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/flag.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:flag
 description: "🚩🐜📋🐜🚩 Create a project-specific flag (blocker, issue, or note)"
@@ -61,23 +62,32 @@ 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:
@@ -119,6 +129,7 @@ Then output based on flag type:
    Use /ant:flags to view all flags.
 ```
 
+
 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)
@@ -127,6 +138,7 @@ 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"
 ```
 
+
 ---
 
 ## Flag Lifecycle

package/.claude/commands/ant/flags.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/flags.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:flags
 description: "📋🐜🚩🐜📋 List project flags (blockers, issues, notes)"
@@ -27,7 +28,10 @@ Examples:
 
 ### Step 2: Handle Resolution/Acknowledgment
 
+
 If `--resolve` was provided, run using the Bash tool with description "Resolving colony flag...":
+
+
 ```bash
 bash .aether/aether-utils.sh flag-resolve "{flag_id}" "{resolution_message}"
 ```
@@ -39,7 +43,10 @@ Output:
 ```
 Stop here.
 
+
 If `--ack` was provided, run using the Bash tool with description "Acknowledging colony flag...":
+
+
 ```bash
 bash .aether/aether-utils.sh flag-acknowledge "{flag_id}"
 ```
@@ -53,7 +60,10 @@ Stop here.
 
 ### Step 3: List Flags
 
+
 Run using the Bash tool with description "Loading colony flags...":
+
+
 ```bash
 bash .aether/aether-utils.sh flag-list {options}
 ```
@@ -64,19 +74,21 @@ Parse result for flags array.
 
 Output header:
 
+
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📋🐜🚩🐜📋  P R O J E C T   F L A G S
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
 
 If no flags:
 ```
        .-.
       (o o)  AETHER COLONY
       | O |  Flags
-       `-`
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+       `-"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ✨ No active flags! Colony is clear.
 
@@ -88,8 +100,8 @@ If flags exist:
        .-.
       (o o)  AETHER COLONY
       | O |  Flags
-       `-`
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+       `-"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 {for each flag, grouped by type:}
 
@@ -114,7 +126,7 @@ If flags exist:
    {flag_id}: {title}
    Resolved: {date} | {resolution}
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Summary: {blockers} blockers | {issues} issues | {notes} notes
 
@@ -127,6 +139,7 @@ Commands:
   /ant:flag "description"               Create new flag
 ```
 
+
 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)
@@ -135,6 +148,7 @@ 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"
 ```
 
+
 ---
 
 ## Quick Actions

package/.claude/commands/ant/focus.md

@@ -1,10 +1,14 @@
+<!-- Generated from .aether/commands/focus.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:focus
 description: "Emit FOCUS signal to guide colony attention"
 ---
 
+
 You are the **Queen**. Emit a FOCUS pheromone signal.
 
+
+
 ## Instructions
 
 The focus area is: `$ARGUMENTS`
@@ -14,15 +18,18 @@ The focus area is: `$ARGUMENTS`
 If `$ARGUMENTS` empty -> show usage: `/ant:focus <area>`, stop.
 If content > 500 chars -> "Focus 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 focus area.
 
+
 ### 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 focus...":
 ```bash
 bash .aether/aether-utils.sh pheromone-write FOCUS "<content>" --strength 0.8 --reason "User directed colony attention" --ttl <ttl>
@@ -30,6 +37,13 @@ bash .aether/aether-utils.sh pheromone-write FOCUS "<content>" --strength 0.8 --
 
 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 focus "<content>" "user" 2>/dev/null || true
+```
+
 ### Step 3: Get Active Counts
 
 Run using the Bash tool with description "Counting active signals...":
@@ -47,6 +61,9 @@ FOCUS signal emitted
   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...":
@@ -56,3 +73,4 @@ 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/.claude/commands/ant/help.md

@@ -1,6 +1,7 @@
+<!-- Generated from .aether/commands/help.yaml - DO NOT EDIT DIRECTLY -->
 ---
-name: help
-description: "🐜📖 Aether Colony - command reference and system overview"
+name: ant:help
+description: "Aether Colony - command reference and system overview"
 ---
 
 You are the **Queen Ant Colony**. Display the system overview and available commands.
@@ -13,12 +14,14 @@ Output the following:
 👑 AETHER QUEEN ANT COLONY
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+
   A multi-agent system built on ant colony intelligence.
   Workers self-organize via pheromone signals. You guide with intention.
 
-GETTING STARTED
+SETUP & GETTING STARTED
 
-  /ant:init "<goal>"     Set colony intention and initialize
+  /ant:lay-eggs          Set up Aether in this repo (one-time, creates .aether/)
+  /ant:init "<goal>"     Start a colony with a goal
   /ant:colonize          Analyze existing codebase (optional)
   /ant:plan              Generate project plan
   /ant:build <phase>     Execute a phase (spawns parallel workers)
@@ -29,24 +32,36 @@ PHEROMONE COMMANDS
   /ant:focus "<area>"    Guide colony attention (priority: normal, expires: phase end)
   /ant:redirect "<pat>"  Warn away from pattern (priority: high, expires: phase end)
   /ant:feedback "<msg>"  Adjust behavior (priority: low, expires: phase end)
+  /ant:pheromones        View and manage active pheromone signals
+  /ant:export-signals [path]  Export pheromone signals to portable XML
+  /ant:import-signals <file> [colony]  Import signals from another colony's XML
 
 STATUS & UPDATES
 
   /ant:status            Colony dashboard — goal, phase, instincts, flags
   /ant:update            Update system files from global hub (~/.aether/)
   /ant:phase [N|list]    View phase details or list all phases
+  /ant:insert-phase      Insert a corrective phase after current phase
   /ant:flags             List active flags (blockers, issues, notes)
   /ant:flag "<title>"    Create a flag (blocker, issue, or note)
 
+  /ant:memory-details    Show detailed colony memory — wisdom, promotions, failures
+  /ant:maturity          View colony maturity journey and milestone progress
+
+
 SESSION COMMANDS
 
   /ant:pause-colony      Save state and create handoff document
   /ant:resume-colony     Restore from pause (full state + context)
+
+  /ant:resume            Quick session restore (memory health + next steps)
+
   /ant:watch             Set up tmux session for live colony visibility
 
 COLONY LIFECYCLE
 
   /ant:seal             Seal colony with Crowned Anthill milestone
+  /ant:entomb           Archive completed colony into chambers
   /ant:history          Browse colony event history
 
 ADVANCED
@@ -58,10 +73,15 @@ ADVANCED
   /ant:interpret         Review dreams — validate against codebase, discuss action
   /ant:chaos             🎲 Resilience testing — adversarial probing of the codebase
   /ant:archaeology       🏺 Git history analysis — excavate patterns from commit history
+  /ant:tunnels           Browse archived colonies and compare chambers
 
 TYPICAL WORKFLOW
 
-  1. /ant:init "Build a REST API with auth"
+  First time in a repo:
+  0. /ant:lay-eggs                           (set up Aether in this repo)
+
+  Starting a colony:
+  1. /ant:init "Build a REST API with auth"  (start colony with a goal)
   2. /ant:colonize                           (if existing code)
   3. /ant:plan                               (generates phases)
   4. /ant:focus "security"                   (optional guidance)
@@ -73,6 +93,11 @@ TYPICAL WORKFLOW
   8. /ant:resume-colony                      (restore full context)
   9. /ant:status                             (see where you left off)
 
+  After completing a colony:
+  10. /ant:seal                              (mark as complete)
+  11. /ant:entomb                            (archive to chambers)
+  12. /ant:init "next project goal"          (start fresh colony)
+
 WORKER CASTES
 
   👑 Queen        — orchestrates, spawns workers, synthesizes results
@@ -88,8 +113,11 @@ WORKER CASTES
 HOW IT WORKS
 
   Colony Lifecycle:
+
     INIT → PLAN → BUILD → CONTINUE → BUILD → ... → COMPLETE
 
+
+
   Workers spawn sub-workers autonomously (max depth 3).
   Builders receive colony knowledge (instincts, learnings, error patterns).
   Watchers independently verify work — builders never self-approve.
@@ -105,18 +133,22 @@ HOW IT WORKS
     Graveyards — markers on files where workers previously failed
 
   State Files (.aether/data/):
-    COLONY_STATE.json   Goal, phases, tasks, memory, signals, events
+    COLONY_STATE.json   Goal, phases, tasks, memory, events
     activity.log        Timestamped worker activity
     spawn-tree.txt      Worker spawn hierarchy
-    constraints.json    Focus/redirect pheromone data
+    pheromones.json     Active FOCUS/REDIRECT/FEEDBACK signals
+    constraints.json    Compatibility mirror for focus/redirect data
+
 ```
 
+
 ### Next Up
 
-Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+Generate the state-based Next Up block by Run 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/.claude/commands/ant/history.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/history.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:history
 description: "📜🐜📜 Show colony event history"
@@ -126,6 +127,7 @@ Show total event count at the end:
 Total events recorded: <count>
 ```
 
+
 ### Step 8: Next Up
 
 Generate the state-based Next Up block using the Bash tool with description "Generating Next Up suggestions...":
@@ -135,3 +137,4 @@ 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/.claude/commands/ant/import-signals.md

@@ -0,0 +1,71 @@
+<!-- Generated from .aether/commands/import-signals.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:import-signals
+description: "Import pheromone signals from another colony's XML export"
+---
+
+You are the **Queen**. Import pheromone signals from another colony's XML export.
+
+## Instructions
+
+The arguments are: `$ARGUMENTS`
+
+### Step 1: Validate
+
+Read `.aether/data/COLONY_STATE.json`.
+If file missing or `goal: null` -> "No colony initialized. Run /ant:init first.", stop.
+
+Parse `$ARGUMENTS`:
+- First argument: path to XML file (required).
+- Second argument: colony name/prefix (optional; default: derive from XML filename without extension, or use "imported").
+
+If no arguments provided, show usage and stop:
+```
+Usage: /ant:import-signals <path-to-signals.xml> [colony-name]
+
+  <path-to-signals.xml>  Path to an exported pheromone XML file
+  [colony-name]          Optional prefix for imported signal IDs (prevents collisions)
+
+Example:
+  /ant:import-signals .aether/exchange/pheromones.xml partner-colony
+```
+
+Verify the XML file exists. If not -> "File not found: <path>", stop.
+
+### Step 2: Import
+
+Run using the Bash tool with description "Importing pheromone signals from XML...":
+```bash
+bash .aether/aether-utils.sh pheromone-import-xml "<xml_path>" "<colony_prefix>"
+```
+
+Parse the returned JSON:
+- If `.ok` is `true`: extract `.result.signal_count` and `.result.source`.
+- If `.ok` is `false`: check `.error` for details. If error mentions `xmllint` or `E_FEATURE_UNAVAILABLE`, display: "XML import requires xmllint. Install with: xcode-select --install (macOS) or apt-get install libxml2-utils (Linux)." Otherwise display the error message and stop.
+
+### Step 3: Confirm
+
+
+Output (4-5 lines, no banners):
+```
+Pheromone signals imported
+  Source: <xml_path>
+  Signals imported: <signal_count>
+  Colony prefix: <colony_prefix>
+
+Note: On signal ID collision, current colony signals take priority.
+```
+
+
+
+
+### Step 4: 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"
+```
+