aether-colony 5.0.0 → 5.2.1

package/.opencode/commands/ant/oracle.md

@@ -1,8 +1,15 @@
+<!-- Generated from .aether/commands/oracle.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:oracle
 description: "🔮🐜🧠🐜🔮 Oracle Ant - deep research agent using RALF iterative loop pattern"
 ---
 
+### 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 **Oracle Ant** command handler. You configure and launch a deep research loop that runs autonomously in a separate process.
 
 The user's input is: `$normalized_args`
@@ -13,12 +20,6 @@ Oracle NEVER touches COLONY_STATE.json, constraints.json, activity.log, or any c
 
 ## Instructions
 
-### 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.
-
 ### Step 0: Parse Arguments and Route
 
 Parse `$normalized_args` to determine the action:
@@ -30,19 +31,10 @@ Parse `$normalized_args` to determine the action:
 
 2. **If remaining arguments is exactly `stop`** — go to **Step 0b: Stop Oracle**
 3. **If remaining arguments is exactly `status`** — go to **Step 0c: Show Status**
-4. **Otherwise** — go to **Step 0.5: Initialize Visual Mode** then **Step 1: Research Wizard**
+4. **If remaining arguments is exactly `promote`** — go to **Step 0d: Promote Findings**
+5. **Otherwise** — go to **Step 0.5: Initialize Visual Mode** then **Step 1: Research Wizard**
 
-### Step 0.5: Initialize Visual Mode (if enabled)
-
-If `visual_mode` is true:
-```bash
-# Generate session ID
-oracle_id="oracle-$(date +%s)"
-
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$oracle_id"
-bash .aether/aether-utils.sh swarm-display-update "Oracle" "oracle" "researching" "Deep research in progress" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
-```
+### Step 0.5: Display Header
 
 Display visual header:
 ```
@@ -80,35 +72,31 @@ Stop here. Do not proceed.
 
 ### Step 0c: Show Status
 
-Check if `.aether/oracle/progress.md` exists using the Read tool.
+Check if `.aether/oracle/research-plan.md` exists using the Read tool.
 
 **If it does NOT exist**, output:
 
 ```
 🔮 Oracle Status: No Research In Progress
 
