Menu
Colony health diagnostics and repair — healthy state specifications for all colony data files, failure modes, and remedies
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when Codex is asked to colonize, plan, build, continue, swarm, or seal an Aether colony and must mirror wrapper orchestration safely
Use when Codex is asked to initialize or set up an Aether colony and should refine intent before running init
Use when Codex is asked to run Aether Oracle or discuss flows and should refine scope before research or clarification
Use when acceptance criteria need unit, integration, or end-to-end tests generated from implementation context
Use when delivered functionality needs acceptance-criteria verification before a phase advances
Use when a phase involves LLMs, AI agents, RAG, ML inference, or prompt/tool integration design
| source | shipped |
| name | medic |
| description | Colony health diagnostics and repair — healthy state specifications for all colony data files, failure modes, and remedies |
| type | colony |
| domains | ["health","diagnostics","repair","data-integrity","validation"] |
| agent_roles | ["builder","watcher","medic"] |
| priority | normal |
| version | 1.0 |
This skill defines what healthy colony data looks like. Workers should reference this when modifying colony state files or diagnosing colony issues. The Medic worker (aether medic) uses these rules to scan for problems and repair them.
| Field | Type | Required | Valid Values |
|---|---|---|---|
| version | string | yes | "3.0" |
| goal | *string | yes | non-empty string |
| state | State | yes | IDLE, READY, EXECUTING, BUILT, COMPLETED |
| scope | ColonyScope | yes | "project", "meta" |
| current_phase | int | yes | >= 0 |
| colony_version | int | no | starts at 1 |
| session_id | *string | no | format: {unix}_{hex} |
| parallel_mode | ParallelMode | no | "in-repo", "worktree" |
| paused | bool | no | only valid when state is READY |
| milestone | string | no | milestone name |
| worktrees | []WorktreeEntry | no | each has status field |
| signals | []Signal | deprecated | should be empty — migrated to pheromones.json |
| events | []string | no | pipe-delimited: timestamp|type|source|description |
| plan | Plan | no | phases with PhaseStatus and tasks |
| memory | Memory | no | instincts, learnings, errors |
Legal transitions (from pkg/colony/colony.go:490):
state is EXECUTING, current_phase must be > 0paused is true, state should be READYparallel_mode is "worktree", worktrees array should be maintained| Failure | Severity | Detection |
|---|---|---|
| Missing or empty goal | critical | goal field nil or empty |
| Invalid state value | critical | not in IDLE/READY/EXECUTING/BUILT/COMPLETED |
| EXECUTING with phase 0 | warning | state mismatch |
| Paused but not READY | warning | flag/state conflict |
| Deprecated signals present | warning | signals array non-empty |
| Orphaned worktrees | warning | status="orphaned" entries |
| Invalid parallel_mode | warning | not "in-repo" or "worktree" |
| Malformed event entries | warning | missing pipe delimiters |
| Legacy state strings | warning | PAUSED/PLANNED/SEALED/ENTOMBED |
normalizeLegacyColonyState() in cmd/state_load.go| Field | Type | Required | Valid Values |
|---|---|---|---|
| id | string | yes | unique identifier |
| type | PheromoneType | yes | FOCUS, REDIRECT, FEEDBACK |
| active | bool | yes | true/false |
| content | json.RawMessage | yes | valid JSON (supports nested objects) |
| created_at | string | yes | parseable timestamp |
| expires_at | *string | no | parseable timestamp |
| content_hash | *string | no | SHA-256 for dedup |
| strength | *float64 | no | 0.0-1.0 |
| priority | string | no | "normal", "high", "low" |
json.RawMessage, NOT a plain string{"text": "..."}SanitizeSignalContent())| Failure | Severity | Detection |
|---|---|---|
| Missing signal ID | warning | id field empty |
| Invalid signal type | warning | not FOCUS/REDIRECT/FEEDBACK |
| Expired but still active | warning | expires_at past, active=true |
| Duplicate content hash | warning | same hash with different IDs |
| Invalid content JSON | critical | content not valid JSON |
sig_{unix}_{4hex}| Field | Type | Required | Notes |
|---|---|---|---|
| session_id | string | yes | unique session identifier |
| started_at | string | yes | parseable timestamp |
| colony_goal | string | yes | should match COLONY_STATE goal |
| current_phase | int | yes | should match COLONY_STATE current_phase |
| current_milestone | string | no | milestone name |
| suggested_next | string | no | next recommended command |
| context_cleared | bool | no | whether context was cleared |
| baseline_commit | string | no | git commit hash |
| last_command | string | no | last command run |
| last_command_at | string | no | timestamp of last command |
| active_todos | []string | no | active todo items |
| summary | string | no | session summary |
current_phase must match COLONY_STATE.json current_phasecolony_goal must match COLONY_STATE.json goal| Failure | Severity | Detection |
|---|---|---|
| Phase mismatch with COLONY_STATE | warning | values differ |
| Goal mismatch with COLONY_STATE | warning | strings differ |
| Missing session_id | warning | field empty |
| Invalid started_at | warning | not parseable |
| Stale session | warning/critical | >7d or >30d |
/ant-resume to refresh.aether/data/midden/midden.json (subdirectory — different from other data files)MiddenFile with archived_signals, entries, spawn_metrics--forceInstinctsFile with entries (trigger, action, domain, trust_score, confidence, provenance)Instinct in ColonyState.Memory and rich InstinctEntry here--forceLearningFile with observations (content_hash, content, wisdom_type, trust_score)--forceAssumptionsFile with assumptions (id, phase, category, confidence, validated)--forceFlagsFile with entries (id, type, description, resolved)--force{}, content is ignored by all Go code{} (empty object){}.cache_COLONY_STATE.json — expected, auto-rebuilt by runtime.cache_instincts.json — expected, auto-rebuilt by runtimeTraceEntry (id, run_id, timestamp, level, topic, payload, source)pkg/trace/rotate.go)ReadJSONL; rotation is automaticEvent (id, topic, payload, source, timestamp, ttl_days, expires_at)SpawnEntry rows| Surface | Count | Path |
|---|---|---|
| YAML commands | 50 | .aether/commands/*.yaml |
| Claude commands | 50 | .claude/commands/ant/*.md |
| OpenCode commands | 50 | .opencode/commands/ant/*.md |
| Claude agents | 25 | .claude/agents/ant/*.md |
| OpenCode agents | 25 | .opencode/agents/*.md |
| Codex agents | 25 | .codex/agents/*.toml |
| Claude mirror | 25 | .aether/agents-claude/*.md |
| Codex mirror | 25 | .aether/agents-codex/*.toml |
| Colony skills | 11 | .aether/skills/colony/*/SKILL.md |
| Domain skills | 18 | .aether/skills/domain/*/SKILL.md |
aether updateaether install to regenerate wrappers from YAML sources.aether/commands/*.yaml as source of truth| Surface | Count | Path |
|---|---|---|
| Hub Claude commands | 50 | ~/.aether/system/commands/claude/*.md |
| Hub OpenCode commands | 50 | ~/.aether/system/commands/opencode/*.md |
| Hub OpenCode agents | 25 | ~/.aether/system/agents/*.md |
| Hub Codex agents | 25 | ~/.aether/system/codex/*.toml |
| Hub Codex skills | 29 | ~/.aether/system/skills-codex/*/*/SKILL.md |
aether update --force reports Commands (claude) — 0 copied, 0 unchangedaether update --force reports Commands (opencode) — 0 copied, 0 unchangedaether update --force reports fewer than 25 OpenCode agentsaether publish from the Aether repo (builds binary, syncs hub, verifies version agreement), then aether update --force in target repos. aether install --package-dir "$PWD" also works as backward-compatible fallbackaether publish --channel dev --binary-dest "$HOME/.local/bin" from the Aether repo, then aether-dev update --force in target repos. go run ./cmd/aether install --channel dev --package-dir "$PWD" --binary-dest "$HOME/.local/bin" also works as fallbackaether install itself: bootstrap with go run ./cmd/aether install --package-dir "$PWD" --binary-dest "$HOME/.local/bin"aether update --force --download-binarynpx --yes aether-colony@latestaether medic --deep includes release integrity scanning via scanIntegrity() which checks binary/hub version agreement and stale publish classification. Issues surface with severity and recovery commands inline.aether integrity is the dedicated command for full release pipeline validation. Auto-detects source vs consumer repo context. Source repos get 5 checks (source version, binary version, hub version, companion files, downstream simulation); consumer repos get 4 checks (binary version, hub version, companion files, downstream simulation). Flags: --json (machine-readable output), --channel stable|dev (override channel), --source (force source-repo checks). Cross-reference the operations guide for full workflow documentation..aether/version.json is the source-checkout release version filenpm/package.json version must equal .aether/version.jsonREADME.md, npm/README.md, AGENTS.md, CLAUDE.md, .codex/CODEX.md, .opencode/OPENCODE.md, RUNTIME UPDATE ARCHITECTURE.md, .aether/docs/publish-update-runbook.md, CHANGELOG.md, and roadmap docs should agree on the install/update storynpx --yes aether-colony@latest should resolve to the same stable version as the current GitHub releasenpm/README.md in the published package, not the root repo READMEnpm/README.md in git is not enoughaether update --force, local aether version, and npm bootstrap verification as part of release integrityaether + ~/.aether/; dev/maintainer runtime uses aether-dev + ~/.aether-dev/gh run list --workflow Release shows no run and gh release view vX.Y.Z shows no release, report that the GitHub release did not materialize and recommend gh workflow run Release -f tag=vX.Y.Z firstgh workflow run Release -f tag=vX.Y.Z returns HTTP 422: Actions has been disabled for this user, report that as a GitHub Actions actor/policy failure and recommend another maintainer or the local GoReleaser fallbackexport GITHUB_TOKEN=\"$(gh auth token)\" && goreleaser release --clean before npm publishgit push --tags as a release risk. Push a single annotated release tag insteadversion field is "3.0" (string).aether/version.json; installed/runtime detection uses ldflags or the hub version