aether-colony 3.1.17 → 5.1.0

package/.aether/commands/watch.yaml

@@ -0,0 +1,454 @@
+name: "ant:watch"
+description: "👁️🔄🐜🏠🔄👁️ Set up tmux session to watch ants working in real-time"
+body_claude: |
+  You are the **Queen**. Set up live visibility into colony activity.
+
+  ## Instructions
+
+  ### Step 1: Check Prerequisites
+
+  Use Bash with description "Checking for tmux..." to check if tmux is available:
+  ```bash
+  command -v tmux >/dev/null 2>&1 && echo "tmux_available" || echo "tmux_missing"
+  ```
+
+  If tmux is missing:
+  ```
+  tmux is required for live colony viewing.
+
+  Install with:
+    macOS:  brew install tmux
+    Ubuntu: sudo apt install tmux
+    Fedora: sudo dnf install tmux
+  ```
+  Stop here.
+
+  ### Step 2: Initialize Activity Log
+
+  Ensure activity log exists by running using the Bash tool with description "Initializing watch files...":
+  ```bash
+  mkdir -p .aether/data
+  touch .aether/data/activity.log
+  ```
+
+  ### Step 2.5: Check for Stale Watch Session
+
+  Capture session start time:
+  ```bash
+  WATCH_START=$(date +%s)
+  ```
+
+  Check for stale watch files by running using the Bash tool with description "Checking for stale watch session...":
+  ```bash
+  stale_check=$(bash .aether/aether-utils.sh session-verify-fresh --command watch "" "$WATCH_START")
+  has_stale=$(echo "$stale_check" | jq -r '.stale | length' 2>/dev/null || echo "0")
+  ```
+
+  If stale files exist, they will be overwritten by the new watch session.
+  The tmux session check in Step 4 handles concurrent sessions.
+
+  ### Step 3: Create Status File
+
+  Write initial status to `.aether/data/watch-status.txt`:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY
+        | O |  Live Status
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Session Started: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  State: IDLE
+  Phase: -/-
+
+  Active Workers:
+    (none)
+
+  Last Activity:
+    (waiting for colony activity)
+  ```
+
+  ### Step 4: Create or Attach to tmux Session
+
+  Check if session exists by running using the Bash tool with description "Checking tmux session...":
+  ```bash
+  tmux has-session -t aether-colony 2>/dev/null && echo "exists" || echo "new"
+  ```
+
+  **If session exists:** Attach to it by running using the Bash tool with description "Attaching to watch session...":
+  ```bash
+  tmux attach-session -t aether-colony
+  ```
+  Output: `Attached to existing aether-colony session.`
+  Stop here.
+
+  **If session is new:** Create the layout.
+
+  ### Step 5: Create tmux Layout (4-Pane)
+
+  Use Bash with description "Creating watch session layout..." to create the session with 4 panes in a 2x2 grid:
+
+  ```bash
+  # Create session with first pane
+  tmux new-session -d -s aether-colony -n colony
+
+  # Split into 4 panes (2x2 grid)
+  # First split horizontally (left|right)
+  tmux split-window -h -t aether-colony:colony
+
+  # Split left side vertically (top-left, bottom-left)
+  tmux split-window -v -t aether-colony:colony.0
+
+  # Split right side vertically (top-right, bottom-right)
+  tmux split-window -v -t aether-colony:colony.2
+
+  # Set pane contents:
+  # Pane 0 (top-left): Status display
+  tmux send-keys -t aether-colony:colony.0 'watch -n 1 cat .aether/data/watch-status.txt' C-m
+
+  # Pane 1 (bottom-left): Progress bar
+  tmux send-keys -t aether-colony:colony.1 'watch -n 1 cat .aether/data/watch-progress.txt' C-m
+
+  # Pane 2 (top-right): Spawn tree visualization
+  tmux send-keys -t aether-colony:colony.2 'bash .aether/utils/watch-spawn-tree.sh .aether/data' C-m
+
+  # Pane 3 (bottom-right): Colorized activity log stream
+  tmux send-keys -t aether-colony:colony.3 'bash .aether/utils/colorize-log.sh .aether/data/activity.log' C-m
+
+  # Set pane titles (if supported)
+  tmux select-pane -t aether-colony:colony.0 -T "Status"
+  tmux select-pane -t aether-colony:colony.1 -T "Progress"
+  tmux select-pane -t aether-colony:colony.2 -T "Spawn Tree"
+  tmux select-pane -t aether-colony:colony.3 -T "Activity Log"
+
+  # Balance panes for even 2x2 grid
+  tmux select-layout -t aether-colony:colony tiled
+
+  echo "Session created"
+  ```
+
+  ### Step 6: Create Progress File
+
+  Write initial progress to `.aether/data/watch-progress.txt`:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY
+        | O |  Progress
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Phase: -/-
+
+  [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0%
+
+  ⏳ Waiting for build...
+
+  Target: 95% confidence
+  ```
+
+  ### Step 7: Attach and Display
+
+  Run using the Bash tool with description "Attaching to watch display...":
+  ```bash
+  tmux attach-session -t aether-colony
+  ```
+
+  Before attaching, output:
+
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  👁️🔄🐜🏠🔄👁️  A E T H E R   C O L O N Y   W A T C H
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  tmux session 'aether-colony' created.
+
+  Layout (4-pane 2x2 grid):
+    +------------------+------------------+
+    | Status           | Spawn Tree       |
+    | Colony state     | Worker hierarchy |
+    +------------------+------------------+
+    | Progress         | Activity Log     |
+    | Phase progress   | Live stream      |
+    +------------------+------------------+
+
+  Commands:
+    Ctrl+B D          Detach from session
+    Ctrl+B [          Scroll mode (q to exit)
+    Ctrl+B Arrow      Navigate between panes
+    tmux kill-session -t aether-colony   Stop watching
+
+  The session will update in real-time as colony works.
+  Attaching now...
+  ```
+
+  Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+
+  ---
+
+  ## Status Update Protocol
+
+  Workers and commands update watch files as they work:
+
+  ### Activity Log
+  Workers write via: `bash .aether/aether-utils.sh activity-log "ACTION" "caste" "description"`
+
+  For named ants (recommended):
+  ```bash
+  # Generate a name first
+  ant_name=$(bash .aether/aether-utils.sh generate-ant-name "builder" | jq -r '.result')
+  # Log with ant name
+  bash .aether/aether-utils.sh activity-log "CREATED" "$ant_name (Builder)" "Implemented auth module"
+  ```
+
+  ### Spawn Tracking
+  Log spawns for tree visualization:
+  ```bash
+  bash .aether/aether-utils.sh spawn-log "Prime" "builder" "Hammer-42" "implementing auth"
+  bash .aether/aether-utils.sh spawn-complete "Hammer-42" "completed" "auth module done"
+  ```
+
+  ### Status File
+  Commands update `.aether/data/watch-status.txt` with current state:
+  - State: PLANNING, EXECUTING, READY
+  - Phase: current/total
+  - Active Workers: list of named ants
+  - Last Activity: most recent log entry
+
+  ### Progress File
+  Update via: `bash .aether/aether-utils.sh update-progress <percent> "<message>" <phase> <total>`
+
+  Example:
+  ```bash
+  bash .aether/aether-utils.sh update-progress 45 "Building auth module..." 2 5
+  ```
+
+  ---
+
+  ## Cleanup
+
+  To stop watching:
+  ```bash
+  tmux kill-session -t aether-colony
+  ```
+
+  This stops the session but preserves all log files.
+
+body_opencode: |
+  You are the **Queen**. Set up live visibility into colony activity.
+
+  ## Instructions
+
+  ### Step 1: Check Prerequisites
+
+  Use Bash to check if tmux is available:
+  ```bash
+  command -v tmux >/dev/null 2>&1 && echo "tmux_available" || echo "tmux_missing"
+  ```
+
+  If tmux is missing:
+  ```
+  tmux is required for live colony viewing.
+
+  Install with:
+    macOS:  brew install tmux
+    Ubuntu: sudo apt install tmux
+    Fedora: sudo dnf install tmux
+  ```
+  Stop here.
+
+  ### Step 2: Initialize Activity Log
+
+  Ensure activity log exists:
+  ```bash
+  mkdir -p .aether/data
+  touch .aether/data/activity.log
+  ```
+
+  ### Step 3: Create Status File
+
+  Write initial status to `.aether/data/watch-status.txt`:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY
+        | O |  Live Status
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  State: IDLE
+  Phase: -/-
+
+  Active Workers:
+    (none)
+
+  Last Activity:
+    (waiting for colony activity)
+  ```
+
+  ### Step 4: Create or Attach to tmux Session
+
+  Check if session exists:
+  ```bash
+  tmux has-session -t aether-colony 2>/dev/null && echo "exists" || echo "new"
+  ```
+
+  **If session exists:** Attach to it
+  ```bash
+  tmux attach-session -t aether-colony
+  ```
+  Output: `Attached to existing aether-colony session.`
+  Stop here.
+
+  **If session is new:** Create the layout.
+
+  ### Step 5: Create tmux Layout (4-Pane)
+
+  Use Bash to create the session with 4 panes in a 2x2 grid:
+
+  ```bash
+  # Create session with first pane
+  tmux new-session -d -s aether-colony -n colony
+
+  # Split into 4 panes (2x2 grid)
+  # First split horizontally (left|right)
+  tmux split-window -h -t aether-colony:colony
+
+  # Split left side vertically (top-left, bottom-left)
+  tmux split-window -v -t aether-colony:colony.0
+
+  # Split right side vertically (top-right, bottom-right)
+  tmux split-window -v -t aether-colony:colony.2
+
+  # Set pane contents:
+  # Pane 0 (top-left): Status display
+  tmux send-keys -t aether-colony:colony.0 'watch -n 1 cat .aether/data/watch-status.txt' C-m
+
+  # Pane 1 (bottom-left): Progress bar
+  tmux send-keys -t aether-colony:colony.1 'watch -n 1 cat .aether/data/watch-progress.txt' C-m
+
+  # Pane 2 (top-right): Spawn tree visualization
+  tmux send-keys -t aether-colony:colony.2 'bash .aether/utils/watch-spawn-tree.sh .aether/data' C-m
+
+  # Pane 3 (bottom-right): Colorized activity log stream
+  tmux send-keys -t aether-colony:colony.3 'bash .aether/utils/colorize-log.sh .aether/data/activity.log' C-m
+
+  # Set pane titles (if supported)
+  tmux select-pane -t aether-colony:colony.0 -T "Status"
+  tmux select-pane -t aether-colony:colony.1 -T "Progress"
+  tmux select-pane -t aether-colony:colony.2 -T "Spawn Tree"
+  tmux select-pane -t aether-colony:colony.3 -T "Activity Log"
+
+  # Balance panes for even 2x2 grid
+  tmux select-layout -t aether-colony:colony tiled
+
+  echo "Session created"
+  ```
+
+  ### Step 6: Create Progress File
+
+  Write initial progress to `.aether/data/watch-progress.txt`:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY
+        | O |  Progress
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Phase: -/-
+
+  [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0%
+
+  ⏳ Waiting for build...
+
+  Target: 95% confidence
+  ```
+
+  ### Step 7: Attach and Display
+
+  ```bash
+  tmux attach-session -t aether-colony
+  ```
+
+  Before attaching, output:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY :: WATCH
+        | O |
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  tmux session 'aether-colony' created.
+
+  Layout (4-pane 2x2 grid):
+    +------------------+------------------+
+    | Status           | Spawn Tree       |
+    | Colony state     | Worker hierarchy |
+    +------------------+------------------+
+    | Progress         | Activity Log     |
+    | Phase progress   | Live stream      |
+    +------------------+------------------+
+
+  Commands:
+    Ctrl+B D          Detach from session
+    Ctrl+B [          Scroll mode (q to exit)
+    Ctrl+B Arrow      Navigate between panes
+    tmux kill-session -t aether-colony   Stop watching
+
+  The session will update in real-time as colony works.
+  Attaching now...
+  ```
+
+  ---
+
+  ## Status Update Protocol
+
+  Workers and commands update watch files as they work:
+
+  ### Activity Log
+  Workers write via: `bash .aether/aether-utils.sh activity-log "ACTION" "caste" "description"`
+
+  For named ants (recommended):
+  ```bash
+  # Generate a name first
+  ant_name=$(bash .aether/aether-utils.sh generate-ant-name "builder" | jq -r '.result')
+  # Log with ant name
+  bash .aether/aether-utils.sh activity-log "CREATED" "$ant_name (Builder)" "Implemented auth module"
+  ```
+
+  ### Spawn Tracking
+  Log spawns for tree visualization:
+  ```bash
+  bash .aether/aether-utils.sh spawn-log "Prime" "builder" "Hammer-42" "implementing auth"
+  bash .aether/aether-utils.sh spawn-complete "Hammer-42" "completed" "auth module done"
+  ```
+
+  ### Status File
+  Commands update `.aether/data/watch-status.txt` with current state:
+  - State: PLANNING, EXECUTING, READY
+  - Phase: current/total
+  - Active Workers: list of named ants
+  - Last Activity: most recent log entry
+
+  ### Progress File
+  Update via: `bash .aether/aether-utils.sh update-progress <percent> "<message>" <phase> <total>`
+
+  Example:
+  ```bash
+  bash .aether/aether-utils.sh update-progress 45 "Building auth module..." 2 5
+  ```
+
+  ---
+
+  ## Cleanup
+
+  To stop watching:
+  ```bash
+  tmux kill-session -t aether-colony
+  ```
+
+  This stops the session but preserves all log files.
+

package/.aether/docs/INCIDENT_TEMPLATE.md

@@ -0,0 +1,32 @@
+# Incident Report: {INCIDENT_ID}
+
+## Trigger
+- Command run: `/ant:{command}`
+- Expected outcome:
+- Actual outcome:
+
+## Root Cause Analysis
+- What failed:
+- Why it failed:
+- Which component: [ ] Orchestration [ ] State [ ] Memory [ ] Verification [ ] Spawn
+
+## Fix Applied
+- Commit: {hash}
+- Files changed:
+- Fix description:
+
+## Regression Test Added
+- Test file:
+- Test description:
+- How to run: `bash .aether/tests/{test_name}.sh`
+
+## Rule Added
+- Rule type: [ ] QUEEN.md decree [ ] workers.md constraint [ ] command-playbooks gate
+- Rule text:
+- Location:
+
+## Metrics
+- Time to detect:
+- Time to fix:
+- Spawn efficiency before:
+- Spawn efficiency after:

package/.aether/docs/QUEEN-SYSTEM.md

@@ -0,0 +1,211 @@
+# QUEEN.md System
+
+The QUEEN.md system is Aether's wisdom feedback loop - a mechanism for capturing, validating, and propagating learnings across colonies.
+
+## Overview
+
+The Queen represents the accumulation of validated knowledge from all colonies. As colonies complete work, they promote significant patterns, decisions, and insights to QUEEN.md. Future colonies can then read this wisdom to benefit from previous experience.
+
+## File Location
+
+```
+.aether/QUEEN.md
+```
+
+## Structure
+
+### 📜 Philosophies
+
+Core beliefs validated through repeated successful application across multiple colonies.
+
+**Threshold:** 1 successful validation required for promotion
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:24Z): Test-driven development ensures quality
+```
+
+### 🧭 Patterns
+
+Validated approaches that consistently work. These represent discovered best practices.
+
+**Threshold:** 1 successful validation required for promotion
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:28Z): Always validate inputs
+```
+
+### ⚠️ Redirects
+
+Anti-patterns to avoid. Approaches that have caused problems.
+
+**Threshold:** 1 failed validation required for promotion
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:31Z): Never skip security checks
+```
+
+### 🔧 Stack Wisdom
+
+Technology-specific insights detected through codebase analysis.
+
+**Threshold:** 1 validation required for promotion
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:36Z): Use jq for JSON in bash
+```
+
+### 🏛️ Decrees
+
+User-mandated rules that override other guidance.
+
+**Threshold:** 0 validations required (immediate promotion)
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:40Z): All code must have tests
+```
+
+### 📊 Evolution Log
+
+Track how wisdom has evolved over time.
+
+## Commands
+
+### queen-init
+
+Initialize QUEEN.md from template if it doesn't exist.
+
+```bash
+bash .aether/aether-utils.sh queen-init
+```
+
+**Returns:**
+```json
+{"created": true, "path": ".aether/QUEEN.md", "source": "~/.aether/system/templates/QUEEN.md.template"}
+```
+
+### queen-read
+
+Read QUEEN.md and return wisdom as JSON for worker priming.
+
+```bash
+bash .aether/aether-utils.sh queen-read
+```
+
+**Returns:**
+```json
+{
+  "metadata": {
+    "version": "1.0.0",
+    "last_evolved": "2026-02-15T13:08:40Z",
+    "colonies_contributed": ["colony-a"],
+    "promotion_thresholds": {...},
+    "stats": {...}
+  },
+  "wisdom": {
+    "philosophies": "...",
+    "patterns": "...",
+    "redirects": "...",
+    "stack_wisdom": "...",
+    "decrees": "..."
+  },
+  "priming": {
+    "has_philosophies": true,
+    "has_patterns": true,
+    ...
+  }
+}
+```
+
+### queen-promote
+
+Promote a learning to QUEEN.md wisdom.
+
+```bash
+bash .aether/aether-utils.sh queen-promote <type> <content> <colony_name>
+```
+
+**Types:** `philosophy`, `pattern`, `redirect`, `stack`, `decree`
+
+**Example:**
+```bash
+bash .aether/aether-utils.sh queen-promote pattern "Always validate inputs" "my-colony"
+```
+
+## Integration with Commands
+
+### init.md
+
+Calls `queen-init` after bootstrap to ensure QUEEN.md exists for the colony.
+
+### build.md
+
+Calls `queen-read` before spawning workers to inject wisdom into worker prompts.
+
+### continue.md
+
+After verification, promotes validated learnings to QUEEN.md using `queen-promote`.
+
+### seal.md
+
+Before archiving, promotes significant patterns and decisions to QUEEN.md.
+
+### entomb.md
+
+Before creating the chamber, promotes validated learnings to QUEEN.md.
+
+## Promotion Thresholds
+
+| Type | Threshold | Rationale |
+|------|-----------|-----------|
+| Philosophy | 1 | Promote validated guidance quickly |
+| Pattern | 1 | Promote reusable practices quickly |
+| Redirect | 1 | Promote anti-pattern protection immediately |
+| Stack | 1 | Tech insights are domain-specific |
+| Decree | 0 | User mandates are immediate |
+
+## Metadata
+
+The QUEEN.md file includes a METADATA block at the end:
+
+```html
+<!-- METADATA
+{
+  "version": "1.0.0",
+  "last_evolved": "2026-02-15T13:08:40Z",
+  "colonies_contributed": ["colony-a"],
+  "promotion_thresholds": {
+    "philosophy": 1,
+    "pattern": 1,
+    "redirect": 1,
+    "stack": 1,
+    "decree": 0
+  },
+  "stats": {
+    "total_philosophies": 1,
+    "total_patterns": 1,
+    ...
+  }
+}
+-->
+```
+
+## Best Practices
+
+1. **Don't manually edit QUEEN.md** - Use `queen-promote` to ensure proper formatting
+2. **Validate before promoting** - Only promote learnings that have been tested
+3. **Use descriptive colony names** - Helps track wisdom origins
+4. **Read wisdom at build start** - Workers benefit from accumulated knowledge
+5. **Review periodically** - Some wisdom may become outdated as the system evolves
+
+## See Also
+
+- `/ant:init` - Initializes QUEEN.md for new colonies
+- `/ant:build` - Reads QUEEN.md wisdom for worker priming
+- `/ant:continue` - Promotes validated learnings
+- `/ant:seal` - Promotes final colony wisdom
+- `/ant:entomb` - Promotes wisdom before archiving