aether-colony 3.1.17 → 5.1.0

package/.claude/commands/ant/insert-phase.md

@@ -0,0 +1,101 @@
+<!-- Generated from .aether/commands/insert-phase.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:insert-phase
+description: "➕🐜 Insert a corrective phase into the active plan"
+---
+
+You are the **Queen**. Insert a new corrective phase without forcing the user to provide flags.
+
+## Instructions
+
+### Step 1: Validate Colony State
+
+Read `.aether/data/COLONY_STATE.json`.
+
+If `goal` is null:
+`No colony initialized. Run /ant:init first.`
+Stop.
+
+If `plan.phases` is empty:
+`No project plan. Run /ant:plan first.`
+Stop.
+
+Determine:
+- `current_phase`
+- `total_phases`
+- `current_phase_name` (if available)
+
+### Step 2: Collect Minimal Input
+
+This command is designed to work with no arguments.
+
+If `$ARGUMENTS` is non-empty:
+- Use `$ARGUMENTS` as the issue summary.
+- Skip the first question.
+
+Otherwise ask:
+```text
+What is not working and needs a corrective phase?
+```
+
+Then ask:
+```text
+What should the inserted phase accomplish?
+```
+
+Then ask (optional):
+```text
+Any hard constraints to enforce while fixing this? (or say "none")
+```
+
+If constraints answer is `none` (case-insensitive), treat constraints as empty.
+
+### Step 3: Derive Phase Name
+
+Create a concise phase name from the user goal:
+- Start with `Stabilize`
+- Add a short noun phrase from the goal (max 6 words)
+- Keep under 80 characters
+
+Example:
+- Goal: `Fix retry flow and stop duplicate requests`
+- Name: `Stabilize retry flow and duplicate requests`
+
+### Step 4: Insert Phase Safely
+
+Run using the Bash tool with description "Inserting corrective phase...":
+
+```bash
+bash .aether/aether-utils.sh phase-insert "<phase_name>" "<goal_text>" "<constraints_text>"
+```
+
+Parse JSON result:
+- If `ok != true`, display error and stop.
+- Extract `inserted_phase_id` and `after_phase`.
+
+### Step 5: Confirm Outcome
+
+Display:
+
+```text
+Inserted corrective phase successfully.
+  New phase: <inserted_phase_id> — <phase_name>
+  Inserted after phase: <after_phase>
+  Goal: <goal_text>
+```
+
+If constraints were provided, also display:
+```text
+  Constraints captured: <constraints_text>
+```
+
+### Step 6: Next Up
+
+Show:
+
+```text
+Next steps:
+  /ant:phase <inserted_phase_id>   Review inserted phase details
+  /ant:build <inserted_phase_id>   Execute corrective phase
+  /ant:status                      Verify updated plan state
+```

package/.claude/commands/ant/interpret.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/interpret.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:interpret
 description: "🔍🐜💭🐜🔍 The Interpreter - grounds dreams in reality, validates against codebase, and discusses what to implement"
@@ -52,10 +53,13 @@ Also read in parallel:
 
 ### Step 2: Display Header
 
+
 ```
-🔍🐜💭🐜🔍 ═══════════════════════════════════════════════
+🔍🐜💭🐜🔍 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
          D R E A M   I N T E R P R E T E R
-═══════════════════════════════════════════════ 🔍🐜💭🐜🔍
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔍🐜💭🐜🔍
+
+
 
 📓 Reviewing: {dream_filename}
    {N} dreams | {concerns} concerns | {pheromones} suggested pheromones
@@ -146,10 +150,13 @@ Verdict emoji mapping:
 
 After all dreams are interpreted, display:
 
+
 ```
-🔍🐜💭🐜🔍 ═══════════════════════════════════════════════
+🔍🐜💭🐜🔍 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
          I N T E R P R E T A T I O N   C O M P L E T E
-═══════════════════════════════════════════════ 🔍🐜💭🐜🔍
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔍🐜💭🐜🔍
+
+
 
 📊 Results:
    {confirmed_count} confirmed | {partial_count} partially confirmed | {unconfirmed_count} unconfirmed | {refuted_count} refuted
