aether-colony 5.3.2 → 5.4.0

package/.aether/commands/oracle.yaml

@@ -42,10 +42,10 @@ body_claude: |
 
   ### Step 0b: Stop Oracle
 
-  Create the stop signal file by running using the Bash tool with description "Stopping oracle research...":
+  Stop any active Oracle research by running using the Bash tool with description "Stopping oracle research...":
 
   ```bash
-  mkdir -p .aether/oracle && touch .aether/oracle/.stop
+  mkdir -p .aether/oracle && touch .aether/oracle/.stop && rm -f .aether/oracle/.loop-active
   ```
 
   Output:
@@ -53,8 +53,11 @@ body_claude: |
   ```
   🔮🐜 Oracle Stop Signal Sent
 
-     Created .aether/oracle/.stop
-     The research loop will halt at the end of the current iteration.
+     Removed loop state files.
+     - .aether/oracle/.stop (signal for legacy tmux loop)
+     - .aether/oracle/.loop-active (signal for in-session loop)
+
+     Any active research will halt at the next iteration boundary.
 
      To check final results: /ant:oracle status
   ```
@@ -276,6 +279,41 @@ body_claude: |
 
   (The user will type their topic via the "Other" free-text option.)
 
+  **Question 1.5: Research Brief — Formulate and Approve**
+
+  Take the user's raw topic (from `$ARGUMENTS` or Question 1) and reformulate it into a structured research brief. The user may have typed casual natural language — your job is to sharpen it into a clear, well-scoped research prompt that will produce better results.
+
+  Display the brief for approval:
+
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🔮 R E S E A R C H   B R I E F
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  **Topic:** {reformulated topic — clear, specific, actionable}
+  **Core Question:** {the single most important question this research should answer}
+  **Context:** {what we already know from the codebase or user input}
+  **Success Criteria:** {what a good answer looks like — what would make this research useful}
+  ```
+
+  Guidelines for formulation:
+  - Turn vague topics into specific ones ("auth stuff" → "Authentication architecture: session-based vs token-based for this Node.js API")
+  - Add codebase context if relevant (tech stack, existing patterns)
+  - Make the core question answerable — not open-ended philosophy
+  - Keep success criteria concrete ("A recommendation with trade-offs" not "understand everything")
+
+  Then ask the user to approve:
+
+  ```
+  Does this capture what you're looking for? (approve / edit)
+  ```
+
+  - If the user approves: use the reformulated topic as the research topic going forward
+  - If the user edits: incorporate their changes, display the updated brief, and ask again
+  - Max 2 revision rounds (same as init). After 2, ask for final approval or cancel.
+
+  The approved **Topic** from the brief becomes the topic used in all subsequent steps (state.json, plan.json, research-plan.md).
+
   **Question 2: Research Template**
 
   ```
@@ -372,14 +410,14 @@ body_claude: |
 
   Check for stale files by running using the Bash tool with description "Checking for stale oracle session...":
   ```bash
-  stale_check=$(bash .aether/aether-utils.sh session-verify-fresh --command oracle "" "$ORACLE_START")
+  stale_check=$(aether session-verify-fresh --command oracle "" "$ORACLE_START")
   has_stale=$(echo "$stale_check" | jq -r '.stale | length')
   has_progress=$(echo "$stale_check" | jq -r '.fresh | length')
 
   if [[ "$has_stale" -gt 0 ]] || [[ "$has_progress" -gt 0 ]]; then
     # Found existing oracle session
     if [[ "$force_research" == "true" ]]; then
-      bash .aether/aether-utils.sh session-clear --command oracle
+      aether session-clear --command oracle
       echo "Cleared stale oracle session for fresh research"
     else
       # Existing session found - prompt user
@@ -445,7 +483,7 @@ body_claude: |
   For each focus area string from Question 7, run using the Bash tool with description "Emitting focus area pheromones...":
 
   ```bash
