aether-colony 5.0.0 → 5.2.1

package/.aether/commands/export-signals.yaml

@@ -0,0 +1,64 @@
+name: "ant:export-signals"
+description: "Export colony pheromone signals to portable XML format"
+body: |
+  You are the **Queen**. Export colony pheromone signals to portable XML format.
+
+  ## Instructions
+
+  The optional output path is: `{{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}}`:
+  - If a path is provided, use it as the output path.
+  - If empty, default to `.aether/exchange/pheromones.xml`.
+
+  ### Step 2: Export
+
+  Run using the Bash tool with description "Exporting pheromone signals to XML...":
+  ```bash
+  bash .aether/aether-utils.sh pheromone-export-xml "<output_path>"
+  ```
+
+  Parse the returned JSON:
+  - If `.ok` is `true`: extract `.result.path` and `.result.validated` (if present).
+  - If `.ok` is `false`: check `.error` for details. If error mentions `xmllint` or `E_FEATURE_UNAVAILABLE`, display: "XML export 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 (3-5 lines, no banners):
+  ```
+  Pheromone signals exported to XML
+    Path: <output_path>
+    Validated: <yes/no based on .result.validated>
+
+  Share this file with another colony using /ant:import-signals.
+  ```
+  {{/claude}}
+  {{#opencode}}
+  Output:
+  ```
+  Export colony pheromone signals to portable XML format
+
+    Path: <output_path>
+    Validated: <yes/no based on .result.validated>
+
+  Share this file with another colony using /ant:import-signals.
+  ```
+  {{/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}}

package/.aether/commands/feedback.yaml

@@ -0,0 +1,158 @@
+name: "ant:feedback"
+description: "Emit FEEDBACK signal to provide guidance to colony"
+description_opencode: "💬🐜🧠🐜💬 Emit FEEDBACK signal to provide guidance to colony"
+body: |
+  {{#claude}}
+  You are the **Queen**. Emit a FEEDBACK pheromone signal.
+  {{/claude}}
+  {{#opencode}}
+  You are the **Queen**. Emit a FEEDBACK signal.
+  {{/opencode}}
+
+  ## Instructions
+
+  The feedback message is: `{{ARGUMENTS}}`
+
+  ### Step 1: Validate
+
+  If `{{ARGUMENTS}}` empty -> show usage: `/ant:feedback <message>`, stop.
+  If content > 500 chars -> "Signal content too long (max 500 chars)", stop.
+
+  {{#claude}}
+  Parse optional flags from `$ARGUMENTS`:
+  - `--ttl <value>`: signal lifetime (e.g., `2h`, `1d`, `7d`). Default: `phase_end`.
+  - Strip flags from content before using it as the feedback message.
+  {{/claude}}
+
+  ### Step 2: Write Signal and Create Instinct
+
+  Read `.aether/data/COLONY_STATE.json`.
+  If `goal: null` -> "No colony initialized.", stop.
+
+  {{#claude}}
+  {{TOOL_PREFIX "Recording colony feedback..."}}
+  ```bash
+  bash .aether/aether-utils.sh pheromone-write FEEDBACK "<content>" --strength 0.7 --reason "User feedback guidance" --ttl <ttl>
+  ```
+
+  **Create instinct from feedback:**
+  User feedback is high-value learning. Generate ISO-8601 timestamp and append to `memory.instincts` in COLONY_STATE.json:
+  ```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.
+
+  ### Step 2.5: Update Context Document
+
+  {{TOOL_PREFIX "Updating context document..."}}
+  ```bash
+  bash .aether/aether-utils.sh context-update constraint feedback "<content>" "user" 2>/dev/null || true
+  ```
+
+  ### Step 3: Get Active Counts
+
+  {{TOOL_PREFIX "Counting active signals..."}}
+  ```bash
+  bash .aether/aether-utils.sh pheromone-count
+  ```
+
+  ### Step 4: Confirm
+
+  Output (4 lines, no banners):
+  ```
+  FEEDBACK signal emitted
+    Note: "<content truncated to 60 chars>"
+    Strength: 0.7 | Expires: <phase end or ttl value>
+    Active signals: <focus_count> FOCUS, <redirect_count> REDIRECT, <feedback_count> FEEDBACK
+
+  Instinct created: [0.7] <domain>: <action summary>
+  ```
+  {{/claude}}
+  {{#opencode}}
+  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.
+  ```
+  {{/opencode}}
+
+  {{#claude}}
+  ### Step 5: 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}}

package/.aether/commands/flag.yaml

@@ -0,0 +1,160 @@
+name: "ant:flag"
+description: "🚩🐜📋🐜🚩 Create a project-specific flag (blocker, issue, or note)"
+body: |
+  You are the **Queen**. Create a project-specific flag.
+
+  ## Instructions
+
+  The flag is: `{{ARGUMENTS}}`
+
+  ### Step 1: Parse Arguments
+
+  Parse `{{ARGUMENTS}}` 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 `{{ARGUMENTS}}` 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
+
+  {{TOOL_PREFIX "Raising colony flag..."}}
+  ```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:**
+  ```
+  {{#claude}}
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🚩🐜📋🐜🚩  B L O C K E R   F L A G   C R E A T E D
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  {{/claude}}
+  {{#opencode}}
+  🚩🐜📋🐜🚩 ═══════════════════════════════════════════════════
+     B L O C K E R   F L A G   C R E A T E D
+  ═══════════════════════════════════════════════════ 🚩🐜📋🐜🚩
+  {{/opencode}}
+  ```
+
+  **For issue:**
+  ```
+  {{#claude}}
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🚩🐜📋🐜🚩  I S S U E   F L A G   C R E A T E D
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  {{/claude}}
+  {{#opencode}}
+  🚩🐜📋🐜🚩 ═══════════════════════════════════════════════════
+     I S S U E   F L A G   C R E A T E D
+  ═══════════════════════════════════════════════════ 🚩🐜📋🐜🚩
+  {{/opencode}}
+  ```
+
+  **For note:**
+  ```
+  {{#claude}}
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🚩🐜📋🐜🚩  N O T E   F L A G   C R E A T E D
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  {{/claude}}
+  {{#opencode}}
+  🚩🐜📋🐜🚩 ═══════════════════════════════════════════════════
+     N O T E   F L A G   C R E A T E D
+  ═══════════════════════════════════════════════════ 🚩🐜📋🐜🚩
+  {{/opencode}}
+  ```
+
+  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.
+  ```
+
+  {{#claude}}
+  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}}
+
+  ---
+
+  ## 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/flags.yaml

@@ -0,0 +1,177 @@
+name: "ant:flags"
+description: "📋🐜🚩🐜📋 List project flags (blockers, issues, notes)"
+body: |
+  You are the **Queen**. Display project flags.
+
+  ## Instructions
+
+  Arguments: `{{ARGUMENTS}}`
+
+  ### Step 1: Parse Arguments
+
+  Parse `{{ARGUMENTS}}` 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
+
+  {{#claude}}
+  If `--resolve` was provided, run using the Bash tool with description "Resolving colony flag...":
+  {{/claude}}
+  {{#opencode}}
+  If `--resolve` was provided:
+  {{/opencode}}
+  ```bash
+  bash .aether/aether-utils.sh flag-resolve "{flag_id}" "{resolution_message}"
+  ```
+  Output:
+  ```
+  ✅ Flag resolved: {flag_id}
+
+     Resolution: {message}
+  ```
+  Stop here.
+
+  {{#claude}}
+  If `--ack` was provided, run using the Bash tool with description "Acknowledging colony flag...":
+  {{/claude}}
+  {{#opencode}}
+  If `--ack` was provided:
+  {{/opencode}}
+  ```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
+
+  {{#claude}}
+  Run using the Bash tool with description "Loading colony flags...":
+  {{/claude}}
+  {{#opencode}}
+  Run:
+  {{/opencode}}
+  ```bash
+  bash .aether/aether-utils.sh flag-list {options}
+  ```
+
+  Parse result for flags array.
+
+  ### Step 4: Display
+
+  Output header:
+
+  {{#claude}}
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📋🐜🚩🐜📋  P R O J E C T   F L A G S
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  {{/claude}}
+  {{#opencode}}
+  ```
+  📋🐜🚩🐜📋 ═══════════════════════════════════════════════════
+     P R O J E C T   F L A G S
+  ═══════════════════════════════════════════════════ 📋🐜🚩🐜📋
+  {{/opencode}}
+
+  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
+  ```
+
+  {{#claude}}
+  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}}
+
+  ---
+
+  ## 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/focus.yaml

@@ -0,0 +1,112 @@
+name: "ant:focus"
+description: "Emit FOCUS signal to guide colony attention"
+description_opencode: "🔦🐜🔍🐜🔦 Emit FOCUS signal to guide colony attention"
+body: |
+  {{#claude}}
+  You are the **Queen**. Emit a FOCUS pheromone signal.
+  {{/claude}}
+  {{#opencode}}
+  You are the **Queen**. Add a FOCUS constraint.
+  {{/opencode}}
+
+  ## Instructions
+
+  The focus area is: `{{ARGUMENTS}}`
+
+  ### Step 1: Validate
+
+  If `{{ARGUMENTS}}` empty -> show usage: `/ant:focus <area>`, stop.
+  If content > 500 chars -> "Focus content too long (max 500 chars)", stop.
+
+  {{#claude}}
+  Parse optional flags from `$ARGUMENTS`:
+  - `--ttl <value>`: signal lifetime (e.g., `2h`, `1d`, `7d`). Default: `phase_end`.
+  - Strip flags from content before using it as the focus area.
+  {{/claude}}
+
+  ### Step 2: Write Signal
+
+  Read `.aether/data/COLONY_STATE.json`.
+  If `goal: null` -> "No colony initialized.", stop.
+
+  {{#claude}}
+  {{TOOL_PREFIX "Setting colony focus..."}}
+  ```bash
+  bash .aether/aether-utils.sh pheromone-write FOCUS "<content>" --strength 0.8 --reason "User directed colony attention" --ttl <ttl>
+  ```
+
+  Parse the returned JSON for the signal ID.
+
+  ### Step 2.5: Update Context Document
+
+  {{TOOL_PREFIX "Updating context document..."}}
+  ```bash
+  bash .aether/aether-utils.sh context-update constraint focus "<content>" "user" 2>/dev/null || true
+  ```
+
+  ### Step 3: Get Active Counts
+
+  {{TOOL_PREFIX "Counting active signals..."}}
+  ```bash
+  bash .aether/aether-utils.sh pheromone-count
+  ```
+
+  ### Step 4: Confirm
+
+  Output (3-4 lines, no banners):
+  ```
+  FOCUS signal emitted
+    Area: "<content truncated to 60 chars>"
+    Strength: 0.8 | Expires: <phase end or ttl value>
+    Active signals: <focus_count> FOCUS, <redirect_count> REDIRECT, <feedback_count> FEEDBACK
+  ```
+  {{/claude}}
+  {{#opencode}}
+  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.
+  ```
+  {{/opencode}}
+
+  {{#claude}}
+  ### Step 5: 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}}