aether-colony 5.1.0 → 5.3.0

package/.aether/commands/opencode/feedback.md

@@ -0,0 +1,99 @@
+<!-- Generated from .aether/commands/feedback.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:feedback
+description: "💬🐜🧠🐜💬 Emit FEEDBACK signal to provide guidance to colony"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+
+
+You are the **Queen**. Emit a FEEDBACK signal.
+
+
+## Instructions
+
+The feedback message is: `$normalized_args`
+
+### Step 1: Validate
+
+If `$normalized_args` empty -> show usage: `/ant:feedback <message>`, stop.
+If content > 500 chars -> "Signal content too long (max 500 chars)", stop.
+
+
+
+### Step 2: Write Signal and Create Instinct
+
+Read `.aether/data/COLONY_STATE.json`.
+If `goal: null` -> "No colony initialized.", stop.
+
+
+
+Generate ISO-8601 timestamp.
+
+**Add signal:**
+Append to `signals` array:
+```json
+{
+  "id": "feedback_<timestamp_ms>",
+  "type": "FEEDBACK",
+  "content": "<feedback message>",
+  "priority": "low",
+  "created_at": "<ISO-8601>",
+  "expires_at": "phase_end"
+}
+```
+
+**Create instinct from feedback:**
+User feedback is high-value learning. Append to `memory.instincts`:
+```json
+{
+  "id": "instinct_<timestamp>",
+  "trigger": "<infer from feedback context>",
+  "action": "<the feedback guidance>",
+  "confidence": 0.7,
+  "domain": "<infer: testing|architecture|code-style|debugging|workflow>",
+  "source": "user_feedback",
+  "evidence": ["User feedback: <content>"],
+  "created_at": "<ISO-8601>",
+  "last_applied": null,
+  "applications": 0,
+  "successes": 0
+}
+```
+
+Write COLONY_STATE.json.
+
+**Write pheromone signal and update context:**
+```bash
+bash .aether/aether-utils.sh pheromone-write FEEDBACK "$normalized_args" --strength 0.7 --reason "User feedback guidance" 2>/dev/null || true
+bash .aether/aether-utils.sh context-update constraint feedback "$normalized_args" "user" 2>/dev/null || true
+```
+
+### Step 3: Confirm
+
+Output header:
+
+```
+💬🐜🧠🐜💬 ═══════════════════════════════════════════════════
+   F E E D B A C K   S I G N A L
+═══════════════════════════════════════════════════ 💬🐜🧠🐜💬
+```
+
+Then output:
+```
+💬 FEEDBACK signal emitted
+
+   "{content preview}"
+
+🧠 Instinct created: [0.7] <domain>: <action summary>
+
+🐜 The colony will remember this guidance.
+```
+
+
+

package/.aether/commands/opencode/flag.md