-  bash .aether/aether-utils.sh pheromone-write FOCUS "$focus_area" \
+  aether pheromone-write --type FOCUS --content "$focus_area" \
     --strength 0.8 --source "oracle:wizard" \
     --reason "Focus area set in oracle wizard" --ttl "24h" 2>/dev/null || true
   ```
@@ -544,7 +582,7 @@ body_claude: |
 
   Verify that state.json, plan.json, gaps.md, synthesis.md, and research-plan.md were created successfully by running using the Bash tool with description "Verifying oracle files...":
   ```bash
-  verify_result=$(bash .aether/aether-utils.sh session-verify-fresh --command oracle "" "$ORACLE_START")
+  verify_result=$(aether session-verify-fresh --command oracle "" "$ORACLE_START")
   fresh_count=$(echo "$verify_result" | jq -r '.fresh | length')
 
   if [[ "$fresh_count" -lt 5 ]]; then
@@ -556,7 +594,7 @@ body_claude: |
 
   ---
 
-  ### Step 3: Launch
+  ### Step 3: Launch (In-Session Loop)
 
   Output the research configuration summary, showing the sub-questions from plan.json:
 
@@ -580,65 +618,63 @@ body_claude: |
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   ```
 
-  Now launch the loop. Try tmux first, fall back to manual.
-
-  **Try tmux** by running using the Bash tool with description "Launching oracle in tmux...":
+  **Create the loop marker file** by running using the Bash tool with description "Creating oracle loop marker...":
 
   ```bash
-  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"
+  SESSION_ID="${CLAUDE_SESSION_ID:-$(uuidgen 2>/dev/null || date +%s)}"
+  MAX_IT=<max_iterations from wizard>
+  TARGET_CONF=<target_confidence from wizard>
+  cat > .aether/oracle/.loop-active <<MARKER
+  ---
+  iteration: 0
+  max_iterations: $MAX_IT
+  session_id: $SESSION_ID
+  phase: survey
+  target_confidence: $TARGET_CONF
+  synthesis_done: false
+  oracle_md_path: .aether/utils/oracle/oracle.md
+  ---
+  Oracle research loop active
+  MARKER
+  echo "LOOP_MARKER_CREATED"
   ```
 
-  **If TMUX_OK:**
+  Output:
 
   ```
-  🔮🐜 Oracle Launched
+  🔮🐜 Oracle Research Started (In-Session Loop)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-     The Oracle is researching in a background tmux session.
+     The Oracle is researching IN THIS SESSION.
+
+     The Stop hook will keep the loop running automatically:
+     - Each iteration researches one question
+     - Phases advance: survey -> investigate -> synthesize -> verify
+     - Loop ends when confidence reaches {target_confidence}% or max iterations hit
+     - A final synthesis pass produces the research report
 
-     👁️  Watch live:     tmux attach -t oracle
      📊 Check status:   /ant:oracle status
      🛑 Stop early:     /ant:oracle stop
 
      Research progress visible at .aether/oracle/research-plan.md
-     The Oracle will stop when it reaches {target_confidence}% confidence
-     or completes {max_iterations} iterations.
 
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-     You can keep working. The Oracle runs independently.
-  ```
-
-  Stop here.
-
-  **If TMUX_FAIL** (tmux not installed or error):
-
+     You can continue chatting. The Oracle loop runs between your messages.
   ```
-  🔮 Ready to Launch
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-     tmux not available. Run this in a separate terminal:
 
-     cd {current_working_directory}
-     bash .aether/utils/oracle/oracle.sh
-
-     Then come back here:
-     📊 Check status:   /ant:oracle status
-     🛑 Stop early:     /ant:oracle stop
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  ```
+  **Now begin the first iteration.** Read `.aether/utils/oracle/oracle.md` and start the survey phase research immediately.
+  Target the first untouched question from plan.json. Update state files as you go.
+  When you try to stop, the Stop hook will check progress and continue the loop if needed.
 
   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"
+  aether print-next-up
   ```
 
-  Stop here.
-
 body_opencode: |
   You are the **Oracle Ant** command handler. You configure and launch a deep research loop that runs autonomously in a separate process.
 
@@ -679,10 +715,10 @@ body_opencode: |
 
   ### Step 0b: Stop Oracle
 
