aether-colony 1.1.8 → 1.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/.aether/rules/aether-colony.md +23 -13
  2. package/.claude/commands/ant/help.md +13 -4
  3. package/.claude/commands/ant/init.md +15 -46
  4. package/.claude/commands/ant/lay-eggs.md +156 -151
  5. package/.claude/commands/ant/seal.md +26 -0
  6. package/.opencode/commands/ant/help.md +14 -4
  7. package/.opencode/commands/ant/init.md +16 -47
  8. package/.opencode/commands/ant/lay-eggs.md +159 -90
  9. package/.opencode/commands/ant/seal.md +26 -0
  10. package/CHANGELOG.md +7 -0
  11. package/package.json +1 -1
package/.aether/rules/aether-colony.md CHANGED
@@ -19,10 +19,11 @@ This only applies to genuinely new conversations, not after /clear.
19
19
 
20
20
  ## Available Commands
21
21
 
22
- ### Getting Started
22
+ ### Setup & Getting Started
23
23
  | Command | Purpose |
24
24
  |---------|---------|
25
- | `/ant:init "<goal>"` | Set colony intention and initialize |
25
+ | `/ant:lay-eggs` | Set up Aether in this repo (one-time, creates .aether/) |
26
+ | `/ant:init "<goal>"` | Start a colony with a goal |
26
27
  | `/ant:colonize` | Analyze existing codebase |
27
28
  | `/ant:plan` | Generate project phases |
28
29
  | `/ant:build <phase>` | Execute a phase with parallel workers |
@@ -75,19 +76,28 @@ This only applies to genuinely new conversations, not after /clear.
75
76
  ## Typical Workflow
76
77
 
77
78
  ```
78
- /ant:init "Build feature X" → Set colony goal
79
- /ant:colonize → Understand existing code (optional)
80
- /ant:plan → Generate phases
81
- /ant:focus "security" → Steer attention (optional)
82
- /ant:build 1 → Execute phase 1
83
- /ant:continue → Verify, learn, advance
84
- /ant:build 2 → Execute phase 2
85
- ...repeat until complete...
86
- /ant:seal → Seal completed colony
79
+ First time in a repo:
80
+ 0. /ant:lay-eggs (set up Aether in this repo)
81
+
82
+ Starting a colony:
83
+ 1. /ant:init "Build feature X" (start colony with a goal)
84
+ 2. /ant:colonize (if existing code)
85
+ 3. /ant:plan (generates phases)
86
+ 4. /ant:focus "security" (optional guidance)
87
+ 5. /ant:build 1 (workers execute phase 1)
88
+ 6. /ant:continue (verify, learn, advance)
89
+ 7. /ant:build 2 (repeat until complete)
90
+
91
+ After /clear or session break:
92
+ 8. /ant:resume-colony (restore full context)
93
+ 9. /ant:status (see where you left off)
94
+
95
+ After completing a colony:
96
+ 10. /ant:seal (mark as complete)
97
+ 11. /ant:entomb (archive to chambers)
98
+ 12. /ant:init "next project goal" (start fresh colony)
87
99
  ```
88
100
 
89
- After `/clear` or session break: `/ant:resume-colony` to restore context.
90
-
91
101
  ## Worker Castes
92
102
 
93
103
  Workers are assigned to castes based on task type:
package/.claude/commands/ant/help.md CHANGED
@@ -16,9 +16,10 @@ Output the following:
16
16
  A multi-agent system built on ant colony intelligence.
17
17
  Workers self-organize via pheromone signals. You guide with intention.
18
18
 
19
- GETTING STARTED
19
+ SETUP & GETTING STARTED
20
20
 
21
- /ant:init "<goal>" Set colony intention and initialize
21
+ /ant:lay-eggs Set up Aether in this repo (one-time, creates .aether/)
22
+ /ant:init "<goal>" Start a colony with a goal
22
23
  /ant:colonize Analyze existing codebase (optional)
23
24
  /ant:plan Generate project plan
24
25
  /ant:build <phase> Execute a phase (spawns parallel workers)
@@ -53,7 +54,6 @@ COLONY LIFECYCLE
53
54
 
54
55
  /ant:seal Seal colony with Crowned Anthill milestone
55
56
  /ant:entomb Archive completed colony into chambers
56
- /ant:lay-eggs Lay first eggs of new colony (First Eggs milestone)
57
57
  /ant:history Browse colony event history
58
58
 
59
59
  ADVANCED
@@ -75,7 +75,11 @@ MAINTENANCE
75
75
 
76
76
  TYPICAL WORKFLOW
77
77
 
78
- 1. /ant:init "Build a REST API with auth"
78
+ First time in a repo:
79
+ 0. /ant:lay-eggs (set up Aether in this repo)
80
+
81
+ Starting a colony:
82
+ 1. /ant:init "Build a REST API with auth" (start colony with a goal)
79
83
  2. /ant:colonize (if existing code)
80
84
  3. /ant:plan (generates phases)
81
85
  4. /ant:focus "security" (optional guidance)
@@ -87,6 +91,11 @@ TYPICAL WORKFLOW
87
91
  8. /ant:resume-colony (restore full context)
88
92
  9. /ant:status (see where you left off)
89
93
 
94
+ After completing a colony:
95
+ 10. /ant:seal (mark as complete)
96
+ 11. /ant:entomb (archive to chambers)
97
+ 12. /ant:init "next project goal" (start fresh colony)
98
+
90
99
  WORKER CASTES
91
100
 
92
101
  👑 Queen — orchestrates, spawns workers, synthesizes results
package/.claude/commands/ant/init.md CHANGED
@@ -64,57 +64,26 @@ Aether Colony
64
64
 
65
65
  Stop here. Do not proceed.
66
66
 