-   No progress.md found. Start a research session:
+   No active research session. Start one:
    /ant:oracle
 ```
 
 Stop here.
 
-**If it exists**, read `.aether/oracle/progress.md` and `.aether/oracle/research.json` (if present).
-
-Count the number of `## Iteration` headings in progress.md to determine iterations completed.
+**If it exists**, read `.aether/oracle/research-plan.md` and `.aether/oracle/state.json` (if present).
 
 Output:
 
 ```
 🔮 Oracle Status
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Topic:       {topic from research.json, or "unknown"}
-Confidence:  {target_confidence}%
-Iterations:  {completed} / {max_iterations}
-Started:     {started_at}
+Topic:       {topic from state.json, or "unknown"}
+Iteration:   {iteration} of {max_iterations}
+Status:      {status}
 
-Progress:
-{last 50 lines of progress.md}
+{contents of research-plan.md}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   /ant:oracle stop     Halt the loop
@@ -119,6 +107,143 @@ Stop here.
 
 ---
 
+### Step 0d: Promote Findings to Colony
+
+Check if `.aether/oracle/state.json` exists. If it does NOT exist, or if the status is "active", output:
+
+```
+🔮 Oracle Promote: No Completed Research
+
+   No completed research to promote. Run /ant:oracle first, then wait for completion.
+```
+
+Stop here.
+
+**If state.json exists and status is "complete" or "stopped":**
+
+Read `.aether/oracle/plan.json` and extract high-confidence findings:
+
+```bash
+ORACLE_DIR=".aether/oracle"
+topic=$(jq -r '.topic // "unknown"' "$ORACLE_DIR/state.json")
+status=$(jq -r '.status // "active"' "$ORACLE_DIR/state.json")
+count=$(jq '[.questions[] | select(.status == "answered" and .confidence >= 80)] | length' "$ORACLE_DIR/plan.json" 2>/dev/null || echo "0")
+total=$(jq '[.questions[]] | length' "$ORACLE_DIR/plan.json" 2>/dev/null || echo "0")
+echo "TOPIC=$topic"
+echo "STATUS=$status"
+echo "QUALIFYING=$count"
+echo "TOTAL=$total"
+```
+
+If qualifying count is 0, output:
+
+```
+🔮 Oracle Promote: No Qualifying Findings
+
+   Topic:    {topic}
+   Status:   {status}
+   Findings: 0 of {total} questions meet the threshold (answered + 80%+ confidence)
+
+   Lower-confidence findings remain in .aether/oracle/synthesis.md for reference.
+```
+
+Stop here.
+
+**If qualifying count > 0**, display the summary and ask for confirmation:
+
+```
+🔮 Oracle Promote: Colony Knowledge Integration
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Oracle Research: {topic}
+   Status: {status}
+   High-confidence findings: {count} (answering {count} of {total} questions)
+
+   These findings will be promoted to:
+   - Colony instincts (COLONY_STATE.json)
+   - Colony learnings (learnings.json)
+   - Observation pipeline (for queen-promote)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use AskUserQuestion to ask:
+
+```
+Promote these findings to colony knowledge?
+```
+
+Options:
+1. **Yes, promote all high-confidence findings** -- Push qualifying findings to colony instincts, learnings, and observations
+2. **No, skip promotion** -- Findings remain in .aether/oracle/ for reference only
+
+**If user selects Yes:**
+
+Run promotion. For each qualifying question, call the colony APIs directly:
+
+```bash
+ORACLE_DIR=".aether/oracle"
+UTILS=".aether/aether-utils.sh"
+topic=$(jq -r '.topic // "unknown"' "$ORACLE_DIR/state.json")
+promoted=0
+
+while IFS= read -r question; do
+  q_text=$(echo "$question" | jq -r '.text')
+  q_confidence=$(echo "$question" | jq -r '.confidence')
+  findings_text=$(echo "$question" | jq -r '[.key_findings[].text // .key_findings[]] | join("; ")' 2>/dev/null | head -c 200)
+  first_finding=$(echo "$question" | jq -r '[.key_findings[].text // .key_findings[]] | first // "No findings"' 2>/dev/null)
+
+  bash "$UTILS" instinct-create \
+    --trigger "researching: $q_text" \
+    --action "Oracle found (${q_confidence}% confidence): $findings_text" \
+    --confidence "$(echo "scale=2; $q_confidence / 100" | bc)" \
+    --domain "research" \
+    --source "oracle:$topic" \
+    --evidence "Oracle research: $q_text" 2>/dev/null || true
+
+  bash "$UTILS" learning-promote \
+    "Oracle: $q_text -- $first_finding" \
+    "oracle" \
+    "oracle-research" \
+    "oracle,research" 2>/dev/null || true
+
+  bash "$UTILS" memory-capture learning \
+    "Oracle research finding: $q_text (${q_confidence}%)" \
+    "pattern" \
+    "oracle:promote" 2>/dev/null || true
+
+  promoted=$((promoted + 1))
+done < <(jq -c '[.questions[] | select(.status == "answered" and .confidence >= 80)] | .[]' "$ORACLE_DIR/plan.json")
+
+echo "Promoted $promoted findings"
+```
+
+Output:
+
+```
+🔮 Oracle Promote: Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Promoted {count} findings to colony knowledge:
+   - Instincts created in COLONY_STATE.json
+   - Learnings stored in learnings.json
+   - Observations tracked for wisdom promotion
+
+   Run /ant:status to see colony knowledge updates.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**If user selects No:**
+
+```
+🔮 Promotion skipped. Findings remain in .aether/oracle/synthesis.md.
+```
+
+Stop here.
+
+---
+
 ### Step 1: Research Wizard
 
 This is the setup phase. The Oracle asks questions to configure the research before launching.
@@ -158,7 +283,22 @@ Describe the research topic in detail. The more specific, the better the Oracle'
 
 (The user will type their topic via the "Other" free-text option.)
 
-**Question 2: Research Depth**
+**Question 2: Research Template**
+
+```
+What type of research is this?
+```
+
+Options:
+1. **Technology evaluation** -- Compare and evaluate a technology, library, or tool
+2. **Architecture review** -- Analyze system design, components, and dependencies
+3. **Bug investigation** -- Track down and understand a specific bug or issue
+4. **Best practices** -- Research recommended approaches for a domain or technique
+5. **Custom research** -- Free-form research (Oracle decomposes the topic as it sees fit)
+
+Map selection to template value: 1->tech-eval, 2->architecture-review, 3->bug-investigation, 4->best-practices, 5->custom
+
+**Question 3: Research Depth**
 
 ```
 How deep should the Oracle go?