-  Create the stop signal file:
+  Stop any active Oracle research:
 
   ```bash
-  mkdir -p .aether/oracle && touch .aether/oracle/.stop
+  mkdir -p .aether/oracle && touch .aether/oracle/.stop && rm -f .aether/oracle/.loop-active
   ```
 
   Output:
@@ -690,8 +726,9 @@ body_opencode: |
   ```
   🔮 Oracle Stop Signal Sent
 
-     Created .aether/oracle/.stop
-     The research loop will halt at the end of the current iteration.
+     Created .aether/oracle/.stop (legacy tmux signal)
+     Removed .aether/oracle/.loop-active (in-session loop marker)
+     The research loop will halt at the next iteration boundary.
 
      To check final results: /ant:oracle status
   ```
@@ -913,6 +950,41 @@ body_opencode: |
 
   (The user will type their topic via the "Other" free-text option.)
 
+  **Question 1.5: Research Brief — Formulate and Approve**
+
+  Take the user's raw topic (from `$normalized_args` or Question 1) and reformulate it into a structured research brief. The user may have typed casual natural language — your job is to sharpen it into a clear, well-scoped research prompt that will produce better results.
+
+  Display the brief for approval:
+
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🔮 R E S E A R C H   B R I E F
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  **Topic:** {reformulated topic — clear, specific, actionable}
+  **Core Question:** {the single most important question this research should answer}
+  **Context:** {what we already know from the codebase or user input}
+  **Success Criteria:** {what a good answer looks like — what would make this research useful}
+  ```
+
+  Guidelines for formulation:
+  - Turn vague topics into specific ones ("auth stuff" → "Authentication architecture: session-based vs token-based for this Node.js API")
+  - Add codebase context if relevant (tech stack, existing patterns)
+  - Make the core question answerable — not open-ended philosophy
+  - Keep success criteria concrete ("A recommendation with trade-offs" not "understand everything")
+
+  Then ask the user to approve:
+
+  ```
+  Does this capture what you're looking for? (approve / edit)
+  ```
+
+  - If the user approves: use the reformulated topic as the research topic going forward
+  - If the user edits: incorporate their changes, display the updated brief, and ask again
+  - Max 2 revision rounds (same as init). After 2, ask for final approval or cancel.
+
+  The approved **Topic** from the brief becomes the topic used in all subsequent steps (state.json, plan.json, research-plan.md).
+
   **Question 2: Research Template**
 
   ```
@@ -1048,7 +1120,7 @@ body_opencode: |
   For each focus area string from Question 7:
 
   ```bash
-  bash .aether/aether-utils.sh pheromone-write FOCUS "$focus_area" \
+  aether pheromone-write --type FOCUS --content "$focus_area" \
     --strength 0.8 --source "oracle:wizard" \
     --reason "Focus area set in oracle wizard" --ttl "24h" 2>/dev/null || true
   ```
@@ -1147,7 +1219,7 @@ body_opencode: |
 
   ---
 
-  ### Step 3: Launch
+  ### Step 3: Launch (In-Session Loop)
 
   Output the research configuration summary, showing the sub-questions from plan.json:
 
@@ -1171,54 +1243,47 @@ body_opencode: |
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   ```
 
-  Now launch the loop. Try tmux first, fall back to manual.
-
-  **Try tmux:**
+  **Create the loop marker file:**
 
   ```bash
-  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:**
-
-  ```
-  🔮 Oracle Launched
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-     The Oracle is researching in a background tmux session.
-
-     👁️  Watch live:     tmux attach -t oracle
-     📊 Check status:   /ant:oracle status
-     🛑 Stop early:     /ant:oracle stop
-
-     Research progress visible at .aether/oracle/research-plan.md
-     The Oracle will stop when it reaches {target_confidence}% confidence
-     or completes {max_iterations} iterations.
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-     You can keep working. The Oracle runs independently.
+  SESSION_ID="${CLAUDE_SESSION_ID:-$(uuidgen 2>/dev/null || date +%s)}"
+  MAX_IT=<max_iterations from wizard>
+  TARGET_CONF=<target_confidence from wizard>
+  cat > .aether/oracle/.loop-active <<MARKER
+  ---
+  iteration: 0
+  max_iterations: $MAX_IT
+  session_id: $SESSION_ID
+  phase: survey
+  target_confidence: $TARGET_CONF
+  synthesis_done: false
+  oracle_md_path: .aether/utils/oracle/oracle.md
+  ---
+  Oracle research loop active
+  MARKER
+  echo "LOOP_MARKER_CREATED"
   ```
 
