aether-colony 5.0.0 → 5.2.1

package/.aether/commands/help.yaml

@@ -0,0 +1,167 @@
+---
+name: ant:help
+description: "Aether Colony - command reference and system overview"
+body: |
+  You are the **Queen Ant Colony**. Display the system overview and available commands.
+
+  ## Instructions
+
+  Output the following:
+
+  ```
+  👑 AETHER QUEEN ANT COLONY
+  {{#claude}}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━{{/claude}}
+  {{#opencode}}══════════════════════════════════════════{{/opencode}}
+
+    A multi-agent system built on ant colony intelligence.
+    Workers self-organize via pheromone signals. You guide with intention.
+
+  SETUP & GETTING STARTED
+
+    /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)
+    /ant:continue          Verify work, extract learnings, advance
+
+  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)
+  {{#claude}}
+    /ant:memory-details    Show detailed colony memory — wisdom, promotions, failures
+    /ant:maturity          View colony maturity journey and milestone progress
+  {{/claude}}
+
+  SESSION COMMANDS
+
+    /ant:pause-colony      Save state and create handoff document
+    /ant:resume-colony     Restore from pause (full state + context)
+  {{#claude}}
+    /ant:resume            Quick session restore (memory health + next steps)
+  {{/claude}}
+    /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
+
+    /ant:swarm "<bug>"     Parallel scouts investigate stubborn bugs
+    /ant:organize          Codebase hygiene report (stale files, dead code)
+    /ant:council           Convene council for intent clarification
+    /ant:dream             Philosophical wanderer — observes and writes wisdom
+    /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
+
+    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)
+    5. /ant:build 1                            (workers execute phase 1)
+    6. /ant:continue                           (verify, learn, advance)
+    7. /ant:build 2                            (repeat until complete)
+
+    After /clear or session break:
+    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
+    🗺️ colonizer    — explores codebase, maps structure
+    📋 route-setter — plans phases, breaks down goals
+    🔨 builder      — implements code, runs commands
+    👁️ watcher      — validates, tests, independent quality checks
+    🔍 scout        — researches, gathers information
+    🏛️ architect    — synthesizes knowledge, extracts patterns
+    🎲 chaos        — resilience tester, adversarial probing
+    🏺 archaeologist — git history analyst, excavates commit patterns
+
+  HOW IT WORKS
+
+    Colony Lifecycle:
+  {{#claude}}
+      INIT → PLAN → BUILD → CONTINUE → BUILD → ... → COMPLETE
+  {{/claude}}
+  {{#opencode}}
+      LAY-EGGS → INIT → PLAN → BUILD → CONTINUE → BUILD → ... → SEAL → ENTOMB
+  {{/opencode}}
+
+    Workers spawn sub-workers autonomously (max depth 3).
+    Builders receive colony knowledge (instincts, learnings, error patterns).
+    Watchers independently verify work — builders never self-approve.
+    Phase boundaries are control points: emergence within, gates between.
+
+    Pheromone System:
+      Signals expire after their TTL. Workers sense active signals
+      and adjust behavior. FOCUS attracts, REDIRECT repels, FEEDBACK calibrates.
+
+    Colony Memory:
+      Instincts — learned patterns with confidence scores (validated through use)
+      Learnings — per-phase observations (hypothesis → validated → disproven)
+      Graveyards — markers on files where workers previously failed
+
+    State Files (.aether/data/):
+      COLONY_STATE.json   Goal, phases, tasks, memory, events
+      activity.log        Timestamped worker activity
+      spawn-tree.txt      Worker spawn hierarchy
+      pheromones.json     Active FOCUS/REDIRECT/FEEDBACK signals
+      constraints.json    Compatibility mirror for focus/redirect data
+  {{#opencode}}
+
+  OPENCODE USERS
+
+    Argument syntax: OpenCode handles multi-word arguments differently than Claude.
+    Wrap text arguments in quotes for reliable parsing:
+
+      ✅ /ant:init "Build a REST API"
+      ✅ /ant:plan "authentication system"
+      ✅ /ant:focus "database layer"
+
+    Without quotes, only the first word may be captured. This is now handled
+    automatically by the normalize-args utility, but quoting is recommended.
+  {{/opencode}}
+  ```
+  {{#claude}}
+
+  ### Next Up
+
+  Generate the state-based Next Up block by {{TOOL_PREFIX "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/history.yaml

@@ -0,0 +1,137 @@
+name: "ant:history"
+description: "📜🐜📜 Show colony event history"
+body: |
+  You are the **Queen**. Show colony history.
+
+  ## Instructions
+
+  ### Step 1: Read State
+
+  Read `.aether/data/COLONY_STATE.json`.
+
+  If file missing or `goal: null`:
+  ```
+  No colony initialized. Run /ant:init first.
+  ```
+  Stop here.
+
+  ### Step 2: Parse Events
+
+  Extract the `events` array from the state.
+
+  Each event is in format: `timestamp|type|source|description`
+
+  Parse each event into components:
+  - timestamp: before first `|`
+  - type: between first and second `|`
+  - source: between second and third `|`
+  - description: after third `|`
+
+  ### Step 3: Parse Filter Arguments
+
+  Parse optional filter arguments:
+
+  **Event Type Filter:**
+  - `--type TYPE` or `-t TYPE`: Filter by event type
+  - Multiple types can be specified (comma-separated)
+  - Valid types: `colony_initialized`, `phase_started`, `phase_advanced`, `plan_generated`, `milestone_reached`, `state_upgraded`
+
+  **Date Range Filter:**
+  - `--since DATE`: Show events since DATE
+    - ISO format: `2026-02-13`, `2026-02-13T14:30:00`
+    - Relative: `1d` (1 day ago), `2h` (2 hours ago), `30m` (30 minutes ago)
+  - `--until DATE`: Show events until DATE
+    - Same format options as `--since`
+
+  ### Step 4: Apply Limit
+
+  Parse optional `--limit N` argument (default: 10).
+
+  If `--limit` is provided, only show N events.
+
+  ### Step 5: Filter Events
+
+  Apply filters to the events array:
+
+  **Type Filtering:**
+  - If `--type` is provided, split by comma to get list of types
+  - Filter events to only include those where type matches any of the specified types (case-insensitive)
+
+  **Date Range Filtering:**
+  - For `--since`: Parse the date value
+    - If relative (e.g., "1d", "2h", "30m"), calculate timestamp by subtracting from current time
+    - If ISO format, parse directly
+    - Filter events with timestamp >= since date
+  - For `--until`: Same parsing logic
+    - Filter events with timestamp <= until date
+
+  **Track Active Filters:**
+  - Record which filters are active for display indicator
+
+  ### Step 6: Sort and Display
+
+  Sort events in reverse chronological order (most recent first).
+
+  If events array is empty:
+  ```
+  No colony events recorded yet.
+  ```
+
+  **Filter Indicators:**
+  - If any filters are active, show at the top:
+    - Type filter: `Filters: type=<TYPE>[,<TYPE>...]`
+    - Since filter: `Filters: since=<DATE>`
+    - Until filter: `Filters: until=<DATE>`
+    - Multiple filters: Combine on same line (e.g., `Filters: type=phase_started,phase_advanced since=1d`)
+  - Show filtered count: "Showing X of Y events (filtered from Z total)"
+
+  Otherwise, display in format:
+  ```
+  ━━━ Colony History (most recent first) ━━━
+
+  [TIMESTAMP] [TYPE] from [SOURCE]
+    Description: [description]
+
+  [TIMESTAMP] [TYPE] from [SOURCE]
+    Description: [description]
+
+  ... (up to limit)
+  ```
+
+  **Format:**
+  - Timestamp: Show in readable format (e.g., "2026-02-13 14:30:00")
+  - Type: Uppercase event type
+  - Source: Italics for source
+  - Description: Plain text
+
+  **Event type icons:**
+  - `colony_initialized`: 🏠
+  - `phase_started`: 🚀
+  - `phase_advanced`: ➡️
+  - `plan_generated`: 📋
+  - `milestone_reached`: 🏆
+  - `state_upgraded`: 🔄
+  - `default`: 📌
+
+  **Limit display:**
+  - If filtering is active, show: "Showing X of Y events (filtered from Z total)"
+  - If only limit is applied (no filters), show: "Showing X of Y events"
+
+  ### Step 7: Display Summary
+
+  Show total event count at the end:
+  ```
+  Total events recorded: <count>
+  ```
+
+  {{#claude}}
+  ### Step 8: Next Up
+
+  Generate the state-based Next Up block 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/import-signals.yaml

@@ -0,0 +1,79 @@
+name: "ant:import-signals"
+description: "Import pheromone signals from another colony's XML export"
+body: |
+  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
+
+  {{#claude}}
+  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.
+  ```
+  {{/claude}}
+  {{#opencode}}
+  Output:
+  ```
+  Pheromone signals imported
+
+    Source: <xml_path>
+    Signals imported: <signal_count>
+    Colony prefix: <colony_prefix>
+
+  Note: On signal ID collision, current colony signals take priority.
+  ```
+  {{/opencode}}
+
+  {{#claude}}
+  ### 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"
+  ```
+  {{/claude}}