@@ -170,7 +310,7 @@ Options:
 3. **Deep dive (30 iterations)** — Exhaustive research, leaves no stone unturned
 4. **Marathon (50 iterations)** — Maximum depth, may take hours
 
-**Question 3: Confidence Target**
+**Question 4: Confidence Target**
 
 ```
 When should the Oracle consider the research complete?
@@ -182,7 +322,7 @@ Options:
 3. **95% confidence (recommended)** — Thorough, few gaps remaining
 4. **99% confidence** — Near-exhaustive, won't stop until almost everything is known
 
-**Question 4: Research Scope** (only if topic involves codebase)
+**Question 5: Research Scope** (only if topic involves codebase)
 
 ```
 Should the Oracle also search the web, or stay within the codebase?
@@ -193,6 +333,37 @@ Options:
 2. **Codebase + web** — Also use WebSearch and WebFetch for docs, best practices, prior art
 3. **Web only** — Focus on external research (libraries, concepts, techniques)
 
+**Question 6: Search Strategy**
+
+(Ask this question for all research types.)
+
+```
+How should the Oracle approach the research?
+```
+
+Options:
+1. **Adaptive (recommended)** -- Oracle decides when to go broad vs deep based on research progress
+2. **Breadth-first** -- Cover all questions with initial findings before going deep on any single one
+3. **Depth-first** -- Pick the most important question and investigate it exhaustively before moving on
+
+**Question 7: Focus Areas** (optional)
+
+```
+Are there specific aspects you want the Oracle to prioritize?
+```
+
+Options:
+1. **No specific focus** -- Let the Oracle decide what to investigate first
+2. **Yes, I have focus areas** -- I want to steer the research toward specific aspects
+
+If the user selects option 2, ask a follow-up AskUserQuestion with free-text:
+
+```
+List your focus areas (comma-separated). Example: "security implications, performance under load, migration path"
+```
+
+Parse the comma-separated response into individual focus area strings.
+
 After collecting all answers, proceed to Step 2.
 
 ---
@@ -209,56 +380,137 @@ Generate an ISO-8601 UTC timestamp.
 
 **Archive previous research if it exists:**
 
-Check if `.aether/oracle/progress.md` exists. If it does:
+Check if `.aether/oracle/state.json` exists. If it does:
 
 ```bash
-DATE=$(date +%Y-%m-%d)
-TIMESTAMP=$(date +%H%M%S)
-mkdir -p .aether/oracle/archive
-cp .aether/oracle/progress.md ".aether/oracle/archive/${DATE}-${TIMESTAMP}-progress.md" 2>/dev/null || true
-cp .aether/oracle/research.json ".aether/oracle/archive/${DATE}-${TIMESTAMP}-research.json" 2>/dev/null || true
+ARCHIVE_TS=$(date +%Y-%m-%d-%H%M%S)
+mkdir -p .aether/oracle/archive/$ARCHIVE_TS
+for f in state.json plan.json gaps.md synthesis.md research-plan.md; do
+  [ -f ".aether/oracle/$f" ] && cp ".aether/oracle/$f" ".aether/oracle/archive/$ARCHIVE_TS/"
+done
 ```
 
-**Write research.json:**
+**Write state.json** (replaces research.json):
 
-Use the Write tool to write `.aether/oracle/research.json`:
+Use the Write tool to create `.aether/oracle/state.json`:
 
 ```json
 {
+  "version": "1.1",
   "topic": "<the research topic>",
   "scope": "<codebase|web|both>",
-  "questions": [
-    "<break the topic into 3-5 specific research questions>"
-  ],
+  "template": "<template from Question 2: tech-eval|architecture-review|bug-investigation|best-practices|custom>",
+  "phase": "survey",
+  "iteration": 0,
   "max_iterations": <number from depth choice>,
   "target_confidence": <number from confidence choice>,
-  "started_at": "<ISO-8601 UTC timestamp>"
+  "overall_confidence": 0,
+  "started_at": "<ISO-8601 UTC timestamp>",
+  "last_updated": "<ISO-8601 UTC timestamp>",
+  "status": "active",
+  "strategy": "<strategy from Question 6: adaptive|breadth-first|depth-first>",
+  "focus_areas": [<array of focus area strings from Question 7, or empty array if no focus>]
 }
 ```
 
