aether-colony 1.1.0

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

@@ -0,0 +1,201 @@
+---
+name: ant:lay-eggs
+description: "🥚🐜🥚 Lay first eggs of new colony (First Eggs milestone)"
+---
+
+You are the **Queen**. Begin a new colony, preserving pheromones.
+
+## Instructions
+
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+<failure_modes>
+### Plan File Write Failure
+If writing phase plans to COLONY_STATE.json fails:
+- Do not leave partial plan data in state
+- Report what was successfully written vs. what failed
+- Recovery: user can re-run /ant:lay-eggs to regenerate plans
+
+### Goal Parsing Failure
+If the user's goal cannot be parsed into actionable phases:
+- Do not generate placeholder phases
+- Ask user to clarify or simplify the goal
+- Offer examples of well-formed goals
+</failure_modes>
+
+<success_criteria>
+Command is complete when:
+- Phase plan is written to COLONY_STATE.json with tasks and success criteria
+- Plan structure is valid (phases have tasks, tasks have descriptions)
+- User sees the plan and can approve or request changes
+</success_criteria>
+
+<read_only>
+Do not touch during lay-eggs:
+- .aether/dreams/ (user notes)
+- .aether/chambers/ (archived colonies)
+- Source code files (planning only, no implementation)
+- .env* files
+- .claude/settings.json
+</read_only>
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true, run using the Bash tool with description "Initializing colony display...":
+```bash
+# Generate session ID and persist it for later steps
+layeggs_id="layeggs-$(date +%s)"
+echo "$layeggs_id" > .aether/data/.layeggs_session
+
+# 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
+```
+
+### 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": []
+}
+```
+
+### Step 6: Display Result
+
+**If visual_mode is true, render final swarm display** by running using the Bash tool with description "Updating colony display...":
+```bash
+# Read persisted session ID from Step 0
+layeggs_id=$(cat .aether/data/.layeggs_session 2>/dev/null || echo "layeggs-$(date +%s)")
+
+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-text "$layeggs_id"
+```
+
+```
+🥚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   F I R S T   E G G S   L A I D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🥚
+
+👑 New colony goal:
+   "{goal}"
+
+🏆 Milestone: First Mound (v0.1.0)
+
+{If inherited knowledge:}
+🧠 Inherited from prior colonies:
+   {N} instinct(s) | {N} decision(s) | {N} learning(s)
+{End if}
+
+🐜 The colony begins anew.
+
+   /ant:plan      📋 Chart the course
+   /ant:colonize  🗺️  Analyze existing code
+```
+
+Include edge case handling:
+- If no prior knowledge: omit the inheritance section
+- If prior colony had no phases: allow laying eggs without entombment
+
+### Step 7: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+if [ -f .aether/data/COLONY_STATE.json ]; then
+  state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json 2>/dev/null || echo "IDLE")
+  current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+  total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+else
+  state="IDLE"
+  current_phase="0"
+  total_phases="0"
+fi
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"

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

@@ -0,0 +1,102 @@
+---
+name: ant:maturity
+description: "👑🐜🏛️🐜👑 View colony maturity journey with ASCII art anthill"
+---
+
+You are the **Queen**. Display the colony's maturity journey.
+
+## Instructions
+
+### Step 1: Detect Current Milestone
+
+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)
+- `version`: Computed version string
+- `phases_completed`: Number of completed phases
+- `total_phases`: Total phases in plan
+
+### Step 2: Read Colony State
+
+Read `.aether/data/COLONY_STATE.json` to get:
+- `goal`: Colony goal
+- `initialized_at`: When colony was started
+
+Calculate colony age from initialized_at to now (in days).
+
+### Step 3: Display Maturity Journey
+
+Display header:
+```
+       .-.
+      (o o)  AETHER COLONY
+      | O |  Maturity Journey
+       `-`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+👑 Goal: {goal (truncated to 50 chars)}
+🏆 Current: {milestone} ({version})
+📍 Progress: {phases_completed} of {total_phases} phases
+📅 Colony Age: {N} days
+```
+
+### 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).
+
+### Step 5: Show Journey Progress Bar
+
+Display progress through all milestones:
+
+```
+Journey Progress:
+
+[█░░░░░] First Mound        (0 phases)   - Complete
+[██░░░░] Open Chambers      (1-3 phases) - Complete
+[███░░░] Brood Stable       (4-6 phases) - Complete
+[████░░] Ventilated Nest    (7-10 phases) - Current
+[█████░] Sealed Chambers    (11-14 phases)
+[██████] Crowned Anthill    (15+ phases)
+
+Next: Ventilated Nest → Sealed Chambers
+      Complete {N} more phases to advance
+```
+
+Calculate which milestones are complete vs current vs upcoming based on phases_completed.
+
+### Step 6: Show Colony Statistics
+
+Display summary stats:
+```
+Colony Statistics:
+  🐜 Phases Completed: {phases_completed}
+  📋 Total Phases: {total_phases}
+  📅 Days Active: {colony_age_days}
+  🏆 Current Milestone: {milestone}
+  🎯 Completion: {percent}%
+```
+
+### Edge Cases
+
+- If milestone file doesn't exist: Show error "Milestone visualization not found"
+- 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 @@
+---
+name: memory-details
+description: "Show detailed colony memory — wisdom, pending promotions, and recent failures"
+symbol: brain
+---
+
+# /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
+```

