aether-colony 3.1.4 → 3.1.15

package/.claude/commands/ant/chaos.md

@@ -60,6 +60,22 @@ Categories tested:
 
 ## Instructions
 
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+chaos_id="chaos-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$chaos_id"
+bash .aether/aether-utils.sh swarm-display-update "Chaos Ant" "chaos" "excavating" "Probing for weaknesses" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
 ### Step 1: Awaken — Load Context
 
 Read these files in parallel to understand the colony and codebase:
@@ -76,7 +92,7 @@ Read these files in parallel to understand the colony and codebase:
 
 **If no relevant files can be found for the target:**
 ```
-🎲 Chaos Ant cannot locate target: $ARGUMENTS
+🎲🐜 Chaos Ant cannot locate target: $ARGUMENTS
    Searched for matching files and modules but found nothing.
    Please provide a valid file path, module name, or feature description.
 ```
@@ -206,6 +222,12 @@ For each scenario, produce a finding in this format. Display each to the termina
 
 ### Step 5: Produce the Chaos Report
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Chaos Ant" "chaos" "completed" "Resilience test complete" "Colony" '{"read":8,"grep":4,"edit":0,"bash":3}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$chaos_id"
+```
+
 After all 5 scenarios, compile the structured report:
 
 ```

package/.claude/commands/ant/colonize.md

@@ -1,12 +1,40 @@
 ---
 name: ant:colonize
-description: "🔍🐜🗺️🐜🔍 Analyze codebase and prepare for colony work"
+description: "📊🐜🗺️🐜📊 Survey territory with 4 parallel scouts for comprehensive colony intelligence"
 ---
 
-You are the **Queen**. Perform initial codebase analysis.
+You are the **Queen**. Dispatch Surveyor Ants to map the territory.
+
+The arguments are: `$ARGUMENTS`
+
+**Parse arguments:**
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- If contains `--force` or `--force-resurvey`: set `force_resurvey = true`
+- Otherwise: set `visual_mode = true`, `force_resurvey = false`
 
 ## Instructions
 
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+colonize_id="colonize-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$colonize_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "dispatching" "Surveying territory" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
+Display header:
+```
+📊🐜🗺️🐜📊 ═══════════════════════════════════════════════
+         C O L O N I Z E  —  T e r r i t o r y  S u r v e y
+═══════════════════════════════════════════════ 📊🐜🗺️🐜📊
+
+Queen dispatching Surveyor Ants...
+```
+
 ### Step 1: Validate
 
 Read `.aether/data/COLONY_STATE.json`.
@@ -15,15 +43,15 @@ Read `.aether/data/COLONY_STATE.json`.
 1. Create `.aether/data/` directory if it does not exist.
 2. Write a minimal COLONY_STATE.json:
    `{"version": "3.0", "goal": null, "state": "IDLE", "current_phase": 0, "session_id": null, "initialized_at": null, "build_started_at": null, "plan": {"generated_at": null, "confidence": null, "phases": []}, "memory": {"phase_learnings": [], "decisions": [], "instincts": []}, "errors": {"records": [], "flagged_patterns": []}, "signals": [], "graveyards": [], "events": []}`
-3. Output: "No colony state found. Bootstrapping minimal state for codebase analysis."
+3. Output: "No colony state found. Bootstrapping minimal state for territory survey."
 
-**If the file exists:** continue (colonize works with or without a goal).
+**If the file exists:** continue.
 
 **If `plan.phases` is not empty:** output "Colony already has phases. Use /ant:continue.", stop.
 
-### Step 2: Surface Scan
+### Step 2: Quick Surface Scan (for session context)
 
-Use Glob to find key files (read up to 20 total).
+Use Glob to find key files (read up to 20 total) to provide context for the survey.
 
 **Package manifests:**
 - package.json, Cargo.toml, pyproject.toml, go.mod, Gemfile, pom.xml, build.gradle
@@ -37,107 +65,158 @@ Use Glob to find key files (read up to 20 total).
 **Config:**
 - tsconfig.json, .eslintrc.*, jest.config.*, vite.config.*, webpack.config.*
 
-Read found files. Extract:
-- Tech stack (language, framework, key dependencies)
+Read found files. Extract basic info:
+- Tech stack (language, framework)
 - Entry points (main files)
-- Key directories (src/, lib/, tests/, etc.)
-- File counts per top-level directory
+- Key directories
 
-### Step 2.5: Command Detection
+### Step 3: Dispatch Surveyor Ants (Parallel)
 
-Detect build, test, type-check, and lint commands from two sources. Track each command with its source attribution (`claude_md` or `heuristic`).
+Create the survey directory:
+```bash
+mkdir -p .aether/data/survey
+```
 
-**Source 1 — CLAUDE.md (priority):**
+#### Step 3.1: Check for Stale Survey Session
 