@@ -218,6 +225,9 @@ Wait for user response.
 
 ### Step 7: Log Activity
 
+
+Run using the Bash tool with description "Logging interpretation activity...":
+
 ```bash
 bash .aether/aether-utils.sh activity-log "INTERPRET" "Interpreter" "Dream review: {dream_file}, {confirmed} confirmed, {partial} partial, {unconfirmed} unconfirmed, {refuted} refuted, {actions_taken} actions taken"
 ```
@@ -243,6 +253,18 @@ bash .aether/aether-utils.sh activity-log "INTERPRET" "Interpreter" "Dream revie
 /ant:build    🔨 Start building
 ```
 
+
+### Step 9: 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"
+```
+
+
 ## Investigation Guidelines
 
 When investigating dreams, remember:

package/.claude/commands/ant/lay-eggs.md

@@ -1,153 +1,210 @@
+<!-- Generated from .aether/commands/lay-eggs.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:lay-eggs
-description: "🥚🐜🥚 Lay first eggs of new colony (First Eggs milestone)"
+description: "🥚🐜🥚 Set up Aether in this repo — creates .aether/ with all system files"
 ---
 
-You are the **Queen**. Begin a new colony, preserving pheromones.
+You are the **Queen**. Prepare this repository for Aether colony development.
 
 ## Instructions
 
