aether-colony 5.1.0 → 5.3.0

package/.aether/commands/claude/swarm.md

@@ -0,0 +1,349 @@
+<!-- Generated from .aether/commands/swarm.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:swarm
+description: "🔥🐜🗡️🐜🔥 Real-time colony swarm display + stubborn bug destroyer"
+---
+
+You are the **Queen Ant Colony**. Deploy the swarm to destroy a stubborn bug or view real-time colony activity.
+
+## Instructions
+
+### Quick View Mode (No Arguments)
+
+If `$ARGUMENTS` is empty or equals "--watch":
+
+Run the real-time swarm display:
+```bash
+bash .aether/utils/swarm-display.sh
+```
+
+This shows:
+- Active ants with caste colors and emojis (🔨🐜 Builder in blue, etc.)
+- Tool usage stats per ant (📖5 🔍3 ✏️2 ⚡1)
+- Trophallaxis metrics (🍯 token consumption)
+- Timing information (elapsed time per ant)
+- Chamber activity map (which nest zones have active ants)
+- Animated status phrases ("excavating...", "foraging...")
+
+Display updates automatically as ants start/complete work.
+Press Ctrl+C to exit.
+
+### Bug Destruction Mode (With Arguments)
+
+The problem to investigate is: `$ARGUMENTS`
+
+#### Step 1: Validate Input
+
+If `$ARGUMENTS` is empty:
+```
+🔥🐜🗡️🐜🔥 SWARM
+
+Deploy parallel scouts to investigate and fix stubborn bugs.
+
+Usage: /ant:swarm "<describe the problem>"
+
+Examples:
+  /ant:swarm "Tests keep failing in auth module"
+  /ant:swarm "TypeError: Cannot read property 'id' of undefined"
+  /ant:swarm "API returns 500 but I can't find the cause"
+
+This is the nuclear option - use when repeated fix attempts fail.
+```
+Stop here.
+
+#### Step 2: Read State & Initialize
+
+Read `.aether/data/COLONY_STATE.json`.
+If `goal` is null → "No colony initialized. Run /ant:init first.", stop.
+
+Generate swarm ID: `swarm-<unix_timestamp>`
+
+Initialize swarm findings:
+```bash
+bash .aether/aether-utils.sh swarm-findings-init "<swarm_id>"
+```
+
+#### Step 2.5: Check for Stale Swarm Session
+
+Capture session start time:
+```bash
+SWARM_START=$(date +%s)
+```
+
+Check for stale swarm files:
+```bash
+stale_check=$(bash .aether/aether-utils.sh session-verify-fresh --command swarm "" "$SWARM_START")
+has_stale=$(echo "$stale_check" | jq -r '.stale | length')
+
+if [[ "$has_stale" -gt 0 ]]; then
+  # Auto-clear stale swarm findings (safe - findings are temporary)
+  bash .aether/aether-utils.sh session-clear --command swarm
+  echo "Cleared stale swarm findings for fresh investigation"
+fi
+```
+
+After initializing findings, verify swarm files are fresh:
+```bash
+verify_result=$(bash .aether/aether-utils.sh session-verify-fresh --command swarm "" "$SWARM_START")
+if [[ $(echo "$verify_result" | jq -r '.missing | length') -gt 0 ]]; then
+  echo "Warning: Swarm files not properly initialized"
+fi
+```
+
+Display header:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔥🐜🗡️🐜🔥  S W A R M   D E P L O Y E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 Target: "{problem description}"
+📍 Swarm ID: {swarm_id}
+
+⚡ Deploying 4 parallel scouts...
+```
+
+#### Step 3: Create Git Checkpoint
+
+Before any investigation that might lead to fixes, run using the Bash tool:
+```bash
+bash .aether/aether-utils.sh autofix-checkpoint "pre-swarm-$SWARM_ID"
+```
+
+Store the result for potential rollback:
+- `checkpoint_type` = result.type ("stash", "commit", or "none")
+- `checkpoint_ref` = result.ref
+
+```
+💾 Checkpoint: {checkpoint_type} → {checkpoint_ref}
+```
+
+#### Step 4: Read Context
+
+Read existing blockers for context:
+```bash
+bash .aether/aether-utils.sh flag-list --type blocker
+```
+
+Read recent activity:
+```bash
+tail -50 .aether/data/activity.log 2>/dev/null || echo "(no activity log)"
+```
+
+Scan recent git commits for context:
+```bash
+git log --oneline -20 2>/dev/null || echo "(no git history)"
+```
+
+#### Step 5: Deploy 4 Parallel Scouts
+
+Use the **Task** tool to spawn 4 scouts **in a single message** (parallel execution):
+
+**Scout 1: 🏛️ Git Archaeologist** (use Task tool with `subagent_type="aether-archaeologist"`)
+# FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are an Archaeologist Ant - git historian that excavates why code exists."
+```
+You are {swarm_id}-Archaeologist, a 🏛️🐜 Archaeologist Ant.
+
+Investigate git history for: {problem description}
+
+Steps:
+1. Run `git log --oneline -30`
+2. Run `git log -p --since="1 week ago" -- {relevant files}`
+3. Run `git blame {suspected file}` if mentioned
+4. Find commits that introduced the bug
+
+Return ONLY this JSON:
+{"scout": "git-archaeologist", "confidence": 0.0-1.0, "finding": {"likely_cause": "...", "relevant_commits": [], "when_it_broke": "...", "evidence": []}, "suggested_fix": "..."}
+```
+
+**Scout 2: 🔍 Pattern Hunter** (use Task tool with `subagent_type="aether-scout"`)
+```
+You are {swarm_id}-PatternHunter, a 🔍🐜 Scout Ant.
+
+Find working patterns for: {problem description}
+
+Steps:
+1. Grep/glob for related working code
+2. Find how other parts handle this
+3. Look for test files showing correct usage
+4. Identify applicable patterns
+
+Return ONLY this JSON:
+{"scout": "pattern-hunter", "confidence": 0.0-1.0, "finding": {"working_examples": [], "applicable_patterns": [], "differences": "..."}, "suggested_fix": "..."}
+```
+
+**Scout 3: 💥 Error Analyst** (use Task tool with `subagent_type="aether-tracker"`)
+```
+You are {swarm_id}-ErrorAnalyst, a 🔍🐜 Tracker Ant.
+
+Analyze error: {problem description}
+
+Steps:
+1. Trace through stack trace frames
+2. Identify actual failing line vs surface error
+3. Check for null refs, async issues, type mismatches
+4. Look for error handling masking the issue
+
+Return ONLY this JSON:
+{"scout": "error-analyst", "confidence": 0.0-1.0, "finding": {"root_cause": "...", "error_chain": [], "masked_by": "...", "category": "null-ref|async|type|logic|config|dependency"}, "suggested_fix": "..."}
+```
+
+**Scout 4: 🌐 Web Researcher** (use Task tool with `subagent_type="aether-scout"`)
+```
+You are {swarm_id}-WebResearcher, a 🔍🐜 Scout Ant.
+
+Research external solutions for: {problem description}
+
+Steps:
+1. Search for exact error message
+2. Find library/framework docs
+3. Check GitHub issues
+4. Find Stack Overflow answers
+
+Return ONLY this JSON:
+{"scout": "web-researcher", "confidence": 0.0-1.0, "finding": {"known_issue": true/false, "documentation_link": "...", "similar_issues": [], "community_solutions": []}, "suggested_fix": "..."}
+```
+
+Wait for all 4 scouts to complete.
+
+#### Step 6: Collect and Cross-Compare Findings
+
+As each scout returns, add their findings:
+```bash
+bash .aether/aether-utils.sh swarm-findings-add "{swarm_id}" "{scout_type}" "{confidence}" '{finding_json}'
+```
+
+Display each scout's report as they complete:
+```
+🏛️ Archaeologist [{confidence}]
+   {summary of finding}
+
+🔍 PatternHunter [{confidence}]
+   {summary of finding}
+
+💥 ErrorAnalyst [{confidence}]
+   {summary of finding}
+
+🌐 WebResearcher [{confidence}]
+   {summary of finding}
+```
+
+#### Step 7: Synthesize Solution
+
+Cross-compare all findings:
+1. Identify where scouts agree (high confidence)
+2. Note where scouts disagree (investigate further)
+3. Weight by confidence scores
+4. Prefer findings with concrete evidence
+
+Rank fix options:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+              S O L U T I O N   R A N K I N G
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#1 [0.85 confidence] {best solution}
+   Evidence: {supporting scouts}
+
+#2 [0.72 confidence] {alternative}
+   Evidence: {supporting scouts}
+
+#3 [0.45 confidence] {fallback}
+   Evidence: {limited support}
+```
+
+#### Step 8: Apply Best Fix
+
+Select the highest-confidence solution and apply it:
+
+**Command Resolution:** Before running verification, resolve `{build_command}` and `{test_command}` using this priority chain (stop at first match per command):
+1. **CLAUDE.md** — Check project CLAUDE.md (in your system context) for explicit build/test commands
+2. **CODEBASE.md** — Read `.aether/data/codebase.md` `## Commands` section
+3. **Fallback** — Use project manifest heuristics (e.g., `npm run build`/`npm test` for package.json)
+
+```
+🔧 Applying Fix #1...
+```
+
+Make the actual code changes using Edit/Write tools.
+
+After applying:
+```bash
+# Run verification
+{build_command} 2>&1 | tail -30
+{test_command} 2>&1 | tail -50
+```
+
+#### Step 9: Verify and Report
+
+**If verification passes:**
+```
+✅ FIX VERIFIED
+
+Build: PASS
+Tests: PASS
+
+🔥🐜🗡️🐜🔥 Swarm successful!
+
+The fix will be confirmed when you run:
+  /ant:continue
+```
+
+Inject learnings:
+- Add FOCUS for the pattern that worked (to constraints.json)
+- Add REDIRECT for the anti-pattern that caused the bug (to constraints.json)
+
+Set solution in swarm findings and log success:
+```bash
+bash .aether/aether-utils.sh swarm-solution-set "{swarm_id}" '{solution_json}'
+bash .aether/aether-utils.sh activity-log "SWARM_SUCCESS" "Queen" "Swarm {swarm_id} fixed: {brief description}"
+```
+
+**If verification fails:**
+```
+❌ FIX VERIFICATION FAILED
+
+Build: {status}
+Tests: {status}
+
+Attempting rollback...
+```
+
+Rollback and log failure:
+```bash
+bash .aether/aether-utils.sh autofix-rollback "{checkpoint_type}" "{checkpoint_ref}"
+bash .aether/aether-utils.sh activity-log "SWARM_FAILED" "Queen" "Swarm {swarm_id} fix failed verification"
+```
+
+Track attempt count. If this is the 3rd failure on the same issue:
+```
+⚠️ ARCHITECTURAL CONCERN
+
+This problem has resisted 3 swarm attempts.
+
+This suggests:
+  - Root cause may be architectural, not implementational
+  - Pattern may be fundamentally unsound
+  - Different approach needed
+
+Recommended:
+  - Review the codebase architecture
+  - Consider refactoring vs. patching
+  - Create a new phase for structural fix
+
+Swarm will not attempt further fixes on this issue.
+```
+
+#### Step 10: Cleanup
+
+Archive findings:
+```bash
+bash .aether/aether-utils.sh swarm-cleanup "{swarm_id}" --archive
+```
+
+Generate the state-based Next Up block:
+```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"
+```