-Read `CLAUDE.md` in the project root. If it does not exist, skip to Source 2.
-Scan for commands under headings matching: `Commands`, `Scripts`, `Development`, `Build`, `Testing`, `Lint`, or similar.
-Also extract inline code blocks containing patterns like `npm`, `npx`, `yarn`, `pnpm`, `cargo`, `go`, `pytest`, `make`, `gradle`, `mvn`.
-For each command found, store: `{ label, command, source: "claude_md" }`.
+Before dispatching surveyors, check for existing survey files and capture session start time:
 
-**Source 2 — Heuristic from package manifests:**
+```bash
+SURVEY_START=$(date +%s)
 
-Using the manifests found in Step 2, infer commands with this table:
+# Check for stale survey files
+stale_check=$(bash .aether/aether-utils.sh session-verify-fresh --command survey "" "$SURVEY_START")
+has_stale=$(echo "$stale_check" | jq -r '.stale | length')
+has_fresh=$(echo "$stale_check" | jq -r '.fresh | length')
 
-| Manifest | Field/Pattern | Label | Command |
-|---|---|---|---|
-| package.json | `scripts.test` | test | `npm test` |
-| package.json | `scripts.build` | build | `npm run build` |
-| package.json | `scripts.lint` | lint | `npm run lint` |
-| package.json | `scripts.typecheck` or `scripts.type-check` | typecheck | `npm run typecheck` |
-| Cargo.toml | (exists) | test | `cargo test` |
-| Cargo.toml | (exists) | build | `cargo build` |
-| Cargo.toml | `clippy` in deps | lint | `cargo clippy` |
-| pyproject.toml | `[tool.pytest]` or pytest in deps | test | `pytest` |
-| pyproject.toml | `[tool.ruff]` or ruff in deps | lint | `ruff check .` |
-| pyproject.toml | `[tool.mypy]` or mypy in deps | typecheck | `mypy .` |
-| go.mod | (exists) | test | `go test ./...` |
-| go.mod | (exists) | build | `go build ./...` |
+if [[ "$has_stale" -gt 0 ]] || [[ "$has_fresh" -gt 0 ]]; then
+  # Found existing survey files
+  if [[ "$force_resurvey" == "true" ]]; then
+    bash .aether/aether-utils.sh session-clear --command survey
+    echo "Cleared existing survey files for fresh territory mapping"
+  else
+    echo "Found existing territory survey. Use --force-resurvey to remap."
+    # Continue - will use existing survey files
+  fi
+fi
+```
 
-For each inferred command, only store it if no command with the same label was already found from CLAUDE.md (CLAUDE.md wins per-label). Store as: `{ label, command, source: "heuristic" }`.
+Generate unique names for the 4 Surveyor Ants and log their dispatch:
+```bash
+bash .aether/aether-utils.sh generate-ant-name "surveyor"
+bash .aether/aether-utils.sh generate-ant-name "surveyor"
+bash .aether/aether-utils.sh generate-ant-name "surveyor"
+bash .aether/aether-utils.sh generate-ant-name "surveyor"
+```
 
-If neither source yields any commands, set the detected commands list to empty.
+Log the dispatch:
+```bash
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{provisions_name}" "Mapping provisions and trails"
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{nest_name}" "Mapping nest structure"
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{disciplines_name}" "Mapping disciplines and sentinels"
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{pathogens_name}" "Identifying pathogens"
+```
 
-### Step 3: Write CODEBASE.md
+**Spawn 4 Surveyor Ants in parallel using the Task tool:**
 
-Create `.planning/CODEBASE.md` (ensure `.planning/` exists first):
+Each Task should use `subagent_type="aether-surveyor-{focus}"`:
+1. `aether-surveyor-provisions` — Maps PROVISIONS.md and TRAILS.md
+2. `aether-surveyor-nest` — Maps BLUEPRINT.md and CHAMBERS.md
+3. `aether-surveyor-disciplines` — Maps DISCIPLINES.md and SENTINEL-PROTOCOLS.md
+4. `aether-surveyor-pathogens` — Maps PATHOGENS.md
 
-```markdown
-# Codebase Overview
+**Prompt for each surveyor:**
+```
+You are Surveyor Ant {name}. Explore this codebase and write your survey documents.
 
-**Stack:** <language> + <framework>
-**Entry:** <main entry points>
+Focus: {provisions|nest|disciplines|pathogens}
 
-**Structure:**
-- <dir>/ (<count> files)
-- ...
+The surface scan found:
+- Language: {language}
+- Framework: {framework}
+- Key directories: {dirs}
 