67
- ### Step 1.5: Bootstrap System Files (Conditional)
67
+ ### Step 1.5: Verify Aether Setup
68
68
 
69
69
  Check if `.aether/aether-utils.sh` exists using the Read tool.
70
70
 
71
- **If the file already exists** — skip this step entirely. System files are present.
71
+ **If the file already exists** — skip this step entirely. Aether is set up.
72
72
 
73
73
  **If the file does NOT exist:**
74
- - Check if `~/.aether/system/aether-utils.sh` exists (expand `~` to the user's home directory)
75
- - **If the hub exists:** Run using the Bash tool:
76
- ```bash
77
- mkdir -p \
78
- .aether/data \
79
- .aether/data/midden \
80
- .aether/data/backups \
81
- .aether/data/survey \
82
- .aether/dreams \
83
- .aether/chambers \
84
- .aether/locks \
85
- .aether/temp \
86
- .aether/docs \
87
- .aether/utils \
88
- .aether/templates \
89
- .aether/schemas \
90
- .aether/exchange \
91
- .aether/rules \
92
- .claude/rules && \
93
- cp -f ~/.aether/system/aether-utils.sh .aether/ && \
94
- cp -f ~/.aether/system/workers.md .aether/ 2>/dev/null || true && \
95
- cp -f ~/.aether/system/CONTEXT.md .aether/ 2>/dev/null || true && \
96
- cp -f ~/.aether/system/model-profiles.yaml .aether/ 2>/dev/null || true && \
97
- cp -Rf ~/.aether/system/docs/* .aether/docs/ 2>/dev/null || true && \
98
- cp -Rf ~/.aether/system/utils/* .aether/utils/ 2>/dev/null || true && \
99
- cp -Rf ~/.aether/system/templates/* .aether/templates/ 2>/dev/null || true && \
100
- cp -Rf ~/.aether/system/schemas/* .aether/schemas/ 2>/dev/null || true && \
101
- cp -Rf ~/.aether/system/exchange/* .aether/exchange/ 2>/dev/null || true && \
102
- cp -Rf ~/.aether/system/rules/* .claude/rules/ 2>/dev/null || true && \
103
- touch .aether/dreams/.gitkeep && \
104
- touch .aether/chambers/.gitkeep && \
105
- touch .aether/data/midden/.gitkeep && \
106
- chmod +x .aether/aether-utils.sh
107
- ```
108
- This copies system files from the global hub into `.aether/` and creates all required directories upfront. Display:
109
- ```
110
- Bootstrapped system files from global hub.
111
- ```
112
- - **If the hub does NOT exist:** Output:
113
- ```
114
- No Aether system files found locally or in ~/.aether/system/.
115
- Run `aether install` or `npx aether-colony install` to set up the global hub first.
116
- ```
117
- Stop here. Do not proceed.
74
+ ```
75
+ Aether is not set up in this repo yet.
76
+
77
+ Run /ant:lay-eggs first to create the .aether/ directory
78
+ with all system files, then run /ant:init "your goal" to
79
+ start a colony.
80
+
81
+ If the global hub isn't installed either:
82
+ npm install -g aether-colony (installs the hub)
83
+ /ant:lay-eggs (sets up this repo)
84
+ /ant:init "your goal" (starts the colony)
85
+ ```
86
+ Stop here. Do not proceed.
118
87
 
119
88
  ### Step 1.6: Initialize QUEEN.md Wisdom Document
120
89
 
package/.claude/commands/ant/lay-eggs.md CHANGED
@@ -1,190 +1,195 @@
1
1
  ---
2
2
  name: ant:lay-eggs
3
- description: "🥚🐜🥚 Lay first eggs of new colony (First Eggs milestone)"
3
+ description: "🥚🐜🥚 Set up Aether in this repo — creates .aether/ with all system files"
4
4
  ---
5
5
 
6
- You are the **Queen**. Begin a new colony, preserving pheromones.
6
+ You are the **Queen**. Prepare this repository for Aether colony development.
7
7
 
8
8
  ## Instructions
9
9
 
10
- Parse `$ARGUMENTS`:
11
- - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
12
- - Otherwise: set `visual_mode = true`
10
+ This command sets up the `.aether/` directory structure and copies all system files from the global hub. It does NOT start a colony — that's what `/ant:init "goal"` is for.
13
11
 
14
12
  <failure_modes>
15
- ### Plan File Write Failure
16
- If writing phase plans to COLONY_STATE.json fails:
17
- - Do not leave partial plan data in state
18
- - Report what was successfully written vs. what failed
19
- - Recovery: user can re-run /ant:lay-eggs to regenerate plans
20
-
21
- ### Goal Parsing Failure
22
- If the user's goal cannot be parsed into actionable phases:
23
- - Do not generate placeholder phases
24
- - Ask user to clarify or simplify the goal
25
- - Offer examples of well-formed goals
13
+ ### Hub Not Found
14
+ If `~/.aether/system/aether-utils.sh` does not exist:
15
+ - The global hub is not installed
16
+ - Tell the user to run `npm install -g aether-colony` first
17
+ - Stop — cannot proceed without hub
18
+
19
+ ### Partial Copy Failure
20
+ If some files fail to copy from hub:
21
+ - Report which files succeeded and which failed
22
+ - The user can re-run `/ant:lay-eggs` safely (idempotent)
26
23
  </failure_modes>
27
24
 
28
25
  <success_criteria>
29
26
  Command is complete when:
30
- - Phase plan is written to COLONY_STATE.json with tasks and success criteria
31
- - Plan structure is valid (phases have tasks, tasks have descriptions)
32
- - User sees the plan and can approve or request changes
27
+ - `.aether/` directory exists with all subdirectories
28
+ - System files (aether-utils.sh, workers.md, etc.) are present
29
+ - Templates, docs, utils, schemas are populated
30
+ - QUEEN.md is initialized
31
+ - User sees confirmation and next steps
33
32
  </success_criteria>
34
33
 
35
34
  <read_only>
36
35
  Do not touch during lay-eggs:
37
- - .aether/dreams/ (user notes)
38
- - .aether/chambers/ (archived colonies)
39
- - Source code files (planning only, no implementation)
36
+ - .aether/data/COLONY_STATE.json (colony state belongs to init)
37
+ - .aether/dreams/ contents (user notes — create dir but don't modify files)
38
+ - .aether/chambers/ contents (archived colonies — create dir but don't modify files)
39
+ - Source code files
40
40
  - .env* files
41
41
  - .claude/settings.json
42
42
  </read_only>
43
43
 
44
- ### Step 0: Initialize Visual Mode (if enabled)
44
+ ### Step 1: Check Hub Availability
45
45
 
46
- If `visual_mode` is true, run using the Bash tool with description "Initializing colony display...":
46
+ Check if the global hub exists by reading `~/.aether/system/aether-utils.sh` (expand `~` to the user's home directory).
47
+
48
+ **If the hub does NOT exist:**
49
+ ```
50
+ Aether hub not found at ~/.aether/system/
51
+
52
+ The global hub must be installed before setting up a repo.
53
+
54
+ npm install -g aether-colony
55
+
56
+ This installs the Aether CLI and populates the hub at ~/.aether/system/
57
+ with all the system files your repo needs.
58
+
59
+ After installing, run /ant:lay-eggs again.
60
+ ```
61
+ Stop here.
62
+
63
+ ### Step 2: Check Existing Setup
64
+
65
+ Check if `.aether/aether-utils.sh` already exists using the Read tool.
66
+
67
+ **If it exists:**
68
+ ```
69
+ Aether is already set up in this repo.
70
+
71
+ Refreshing system files from hub...
72
+ ```
73
+ Proceed to Step 3 (this makes the command safe to re-run as an update/repair).
74
+
75
+ **If it does NOT exist:**
76
+ ```
77
+ Setting up Aether in this repo...
78
+ ```
79
+ Proceed to Step 3.
80
+
81
+ ### Step 3: Create Directory Structure
82
+
83
+ Run using the Bash tool with description "Creating Aether directory structure...":
47
84
  ```bash
48
- # Generate session ID and persist it for later steps
49
- layeggs_id="layeggs-$(date +%s)"
50
- echo "$layeggs_id" > .aether/data/.layeggs_session
85
+ mkdir -p \
86
+ .aether/data \
87
+ .aether/data/midden \
88
+ .aether/data/backups \
89
+ .aether/data/survey \
90
+ .aether/dreams \
91
+ .aether/chambers \
92
+ .aether/locks \
93
+ .aether/temp \
94
+ .aether/docs \
95
+ .aether/utils \
96
+ .aether/templates \
97
+ .aether/schemas \
98
+ .aether/exchange \
99
+ .aether/rules \
100
+ .aether/scripts \
101
+ .claude/rules && \
102
+ touch .aether/dreams/.gitkeep && \
103
+ touch .aether/chambers/.gitkeep && \
104
+ touch .aether/data/midden/.gitkeep
51
105
  ```
52
106
 
53
- ### Step 1: Validate Input
54
-
55
- - If `$ARGUMENTS` is empty:
56
- ```
57
- Usage: /ant:lay-eggs "<new colony goal>"
58
-
59
- Start a fresh colony, preserving pheromones from prior colonies.
60
- Requires current colony to be entombed or reset.
61
-
62
- Example:
63
- /ant:lay-eggs "Build a REST API with authentication"
64
- ```
65
- Stop here.
66
-
67
- ### Step 2: Check Current Colony
68
-
69
- - Read `.aether/data/COLONY_STATE.json`
70
- - If goal is not null AND phases exist with status != "completed":
71
- ```
72
- 🚫 Cannot lay eggs — active colony has unsaved pheromones
73
-
74
- Active colony: {goal}
75
- Current: Phase {current_phase}, {phases_count} phases in plan
76
-
77
- ┌─────────────────────────────────────────────────────────┐
78
- │ COLONY LIFECYCLE │
79
- ├─────────────────────────────────────────────────────────┤
80
- │ │
81
- │ 🟢 ACTIVE COLONY → 🏺 SEAL/ENTOMB → 🥚 LAY EGGS │
82
- │ (working) (preserve memory) (new goal) │
83
- │ │
84
- └─────────────────────────────────────────────────────────┘
85
-
86
- Why this matters:
87
- Your active colony contains preserved learnings, decisions, and
88
- instincts (pheromones) from prior work. These must be sealed
89
- before starting a new project, or they will be lost forever.
90
-
91
- To start a new colony:
92
- 1. Complete work → run `/ant:seal` or `/ant:entomb` to archive
93
- 2. Then run `/ant:lay-eggs "new goal"` to begin fresh
94
-
95
- Emergency reset (loses all pheromones):
96
- rm .aether/data/COLONY_STATE.json
97
- ```
98
- Stop here.
99
-
100
- ### Step 3: Extract Preserved Knowledge
101
-
102
- - Read current state to extract preserved fields:
103
- - `memory.phase_learnings` (all items)
104
- - `memory.decisions` (all items)
105
- - `memory.instincts` (all items with confidence >= 0.5)
106
- - Store for use in Step 4
107
-
108
- ### Step 4: Create New Colony State
109
-
110
- Generate new state following RESEARCH.md Pattern 2 (State Reset with Pheromone Preservation):
111
-
112
- **Fields to preserve from old state:**
113
- - memory.phase_learnings
114
- - memory.decisions
115
- - memory.instincts (high confidence only)
116
-
117
- **Fields to reset:**
118
- - goal: new goal from $ARGUMENTS
119
- - state: "READY"
120
- - current_phase: 0
121
- - session_id: new session_{unix_timestamp}_{random}
122
- - initialized_at: current ISO-8601 timestamp
123
- - build_started_at: null
124
- - plan: { generated_at: null, confidence: null, phases: [] }
125
- - errors: { records: [], flagged_patterns: [] }
126
- - signals: []
127
- - graveyards: []
128
- - events: [colony_initialized event with new goal]
129
-
130
- **New milestone fields:**
131
- - milestone: "First Mound"
132
- - milestone_updated_at: current timestamp
133
- - milestone_version: "v0.1.0"
134
-
135
- Write to `.aether/data/COLONY_STATE.json`
136
-
137
- ### Step 5: Reset Constraints
138
-
139
- Write `.aether/data/constraints.json`:
140
- ```json
141
- {
142
- "version": "1.0",
143
- "focus": [],
144
- "constraints": []
145
- }
107
+ ### Step 4: Copy System Files from Hub
108
+
109
+ Run using the Bash tool with description "Copying system files from hub...":
110
+ ```bash
111
+ # Core system files
112
+ cp -f ~/.aether/system/aether-utils.sh .aether/ && \
113
+ chmod +x .aether/aether-utils.sh && \
114
+ cp -f ~/.aether/system/workers.md .aether/ 2>/dev/null || true && \
115
+ cp -f ~/.aether/system/CONTEXT.md .aether/ 2>/dev/null || true && \
116
+ cp -f ~/.aether/system/model-profiles.yaml .aether/ 2>/dev/null || true && \
117
+
118
+ # Directories
119
+ cp -Rf ~/.aether/system/docs/* .aether/docs/ 2>/dev/null || true && \
120
+ cp -Rf ~/.aether/system/utils/* .aether/utils/ 2>/dev/null || true && \
121
+ cp -Rf ~/.aether/system/templates/* .aether/templates/ 2>/dev/null || true && \
122
+ cp -Rf ~/.aether/system/schemas/* .aether/schemas/ 2>/dev/null || true && \
123
+ cp -Rf ~/.aether/system/exchange/* .aether/exchange/ 2>/dev/null || true && \
124
+ cp -Rf ~/.aether/system/rules/* .claude/rules/ 2>/dev/null || true && \
125
+
126
+ # Version tracking
127
+ cp -f ~/.aether/version.json .aether/version.json 2>/dev/null || true
128
+
129
+ echo "System files copied."
146
130
  ```
147
131
 
148
- ### Step 6: Display Result
132
+ ### Step 5: Initialize QUEEN.md
149
133
 
150
- **If visual_mode is true, render final swarm display** by running using the Bash tool with description "Updating colony display...":
134
+ Run using the Bash tool with description "Initializing QUEEN.md...":
151
135
  ```bash
136
+ bash .aether/aether-utils.sh queen-init
152
137
  ```
153
- 🥚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
154
- F I R S T E G G S L A I D
155
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🥚
156
138
 
157
- 👑 New colony goal:
158
- "{goal}"
139
+ Parse the JSON result:
140
+ - If `created` is true: note `QUEEN.md initialized`
141
+ - If `created` is false: note `QUEEN.md already exists (preserved)`
159
142
 
160
- 🏆 Milestone: First Mound (v0.1.0)
143
+ ### Step 6: Register Repo (Silent)
161
144
 
162
- {If inherited knowledge:}
163
- 🧠 Inherited from prior colonies:
164
- {N} instinct(s) | {N} decision(s) | {N} learning(s)
165
- {End if}
145
+ Attempt to register this repo in the global hub. Silent on failure — registry is optional.
166
146
 
167
- 🐜 The colony begins anew.
147
+ Run using the Bash tool with description "Registering repo..." (ignore errors):
148
+ ```bash
149
+ bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" 2>/dev/null || true
150
+ ```
168
151
 
169
- /ant:plan 📋 Chart the course
170
- /ant:colonize 🗺️ Analyze existing code
152
+ ### Step 7: Verify Setup
153
+
154
+ Run using the Bash tool with description "Verifying setup...":
155
+ ```bash
156
+ # Count what was set up
157
+ dirs=0
158
+ files=0
159
+ for d in .aether/data .aether/docs .aether/utils .aether/templates .aether/schemas .aether/exchange .aether/dreams .aether/chambers; do
160
+ [ -d "$d" ] && dirs=$((dirs + 1))
161
+ done
162
+ [ -f .aether/aether-utils.sh ] && files=$((files + 1))
163
+ [ -f .aether/workers.md ] && files=$((files + 1))
164
+ [ -f .aether/QUEEN.md ] && files=$((files + 1))
165
+ [ -f .aether/CONTEXT.md ] && files=$((files + 1))
166
+ [ -d .aether/templates ] && templates=$(ls .aether/templates/*.template.* 2>/dev/null | wc -l | tr -d ' ') || templates=0
167
+ [ -d .aether/utils ] && utils=$(ls .aether/utils/*.sh 2>/dev/null | wc -l | tr -d ' ') || utils=0
168
+
169
+ echo "{\"dirs\": $dirs, \"core_files\": $files, \"templates\": $templates, \"utils\": $utils}"
171
170
  ```
172
171
 
173
- Include edge case handling:
174
- - If no prior knowledge: omit the inheritance section
175
- - If prior colony had no phases: allow laying eggs without entombment
172
+ Parse the JSON output for the display step.
176
173
 
177
- ### Step 7: Next Up
174
+ ### Step 8: Display Result
178
175
 
179
- Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
180
- ```bash
181
- if [ -f .aether/data/COLONY_STATE.json ]; then
182
- state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json 2>/dev/null || echo "IDLE")
183
- current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
184
- total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
185
- else
186
- state="IDLE"
187
- current_phase="0"
188
- total_phases="0"
189
- fi
190
- bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
176
+ ```
177
+ 🥚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
178
+ A E T H E R R E A D Y
179
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🥚
180
+
181
+ {dirs} directories created
182
+ {core_files} core system files
183
+ {templates} templates
184
+ {utils} utility scripts
185
+ QUEEN.md: {status}
186
+
187
+ .aether/ is set up and ready for colony work.
188
+
189
+ ──────────────────────────────────────────────────
190
+ 🐜 Next Up
191
+ ──────────────────────────────────────────────────
192
+ /ant:init "your goal" 🌱 Start a colony
193
+ /ant:colonize 🗺️ Analyze existing code first
194
+ /ant:help 📖 See all commands
195
+ ```
package/.claude/commands/ant/seal.md CHANGED
@@ -267,6 +267,32 @@ Update COLONY_STATE.json:
267
267
 
268
268
  Run `bash .aether/aether-utils.sh validate-state colony` after write.
269
269
 
270
+ ### Step 5.1: Update Changelog
271
+
272
+ **MANDATORY: Record the seal in the project changelog. This step is never skipped.**
273
+
274
+ If no `CHANGELOG.md` exists, `changelog-append` creates one automatically.
275
+
276
+ Build a summary of what the colony accomplished across all phases:
277
+ - Collect completed phase names from COLONY_STATE.json
278
+ - Summarize the goal and key outcomes in one line
279
+
280
+ ```bash
281
+ bash .aether/aether-utils.sh changelog-append \
282
+ "$(date +%Y-%m-%d)" \
283
+ "seal-crowned-anthill" \
284
+ "00" \
285
+ "{key_files_csv}" \
286
+ "Colony sealed at Crowned Anthill;{goal}" \
287
+ "{phases_completed} phases completed;Colony wisdom promoted to QUEEN.md" \
288
+ ""
289
+ ```
290
+
291
+ - `{key_files_csv}` — list the most significant files created or modified across the colony's lifetime (derive from phase plans or git log)
292
+ - `{goal}` — the colony goal from COLONY_STATE.json
293
+
294
+ **Error handling:** If `changelog-append` fails, log to midden and continue — changelog failure never blocks sealing.
295
+
270
296
  ### Step 5.5: Documentation Coverage Audit
271
297
 
272
298
  Before writing the seal document, spawn a Chronicler to survey documentation coverage.
package/.opencode/commands/ant/help.md CHANGED
@@ -16,9 +16,10 @@ Output the following:
16
16
  A multi-agent system built on ant colony intelligence.
17
17
  Workers self-organize via pheromone signals. You guide with intention.
18
18
 
19
- GETTING STARTED
19
+ SETUP & GETTING STARTED
20
20
 
21
- /ant:init "<goal>" Set colony intention and initialize
21
+ /ant:lay-eggs Set up Aether in this repo (one-time, creates .aether/)
22
+ /ant:init "<goal>" Start a colony with a goal
22
23
  /ant:colonize Analyze existing codebase (optional)
23
24
  /ant:plan Generate project plan
24
25
  /ant:build <phase> Execute a phase (spawns parallel workers)
@@ -62,7 +63,11 @@ ADVANCED
62
63
 
63
64
  TYPICAL WORKFLOW
64
65
 
65
- 1. /ant:init "Build a REST API with auth"
66
+ First time in a repo:
67
+ 0. /ant:lay-eggs (set up Aether in this repo)
68
+
69
+ Starting a colony:
70
+ 1. /ant:init "Build a REST API with auth" (start colony with a goal)
66
71
  2. /ant:colonize (if existing code)
67
72
  3. /ant:plan (generates phases)
68
73
  4. /ant:focus "security" (optional guidance)
@@ -74,6 +79,11 @@ TYPICAL WORKFLOW
74
79
  8. /ant:resume-colony (restore full context)
75
80
  9. /ant:status (see where you left off)
76
81
 
82
+ After completing a colony:
83
+ 10. /ant:seal (mark as complete)
84
+ 11. /ant:entomb (archive to chambers)
85
+ 12. /ant:init "next project goal" (start fresh colony)
86
+
77
87
  WORKER CASTES
78
88
 
79
89
  👑 Queen — orchestrates, spawns workers, synthesizes results
@@ -89,7 +99,7 @@ WORKER CASTES
89
99
  HOW IT WORKS
90
100
 
91
101
  Colony Lifecycle:
92
- INIT → PLAN → BUILD → CONTINUE → BUILD → ... → COMPLETE
102
+ LAY-EGGS → INIT → PLAN → BUILD → CONTINUE → BUILD → ... → SEAL → ENTOMB
93
103
 
94
104
  Workers spawn sub-workers autonomously (max depth 3).
95
105
  Builders receive colony knowledge (instincts, learnings, error patterns).
package/.opencode/commands/ant/init.md CHANGED
@@ -45,57 +45,26 @@ Aether Colony
45
45
 
46
46
  Stop here. Do not proceed.
47
47
 
48
- ### Step 1.5: Bootstrap System Files (Conditional)
48
+ ### Step 1.5: Verify Aether Setup
49
49
 
50
- Check if `.aether/aether-utils.sh` exists using the Read tool.
50
+ Check if `.aether/aether-utils.sh` exists.
51
51
 
52
- **If the file already exists** — skip this step entirely. System files are present.
52
+ **If the file already exists** — skip this step entirely. Aether is set up.
53
53
 
54
54
  **If the file does NOT exist:**
55
- - Check if `~/.aether/system/aether-utils.sh` exists (expand `~` to the user's home directory)
56
- - **If the hub exists:** Run using the Bash tool:
57
- ```bash
58
- mkdir -p \
59
- .aether/data \
60
- .aether/data/midden \
61
- .aether/data/backups \
62
- .aether/data/survey \
63
- .aether/dreams \
64
- .aether/chambers \
65
- .aether/locks \
66
- .aether/temp \
67
- .aether/docs \
68
- .aether/utils \
69
- .aether/templates \
70
- .aether/schemas \
71
- .aether/exchange \
72
- .aether/rules \
73
- .claude/rules && \
74
- cp -f ~/.aether/system/aether-utils.sh .aether/ && \
75
- cp -f ~/.aether/system/workers.md .aether/ 2>/dev/null || true && \
76
- cp -f ~/.aether/system/CONTEXT.md .aether/ 2>/dev/null || true && \
77
- cp -f ~/.aether/system/model-profiles.yaml .aether/ 2>/dev/null || true && \
78
- cp -Rf ~/.aether/system/docs/* .aether/docs/ 2>/dev/null || true && \
79
- cp -Rf ~/.aether/system/utils/* .aether/utils/ 2>/dev/null || true && \
80
- cp -Rf ~/.aether/system/templates/* .aether/templates/ 2>/dev/null || true && \
81
- cp -Rf ~/.aether/system/schemas/* .aether/schemas/ 2>/dev/null || true && \
82
- cp -Rf ~/.aether/system/exchange/* .aether/exchange/ 2>/dev/null || true && \
83
- cp -Rf ~/.aether/system/rules/* .claude/rules/ 2>/dev/null || true && \
84
- touch .aether/dreams/.gitkeep && \
85
- touch .aether/chambers/.gitkeep && \
86
- touch .aether/data/midden/.gitkeep && \
87
- chmod +x .aether/aether-utils.sh
88
- ```
89
- This copies system files from the global hub into `.aether/` and creates all required directories upfront. Display:
90
- ```
91
- Bootstrapped system files from global hub.
92
- ```
93
- - **If the hub does NOT exist:** Output:
94
- ```
95
- No Aether system files found locally or in ~/.aether/system/.
96
- Run `aether install` or `npx aether-colony install` to set up the global hub first.
97
- ```
98
- Stop here. Do not proceed.
55
+ ```
56
+ Aether is not set up in this repo yet.
57
+
58
+ Run /ant:lay-eggs first to create the .aether/ directory
59
+ with all system files, then run /ant:init "your goal" to
60
+ start a colony.
61
+
62
+ If the global hub isn't installed either:
63
+ npm install -g aether-colony (installs the hub)
64
+ /ant:lay-eggs (sets up this repo)
65
+ /ant:init "your goal" (starts the colony)
66
+ ```
67
+ Stop here. Do not proceed.
99
68
 
100
69
  ### Step 2: Read Current State
101
70
 
package/.opencode/commands/ant/lay-eggs.md CHANGED
@@ -1,123 +1,192 @@
1
1
  ---
2
2
  name: ant:lay-eggs
3
- description: "🥚🐜🥚 Lay first eggs of new colony (First Eggs milestone)"
3
+ description: "🥚🐜🥚 Set up Aether in this repo — creates .aether/ with all system files"
4
4
  ---
5
5
 
6
- You are the **Queen**. Begin a new colony, preserving pheromones.
6
+ You are the **Queen**. Prepare this repository for Aether colony development.
7
7
 
8
8
  ## Instructions
9
9
 
10
+ This command sets up the `.aether/` directory structure and copies all system files from the global hub. It does NOT start a colony — that's what `/ant:init "goal"` is for.
11
+
10
12
  ### Step -1: Normalize Arguments
11
13
 
12
14
  Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
13
15
 
14
- This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
15
-
16
- Parse `$normalized_args`:
17
- - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
18
- - Otherwise: set `visual_mode = true`
19
-
20
- ### Step 1: Validate Input
21
-
22
- - If `$normalized_args` is empty:
23
- ```
24
- Usage: /ant:lay-eggs "<new colony goal>"
16
+ This ensures arguments work correctly in both Claude Code and OpenCode.
17
+
18
+ <failure_modes>
19
+ ### Hub Not Found
20
+ If `~/.aether/system/aether-utils.sh` does not exist:
21
+ - The global hub is not installed
22
+ - Tell the user to run `npm install -g aether-colony` first
23
+ - Stop — cannot proceed without hub
24
+
25
+ ### Partial Copy Failure
26
+ If some files fail to copy from hub:
27
+ - Report which files succeeded and which failed
28
+ - The user can re-run `/ant:lay-eggs` safely (idempotent)
29
+ </failure_modes>
30
+
31
+ <success_criteria>
32
+ Command is complete when:
33
+ - `.aether/` directory exists with all subdirectories
34
+ - System files (aether-utils.sh, workers.md, etc.) are present
35
+ - Templates, docs, utils, schemas are populated
36
+ - QUEEN.md is initialized
37
+ - User sees confirmation and next steps
38
+ </success_criteria>
39
+
40
+ <read_only>
41
+ Do not touch during lay-eggs:
42
+ - .aether/data/COLONY_STATE.json (colony state belongs to init)
43
+ - .aether/dreams/ contents (user notes — create dir but don't modify files)
44
+ - .aether/chambers/ contents (archived colonies — create dir but don't modify files)
45
+ - Source code files
46
+ - .env* files
47
+ </read_only>
48
+
49
+ ### Step 1: Check Hub Availability
50
+
51
+ Check if the global hub exists by reading `~/.aether/system/aether-utils.sh` (expand `~` to the user's home directory).
52
+
53
+ **If the hub does NOT exist:**
54
+ ```
55
+ Aether hub not found at ~/.aether/system/
25
56
 
26
- Start a fresh colony, preserving pheromones from prior colonies.
27
- Requires current colony to be entombed or reset.
57
+ The global hub must be installed before setting up a repo.
28
58
 
29
- Example:
30
- /ant:lay-eggs "Build a REST API with authentication"
31
- ```
32
- Stop here.
59
+ npm install -g aether-colony
33
60
 
34
- ### Step 2: Check Current Colony
61
+ This installs the Aether CLI and populates the hub at ~/.aether/system/
62
+ with all the system files your repo needs.
35
63
 
36
- - Read `.aether/data/COLONY_STATE.json`
37
- - If goal is not null AND phases exist with status != "completed":
38
- ```
39
- Active colony exists: {goal}
64
+ After installing, run /ant:lay-eggs again.
65
+ ```
66
+ Stop here.
40
67
 
41
- To start a new colony, you must first:
42
- 1. Complete all phases, then /ant:entomb to archive
43
- 2. Or manually reset by deleting .aether/data/COLONY_STATE.json
68
+ ### Step 2: Check Existing Setup
44
69
 
45
- Current: Phase {current_phase}, {phases_count} phases in plan
46
- ```
47
- Stop here.
70
+ Check if `.aether/aether-utils.sh` already exists.
48
71
 
49
- ### Step 3: Extract Preserved Knowledge
72
+ **If it exists:**
73
+ ```
74
+ Aether is already set up in this repo.
50
75
 
51
- - Read current state to extract preserved fields:
52
- - `memory.phase_learnings` (all items)
53
- - `memory.decisions` (all items)
54
- - `memory.instincts` (all items with confidence >= 0.5)
55
- - Store for use in Step 4
76
+ Refreshing system files from hub...
77
+ ```
78
+ Proceed to Step 3 (this makes the command safe to re-run as an update/repair).
56
79
 
57
- ### Step 4: Create New Colony State
80
+ **If it does NOT exist:**
81
+ ```
82
+ Setting up Aether in this repo...
83
+ ```
84
+ Proceed to Step 3.
85
+
86
+ ### Step 3: Create Directory Structure
87
+
88
+ Run:
89
+ ```bash
90
+ mkdir -p \
91
+ .aether/data \
92
+ .aether/data/midden \
93
+ .aether/data/backups \
94
+ .aether/data/survey \
95
+ .aether/dreams \
96
+ .aether/chambers \
97
+ .aether/locks \
98
+ .aether/temp \
99
+ .aether/docs \
100
+ .aether/utils \
101
+ .aether/templates \
102
+ .aether/schemas \
103
+ .aether/exchange \
104
+ .aether/rules \
105
+ .aether/scripts \
106
+ .claude/rules && \
107
+ touch .aether/dreams/.gitkeep && \
108
+ touch .aether/chambers/.gitkeep && \
109
+ touch .aether/data/midden/.gitkeep
110
+ ```
58
111
 
59
- Generate new state following RESEARCH.md Pattern 2 (State Reset with Pheromone Preservation):
112
+ ### Step 4: Copy System Files from Hub
113
+
114
+ Run:
115
+ ```bash
116
+ # Core system files
117
+ cp -f ~/.aether/system/aether-utils.sh .aether/ && \
118
+ chmod +x .aether/aether-utils.sh && \
119
+ cp -f ~/.aether/system/workers.md .aether/ 2>/dev/null || true && \
120
+ cp -f ~/.aether/system/CONTEXT.md .aether/ 2>/dev/null || true && \
121
+ cp -f ~/.aether/system/model-profiles.yaml .aether/ 2>/dev/null || true && \
122
+
123
+ # Directories
124
+ cp -Rf ~/.aether/system/docs/* .aether/docs/ 2>/dev/null || true && \
125
+ cp -Rf ~/.aether/system/utils/* .aether/utils/ 2>/dev/null || true && \
126
+ cp -Rf ~/.aether/system/templates/* .aether/templates/ 2>/dev/null || true && \
127
+ cp -Rf ~/.aether/system/schemas/* .aether/schemas/ 2>/dev/null || true && \
128
+ cp -Rf ~/.aether/system/exchange/* .aether/exchange/ 2>/dev/null || true && \
129
+ cp -Rf ~/.aether/system/rules/* .claude/rules/ 2>/dev/null || true && \
130
+
131
+ # Version tracking
132
+ cp -f ~/.aether/version.json .aether/version.json 2>/dev/null || true
133
+
134
+ echo "System files copied."
135
+ ```
60
136
 
61
- **Fields to preserve from old state:**
62
- - memory.phase_learnings
63
- - memory.decisions
64
- - memory.instincts (high confidence only)
137
+ ### Step 5: Initialize QUEEN.md
65
138
 
66
- **Fields to reset:**
67
- - goal: new goal from $normalized_args
68
- - state: "READY"
69
- - current_phase: 0
70
- - session_id: new session_{unix_timestamp}_{random}
71
- - initialized_at: current ISO-8601 timestamp
72
- - build_started_at: null
73
- - plan: { generated_at: null, confidence: null, phases: [] }
74
- - errors: { records: [], flagged_patterns: [] }
75
- - signals: []
76
- - graveyards: []
77
- - events: [colony_initialized event with new goal]
139
+ Run: `bash .aether/aether-utils.sh queen-init`
78
140
 
79
- **New milestone fields:**
80
- - milestone: "First Mound"
81
- - milestone_updated_at: current timestamp
82
- - milestone_version: "v0.1.0"
141
+ Parse the JSON result:
142
+ - If `created` is true: note `QUEEN.md initialized`
143
+ - If `created` is false: note `QUEEN.md already exists (preserved)`
83
144
 
84
- Write to `.aether/data/COLONY_STATE.json`
145
+ ### Step 6: Register Repo (Silent)
85
146
 
86
- ### Step 5: Reset Constraints
147
+ Run (ignore errors):
148
+ ```bash
149
+ bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" 2>/dev/null || true
150
+ ```
87
151
 
88
- Write `.aether/data/constraints.json`:
89
- ```json
90
- {
91
- "version": "1.0",
92
- "focus": [],
93
- "constraints": []
94
- }
152
+ ### Step 7: Verify Setup
153
+
154
+ Run:
155
+ ```bash
156
+ dirs=0
157
+ files=0
158
+ for d in .aether/data .aether/docs .aether/utils .aether/templates .aether/schemas .aether/exchange .aether/dreams .aether/chambers; do
159
+ [ -d "$d" ] && dirs=$((dirs + 1))
160
+ done
161
+ [ -f .aether/aether-utils.sh ] && files=$((files + 1))
162
+ [ -f .aether/workers.md ] && files=$((files + 1))
163
+ [ -f .aether/QUEEN.md ] && files=$((files + 1))
164
+ [ -f .aether/CONTEXT.md ] && files=$((files + 1))
165
+ [ -d .aether/templates ] && templates=$(ls .aether/templates/*.template.* 2>/dev/null | wc -l | tr -d ' ') || templates=0
166
+ [ -d .aether/utils ] && utils=$(ls .aether/utils/*.sh 2>/dev/null | wc -l | tr -d ' ') || utils=0
167
+
168
+ echo "{\"dirs\": $dirs, \"core_files\": $files, \"templates\": $templates, \"utils\": $utils}"
95
169
  ```
96
170
 
97
- ### Step 6: Display Result
171
+ ### Step 8: Display Result
98
172
 
99
173
  ```
100
174
  🥚 ═══════════════════════════════════════════════════
101
- F I R S T E G G S L A I D
102
- ══════════════════════════════════════════════════ 🥚
103
-
104
- 👑 New colony goal:
105
- "{goal}"
106
-
107
- 📋 Session: {session_id}
108
- 🏆 Milestone: First Mound (v0.1.0)
109
-
110
- {If inherited knowledge:}
111
- 🧠 Inherited from prior colonies:
112
- {N} instinct(s) | {N} decision(s) | {N} learning(s)
113
- {End if}
114
-
115
- 🐜 The colony begins anew.
116
-
117
- /ant:plan 📋 Chart the course
118
- /ant:colonize 🗺️ Analyze existing code
175
+ A E T H E R R E A D Y
176
+ ═══════════════════════════════════════════════════ 🥚
177
+
178
+ {dirs} directories created
179
+ {core_files} core system files
180
+ {templates} templates
181
+ {utils} utility scripts
182
+ QUEEN.md: {status}
183
+
184
+ .aether/ is set up and ready for colony work.
185
+
186
+ ──────────────────────────────────────────────────
187
+ 🐜 Next Up
188
+ ──────────────────────────────────────────────────
189
+ /ant:init "your goal" 🌱 Start a colony
190
+ /ant:colonize 🗺️ Analyze existing code first
191
+ /ant:help 📖 See all commands
119
192
  ```
120
-
121
- Include edge case handling:
122
- - If no prior knowledge: omit the inheritance section
123
- - If prior colony had no phases: allow laying eggs without entombment
package/.opencode/commands/ant/seal.md CHANGED
@@ -134,6 +134,32 @@ Update COLONY_STATE.json:
134
134
  2. Set `milestone_updated_at` to current ISO-8601 timestamp
135
135
  3. Append event: `"<timestamp>|milestone_reached|archive|Achieved Crowned Anthill milestone - colony archived"`
136
136
 
137
+ ### Step 5.1: Update Changelog
138
+
139
+ **MANDATORY: Record the seal in the project changelog. This step is never skipped.**
140
+
141
+ If no `CHANGELOG.md` exists, `changelog-append` creates one automatically.
142
+
143
+ Build a summary of what the colony accomplished across all phases:
144
+ - Collect completed phase names from COLONY_STATE.json
145
+ - Summarize the goal and key outcomes in one line
146
+
147
+ ```bash
148
+ bash .aether/aether-utils.sh changelog-append \
149
+ "$(date +%Y-%m-%d)" \
150
+ "seal-crowned-anthill" \
151
+ "00" \
152
+ "{key_files_csv}" \
153
+ "Colony sealed at Crowned Anthill;{goal}" \
154
+ "{phases_completed} phases completed;Colony wisdom promoted to QUEEN.md" \
155
+ ""
156
+ ```
157
+
158
+ - `{key_files_csv}` — list the most significant files created or modified across the colony's lifetime (derive from phase plans or git log)
159
+ - `{goal}` — the colony goal from COLONY_STATE.json
160
+
161
+ **Error handling:** If `changelog-append` fails, log to midden and continue — changelog failure never blocks sealing.
162
+
137
163
  ### Step 5.5: Write Final Handoff
138
164
 
139
165
  After archiving, write the final handoff documenting the completed colony:
package/CHANGELOG.md CHANGED
@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.1.10] - 2026-02-26
11
+
12
+ ### Changed
13
+ - `lay-eggs` is now a pure bootstrap command — sets up `.aether/` in a repo from the global hub without starting a colony
14
+ - `init` now assumes Aether is already set up and focuses only on starting a colony with a goal
15
+ - All help files, rules, and workflow documentation updated to reflect the lay-eggs/init separation
16
+
10
17
  ## [1.1.5] - 2026-02-23
11
18
 
12
19
  ### Added
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aether-colony",
3
- "version": "1.1.8",
3
+ "version": "1.1.10",
4
4
  "description": "Multi-agent system using ant colony intelligence for Claude Code and OpenCode — workers self-organize via pheromone signals",
5
5
  "bin": {
6
6
  "aether": "bin/cli.js",