-  Stop here.
-
-  **If TMUX_FAIL** (tmux not installed or error):
+  Output:
 
   ```
-  🔮 Ready to Launch
+  🔮 Oracle Research Started (In-Session Loop)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-     tmux not available. Run this in a separate terminal:
+     The Oracle is researching IN THIS SESSION.
 
-     cd {current_working_directory}
-     bash .aether/utils/oracle/oracle.sh
+     The Stop hook keeps the loop running automatically between iterations.
+     Phases advance: survey -> investigate -> synthesize -> verify
+     Loop ends when confidence target is reached or max iterations hit.
 
-     Then come back here:
      📊 Check status:   /ant:oracle status
      🛑 Stop early:     /ant:oracle stop
 
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+     You can continue chatting. The Oracle loop runs between your messages.
   ```
 
-  Stop here.
+  **Now begin the first iteration.** Read `.aether/utils/oracle/oracle.md` and start survey phase research.
+  Target the first untouched question from plan.json. Update state files as you go.
 

package/.aether/commands/organize.yaml

@@ -30,7 +30,7 @@ body_claude: |
 
   Run using the Bash tool with description "Loading active pheromones...":
   ```bash
-  bash .aether/aether-utils.sh pheromone-read
+  aether pheromone-read
   ```
 
   Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
@@ -206,7 +206,7 @@ body_claude: |
 
   Use the Bash tool with description "Logging hygiene activity..." to run:
   ```
-  bash .aether/aether-utils.sh activity-log "COMPLETE" "queen" "Hygiene report generated"
+  aether activity-log "COMPLETE" "queen" "Hygiene report generated"
   ```
 
   Display persistence confirmation:
@@ -225,7 +225,7 @@ body_claude: |
   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"
+  aether print-next-up
   ```
 
 body_opencode: |
@@ -255,7 +255,7 @@ body_opencode: |
 
   Run using the Bash tool:
   ```bash
-  bash .aether/aether-utils.sh pheromone-read
+  aether pheromone-read
   ```
 
   Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
@@ -432,7 +432,7 @@ body_opencode: |
 
   Use the Bash tool to run:
   ```
-  bash .aether/aether-utils.sh activity-log "COMPLETE" "queen" "Hygiene report generated"
+  aether activity-log "COMPLETE" "queen" "Hygiene report generated"
   ```
 
   Display persistence confirmation:

package/.aether/commands/patrol.yaml

@@ -78,7 +78,7 @@ body: |
   Display audit header:
   ```
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     C O L O N Y   A U D I T
+  🔍 C O L O N Y   A U D I T
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   Goal: {goal}
@@ -248,12 +248,12 @@ body: |
 
   **Flags check:**
   ```bash
-  bash .aether/aether-utils.sh flag-list 2>/dev/null || echo '{"result":{"flags":[]}}'
+  aether flag-list --json 2>/dev/null || echo '{"result":{"flags":[]}}'
   ```
 
   **Midden check:**
   ```bash
-  bash .aether/aether-utils.sh midden-recent-failures 2>/dev/null || echo '{"result":{"failures":[]}}'
+  aether midden-recent-failures 2>/dev/null || echo '{"result":{"failures":[]}}'
   ```
 
   **Parse flag results:**
@@ -333,12 +333,12 @@ body: |
 
   **Expire stale pheromones:**
   ```bash
-  bash .aether/aether-utils.sh pheromone-expire 2>/dev/null || true
+  aether pheromone-expire 2>/dev/null || true
   ```
 
   **Load memory metrics:**
   ```bash
-  bash .aether/aether-utils.sh memory-metrics 2>/dev/null || echo '{}'
+  aether memory-metrics 2>/dev/null || echo '{}'
   ```
 
   **Load instincts:**