-The `questions` array is important — break the user's topic into 3-5 concrete, specific questions that the Oracle should answer. These guide each iteration.
+**Emit focus area pheromones** (if any focus areas were set):
 
-**Write progress.md:**
+For each focus area string from Question 7:
 
-Use the Write tool to write `.aether/oracle/progress.md`:
+```bash
+bash .aether/aether-utils.sh pheromone-write FOCUS "$focus_area" \
+  --strength 0.8 --source "oracle:wizard" \
+  --reason "Focus area set in oracle wizard" --ttl "24h" 2>/dev/null || true
+```
+
+**Write plan.json:**
+
+**If template is NOT `custom`**, pre-populate plan.json with the template's default questions. **If template IS `custom`**, break the topic into 3-8 sub-questions (adapt to topic complexity -- broader topics get more questions, focused topics fewer).
+
+Template default questions:
+
+- **tech-eval**: q1 "What problem does this technology solve and what are its core capabilities?", q2 "How does it compare to alternative solutions?", q3 "What are its known limitations and tradeoffs?", q4 "What is the adoption and community status?", q5 "What is the migration or integration path?"
+- **architecture-review**: q1 "What are the main components and their responsibilities?", q2 "What are the dependency relationships between components?", q3 "Where are the risk areas (coupling, complexity, single points of failure)?", q4 "How does it handle scale and growth?", q5 "What would an expert change about this architecture?"
+- **bug-investigation**: q1 "What is the exact failure behavior?", q2 "What are the reproduction conditions?", q3 "What is the root cause?", q4 "What are possible fixes and their tradeoffs?", q5 "Are there related issues or regression risks?"
+- **best-practices**: q1 "What is current industry best practice for this domain?", q2 "How does our implementation compare to best practice?", q3 "What gaps exist between our approach and best practice?", q4 "What is the recommended improvement path?"
+
+Use the Write tool to create `.aether/oracle/plan.json`:
+
+```json
+{
+  "version": "1.1",
+  "sources": {},
+  "questions": [
+    {
+      "id": "q1",
+      "text": "<question text from template or AI-decomposed>",
+      "status": "open",
+      "confidence": 0,
+      "key_findings": [],
+      "iterations_touched": []
+    }
+  ],
+  "created_at": "<ISO-8601 UTC timestamp>",
+  "last_updated": "<ISO-8601 UTC timestamp>"
+}
+```
+
+**Write gaps.md** (initial empty structure):
+
+Use the Write tool to create `.aether/oracle/gaps.md`:
 
 ```markdown
-# Oracle Research Progress
+# Knowledge Gaps
 
-**Topic:** <the research topic>
-**Started:** <ISO-8601 UTC timestamp>
-**Target Confidence:** <N>%
-**Max Iterations:** <N>
-**Scope:** <codebase|web|both>
+## Open Questions
+(No research conducted yet)
 
-## Research Questions
-1. <question 1>
-2. <question 2>
-3. <question 3>
-...
+## Contradictions
+(None identified)
 
----
+## Last Updated
+Iteration 0 -- <ISO-8601 UTC timestamp>
+```
+
+**Write synthesis.md** (initial empty structure):
+
+Use the Write tool to create `.aether/oracle/synthesis.md`:
+
+```markdown
+# Research Synthesis
+
+## Topic
+<the research topic>
+
+## Findings by Question
+(No findings yet -- research has not started)
+
+## Last Updated
+Iteration 0 -- <ISO-8601 UTC timestamp>
+```
 
+**Generate research-plan.md:**
+
+After writing plan.json, generate research-plan.md as the executive summary. Use the Write tool to create `.aether/oracle/research-plan.md`:
+
+```markdown
+# Research Plan
+
+**Topic:** <topic>
+**Status:** active | **Iteration:** 0 of <max>
+**Overall Confidence:** 0%
+
+## Questions
+| # | Question | Status | Confidence |
+|---|----------|--------|------------|
+| q1 | <question text> | open | 0% |
+| q2 | ... | open | 0% |
+
+## Next Steps
+Next investigation: <text of q1, the first question>
+
+---
+*Generated from plan.json -- do not edit directly*
 ```
 
 Proceed to Step 3.
