aether-colony 3.1.17 → 5.1.0

package/.claude/commands/ant/skill-create.md

@@ -0,0 +1,286 @@
+<!-- Generated from .aether/commands/skill-create.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:skill-create
+description: "Create a custom domain skill using Oracle mini-research and a guided wizard"
+---
+
+You are the **Builder**. Create a custom domain skill by researching best practices and guiding the user through a wizard.
+
+The user's input is: `$ARGUMENTS`
+
+## Instructions
+
+### Step 0: Parse Arguments
+
+Extract the topic from `$ARGUMENTS`.
+
+If `$ARGUMENTS` is empty, output:
+
+```
+Skill Creator — Usage
+
+  /ant:skill-create "topic"
+
+  Examples:
+    /ant:skill-create "kubernetes"
+    /ant:skill-create "fastapi"
+    /ant:skill-create "terraform"
+
+  This will research the topic, ask a few questions, and generate
+  a custom SKILL.md in ~/.aether/skills/domain/
+```
+
+Stop here.
+
+Set `TOPIC` to the value of `$ARGUMENTS` (strip surrounding quotes).
+Derive `SKILL_NAME` by lowercasing `TOPIC`, replacing spaces with hyphens, and removing any non-alphanumeric/hyphen characters.
+
+Proceed to Step 1.
+
+---
+
+### Step 1: Oracle Mini-Research (5 iterations)
+
+Run a focused mini-research session on the topic. This is a self-contained research cycle -- it does not require an existing Oracle session.
+
+**1a. Web search for best practices**
+
+Use WebSearch to search for:
+- `"$TOPIC best practices 2025"`
+- `"$TOPIC common mistakes to avoid"`
+- `"$TOPIC project structure conventions"`
+
+Collect the top findings from each search (titles, key points, URLs).
+
+**1b. Codebase scan for existing usage**
+
+Use Grep and Glob to scan the current repository for patterns related to the topic:
+- Search for imports, config files, or dependencies matching `TOPIC`
+- Note any existing conventions or patterns in the codebase
+
+**1c. Compile findings into a research summary**
+
+After 5 iterations of searching and reading (web search results, codebase patterns), compile a structured summary:
+
+```
+Research Summary: $TOPIC
+
+Key Best Practices:
+  1. ...
+  2. ...
+  3. ...
+
+Common Pitfalls:
+  1. ...
+  2. ...
+
+Project Structure Conventions:
+  - ...
+
+Codebase Observations:
+  - (what was found in the current repo, if anything)
+
+Sources:
+  - ...
+```
+
+Display this summary to the user before proceeding.
+
+---
+
+### Step 2: Wizard Questions
+
+Use AskUserQuestion to guide the user through skill customization. Ask each question one at a time.
+
+**Question 1: Focus Area**
+
+Based on the Oracle research findings, identify 2-4 distinct aspects of the topic. Present them as options:
+
+```
+What aspect of $TOPIC should this skill focus on?
+```
+
+Options (dynamically generated from research, for example):
+1. **Core patterns and architecture** -- Fundamental design patterns and project structure
+2. **Performance and optimization** -- Speed, caching, resource management
+3. **Testing and quality** -- Test strategies, coverage, CI/CD integration
+4. **Comprehensive guide** -- Cover all major aspects in a single skill
+
+(Adapt the options based on what the research actually found. Always include a "comprehensive" option as the last choice.)
+
+**Question 2: Experience Level**
+
+```
+What experience level should this skill target?
+```
+
+Options:
+1. **Beginner** -- Explain fundamentals, include examples, avoid advanced patterns
+2. **Intermediate** -- Assume basics, focus on best practices and common patterns
+3. **Advanced** -- Expert-level patterns, performance tuning, edge cases
+
+**Question 3: Custom Rules or Constraints**
+
+```
+Any specific rules or constraints to include? (e.g., "always use TypeScript", "prefer composition over inheritance", "no classes")
+```
+
+Options:
+1. **No specific rules** -- Use standard best practices from the research
+2. **Yes, I have rules** -- I want to add custom constraints
+
+If the user selects option 2, ask a follow-up AskUserQuestion with free text:
+
+```
+Enter your rules or constraints (free text):
+```
+
+Capture the user's custom rules for inclusion in the skill.
+
+---
+
+### Step 3: Generate SKILL.md
+
+Based on the research findings and wizard answers, generate a complete skill file.
+
+**3a. Determine frontmatter values**
+
+- `name`: Use `SKILL_NAME` (the sanitized, lowercased topic)
+- `description`: Generate a concise description like "Use when the project uses $TOPIC" or "Best practices for $TOPIC development"
+- `type: domain`
+- `domains`: Infer 2-4 relevant domain tags from the research (e.g., `[frontend, components]` for React, `[backend, api]` for FastAPI)
+- `agent_roles: [builder]`
+- `detect_files`: Infer file patterns that indicate this technology is in use (e.g., `["*.py", "requirements.txt"]` for Python frameworks, `["Dockerfile", "docker-compose.yml"]` for Docker)
+- `detect_packages`: Infer package names that indicate this technology (e.g., `["fastapi"]`, `["terraform"]`)
+- `priority: normal`
+- `version: "1.0"`
+
+**3b. Generate the body content**
+
+Write a comprehensive best-practices guide structured as follows:
+
+```markdown
+# $TOPIC Best Practices
+
+## [Aspect heading based on focus area]
+
+[2-3 paragraphs of actionable guidance drawn from Oracle research]
+[Adapt depth and complexity to the selected experience level]
+
+## [Next aspect heading]
+
+[More guidance...]
+
+## Common Pitfalls
+
+[List of things to avoid, drawn from research]
+
+## [Additional sections as appropriate for the topic]
+
+[Custom rules or constraints from wizard Question 3, if any, integrated naturally into the guide]
+```
+
+Guidelines for body content:
+- Write in the same style as existing skills (direct, actionable, no fluff)
+- Reference the React SKILL.md at `.aether/skills/domain/react/SKILL.md` for tone and structure
+- Beginner level: include more explanation and examples
+- Intermediate level: focus on patterns and best practices
+- Advanced level: include edge cases, performance tuning, and expert techniques
+- If the user provided custom rules, weave them into the relevant sections rather than listing them separately
+- Keep total body length between 30-80 lines (matching existing skills)
+
+**3c. Assemble the full SKILL.md content**
+
+Combine the frontmatter and body into a single file:
+
+```markdown
+---
+name: {SKILL_NAME}
+description: {description}
+type: domain
+domains: [{domain1}, {domain2}]
+agent_roles: [builder]
+detect_files: ["{pattern1}", "{pattern2}"]
+detect_packages: ["{package1}"]
+priority: normal
+version: "1.0"
+---
+
+{body content}
+```
+
+---
+
+### Step 4: Write and Verify
+
+**4a. Create the skill directory and write the file**
+
+Run using the Bash tool with description "Creating skill directory...":
+
+```bash
+mkdir -p ~/.aether/skills/domain/{SKILL_NAME}
+```
+
+Use the Write tool to create `~/.aether/skills/domain/{SKILL_NAME}/SKILL.md` with the assembled content.
+
+**4b. Verify frontmatter parses correctly**
+
+Run using the Bash tool with description "Verifying skill frontmatter...":
+
+```bash
+bash .aether/aether-utils.sh skill-parse-frontmatter ~/.aether/skills/domain/{SKILL_NAME}/SKILL.md
+```
+
+Check the output. If the result contains `"ok": true` (or the parsed JSON shows the correct name and type), the skill is valid. If parsing fails, fix the frontmatter and retry once.
+
+**4c. Rebuild skill cache**
+
+Run using the Bash tool with description "Rebuilding skill cache...":
+
+```bash
+bash .aether/aether-utils.sh skill-cache-rebuild
+```
+
+**4d. Show the result**
+
+Display the generated skill to the user:
+
+```
+Skill Created: {SKILL_NAME}
+
+  Location:  ~/.aether/skills/domain/{SKILL_NAME}/SKILL.md
+  Type:      domain
+  Domains:   {domains list}
+  Detects:   {detect_files and detect_packages}
+  Level:     {experience level}
+```
+
+Then show the full content of the SKILL.md file.
+
+**4e. Offer adjustments**
+
+Use AskUserQuestion to ask:
+
+```
+Happy with this skill, or want to adjust anything?
+```
+
+Options:
+1. **Looks good** -- Keep it as-is
+2. **Adjust content** -- I want to change some of the guidance
+3. **Regenerate** -- Start over with different options
+
+If the user selects option 2, ask what they want to change, make the edits, re-write the file, and re-run `skill-parse-frontmatter` and `skill-cache-rebuild`.
+
+If the user selects option 3, go back to Step 2.
+
+If the user selects option 1, output:
+
+```
+Skill "{SKILL_NAME}" is ready. It will automatically activate in projects
+that match its detection patterns (files: {detect_files}, packages: {detect_packages}).
+
+You can also view all installed skills with: /ant:skill-list
+```
+
+Stop here.