@@ -0,0 +1,149 @@
+<!-- Generated from .aether/commands/flag.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:flag
+description: "🚩🐜📋🐜🚩 Create a project-specific flag (blocker, issue, or note)"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+You are the **Queen**. Create a project-specific flag.
+
+## Instructions
+
+The flag is: `$normalized_args`
+
+### Step 1: Parse Arguments
+
+Parse `$normalized_args` for:
+- `--type` or `-t`: blocker | issue | note (default: issue)
+- `--phase` or `-p`: phase number (optional)
+- Remaining text: the flag title/description
+
+Examples:
+- `/ant:flag "Build fails on auth module"` → issue type
+- `/ant:flag --type blocker "API rate limit hit"` → blocker type
+- `/ant:flag -t note -p 3 "Consider refactoring later"` → note for phase 3
+
+If `$normalized_args` is empty:
+```
+Usage: /ant:flag "<description>" [--type blocker|issue|note] [--phase N]
+
+Types:
+  blocker  Critical issue that blocks phase advancement
+  issue    Warning that should be addressed (default)
+  note     Informational for future reference
+
+Examples:
+  /ant:flag "Build fails on auth"
+  /ant:flag --type blocker "Tests hanging"
+  /ant:flag -t note "Consider refactoring"
+```
+Stop here.
+
+### Step 2: Validate Colony
+
+Read `.aether/data/COLONY_STATE.json`.
+If file missing or `goal: null`:
+```
+No colony initialized. Run /ant:init first.
+```
+Stop here.
+
+### Step 3: Create Flag
+
+Run:
+```bash
+bash .aether/aether-utils.sh flag-add "{type}" "{title}" "{description}" "manual" {phase_or_null}
+```
+
+Parse the result for the flag ID.
+
+### Step 4: Confirm
+
+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:
+
+**For blocker:**
+```
+🚫 BLOCKER flag created
+
+   "{title}"
+
+   ID: {flag_id}
+   Phase: {phase or "all"}
+
+⚠️  This will BLOCK phase advancement until resolved.
+   Use /ant:flags to view all flags.
+```
+
+**For issue:**
+```
+⚠️  ISSUE flag created
+
+   "{title}"
+
+   ID: {flag_id}
+   Phase: {phase or "all"}
+
+   Use /ant:flags to view all flags.
+```
+
+**For note:**
+```
+📝 NOTE flag created
+
+   "{title}"
+
+   ID: {flag_id}
+   Phase: {phase or "all"}
+
+   Use /ant:flags to view all flags.
+```
+
+
+
+---
+
+## Flag Lifecycle
+
+1. **Created** - Flag is active and visible
+2. **Acknowledged** - Flag noted but continuing (issues/notes only)
+3. **Resolved** - Flag closed with resolution message
+4. **Auto-resolved** - Blockers auto-resolve on build_pass
+
+Blockers CANNOT be acknowledged - they must be resolved before phase advancement.

package/.aether/commands/opencode/flags.md

@@ -0,0 +1,167 @@
+<!-- Generated from .aether/commands/flags.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:flags
+description: "📋🐜🚩🐜📋 List project flags (blockers, issues, notes)"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+You are the **Queen**. Display project flags.
+
+## Instructions
+
+Arguments: `$normalized_args`
+
+### Step 1: Parse Arguments
+
+Parse `$normalized_args` for:
+- `--all` or `-a`: Show resolved flags too
+- `--type` or `-t`: Filter by type (blocker|issue|note)
+- `--phase` or `-p`: Filter by phase number
+- `--resolve` or `-r`: Resolve a specific flag ID
+- `--ack` or `-k`: Acknowledge a specific flag ID
+
+Examples:
+- `/ant:flags` → Show active flags
+- `/ant:flags --all` → Include resolved flags
+- `/ant:flags -t blocker` → Show only blockers
+- `/ant:flags --resolve flag_123 "Fixed by commit abc"` → Resolve a flag
+- `/ant:flags --ack flag_456` → Acknowledge an issue
+
+### Step 2: Handle Resolution/Acknowledgment
+
+
+
+If `--resolve` was provided:
+
+```bash
+bash .aether/aether-utils.sh flag-resolve "{flag_id}" "{resolution_message}"
+```
+Output:
+```
+✅ Flag resolved: {flag_id}
+
+   Resolution: {message}
+```
+Stop here.
+
+
+
+If `--ack` was provided:
+
+```bash
+bash .aether/aether-utils.sh flag-acknowledge "{flag_id}"
+```
+Output:
+```
+👁️ Flag acknowledged: {flag_id}
+
+   Flag noted. Continuing with work.
+```
+Stop here.
+
+### Step 3: List Flags
+
+
+
+Run:
+
+```bash
+bash .aether/aether-utils.sh flag-list {options}
+```
+
+Parse result for flags array.
+
+### Step 4: Display
+
+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.
+
+{if --all was used: "No resolved flags either."}
+```
+
+If flags exist:
+```
+       .-.
+      (o o)  AETHER COLONY
+      | O |  Flags
+       `-"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{for each flag, grouped by type:}
+
+🚫 BLOCKERS ({count})
+   {flag_id}: {title}
+   Phase: {phase or "all"} | Created: {date}
+   └─ {description preview}
+
+⚠️  ISSUES ({count})
+   {flag_id}: {title} {if acknowledged: "[ACK]"}
+   Phase: {phase or "all"} | Created: {date}
+   └─ {description preview}
+
+📝 NOTES ({count})
+   {flag_id}: {title}
+   Phase: {phase or "all"} | Created: {date}
+   └─ {description preview}
+
+{if --all and resolved flags exist:}
+
+✅ RESOLVED ({count})
+   {flag_id}: {title}
+   Resolved: {date} | {resolution}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Summary: {blockers} blockers | {issues} issues | {notes} notes
+
+{if blockers > 0:}
+⚠️  Blockers must be resolved before /ant:continue
+
+Commands:
+  /ant:flags --resolve {id} "message"   Resolve a flag
+  /ant:flags --ack {id}                 Acknowledge an issue
+  /ant:flag "description"               Create new flag
+```
+
+
+
+---
+
+## Quick Actions
+
+**Resolve a flag:**
+```
+/ant:flags --resolve flag_123456 "Fixed in commit abc123"
+```
+
+**Acknowledge an issue:**
+```
+/ant:flags --ack flag_789012
+```
+
+**Create a new flag:**
+```
+/ant:flag --type blocker "Critical issue here"
+```

