aether-colony 5.0.0 → 5.1.0

package/README.md

@@ -1,386 +1,234 @@
-```
-     _    _____ _____ _   _ _____ ____
-    / \  | ____|_   _| | | | ____|  _ \
-   / _ \ |  _|   | | | |_| |  _| | |_) |
-  / ___ \| |___  | | |  _  | |___|  _ <
- /_/   \_\_____| |_| |_| |_|_____|_| \_\
-```
-
 <div align="center">
 
-  **22 specialized agents that spawn, coordinate, and self-organize.**
+# 🐜 Aether Colony
 
-  ➡️ Click **Use this template** (top-right) to create your own Aether repo in 30 seconds.
+**Multi-agent AI development for Claude Code and OpenCode**
 
-  *Inspired by [glittercowboy's GSD system](https://github.com/glittercowboy/gsd)*
+[![npm version](https://img.shields.io/npm/v/aether-colony.svg?style=flat-square)](https://www.npmjs.com/package/aether-colony)
+[![npm downloads](https://img.shields.io/npm/dw/aether-colony.svg?style=flat-square)](https://www.npmjs.com/package/aether-colony)
+[![License: MIT](https://img.shields.io/github/license/calcosmic/Aether.svg?style=flat-square)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/calcosmic/Aether.svg?style=flat-square)](https://github.com/calcosmic/Aether/stargazers)
 
-  [![npm version](https://img.shields.io/npm/v/aether-colony.svg)](https://www.npmjs.com/package/aether-colony)
-  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Spawn a colony of 24 AI specialists that self-organize around your goal using pheromone signals.
+1,000+ weekly installs.
 
-  **v5.0.0** — Worker Emergence (22 real Claude Code agents)
-</div>
+*The whole is greater than the sum of its ants.*
 
----
-
-> *"The whole is greater than the sum of its parts."* — Aristotle
-
----
+```bash
+npm install -g aether-colony
+```
 
-## What Is Aether?
+</div>
 
-Aether brings **ant colony intelligence** to Claude Code. Instead of one agent doing everything sequentially, you get a colony of specialists that self-organize around your goal.
+<p align="center">
+  <img src="./AetherAnts.png" alt="Aether Colony" width="640" />
+</p>
 
 ```
-👑 Queen (you)
-   │
-   ▼ pheromone signals
-   │
-🐜 Workers spawn Workers (max depth 3)
-   │
-   ├── 🔨 Builders — implement code
-   ├── 👁️ Watchers — verify & test
-   ├── 🔍 Scouts — research docs
-   ├── 🗺️ Colonizers — explore codebases
-   ├── 📋 Route-setters — plan phases
-   ├── 🏗️ Architects — extract patterns
-   ├── 🏺 Archaeologists — excavate git history
-   ├── 🔮 Oracles — deep research (RALF pattern)
-   └── 🎲 Chaos Ants — resilience testing
+         👑 Queen (you)
+          │
+          │  set the goal, steer with pheromone signals
+          ▼
+    ┌─────────────────────────────────────────┐
+    │         Colony self-organizes            │
+    │                                         │
+    │  🔨 Builders      write code (TDD)      │
+    │  👁️ Watchers      verify & test          │
+    │  🔍 Scouts        research first         │
+    │  🐛 Trackers      investigate bugs       │
+    │  🗺️ Colonizers    explore codebases      │
+    │  📋 Route-setters plan phases            │
+    │  🏺 Archaeologists excavate git history  │
+    │  🎲 Chaos Ants    resilience testing     │
+    │  📚 Keepers       preserve knowledge     │
+    │  🔮 Oracle        deep research          │
+    │  ...and 24 specialists total             │
+    └─────────────────────────────────────────┘
 ```
 
-When a Builder hits something complex, it spawns a Scout to research. When code is written, a Watcher spawns to verify. **The colony adapts to the problem.**
-
-### Key Features
+## 🐜 The Problem
 
-- **22 Claude Code Agents** — Real subagents, not definitions — `/ant:build` spawns a genuine `aether-builder`
-- **34 Slash Commands** — Lifecycle, research, coordination, and utility
-- **Real Agent Spawning** — Run `/ant:build 1` and a real builder spawns to write your code
-- **6-Phase Verification** — Build, types, lint, tests, security, diff
-- **Colony Memory** — Learnings and instincts persist across sessions
-- **Pheromone Signals** — Focus, Redirect, Feedback to steer the colony
-- **Pause/Resume** — Full state serialization for context breaks
-- **Oracle Deep Research** — 50+ iteration autonomous research loop
+AI coding assistants work sequentially — one agent does everything: research, code, test, review. When it hits something complex, it either guesses or asks you. There's no specialization, no parallel work, no memory across sessions.
 
----
+## 🐜 The Solution
 
-## Quick Start
+Aether brings **ant colony intelligence** to AI-assisted development. Instead of one AI doing everything, you get a colony of specialists that self-organize around your goal.
 
-### Prerequisites
+Workers spawn workers dynamically (max depth 3, max 10 per phase). When a Builder hits something complex, it spawns a Scout to research. When code is written, a Watcher spawns to verify. The colony adapts to the problem.
 
-- [Claude Code](https://claude.ai/code) (Anthropic's CLI)
-- Node.js >= 16
-- `jq` — `brew install jq` on macOS
+You steer the colony with **pheromone signals**, not micromanagement:
 
-### Installation
-
-```bash
-npm install -g aether-colony
+```
+/ant:focus "security"              # 🎯 "Pay attention here"
+/ant:redirect "no jQuery"          # 🚫 "Don't do this" (hard constraint)
+/ant:feedback "prefer composition" # 💬 "Adjust based on this"
 ```
 
-This installs 22 Claude Code agents to `~/.claude/agents/ant/` plus 34 slash commands.
-
-All runtime state, utilities, and worker specs live **repo-local** in `.aether/` — each project is self-contained.
-
-### Your First Colony
+The colony **remembers**. Wisdom, learnings, and instincts persist across sessions. The 🧠 Hive Brain shares knowledge across colonies on your machine.
 
-Open Claude Code in any repo:
+## 🚀 Quick Start
 
 ```bash
-/ant:init "Build a REST API with authentication"
-/ant:plan
-/ant:build 1
-/ant:continue
-```
+# Install globally
+npm install -g aether-colony
 
-That's it. The colony takes over from there.
+# In your project repo:
+/ant:lay-eggs            # 🥚 Set up Aether (one-time)
+/ant:init "Build X"      # 🌱 Start a colony with a goal
+/ant:plan                # 📋 Generate phased roadmap
+/ant:run                 # 🐜 Autopilot: build, verify, advance all phases
+/ant:seal                # 🏺 Done — archive the colony
+```
 
----
+That's it. Five commands from zero to shipped.
 
-## Command Reference
+## ✨ Key Features
 
-### Core Lifecycle
+- 🐜 **24 Specialized Agents** — Real subagents spawned via Task tool, from builders to archaeologists
+- ⚡ **44 Slash Commands** — Full lifecycle management across Claude Code and OpenCode
+- 🎯 **Pheromone System** — Guide the colony with FOCUS, REDIRECT, FEEDBACK signals
+- 🧠 **Colony Memory** — Learnings persist across sessions via QUEEN.md wisdom
+- 🌐 **Hive Brain** — Cross-colony wisdom sharing with domain-scoped retrieval
+- 📚 **Skills System** — 28 skills (10 colony + 18 domain) inject domain knowledge into workers
+- 🤖 **Autopilot** (`/ant:run`) — Automated build-verify-advance loop with smart pause conditions
+- ✅ **6-Phase Verification** — Build, types, lint, tests, security, diff gates before any phase advances
+- 🛡️ **Quality Gates** — Security (Gatekeeper), quality (Auditor), coverage (Probe), performance (Measurer)
+- 🔍 **Per-Phase Research** — Scouts investigate domain knowledge before task decomposition
+- 🔮 **Oracle Deep Research** — Autonomous research loop for complex investigations
+- 💾 **Pause/Resume** — Full state serialization for context breaks
 
-| Command | Description |
-|---------|-------------|
-| `/ant:init "goal"` | Initialize colony with mission |
-| `/ant:plan` | Generate phased roadmap |
-| `/ant:build N` | Execute phase N with worker waves |
-| `/ant:continue` | 6-phase verification, advance to next phase |
-| `/ant:pause-colony` | Save state for context break |
-| `/ant:resume-colony` | Restore from pause |
-| `/ant:seal` | Complete and archive colony |
-| `/ant:entomb` | Create chamber from completed colony |
-
-**Core Flow:**
-```
-/ant:init → /ant:plan → /ant:build 1 → /ant:continue → /ant:build 2 → ... → /ant:seal
-```
+## 📖 Commands
 
-### Research & Analysis
+<details>
+<summary><strong>🏗️ Core Lifecycle</strong></summary>
 
 | Command | Description |
 |---------|-------------|
-| `/ant:colonize` | 4 parallel scouts analyze your codebase |
-| `/ant:archaeology <path>` | Excavate git history for any file |
-| `/ant:oracle ["topic"]` | Deep research (50+ iteration loop) |
-| `/ant:chaos <target>` | Resilience testing, edge case probing |
-| `/ant:swarm ["problem"]` | 4 parallel scouts for stubborn bugs |
-| `/ant:dream` | Philosophical codebase wanderer |
-| `/ant:organize` | Codebase hygiene report |
-
-### Coordination
+| `/ant:lay-eggs` | 🥚 Set up Aether in this repo (one-time) |
+| `/ant:init "goal"` | 🌱 Initialize colony with mission |
+| `/ant:plan` | 📋 Generate phased roadmap with domain research |
+| `/ant:build N` | 🔨 Execute phase N with worker waves |
+| `/ant:continue` | ➡️ 6-phase verification, advance to next phase |
+| `/ant:run` | 🐜 Autopilot — build, verify, advance automatically |
+| `/ant:patrol` | 🔍 Pre-seal audit — verify work against plan |
+| `/ant:seal` | 🏺 Complete and archive colony |
+| `/ant:entomb` | ⚰️ Create chamber from completed colony |
+| `/ant:pause-colony` | 💾 Save state for context break |
+| `/ant:resume-colony` | 🚦 Restore from pause |
+
+</details>
+
+<details>
+<summary><strong>🎯 Pheromone Signals</strong></summary>
 
 | Command | Description |
 |---------|-------------|
-| `/ant:council` | Clarify intent via multi-choice questions |
-| `/ant:focus "area"` | FOCUS signal — guide attention |
-| `/ant:redirect "pattern"` | REDIRECT signal — hard constraint |
-| `/ant:feedback "msg"` | FEEDBACK signal — teach preferences |
+| `/ant:focus "area"` | 🎯 FOCUS — "Pay attention here" |
+| `/ant:redirect "pattern"` | 🚫 REDIRECT — "Don't do this" (hard constraint) |
+| `/ant:feedback "note"` | 💬 FEEDBACK — "Adjust based on this" |
+| `/ant:pheromones` | 📊 View active signals |
+| `/ant:export-signals` | 📤 Export signals to XML |
+| `/ant:import-signals` | 📥 Import signals from XML |
+
+</details>
 
-### Visibility
+<details>
+<summary><strong>🔬 Research & Analysis</strong></summary>
 
 | Command | Description |
 |---------|-------------|
-| `/ant:status` | Colony overview |
-| `/ant:watch` | Real-time swarm display |
-| `/ant:history` | Recent activity log |
-| `/ant:flags` | List blockers and issues |
-| `/ant:help` | Full command reference |
-
----
-
-## CLI Commands
-
-```bash
-# View version and status
-aether version
-
-# Update all registered repos
-aether update --all
-
-# Checkpoints (safe snapshots)
-aether checkpoint create "before refactor"
-aether checkpoint list
-aether checkpoint restore <id>
-
-# View telemetry
-aether telemetry
-
-# Context
-aether context        # Show context including nestmates
-aether nestmates      # List sibling colonies
-aether spawn-tree     # Display worker spawn tree
-```
-
----
-
-## The Castes
-
-Workers have distinct personalities and roles, organized by tier:
-
-### Core Workers
-
-| Caste | Role | Personality |
-|-------|------|-------------|
-| 👑 **Queen** | Orchestrates, spawns workers | Coordinating |
-| 🔨 **Builder** | Writes code, TDD-first | Pragmatic, direct |
-| 👁️ **Watcher** | Tests, validates | Vigilant, careful |
-| 🔍 **Scout** | Researches, discovers | Curious |
-
-### Orchestration
-
-| Caste | Role | Personality |
-|-------|------|-------------|
-| 📋 **Route-Setter** | Plans phases | Structured |
-| 🗺️ **Colonizer** | Explores codebases, maps structure | Exploratory |
-| 📊 **Surveyor** | Measures codebase metrics | Systematic |
-
-### Specialists
-
-| Caste | Role | Personality |
-|-------|------|-------------|
-| 📚 **Keeper** | Curates knowledge, patterns | Preserving |
-| 🐛 **Tracker** | Investigates bugs, root cause | Methodical |
-| 🧪 **Probe** | Generates tests | Thorough |
-| 🔄 **Weaver** | Refactors code | Transformative |
-| 👥 **Auditor** | Reviews code quality | Critical |
-
-### Niche
-
-| Caste | Role | Personality |
-|-------|------|-------------|
-| 📦 **Gatekeeper** | Dependency audits | Protective |
-| ♿ **Includer** | Accessibility audits | Inclusive |
-| ⚡ **Measurer** | Performance profiling | Precise |
-| 🎲 **Chaos** | Resilience testing | Adversarial |
-| 🏺 **Archaeologist** | Excavates git history | Investigative |
-| 🔌 **Ambassador** | Third-party APIs | Diplomatic |
-| 📝 **Chronicler** | Documentation | Recording |
-| 🔮 **Sage** | Deep research (RALF loop) | Analytical |
-
-Run `/ant:colonize` and 4 surveyor agents map your entire codebase. Run `/ant:build 1` and a real builder spawns.
-
----
-
-## Spawn Depth
-
-```
-👑 Queen (depth 0)
-└── 🔨 Builder-1 (depth 1) — can spawn 4 more
-    ├── 🔍 Scout-7 (depth 2) — can spawn 2 more
-    │   └── 🔍 Scout-12 (depth 3) — no more spawning
-    └── 👁️ Watcher-3 (depth 2)
-```
-
-- **Depth 1**: Up to 4 spawns
-- **Depth 2**: Up to 2 spawns (only if genuinely surprised)
-- **Depth 3**: Complete inline, no further spawning
-- **Global cap**: 10 workers per phase
-
----
+| `/ant:colonize` | 📊🗺️ 4 parallel scouts analyze your codebase |
+| `/ant:oracle "topic"` | 🔮 Deep research with autonomous loop |
+| `/ant:archaeology <path>` | 🏺 Excavate git history for any file |
+| `/ant:chaos <target>` | 🎲 Resilience testing, edge case probing |
+| `/ant:swarm "problem"` | 🔥 4 parallel scouts for stubborn bugs |
+| `/ant:dream` | 💭 Philosophical codebase wanderer |
+| `/ant:interpret` | 🔍 Grounds dreams in reality |
+| `/ant:organize` | 🧹 Codebase hygiene report |
 
-## 6-Phase Verification
+</details>
 
-Before any phase advances:
+<details>
+<summary><strong>👁️ Visibility & Status</strong></summary>
 
-| Gate | Check |
-|------|-------|
-| Build | Project compiles/bundles |
-| Types | Type checker passes |
-| Lint | Linter passes |
-| Tests | All tests pass (80%+ coverage target) |
-| Security | No exposed secrets or debug artifacts |
-| Diff | Review changes, no unintended modifications |
-
----
-
-## File Structure
-
-See [repo-structure.md](repo-structure.md) for a quick overview of all directories.
-
-```
-<your-repo>/.aether/              # Repo-local runtime
-    ├── workers.md                # Worker specs and spawn protocol
-    ├── aether-utils.sh           # Utility layer (80+ subcommands)
-    ├── model-profiles.yaml       # Model routing config
-    │
-    ├── docs/                     # Documentation
-    ├── utils/                    # Utility scripts
-    ├── oracle/                   # Oracle research
-    │
-    ├── data/                     # State (NEVER synced)
-    │   ├── COLONY_STATE.json     # Goal, plan, memory
-    │   ├── constraints.json      # Focus and redirects
-    │   └── spawn-tree.txt        # Worker hierarchy
-    │
-    ├── dreams/                   # Session notes (NEVER synced)
-    └── chambers/                 # Archived colonies
-```
-
----
-
-## Pheromone Signals
-
-| Signal | Command | Use When |
-|--------|---------|----------|
-| FOCUS | `/ant:focus "area"` | "Pay attention here" |
-| REDIRECT | `/ant:redirect "avoid"` | "Don't do this" (hard constraint) |
-| FEEDBACK | `/ant:feedback "note"` | "Adjust based on this" |
-
-- **Before builds**: FOCUS + REDIRECT to steer
-- **After builds**: FEEDBACK to adjust
-- **Hard constraints**: REDIRECT (will break)
-- **Gentle nudges**: FEEDBACK (preferences)
-
----
-
-## Typical Workflows
-
-### Starting a New Project
-
-```
-1. /ant:init "Build feature X"     # Set the goal
-2. /ant:colonize                    # Analyze existing code (optional)
-3. /ant:plan                        # Generate phases
-4. /ant:focus "security"            # Guide attention (optional)
-5. /ant:build 1                     # Execute phase 1
-6. /ant:continue                    # Verify, advance
-7. Repeat until done
-8. /ant:seal                        # Complete and archive
-```
-
-### Deep Research
-
-```
-/ant:oracle "research topic"    # Launch Oracle
-/ant:oracle status              # Check progress
-/ant:oracle stop                # Stop if needed
-# Read findings in .aether/oracle/discoveries/
-```
-
-### When Stuck
-
-```
-/ant:dream                      # Let the Dreamer observe
-/ant:swarm "bug description"    # 4 parallel scouts investigate
-/ant:archaeology src/module/    # Excavate why code exists
-/ant:chaos "auth flow"          # Test resilience
-```
-
----
-
-## Safety Features
-
-- **File Locking** — Prevents concurrent modification
-- **Atomic Writes** — Temp file + rename pattern
-- **Update Transactions** — Two-phase commit with rollback
-- **State Validation** — Schema validation before modifications
-- **Git Checkpoints** — Automatic commits before phases
-- **Checkpoint System** — Safe snapshots with `aether checkpoint`
-
----
-
-## Known Issues
-
-1. **Init may fail if `.aether/data/` doesn't exist** — Run `mkdir -p .aether/data` before `/ant:init` if you see "Error writing file".
-
-2. **Long commands can cause Claude to lose context** — Commands like `build.md` (1,000+ lines) may cause Claude to skip steps. Use `/ant:status` and `/ant:continue` to recover.
-
----
-
-## Installation & Updates
-
-```bash
-# Install globally
-npm install -g aether-colony
-
-# Verify install
-aether version
-ls ~/.claude/commands/ant/
-
-# Update all registered repos
-aether update --all
-
-# Update npm package
-npm update -g aether-colony
-```
-
----
-
-## Acknowledgments
-
-Inspired by **[glittercowboy](https://github.com/glittercowboy)** and the **[GSD system](https://github.com/glittercowboy/gsd)**. GSD showed what Claude Code could become with the right orchestration. Aether adds ant colony dynamics — pheromones, castes, nested spawning, and self-organizing workers.
-
----
-
-## License
-
-MIT — do whatever you want with it.
-
----
+| Command | Description |
+|---------|-------------|
+| `/ant:status` | 📈 Colony overview with memory health |
+| `/ant:memory-details` | 🧠 Wisdom, pending promotions, recent failures |
+| `/ant:watch` | 👁️ Real-time swarm display |
+| `/ant:history` | 📜 Recent activity log |
+| `/ant:flags` | 🚩 List blockers and issues |
+| `/ant:help` | 🐜 Full command reference |
 
-<div align="center">
+</details>
 
-*🐜 The colony is greater than the sum of its ants. 🐜*
+<details>
+<summary><strong>🔧 Coordination & Maintenance</strong></summary>
 
-</div>
+| Command | Description |
+|---------|-------------|
+| `/ant:council` | 📜 Clarify intent via multi-choice questions |
+| `/ant:flag "title"` | 🚩 Create project-specific flag |
+| `/ant:data-clean` | 🧹 Remove test artifacts from colony data |
+| `/ant:preferences` | ⚙️ Add or list user preferences |
+| `/ant:skill-create "topic"` | 🐜 Create custom domain skill |
+| `/ant:update` | 🔄 Update system files from hub |
+
+</details>
+
+## 🐜 The 24 Agents
+
+| Tier | Agent | Role |
+|------|-------|------|
+| 👑 **Core** | Builder | 🔨 Writes code, TDD-first |
+| 👑 **Core** | Watcher | 👁️ Tests, validates, quality gates |
+| 👑 **Core** | Scout | 🔍 Researches, discovers |
+| 🏛️ **Orchestration** | Queen | 👑 Orchestrates phases, spawns workers |
+| 🏛️ **Orchestration** | Route-Setter | 📋 Plans phases, breaks down goals |
+| 🏛️ **Orchestration** | Architect | 🏗️ Architecture design |
+| 🗺️ **Surveyor** | surveyor-nest | 📂 Maps directory structure |
+| 🗺️ **Surveyor** | surveyor-disciplines | 📏 Documents conventions |
+| 🗺️ **Surveyor** | surveyor-pathogens | 🦠 Identifies tech debt |
+| 🗺️ **Surveyor** | surveyor-provisions | 📦 Maps dependencies |
+| ⚡ **Specialist** | Keeper | 📚 Preserves knowledge |
+| ⚡ **Specialist** | Tracker | 🐛 Investigates bugs |
+| ⚡ **Specialist** | Probe | 🔬 Coverage analysis |
+| ⚡ **Specialist** | Weaver | 🧵 Refactoring specialist |
+| ⚡ **Specialist** | Auditor | ✅ Quality gate |
+| 🎯 **Niche** | Chaos | 🎲 Resilience testing |
+| 🎯 **Niche** | Archaeologist | 🏺 Excavates git history |
+| 🎯 **Niche** | Gatekeeper | 🛡️ Security gate |
+| 🎯 **Niche** | Includer | ♿ Accessibility audits |
+| 🎯 **Niche** | Measurer | ⏱️ Performance analysis |
+| 🎯 **Niche** | Sage | 🧙 Wisdom synthesis |
+| 🎯 **Niche** | Oracle | 🔮 Deep research |
+| 🎯 **Niche** | Ambassador | 🌐 External integrations |
+| 🎯 **Niche** | Chronicler | 📝 Documentation |
+
+## 🏗️ Architecture
+
+```
+.aether/                      # 🐜 Colony files (repo-local)
+├── aether-utils.sh           # ⚡ Dispatcher (~5,200 lines, ~150 subcommands)
+├── utils/                    # 🔧 ~29 modular scripts
+├── skills/                   # 📚 28 skills (10 colony + 18 domain)
+├── commands/                 # 📖 44 YAML command sources
+├── exchange/                 # 📤 XML exchange modules
+├── docs/                     # 📝 Documentation
+├── templates/                # 📋 12 templates
+└── data/                     # 💾 Colony state (local only)
+
+~/.aether/                    # 🌐 Hub (cross-colony, user-level)
+├── QUEEN.md                  # 👑 Wisdom + preferences
+├── hive/wisdom.json          # 🧠 Cross-colony wisdom (200 cap)
+└── registry.json             # 📊 All registered colonies
+```
+
+## 🔌 Works With
+
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — 44 slash commands + 24 agent definitions
+- **[OpenCode](https://github.com/opencode-ai/opencode)** — 44 slash commands + agent definitions
+
+## 📄 License
+
+MIT