package/.claude/commands/ant/status.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/status.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:status
 description: "📈🐜🏘️🐜📈 Show colony status at a glance"
@@ -9,7 +10,7 @@ You are the **Queen**. Show colony status.
 
 ### Step 0: Version Check (Non-blocking)
 
-Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
+Run using the Bash tool with description "Checking colony version...": `bash .aether/aether-utils.sh version-check-cached 2>/dev/null || true`
 
 If the command succeeds and the JSON result contains a non-empty string, display it as a one-line notice. Proceed regardless of outcome.
 
@@ -51,7 +52,7 @@ If `version` field is missing, "1.0", or "2.0":
 
 ### Step 1.5: Load State and Show Resumption Context
 
-Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+Run using the Bash tool with description "Loading colony state...": `bash .aether/aether-utils.sh load-state`
 
 If successful and goal is not null:
 1. Extract current_phase from state
@@ -69,29 +70,72 @@ If successful and goal is not null:
    - Read .aether/HANDOFF.md content for additional context
    - Remove .aether/HANDOFF.md after displaying (cleanup)
 
-Run: `bash .aether/aether-utils.sh unload-state` to release lock.
+Run using the Bash tool with description "Releasing colony lock...": `bash .aether/aether-utils.sh unload-state` to release lock.
 
 ### Step 2: Compute Summary
 
 From state, extract:
 
