| source | shipped |
| name | colony-lifecycle |
| description | Use when producing command output, handling state transitions, or routing users to the next action in the colony workflow |
| type | colony |
| domains | ["lifecycle","routing","workflow","state"] |
| agent_roles | ["builder","watcher","route_setter","architect"] |
| priority | normal |
| version | 1.0 |
Colony Lifecycle
Purpose
Every command must leave the user with a clear next action. No dead ends. The colony has a defined state machine, and every output must orient the user within it.
Literal CLI Commands
When the user message is already a literal aether ... command, treat it as an instruction to run that command directly.
- Do not inspect repo files first to infer what the command "might mean".
- Use
aether --help or aether <subcommand> --help only to confirm availability or flags.
- Treat the installed
aether binary as the source of truth if docs and runtime disagree.
- If the binary does not expose a documented command, say so plainly and follow the binary's actual command surface.
- When invoking lifecycle commands through Codex shell execution, prefer
AETHER_OUTPUT_MODE=visual aether ... unless the user explicitly wants JSON.
- Do not prepend exploratory narration like "I'm checking the repo" or "I'm treating this as..." before a literal command.
- If the
aether CLI already rendered the result, do not restate the same guidance in a second synthetic "Next Up" block.
State Machine
The colony progresses through these states in order:
IDLE -> READY -> PLANNING -> EXECUTING -> SEALED -> ENTOMBED -> IDLE
The authoritative runtime values in COLONY_STATE.json are IDLE, READY,
EXECUTING, BUILT, and COMPLETED. Terms like "planning", "sealed", and
"entombed" describe lifecycle moments and next steps, not always literal
persisted state values.
| State | Meaning | Entered By | Next Action |
|---|
| IDLE | No active colony | Default / after entomb | /ant-init or aether init |
| READY | Colony initialized, no plan | /ant-init or aether init | /ant-plan or aether plan |
| PLANNING | Plan being generated | /ant-plan or aether plan | /ant-build 1 or aether build 1 |
| EXECUTING | Phases being built | /ant-build or aether build | /ant-continue or aether continue |
| SEALED | Colony marked complete | /ant-seal or aether seal | /ant-entomb or aether entomb |
| ENTOMBED | Colony archived | /ant-entomb or aether entomb | /ant-init or aether init (new goal) |
Next Up Block
Every command output must end with a "Next Up" block. This block tells the user exactly what to do next based on the current state.
Format
━━ N E X T U P ━━
Run /ant-continue or `aether continue` to verify work and advance to the next phase.
Rules
- Always include the exact command to run, with any arguments.
- If multiple valid next actions exist, list the primary one first, then alternatives.
- Match the Next Up to the current state -- never suggest a command that is invalid for the current state.
- After seal, suggest entomb. After entomb, suggest init with a new goal.
- Never output a command result without a Next Up block.
State-Specific Next Up Examples
| Current State | Primary Next Up | Alternatives |
|---|
| READY | /ant-plan or aether plan | /ant-colonize or aether colonize (if existing code) |
| PLANNING | /ant-build 1 or aether build 1 | /ant-focus or aether focus / /ant-redirect or aether redirect (to set signals first) |
| EXECUTING (just built) | /ant-continue or aether continue | /ant-status or aether status (to review) |
| EXECUTING (just verified) | /ant-build N+1 or aether build N+1 | /ant-seal or aether seal (if last phase) |
| SEALED | /ant-entomb or aether entomb | -- |
| ENTOMBED | /ant-init "new goal" or aether init "new goal" | -- |
Routing and Autopilot Guardrails
When user intent is freeform, classify it before acting:
- Small, well-defined task: route to a quick build path with normal verification.
- Ambiguous idea: route to discuss, assumption surfacing, or spec refinement.
- Existing active phase with completed build evidence: route to continue.
- Failed or inconsistent state: route to medic or a repair/reconcile action, not a blind retry.
- Multi-phase autonomous work: continue only while the next step is deterministic and stop when a real user decision is needed.
Do not let "autopilot" bypass lifecycle gates. It may chain valid steps, but each step must still leave state, evidence, and Next Up output consistent.
Command Chaining Awareness
Commands feed into each other. When producing output, be aware of what the previous command was and what the next one expects:
init creates state that plan reads.
plan creates phases that build executes.
build creates artifacts that continue verifies.
continue advances state that the next build reads.
If a command detects that prerequisite state is missing (e.g., build called with no plan), display a clear error explaining what to run first, not a cryptic failure message.
Dead End Prevention
Before finalizing any command output, check: "Does this output end with a Next Up block?" If not, add one. There are zero valid cases where a command should leave the user without guidance on what to do next.