-Parse `$ARGUMENTS`:
-- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
-- Otherwise: set `visual_mode = true`
+This command sets up the `.aether/` directory structure and copies all system files from the global hub. It does NOT start a colony — that's what `/ant:init "goal"` is for.
+
+<failure_modes>
+### Hub Not Found
+If `~/.aether/system/aether-utils.sh` does not exist:
+- The global hub is not installed
+- Tell the user to run `npm install -g aether-colony` first
+- Stop — cannot proceed without hub
+
+### Partial Copy Failure
+If some files fail to copy from hub:
+- Report which files succeeded and which failed
+- The user can re-run `/ant:lay-eggs` safely (idempotent)
+</failure_modes>
+
+<success_criteria>
+Command is complete when:
+- `.aether/` directory exists with all subdirectories
+- System files (aether-utils.sh, workers.md, etc.) are present
+- Templates, docs, utils, schemas are populated
+- QUEEN.md is initialized
+- User sees confirmation and next steps
+</success_criteria>
+
+<read_only>
+Do not touch during lay-eggs:
+- .aether/data/COLONY_STATE.json (colony state belongs to init)
+- .aether/dreams/ contents (user notes — create dir but don't modify files)
+- .aether/chambers/ contents (archived colonies — create dir but don't modify files)
+- Source code files
+- .env* files
+- .claude/settings.json
+</read_only>
+
+### Step 1: Check Hub Availability
+
+Check if the global hub exists by reading `~/.aether/system/aether-utils.sh` (expand `~` to the user's home directory).
+
+**If the hub does NOT exist:**
+```
+Aether hub not found at ~/.aether/system/
 
-### Step 0: Initialize Visual Mode (if enabled)
+The global hub must be installed before setting up a repo.
 
-If `visual_mode` is true:
-```bash
-# Generate session ID
-layeggs_id="layeggs-$(date +%s)"
+  npm install -g aether-colony
+
+This installs the Aether CLI and populates the hub at ~/.aether/system/
+with all the system files your repo needs.
+
+After installing, run /ant:lay-eggs again.
+```
+Stop here.
+
+### Step 2: Check Existing Setup
+
+
+Check if `.aether/aether-utils.sh` already exists using the Read tool.
+
+
+
+**If it exists:**
+```
+Aether is already set up in this repo.
 
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$layeggs_id"
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Laying first eggs" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 0
+Refreshing system files from hub...
 ```
+Proceed to Step 3 (this makes the command safe to re-run as an update/repair).
+
+**If it does NOT exist:**
+```
+Setting up Aether in this repo...
+```
+Proceed to Step 3.
+
+### Step 3: Create Directory Structure
+
+
+Run using the Bash tool with description "Creating Aether directory structure...":
+
+
+```bash
+mkdir -p \
+  .aether/data \
+  .aether/data/midden \
+  .aether/data/backups \
+  .aether/data/survey \
+  .aether/dreams \
+  .aether/chambers \
+  .aether/locks \
+  .aether/temp \
+  .aether/docs \
+  .aether/utils \
+  .aether/templates \
+  .aether/schemas \
+  .aether/exchange \
+  .aether/rules \
+  .aether/scripts \
+  .claude/rules && \
+touch .aether/dreams/.gitkeep && \
+touch .aether/chambers/.gitkeep && \
+touch .aether/data/midden/.gitkeep
+```
+
+### Step 4: Copy System Files from Hub
+
 
-### Step 1: Validate Input
-
-- If `$ARGUMENTS` is empty:
-  ```
-  Usage: /ant:lay-eggs "<new colony goal>"
-
-  Start a fresh colony, preserving pheromones from prior colonies.
-  Requires current colony to be entombed or reset.
-
-  Example:
-    /ant:lay-eggs "Build a REST API with authentication"
-  ```
-  Stop here.
-
-### Step 2: Check Current Colony
-
-- Read `.aether/data/COLONY_STATE.json`
-- If goal is not null AND phases exist with status != "completed":
-  ```
-  🚫 Cannot lay eggs — active colony has unsaved pheromones
-
-  Active colony: {goal}
-  Current: Phase {current_phase}, {phases_count} phases in plan
-
-  ┌─────────────────────────────────────────────────────────┐
-  │  COLONY LIFECYCLE                                       │
-  ├─────────────────────────────────────────────────────────┤
-  │                                                         │
-  │   🟢 ACTIVE COLONY  →  🏺 SEAL/ENTOMB  →  🥚 LAY EGGS   │
-  │       (working)         (preserve memory)   (new goal)  │
-  │                                                         │
-  └─────────────────────────────────────────────────────────┘
-
-  Why this matters:
-  Your active colony contains preserved learnings, decisions, and
-  instincts (pheromones) from prior work. These must be sealed
-  before starting a new project, or they will be lost forever.
-
-  To start a new colony:
-  1. Complete work → run `/ant:seal` or `/ant:entomb` to archive
-  2. Then run `/ant:lay-eggs "new goal"` to begin fresh
-
-  Emergency reset (loses all pheromones):
-     rm .aether/data/COLONY_STATE.json
-  ```
-  Stop here.
-
-### Step 3: Extract Preserved Knowledge
-
-- Read current state to extract preserved fields:
-  - `memory.phase_learnings` (all items)
-  - `memory.decisions` (all items)
-  - `memory.instincts` (all items with confidence >= 0.5)
-- Store for use in Step 4
-
-### Step 4: Create New Colony State
-
-Generate new state following RESEARCH.md Pattern 2 (State Reset with Pheromone Preservation):
-
-**Fields to preserve from old state:**
-- memory.phase_learnings
-- memory.decisions
-- memory.instincts (high confidence only)
-
-**Fields to reset:**
-- goal: new goal from $ARGUMENTS
-- state: "READY"
-- current_phase: 0
-- session_id: new session_{unix_timestamp}_{random}
-- initialized_at: current ISO-8601 timestamp
-- build_started_at: null
-- plan: { generated_at: null, confidence: null, phases: [] }
-- errors: { records: [], flagged_patterns: [] }
-- signals: []
-- graveyards: []
-- events: [colony_initialized event with new goal]
-
-**New milestone fields:**
-- milestone: "First Mound"
-- milestone_updated_at: current timestamp
-- milestone_version: "v0.1.0"
-
-Write to `.aether/data/COLONY_STATE.json`
-
-### Step 5: Reset Constraints
-
-Write `.aether/data/constraints.json`:
-```json
-{
-  "version": "1.0",
-  "focus": [],
-  "constraints": []
-}
+Run using the Bash tool with description "Copying system files from hub...":
+
+
+```bash
+# Core system files
+cp -f ~/.aether/system/aether-utils.sh .aether/ && \
+chmod +x .aether/aether-utils.sh && \
+cp -f ~/.aether/system/workers.md .aether/ 2>/dev/null || true && \
+cp -f ~/.aether/system/CONTEXT.md .aether/ 2>/dev/null || true && \
+# Directories
+cp -Rf ~/.aether/system/docs/* .aether/docs/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/utils/* .aether/utils/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/templates/* .aether/templates/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/schemas/* .aether/schemas/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/exchange/* .aether/exchange/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/rules/* .claude/rules/ 2>/dev/null || true && \
+
+# Version tracking
+cp -f ~/.aether/version.json .aether/version.json 2>/dev/null || true
+
+echo "System files copied."
 ```
 
-### Step 6: Display Result
+### Step 5: Initialize QUEEN.md
 
-**If visual_mode is true, render final swarm display:**
+
+Run using the Bash tool with description "Initializing QUEEN.md...":
 ```bash
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "First eggs laid" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "nursery" 100
-bash .aether/aether-utils.sh swarm-display-inline "$layeggs_id"
+bash .aether/aether-utils.sh queen-init
 ```
 
+
+
+Parse the JSON result:
+- If `created` is true: note `QUEEN.md initialized`
+- If `created` is false: note `QUEEN.md already exists (preserved)`
+
+### Step 6: Register Repo (Silent)
+
+Attempt to register this repo in the global hub. Silent on failure — registry is optional.
+
+
+Run using the Bash tool with description "Registering repo..." (ignore errors):
+
+
+```bash
+bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" 2>/dev/null || true
 ```
-🥚 ═══════════════════════════════════════════════════
-   F I R S T   E G G S   L A I D
-══════════════════════════════════════════════════ 🥚
 
-👑 New colony goal:
-   "{goal}"
+### Step 7: Verify Setup
+
+
+Run using the Bash tool with description "Verifying setup...":
+
+
+```bash
+# Count what was set up
+dirs=0
+files=0
+for d in .aether/data .aether/docs .aether/utils .aether/templates .aether/schemas .aether/exchange .aether/dreams .aether/chambers; do
+  [ -d "$d" ] && dirs=$((dirs + 1))
+done
+[ -f .aether/aether-utils.sh ] && files=$((files + 1))
+[ -f .aether/workers.md ] && files=$((files + 1))
+[ -f .aether/QUEEN.md ] && files=$((files + 1))
+[ -f .aether/CONTEXT.md ] && files=$((files + 1))
+[ -d .aether/templates ] && templates=$(ls .aether/templates/*.template.* 2>/dev/null | wc -l | tr -d ' ') || templates=0
+[ -d .aether/utils ] && utils=$(ls .aether/utils/*.sh 2>/dev/null | wc -l | tr -d ' ') || utils=0
+
+echo "{\"dirs\": $dirs, \"core_files\": $files, \"templates\": $templates, \"utils\": $utils}"
+```
 
-📋 Session: {session_id}
-🏆 Milestone: First Mound (v0.1.0)
+Parse the JSON output for the display step.
 
-{If inherited knowledge:}
-🧠 Inherited from prior colonies:
-   {N} instinct(s) | {N} decision(s) | {N} learning(s)
-{End if}
+### Step 8: Display Result
 
-🐜 The colony begins anew.
 
-   /ant:plan      📋 Chart the course
-   /ant:colonize  🗺️  Analyze existing code
 ```
+🥚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   A E T H E R   R E A D Y
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🥚
+
+
 
-Include edge case handling:
-- If no prior knowledge: omit the inheritance section
-- If prior colony had no phases: allow laying eggs without entombment
+   {dirs} directories created
+   {core_files} core system files
+   {templates} templates ({utils} utils modules)
+
+To start a colony:
+  /ant:init "your goal here"
+
+To verify setup:
+  /ant:status
+```

package/.claude/commands/ant/maturity.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/maturity.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:maturity
 description: "👑🐜🏛️🐜👑 View colony maturity journey with ASCII art anthill"
@@ -9,7 +10,8 @@ You are the **Queen**. Display the colony's maturity journey.
 
 ### Step 1: Detect Current Milestone
 
-Run: `bash .aether/aether-utils.sh milestone-detect`
+Run using the Bash tool with description "Detecting colony milestone...":
+`bash .aether/aether-utils.sh milestone-detect`
 
 Parse JSON result to get:
 - `milestone`: Current milestone name (First Mound, Open Chambers, Brood Stable, Ventilated Nest, Sealed Chambers, Crowned Anthill)
@@ -32,7 +34,7 @@ Display header:
        .-.
       (o o)  AETHER COLONY
       | O |  Maturity Journey
-       `-`
+       `-'
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 👑 Goal: {goal (truncated to 50 chars)}
@@ -43,15 +45,19 @@ Display header:
 
 ### Step 4: Show ASCII Art Anthill
 
-Read the ASCII art file for the current milestone:
-- First Mound → `.aether/visualizations/anthill-stages/first-mound.txt`
-- Open Chambers → `.aether/visualizations/anthill-stages/open-chambers.txt`
-- Brood Stable → `.aether/visualizations/anthill-stages/brood-stable.txt`
-- Ventilated Nest → `.aether/visualizations/anthill-stages/ventilated-nest.txt`
-- Sealed Chambers → `.aether/visualizations/anthill-stages/sealed-chambers.txt`
-- Crowned Anthill → `.aether/visualizations/anthill-stages/crowned-anthill.txt`
 
-Display the ASCII art with current milestone highlighted (bold/bright).
+Display the current milestone with its text description (no external file needed):
+
+- First Mound -- "A small pile of earth. The colony has broken ground."
+- Open Chambers -- "Tunnels branch outward. Feature work is underway."
+- Brood Stable -- "The nursery hums. Tests are consistently green."
+- Ventilated Nest -- "Air flows freely. Performance and latency are acceptable."
+- Sealed Chambers -- "Walls are hardened. Interfaces are frozen."
+- Crowned Anthill -- "The spire rises. The colony is release-ready."
+
+Display the matching description for the current milestone.
+
+
 
 ### Step 5: Show Journey Progress Bar
 
@@ -87,6 +93,21 @@ Colony Statistics:
 
 ### Edge Cases
 
-- If milestone file doesn't exist: Show error "Milestone visualization not found"
+
+- If milestone name is unrecognized: Show "Unknown milestone" with the raw name
+
+
 - If COLONY_STATE.json missing: "No colony initialized. Run /ant:init first."
 - If phases_completed is 0: All milestones show as upcoming except First Mound
+
+
+### Step 7: 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/memory-details.md

@@ -0,0 +1,77 @@
+<!-- Generated from .aether/commands/memory-details.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:memory-details
+description: "Show detailed colony memory — wisdom, pending promotions, and recent failures"
+---
+
+# /ant:memory-details — Colony Memory Details
+
+Drill-down view of accumulated colony wisdom, pending promotions, and recent failures.
+
+## Usage
+
+```bash
+/ant:memory-details
+```
+
+## Implementation
+
+### Step 1: Load Memory Data
+
+Run using the Bash tool with description "Loading colony memory...":
+```bash
+bash .aether/aether-utils.sh memory-metrics
+```
+
+### Step 2: Display Wisdom (from QUEEN.md)
+
+Read .aether/QUEEN.md and display entries by category:
+- Philosophies
+- Patterns
+- Redirects
+- Stack
+- Decrees
+
+Format:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+COLONY WISDOM (X entries)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📜 Philosophies (N)
+   - Entry 1...
+   - Entry 2...
+
+🔧 Patterns (N)
+   - Entry 1...
+```
+
+### Step 3: Display Pending Promotions
+
+Show observations meeting threshold but not yet promoted:
+```
+⏳ Pending Promotions (N)
+   - [type] Content... (X observations)
+```
+
+Show deferred proposals:
+```
+💤 Deferred Proposals (N)
+   - [type] Content... (deferred YYYY-MM-DD)
+```
+
+### Step 4: Display Recent Failures
+
+Show last 5 failures from midden:
+```
+⚠️ Recent Failures (N)
+   [YYYY-MM-DD HH:MM] Source: context
+   Content...
+```
+
+### Step 5: Summary
+
+Show counts summary and reminder command:
+```
+Run /ant:status for quick overview
+```