+### Step 2.4: Survey Freshness (Advisory)
+
+Run using the Bash tool with description "Checking survey freshness...":
+```bash
+survey_docs=$(ls -1 .aether/data/survey/*.md 2>/dev/null | wc -l | tr -d ' ')
+survey_latest=$(ls -t .aether/data/survey/*.md 2>/dev/null | head -1)
+if [[ -n "$survey_latest" ]]; then
+  now_epoch=$(date +%s)
+  modified_epoch=$(stat -f %m "$survey_latest" 2>/dev/null || stat -c %Y "$survey_latest" 2>/dev/null || echo 0)
+  survey_age_days=$(( (now_epoch - modified_epoch) / 86400 ))
+else
+  survey_age_days=-1
+fi
+echo "survey_docs=$survey_docs"
+echo "survey_age_days=$survey_age_days"
+```
+
+Interpretation:
+- If `survey_docs == 0`: `survey_status = "missing"`
+- If `survey_age_days > 14`: `survey_status = "stale"`
+- Otherwise: `survey_status = "fresh"`
+
 ### Step 2.5: Gather Dream Information
 
-Run using Bash tool: `ls -1 .aether/dreams/*.md 2>/dev/null | wc -l`
+Run using the Bash tool with description "Counting dream entries...": `ls -1 .aether/dreams/*.md 2>/dev/null | wc -l`
 
 Capture:
 - Dream count: number of .md files in .aether/dreams/
 - Latest dream: most recent file by name (files are timestamped: YYYY-MM-DD-HHMM.md)
 
-To get latest dream timestamp:
+To get latest dream timestamp, Run using the Bash tool with description "Finding latest dream...":
 ```bash
 ls -1 .aether/dreams/*.md 2>/dev/null | sort | tail -1 | sed 's/.*\/\([0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}\)-\([0-9]\{4\}\).*/\1 \2/'
 ```
 
 Format the timestamp as: YYYY-MM-DD HH:MM
 
+
+### Step 2.5.5: Colony Depth
+
+Run using the Bash tool with description "Reading colony depth...":
+```bash
+depth_result=$(bash .aether/aether-utils.sh colony-depth get 2>/dev/null || echo '{"ok":true,"result":{"depth":"standard","source":"default"}}')
+colony_depth=$(echo "$depth_result" | jq -r '.result.depth // "standard"')
+depth_source=$(echo "$depth_result" | jq -r '.result.source // "default"')
+echo "colony_depth=$colony_depth"
+echo "depth_source=$depth_source"
+```
+
+Store `colony_depth` and `depth_source` for the dashboard display.
+
+Depth label mapping:
+- light -> "Builder only (fastest)"
+- standard -> "Builder + Scout (balanced)"
+- deep -> "Builder + Scout + Oracle (thorough)"
+- full -> "All agents (most thorough)"
+
 From state, extract:
 
+
 **Phase info:**
 - Current phase number: `current_phase`
 - Total phases: `plan.phases.length`
@@ -108,12 +152,21 @@ Read `.aether/data/constraints.json` if exists:
 - Constraints count: `constraints.length`
 
 **Flags:**