-**Key Dependencies:**
-- <dep1>: <purpose>
-- <dep2>: <purpose>
-- ...
+Write your documents to `.aether/data/survey/` following your agent template.
+Return only confirmation when complete — do not include document contents.
+```
 
-## Commands
-<for each detected command from Step 2.5>
-- **<label>**: `<command>` (<source: claude_md | heuristic>)
-<if no commands detected>
-No build system detected.
-</if>
+Collect confirmations from all 4 surveyors. Each should return:
+- Document name(s) written
+- Line count(s)
+- Brief status
+
+### Step 4: Verify Survey Completeness
+
+Check that all 7 documents were created:
+```bash
+ls .aether/data/survey/PROVISIONS.md 2>/dev/null && echo "PROVISIONS: OK" || echo "PROVISIONS: MISSING"
+ls .aether/data/survey/TRAILS.md 2>/dev/null && echo "TRAILS: OK" || echo "TRAILS: MISSING"
+ls .aether/data/survey/BLUEPRINT.md 2>/dev/null && echo "BLUEPRINT: OK" || echo "BLUEPRINT: MISSING"
+ls .aether/data/survey/CHAMBERS.md 2>/dev/null && echo "CHAMBERS: OK" || echo "CHAMBERS: MISSING"
+ls .aether/data/survey/DISCIPLINES.md 2>/dev/null && echo "DISCIPLINES: OK" || echo "DISCIPLINES: MISSING"
+ls .aether/data/survey/SENTINEL-PROTOCOLS.md 2>/dev/null && echo "SENTINEL: OK" || echo "SENTINEL: MISSING"
+ls .aether/data/survey/PATHOGENS.md 2>/dev/null && echo "PATHOGENS: OK" || echo "PATHOGENS: MISSING"
+```
 
-**Test Location:** <tests/ or __tests__/ or similar>
+If any documents are missing, note which ones in the output.
 
-**Notes:**
-- <any notable patterns or conventions observed>
-```
+#### Step 4.5: Verify Survey Files Are Fresh
+
+Verify that all survey files were created after the session start:
+```bash
+verify_result=$(bash .aether/aether-utils.sh session-verify-fresh --command survey "" "$SURVEY_START")
+fresh_count=$(echo "$verify_result" | jq -r '.fresh | length')
 
-Keep output under 50 lines. Focus on what's relevant to the colony goal (if set), or provide a general codebase overview.
+if [[ "$fresh_count" -lt 7 ]]; then
+  echo "Warning: Some survey files may be stale or missing"
+  echo "$verify_result" | jq -r '.stale[], .missing[]' | while read doc; do
+    echo "  - $doc"
+  done
+fi
+```
 
-### Step 4: Update State
+### Step 5: Update State
 
 Read `.aether/data/COLONY_STATE.json`. Update:
 - Set `state` to `"IDLE"` (ready for planning)
+- Set `territory_surveyed` to `"<ISO-8601 UTC>"`
 
 Write Event: Append to the `events` array as pipe-delimited string:
-`"<ISO-8601 UTC>|codebase_colonized|colonize|Codebase analyzed: <primary language/framework>"`
+`"<ISO-8601 UTC>|territory_surveyed|colonize|Territory surveyed: 7 documents"`
 
 If the `events` array exceeds 100 entries, remove the oldest entries to keep only 100.
 
 Write the updated COLONY_STATE.json.
 
-### Step 5: Confirm
+### Step 6: Confirm
 
 Output header:
 
 ```
-🔍🐜🗺️🐜🔍 ═══════════════════════════════════════════════════
-   C O D E B A S E   A N A L Y S I S
-═══════════════════════════════════════════════════ 🔍🐜🗺️🐜🔍
+📊🐜🗺️🐜📊 ═══════════════════════════════════════════════════
+   T E R R I T O R Y   S U R V E Y   C O M P L E T E
+═══════════════════════════════════════════════════ 📊🐜🗺️🐜📊
 ```
 
 Then output:
 
 ```
-Codebase analysis complete.
-See: .planning/CODEBASE.md
+🗺️ Colony territory has been surveyed.
+
+Survey Reports:
+  📦 PROVISIONS.md         — Tech stack & dependencies
+  🛤️  TRAILS.md             — External integrations
+  📐 BLUEPRINT.md          — Architecture patterns
+  🏠 CHAMBERS.md           — Directory structure
+  📜 DISCIPLINES.md        — Coding conventions
+  🛡️  SENTINEL-PROTOCOLS.md — Testing patterns
+  ⚠️  PATHOGENS.md          — Tech debt & concerns
+
+Location: .aether/data/survey/
+
+{If any docs missing:}
+⚠️  Missing: {list missing documents}
+{/if}
 
 Stack: <language> + <framework>
 Entry: <main entry point>
@@ -151,26 +230,7 @@ Next:
 
 {If goal is not null:}
 Next:
-  /ant:plan              Generate project plan
+  /ant:plan              Generate project plan (will load relevant survey docs)
   /ant:focus "<area>"    Inject focus before planning
   /ant:redirect "<pat>"  Inject constraint before planning
 ```
-
-### Step 5.5: Suggest Commands for CLAUDE.md
-
-Skip if all commands came from `claude_md` or none were detected. This is **non-blocking** -- do not edit CLAUDE.md automatically.
-
-For heuristic-sourced commands only, output:
-
-```
-💡 Detected commands not yet in CLAUDE.md. Consider adding:
-```
-
-Then a fenced code block the user can copy-paste into CLAUDE.md:
-
-```markdown
-## Commands
-- <label>: `<command>`
-```
-
-Then: `Paste the above into your project's CLAUDE.md to skip heuristic detection next time.`