aether-colony 5.3.1 → 5.3.3

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

@@ -1,286 +0,0 @@
-<!-- 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/.aether/commands/claude/status.md

@@ -1,410 +0,0 @@
-<!-- Generated from .aether/commands/status.yaml - DO NOT EDIT DIRECTLY -->
----
-name: ant:status
-description: "📈🐜🏘️🐜📈 Show colony status at a glance"
----
-
-You are the **Queen**. Show colony status.
-
-## Instructions
-
-### Step 0: Version Check (Non-blocking)
-
-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.
-
-### Step 1: Read State + Version Check
-
-Read `.aether/data/COLONY_STATE.json`.
-
-If file missing or `goal: null`:
-```
-No colony initialized. Run /ant:init first.
-```
-Stop here.
-
-**Auto-upgrade old state:**
-If `version` field is missing, "1.0", or "2.0":
-1. Preserve: `goal`, `state`, `current_phase`, `plan.phases` (keep phase structure)
-2. Write upgraded state:
-```json
-{
-  "version": "3.0",
-  "goal": "<preserved>",
-  "state": "<preserved or 'READY'>",
-  "current_phase": <preserved or 0>,
-  "session_id": "migrated_<timestamp>",
-  "initialized_at": "<preserved or now>",
-  "build_started_at": null,
-  "plan": {
-    "generated_at": "<preserved or null>",
-    "confidence": null,
-    "phases": <preserved or []>
-  },
-  "memory": { "phase_learnings": [], "decisions": [], "instincts": [] },
-  "errors": { "records": [], "flagged_patterns": [] },
-  "events": ["<now>|state_upgraded|system|Auto-upgraded from v<old> to v3.0"]
-}
-```
-3. Output: `State auto-upgraded to v3.0`
-4. Continue with command.
-
-### Step 1.5: Load State and Show Resumption Context
-
-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
-2. Get phase name from plan.phases[current_phase - 1].name (or "(unnamed)")
-3. Get last event timestamp from events array (last element)
-4. Display extended resumption context:
-   ```
-   🔄 Resuming: Phase X - Name
-      Last activity: timestamp
-   ```
-
-5. Check for .aether/HANDOFF.md existence in the load-state output or via separate check
-6. If .aether/HANDOFF.md exists:
-   - Display: "Resuming from paused session"
-   - Read .aether/HANDOFF.md content for additional context
-   - Remove .aether/HANDOFF.md after displaying (cleanup)
-
-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 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, 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`
-- Phase name: `plan.phases[current_phase - 1].name` (if exists)
-
-**Task progress:**
-- If phases exist, count tasks in current phase
-- Completed: tasks with `status: "completed"`
-- Total: all tasks in current phase
-
-**Constraints:**
-Read `.aether/data/constraints.json` if exists:
-- Focus count: `focus.length`
-- Constraints count: `constraints.length`
-
-**Flags:**
-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`
-- High confidence (≥0.7): count where confidence >= 0.7
-- Top 3: sorted by confidence descending
-
-**Colony state:**
-- `state` field (IDLE, READY, EXECUTING, PLANNING)
-
-**Milestone:**
-- `milestone` field (First Mound, Open Chambers, Brood Stable, Ventilated Nest, Sealed Chambers, Crowned Anthill)
-- `milestone_updated_at` field (timestamp of last milestone change)
-
-### Step 2.6: Detect Milestone
-
-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
-- `version`: Computed version string
-- `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:
-
-```
-       .-.
-      (o o)  AETHER COLONY
-      | O |  Status Report
-       `-`
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-👑 Goal: <goal (truncated to 60 chars)>
-
-📍 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>
-```
-
-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:**
-```
-🧠 Colony Instincts:
-   [0.9] 🐜 testing: Always run tests before completion
-   [0.8] 🐜 architecture: Use composition over inheritance
-   [0.7] 🐜 debugging: Trace to root cause first
-```
-
-**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.
-```
-
-
-**Colony Vital Signs:**
-After the Memory Health table, run:
-```bash
-bash .aether/aether-utils.sh colony-vital-signs
-```
-
-Extract from JSON result:
-- build_velocity.phases_per_day and build_velocity.trend
-- error_rate.errors_per_day and error_rate.status
-- signal_health.active_count and signal_health.status
-- memory_pressure.instinct_count and memory_pressure.status
-- colony_age_hours
-- overall_health (0-100 score)
-
-Map overall_health score to a label:
-- 80-100: "Thriving"
-- 60-79: "Healthy"
-- 40-59: "Stable"
-- 20-39: "Struggling"
-- 0-19: "Critical"
-
-Display:
-```
-💓 Colony Vital Signs
-┌─────────────────┬────────────┬─────────────────────────────┐
-│ Vital Sign      │ Value      │ Status                      │
-├─────────────────┼────────────┼─────────────────────────────┤
-│ Build Velocity  │ {phases_per_day}/d  │ {trend}            │
-│ Error Rate      │ {errors_per_day}/d  │ {error_status}     │
-│ Signal Health   │ {active_count}      │ {signal_status}    │
-│ Memory Pressure │ {instinct_count}    │ {memory_status}    │
-│ Colony Age      │ {colony_age_hours}h │                    │
-├─────────────────┼────────────┼─────────────────────────────┤
-│ Overall Health  │ {overall_health}%   │ {health_label}     │
-└─────────────────┴────────────┴─────────────────────────────┘
-```
-
-If the command fails or returns no data, display:
-```
-💓 Colony Vital Signs: No data available
-```
-
-
-
-**Data Safety:**
-After the Colony Vital Signs panel, run:
-```bash
-bash .aether/aether-utils.sh data-safety-stats
-```
-
-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
-```
-
-
-**Edge cases:**
-- 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).