-Run: `bash .aether/aether-utils.sh flag-check-blockers`
+Run using the Bash tool with description "Checking for blockers...": `bash .aether/aether-utils.sh flag-check-blockers`
 Extract:
 - Blockers count (critical, block advancement)
 - Issues count (high, warnings)
 - Notes count (low, informational)
 
+**Escalation state:**
+Count escalated flags by checking for blocker flags with source "escalation":
+
+Run using the Bash tool with description "Checking escalation state...":
+```bash
+escalated_count=$(bash .aether/aether-utils.sh flag-list --type blocker 2>/dev/null | jq '[.result.flags[] | select(.source == "escalation")] | length' 2>/dev/null || echo "0")
+echo "escalated_count=$escalated_count"
+```
+
 **Instincts:**
 From `memory.instincts`:
 - Total count: `instincts.length`
@@ -129,7 +182,7 @@ From `memory.instincts`:
 
 ### Step 2.6: Detect Milestone
 
-Run using Bash tool: `bash .aether/aether-utils.sh milestone-detect`
+Run using the Bash tool with description "Detecting colony milestone...": `bash .aether/aether-utils.sh milestone-detect`
 
 Extract from JSON result:
 - `milestone`: Current milestone name
@@ -137,6 +190,54 @@ Extract from JSON result:
 - `phases_completed`: Number of completed phases
 - `total_phases`: Total phases in plan
 
+### Step 2.8: Load Memory Health Metrics
+
+Run using the Bash tool with description "Loading memory health metrics...":
+```bash
+bash .aether/aether-utils.sh memory-metrics
+```
+
+Extract from JSON result:
+- wisdom.total
+- pending.total
+- recent_failures.count
+- last_activity.queen_md_updated
+- last_activity.learning_captured
+
+Format timestamps for display (YYYY-MM-DD HH:MM).
+
+### Step 2.7: Generate Progress Bars
+
+Calculate progress metrics and generate visual bars.
+
+Run using the Bash tool with description "Computing phase progress...":
+```bash
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+
+# Calculate task progress in current phase
+if [[ "$current_phase" -gt 0 && "$current_phase" -le "$total_phases" ]]; then
+  phase_idx=$((current_phase - 1))
+  tasks_completed=$(jq -r ".plan.phases[$phase_idx].tasks // [] | map(select(.status == \"completed\")) | length" .aether/data/COLONY_STATE.json)
+  tasks_total=$(jq -r ".plan.phases[$phase_idx].tasks // [] | length" .aether/data/COLONY_STATE.json)
+  phase_name=$(jq -r ".plan.phases[$phase_idx].name // \"Unnamed\"" .aether/data/COLONY_STATE.json)
+else
+  tasks_completed=0
+  tasks_total=0
+  phase_name="No plan created"
+fi
+
+# Generate progress bars
+phase_bar=$(bash .aether/aether-utils.sh generate-progress-bar "$current_phase" "$total_phases" 20)
+task_bar=$(bash .aether/aether-utils.sh generate-progress-bar "$tasks_completed" "$tasks_total" 20)
+
+echo "phase_bar=$phase_bar"
+echo "task_bar=$task_bar"
+echo "phase_name=$phase_name"
+```
+
+Store `phase_bar`, `task_bar`, and `phase_name` values for display in Step 3.
+
 ### Step 3: Display
 
 Output format:
@@ -146,30 +247,40 @@ Output format:
       (o o)  AETHER COLONY
       | O |  Status Report
        `-`
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 👑 Goal: <goal (truncated to 60 chars)>
 
-📍 Phase <N>/<M>: <phase name>
-   Tasks: <completed>/<total> complete
+📍 Progress
+   Phase: [████████░░░░░░░░░░░░] <N>/<M> phases
+   Tasks: [████████████████░░░░] <completed>/<total> tasks in Phase <N>
 
 🎯 Focus: <focus_count> areas | 🚫 Avoid: <constraints_count> patterns
 🧠 Instincts: <total> learned (<high_confidence> strong)
 🚩 Flags: <blockers> blockers | <issues> issues | <notes> notes
+{if escalated_count > 0:}
+⚠️  Escalated: {escalated_count} task(s) awaiting your decision
+{end if}
 🏆 Milestone: <milestone> (<version>)
+
+🔬 Depth: {colony_depth} — {label}{if depth_source == "default": " (default)"}
+
 💭 Dreams: <dream_count> recorded (latest: <latest_dream>)