@@ -267,21 +519,24 @@ Proceed to Step 3.
 
 ### Step 3: Launch
 
-Output the research configuration summary:
+Output the research configuration summary, showing the sub-questions from plan.json:
 
 ```
 🔮 Research Configured
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 📍 Topic:       <topic>
+📐 Template:    <template type, e.g. "tech-eval" or "custom">
 🔄 Iterations:  <max_iterations>
 🎯 Confidence:  <target_confidence>%
 🔍 Scope:       <scope>
+📐 Strategy:    <strategy>
+🎯 Focus:       <focus areas comma-separated, or "None">
 
-📋 Research Questions:
-   1. <question>
-   2. <question>
-   3. <question>
+📋 Sub-Questions:
+   q1. <question text from plan.json>
+   q2. <question text from plan.json>
+   q3. <question text from plan.json>
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -291,7 +546,7 @@ Now launch the loop. Try tmux first, fall back to manual.
 **Try tmux:**
 
 ```bash
-tmux new-session -d -s oracle "cd $(pwd) && bash .aether/oracle/oracle.sh; echo ''; echo '🔮 Oracle loop finished. Press any key to close.'; read -n1" 2>/dev/null && echo "TMUX_OK" || echo "TMUX_FAIL"
+tmux new-session -d -s oracle "cd $(pwd) && bash .aether/utils/oracle/oracle.sh; echo ''; echo '🔮 Oracle loop finished. Press any key to close.'; read -n1" 2>/dev/null && echo "TMUX_OK" || echo "TMUX_FAIL"
 ```
 
 **If TMUX_OK:**
@@ -306,7 +561,7 @@ tmux new-session -d -s oracle "cd $(pwd) && bash .aether/oracle/oracle.sh; echo
    📊 Check status:   /ant:oracle status
    🛑 Stop early:     /ant:oracle stop
 
-   Results will accumulate in .aether/oracle/progress.md
+   Research progress visible at .aether/oracle/research-plan.md
    The Oracle will stop when it reaches {target_confidence}% confidence
    or completes {max_iterations} iterations.
 
@@ -326,7 +581,7 @@ Stop here.
    tmux not available. Run this in a separate terminal:
 
    cd {current_working_directory}
-   bash .aether/oracle/oracle.sh
+   bash .aether/utils/oracle/oracle.sh
 
    Then come back here:
    📊 Check status:   /ant:oracle status

package/.opencode/commands/ant/organize.md

@@ -1,20 +1,21 @@
+<!-- Generated from .aether/commands/organize.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:organize
 description: "🧹🐜🏛️🐜🧹 Run codebase hygiene report - archivist ant scans for stale files, dead code, orphaned configs (report-only)"
 ---
 
-You are the **Queen Ant Colony**. Spawn an archivist to analyze codebase hygiene.
-
-> **Note:** `$normalized_args` is unused. Future extensions could accept a path scope argument.
-
-## Instructions
-
 ### 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**. Spawn an archivist to analyze codebase hygiene.
+
+> **Note:** `$normalized_args` is unused. Future extensions could accept a path scope argument.
+
+## Instructions
+
 ### Step 1: Read State
 
 Use the Read tool to read these files (in parallel):
@@ -33,11 +34,12 @@ From COLONY_STATE.json, extract:
 
 ### Step 2: Compute Active Pheromones
 
-Read active signals from COLONY_STATE.json `signals` array (already loaded in Step 1).
+Run using the Bash tool:
+```bash
+bash .aether/aether-utils.sh pheromone-read
+```
 
-Filter signals where:
-- `expires_at` is null (permanent signals like INIT), OR
-- `expires_at` > current timestamp (not expired)
+Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
 
 Format as the standard ACTIVE PHEROMONES block:
 ```
@@ -54,8 +56,8 @@ If no active signals after filtering:
 
 Read `.aether/workers.md` and extract the `## Keeper` section.
 
-Spawn via **Task tool** with `subagent_type="general-purpose"`:
-# NOTE: Claude Code uses aether-keeper; OpenCode uses general-purpose with role injection
+Spawn via **Task tool** with `subagent_type="aether-keeper"`:
+# NOTE: Claude Code uses aether-keeper; OpenCode now uses same specialist agent
 
 ```
 --- WORKER SPEC ---