@@ -358,7 +358,7 @@ body: |
 
   **Count pheromone signals:**
   ```bash
-  bash .aether/aether-utils.sh pheromone-count 2>/dev/null || echo '{"result":{"count":0}}'
+  aether pheromone-count 2>/dev/null || echo '{"result":{"count":0}}'
   ```
 
   Display:
@@ -502,7 +502,7 @@ body: |
 
   ```
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     A U D I T   R E S U L T S
+  📋 A U D I T   R E S U L T S
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   Goal: {goal}
@@ -587,7 +587,7 @@ body: |
 
   Run using the Bash tool:
   ```bash
-  bash .aether/aether-utils.sh activity-log "COMPLETE" "queen" "Colony audit completed - {recommendation}"
+  aether activity-log "COMPLETE" "queen" "Colony audit completed - {recommendation}"
   ```
 
   Display persistence confirmation:

package/.aether/commands/pause-colony.yaml

@@ -22,7 +22,7 @@ body_claude: |
 
   Run using the Bash tool with description "Loading active pheromones...":
   ```bash
-  bash .aether/aether-utils.sh pheromone-read
+  aether pheromone-read
   ```
 
   Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
@@ -114,7 +114,7 @@ body_claude: |
 
   **4. Generate Enhanced Commit Message:**
   ```bash
-  bash .aether/aether-utils.sh generate-commit-message "contextual" {current_phase} "{phase_name}" "{ai_description}" {plan_number}
+  aether generate-commit-message --type "contextual" --phase {current_phase} --subject "{phase_name}" "{ai_description}" {plan_number}
   ```
 
   Parse the returned JSON to extract `message`, `body`, `files_changed`, `subsystem`, and `scope`.
@@ -170,12 +170,12 @@ body_claude: |
   Log this pause activity to `.aether/CONTEXT.md` by running using the Bash tool with description "Updating context document...":
 
   ```bash
-  bash .aether/aether-utils.sh context-update activity "pause-colony" "Colony paused — handoff created" "—"
+  aether context-update activity "pause-colony" "Colony paused — handoff created" "—"
   ```
 
   Update safe-to-clear status by running using the Bash tool with description "Marking safe to clear...":
   ```bash
-  bash .aether/aether-utils.sh context-update safe-to-clear "YES" "Colony paused — safe to /clear, run /ant:resume-colony to continue"
+  aether context-update safe-to-clear "YES" "Colony paused — safe to /clear, run /ant:resume-colony to continue"
   ```
 
   ### Step 5: Display Confirmation
@@ -226,7 +226,7 @@ body_claude: |
   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"
+  aether print-next-up
   ```
 
 body_opencode: |
@@ -248,7 +248,7 @@ body_opencode: |
 
   Run using the Bash tool:
   ```bash
-  bash .aether/aether-utils.sh pheromone-read
+  aether pheromone-read
   ```
 
   Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
@@ -329,7 +329,7 @@ body_opencode: |
 
   3. **Generate the commit message:**
   ```bash
-  bash .aether/aether-utils.sh generate-commit-message "pause" {current_phase} "{phase_name}"
+  aether generate-commit-message --type "pause" --phase {current_phase} --subject "{phase_name}"
   ```
   Parse the returned JSON to extract `message` and `files_changed`.
 

package/.aether/commands/phase.yaml

@@ -79,7 +79,7 @@ body: |
   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"
+  aether print-next-up
   ```
   {{/claude}}
 

package/.aether/commands/pheromones.yaml

@@ -109,7 +109,7 @@ body: |
 
   Run using the Bash tool with description "Displaying pheromones...":
   ```bash
-  bash .aether/aether-utils.sh pheromone-display "{subcommand or 'all'}"
+  aether pheromone-display "{subcommand or 'all'}"
   ```
 
   The output will be the formatted pheromone table.