+🗺️ Survey: <survey_docs> docs (<survey_age_days>d old, <fresh|stale|missing>)
+
+📚 Memory Health
+┌─────────────────┬────────┬─────────────────────────────┐
+│ Metric          │ Count  │ Last Updated                │
+├─────────────────┼────────┼─────────────────────────────┤
+│ Wisdom Entries  │ {wisdom_total:>6} │ {queen_updated}             │
+│ Pending Promos  │ {pending_total:>6} │ {learning_updated}          │
+│ Recent Failures │ {failures_count:>6} │ {last_failure}              │
+└─────────────────┴────────┴─────────────────────────────┘
 
 State: <state>
-Next:  <suggested_command>   <phase_context>
 ```
 
-**Phase context for Next line:** Include the phase name inline with the suggestion:
-- READY → `Next:  /ant:build 3   Phase 3: Add Authentication`
-- EXECUTING → `Next:  /ant:continue   Phase 3: Add Authentication`
-- PLANNING → `Next:  /ant:plan`
-- IDLE → `Next:  /ant:init`
-
-Look up the phase name from `plan.phases[current_phase].name` and append it.
+Use the `phase_bar` and `task_bar` values computed in Step 2.7 for the actual bar characters and counts.
 
 **If instincts exist, also show top 3:**
 ```
@@ -179,23 +290,77 @@ Look up the phase name from `plan.phases[current_phase].name` and append it.
    [0.7] 🐜 debugging: Trace to root cause first
 ```
 
-**Suggested command logic (use actual values, not templates):**
+**Dream display:**
+- If no dreams exist: `💭 Dreams: None recorded`
+- If dreams exist: `💭 Dreams: <count> recorded (latest: YYYY-MM-DD HH:MM)`
+
+**Memory Health display:**
+- If memory-metrics returns empty/null values, show:
+```
+📚 Memory Health
+   No memory data available. Colony wisdom will accumulate as you complete phases.
+```
 
-Calculate `next_phase = current_phase + 1` from state.
 
-Generate the suggested command based on colony state:
-- IDLE -> `/ant:init`
-- READY -> `/ant:build {next_phase}` (e.g., if current_phase is 2, output `/ant:build 3`)
-- EXECUTING -> `/ant:continue`
-- PLANNING -> `/ant:plan`
+**Data Safety:**
+After the Memory Health table, run:
+```bash
+bash .aether/aether-utils.sh data-safety-stats
+```
 
-The output must be a copy-pasteable command with real numbers, not placeholders.
+If the result contains non-zero counts, display:
+```
+🛡️ Data Safety
+  Stale locks cleaned: {stale_locks_cleaned}
+  JSON validation rejects: {json_validation_rejects}
+```
+
+If all counts are 0 or the subcommand returns no data, display:
+```
+🛡️ Data Safety: No issues detected
+```
+
+**Pheromone Summary:**
+After the Data Safety section, run:
+```bash
+bash .aether/aether-utils.sh pheromone-count
+```
+
+Display:
+```
+🎯 Active Pheromones
+┌────────────┬───────┬──────────────────────────────────┐
+│ Type       │ Count │ Strongest Signal                 │
+├────────────┼───────┼──────────────────────────────────┤
+│ 🎯 FOCUS   │ {n}   │ {strongest_focus or "none"}      │
+│ 🚫 REDIRECT│ {n}   │ {strongest_redirect or "none"}   │
+│ 💬 FEEDBACK│ {n}   │ {strongest_feedback or "none"}   │
+└────────────┴───────┴──────────────────────────────────┘
+
+Run /ant:pheromones for full details
+```
+
+If all counts are 0:
+```
+🎯 Active Pheromones: None
+   Use /ant:focus, /ant:redirect, or /ant:feedback to inject signals
+```
 
-**Dream display:**
-- If no dreams exist: `💭 Dreams: None recorded`
-- If dreams exist: `💭 Dreams: <count> recorded (latest: YYYY-MM-DD HH:MM)`
 
 **Edge cases:**
-- No phases yet: "Phase 0/0: No plan created"
-- No tasks in phase: "Tasks: 0/0 complete"
+- No phases yet: show `[░░░░░░░░░░░░░░░░░░░░] 0/0 phases`
+- No tasks in phase: show `[░░░░░░░░░░░░░░░░░░░░] 0/0 tasks in Phase 0`
 - No constraints file: "Constraints: 0 focus, 0 avoid"
+
+**At the end of the output, generate the Next Up block:**
+
+Run using the Bash tool with description "Generating next steps...":
+```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"
+```
+
+This auto-generates state-based recommendations (IDLE → init, READY → build, EXECUTING → continue, PLANNING → plan).