package/.aether/commands/opencode/focus.md

@@ -0,0 +1,73 @@
+<!-- Generated from .aether/commands/focus.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:focus
+description: "🔦🐜🔍🐜🔦 Emit FOCUS signal to guide colony attention"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+
+
+You are the **Queen**. Add a FOCUS constraint.
+
+
+## Instructions
+
+The focus area is: `$normalized_args`
+
+### Step 1: Validate
+
+If `$normalized_args` empty -> show usage: `/ant:focus <area>`, stop.
+If content > 500 chars -> "Focus content too long (max 500 chars)", stop.
+
+
+
+### Step 2: Write Signal
+
+Read `.aether/data/COLONY_STATE.json`.
+If `goal: null` -> "No colony initialized.", stop.
+
+
+
+Read `.aether/data/constraints.json`. If file doesn't exist, create it with:
+```json
+{"version": "1.0", "focus": [], "constraints": []}
+```
+
+Append the focus area to the `focus` array.
+
+If `focus` array exceeds 5 entries, remove the oldest entries to keep only 5.
+
+Write constraints.json.
+
+**Write pheromone signal and update context:**
+```bash
+bash .aether/aether-utils.sh pheromone-write FOCUS "$normalized_args" --strength 0.8 --reason "User directed colony attention" 2>/dev/null || true
+bash .aether/aether-utils.sh context-update constraint focus "$normalized_args" "user" 2>/dev/null || true
+```
+
+### Step 3: Confirm
+
+Output header:
+
+```
+🔦🐜🔍🐜🔦 ═══════════════════════════════════════════════════
+   F O C U S   S I G N A L
+═══════════════════════════════════════════════════ 🔦🐜🔍🐜🔦
+```
+
+Then output:
+```
+🎯 FOCUS signal emitted
+
+   "{content preview}"
+
+🐜 Colony attention directed.
+```
+
+
+

package/.aether/commands/opencode/help.md

@@ -0,0 +1,157 @@
+<!-- Generated from .aether/commands/help.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:help
+description: "Aether Colony - command reference and system overview"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+You are the **Queen Ant Colony**. Display the system overview and available commands.
+
+## Instructions
+
+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.
+
+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)
+
+
+SESSION COMMANDS
+
+  /ant:pause-colony      Save state and create handoff document
+  /ant:resume-colony     Restore from pause (full state + context)
+
+  /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:
+
+
+    LAY-EGGS → INIT → PLAN → BUILD → CONTINUE → BUILD → ... → SEAL → ENTOMB
+
+
+  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 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.
+
+```
+