package/.claude/commands/ant/migrate-state.md

@@ -0,0 +1,165 @@
+---
+name: ant:migrate-state
+description: "🚚🐜📦🐜🚚 One-time state migration from v1 to v2.0 format"
+---
+
+# 🚚🐜📦🐜🚚 /ant:migrate-state - One-Time State Migration
+
+Migrate colony state from v1 (6-file) format to v2.0 (consolidated single-file) format.
+
+**Usage:** Run once to migrate existing state. Safe to run multiple times - skips if already migrated.
+
+---
+
+## Step 1: Check Migration Status
+
+Read `.aether/data/COLONY_STATE.json` to check if already migrated.
+
+**If file contains `"version": "2.0"`:**
+- Output: "State already migrated to v2.0. No action needed."
+- Stop execution.
+
+**If no version field or version < 2.0:**
+- Continue to Step 2.
+
+---
+
+## Step 2: Read All State Files
+
+Use the Read tool to read all 6 state files from `.aether/data/`:
+
+1. `COLONY_STATE.json` - Colony goal, state machine, workers, spawn outcomes
+2. `PROJECT_PLAN.json` - Phases, tasks, success criteria
+3. `pheromones.json` - Active signals
+4. `memory.json` - Phase learnings, decisions, patterns
+5. `errors.json` - Error records, flagged patterns
+6. `events.json` - Event log
+
+Handle missing files gracefully (use empty defaults).
+
+---
+
+## Step 3: Construct Consolidated State
+
+Build the v2.0 consolidated structure:
+
+```json
+{
+  "version": "2.0",
+  "goal": "<from COLONY_STATE.goal or null>",
+  "state": "<from COLONY_STATE.state or 'IDLE'>",
+  "current_phase": "<from COLONY_STATE.current_phase or 0>",
+  "session_id": "<from COLONY_STATE.session_id or null>",
+  "initialized_at": "<from COLONY_STATE.initialized_at or null>",
+  "mode": "<from COLONY_STATE.mode or null>",
+  "mode_set_at": "<from COLONY_STATE.mode_set_at or null>",
+  "mode_indicators": "<from COLONY_STATE.mode_indicators or null>",
+  "workers": "<from COLONY_STATE.workers or default idle workers>",
+  "spawn_outcomes": "<from COLONY_STATE.spawn_outcomes or default outcomes>",
+  "plan": {
+    "generated_at": "<from PROJECT_PLAN.generated_at or null>",
+    "phases": "<from PROJECT_PLAN.phases or []>"
+  },
+  "signals": "<from pheromones.signals or []>",
+  "memory": {
+    "phase_learnings": "<from memory.phase_learnings or []>",
+    "decisions": "<from memory.decisions or []>",
+    "patterns": "<from memory.patterns or []>"
+  },
+  "errors": {
+    "records": "<from errors.errors or []>",
+    "flagged_patterns": "<from errors.flagged_patterns or []>"
+  },
+  "events": "<converted event strings or []>"
+}
+```
+
+**Event Conversion:**
+Convert each event object to a pipe-delimited string:
+- Old format: `{"id":"evt_123","type":"colony_initialized","source":"init","content":"msg","timestamp":"2026-..."}`
+- New format: `"2026-... | colony_initialized | init | msg"`
+
+If events array is already strings (or empty), keep as-is.
+
+---
+
+## Step 4: Create Backup
+
+Create backup directory and move old files:
+
+```bash
+mkdir -p .aether/data/backup-v1
+```
+
+Move these files to backup (if they exist):
+- `.aether/data/PROJECT_PLAN.json` -> `.aether/data/backup-v1/PROJECT_PLAN.json`
+- `.aether/data/pheromones.json` -> `.aether/data/backup-v1/pheromones.json`
+- `.aether/data/memory.json` -> `.aether/data/backup-v1/memory.json`
+- `.aether/data/errors.json` -> `.aether/data/backup-v1/errors.json`
+- `.aether/data/events.json` -> `.aether/data/backup-v1/events.json`
+- `.aether/data/COLONY_STATE.json` -> `.aether/data/backup-v1/COLONY_STATE.json`
+
+---
+
+## Step 5: Write Consolidated State
+
+Write the new consolidated COLONY_STATE.json with the v2.0 structure from Step 3.
+
+Format the JSON with 2-space indentation for readability.
+
+---
+
+## Step 6: Display Summary
+
+Output header:
+
+```
+🚚🐜📦🐜🚚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   S T A T E   M I G R A T I O N   C O M P L E T E
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚚🐜📦🐜🚚
+```
+
+Then output a migration summary:
+
+```
+State Migration Complete (v1 -> v2.0)
+======================================
+
+Migrated data:
+- Goal: <goal or "(not set)">
+- State: <state>
+- Current phase: <phase>
+- Workers: <count of non-idle workers>
+- Plan phases: <count>
+- Active signals: <count>
+- Phase learnings: <count>
+- Decisions: <count>
+- Error records: <count>
+- Events: <count>
+
+Files backed up to: .aether/data/backup-v1/
+New state file: .aether/data/COLONY_STATE.json (v2.0)
+
+All commands now use consolidated state format.
+```
+
+---
+
+## Notes
+
+- This is a one-time migration command
+- After v5.1 ships, this command can be removed
+- All 12+ ant commands will be updated to use the new single-file format
+- The backup directory preserves original files for rollback if needed
+
+---
+
+## 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"
+```