/goals — Fitness Goal Maintenance Maintain GOALS.yaml and GOALS.md fitness specifications. Use ao goals CLI for all operations. YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it. Quick Start /goals

Measure fitness (default)

/goals init

Bootstrap GOALS.md interactively

/goals steer

Manage directives

/goals add

Add a new goal

/goals drift

Compare snapshots for regressions

/goals history

Show measurement history

/goals export

Export snapshot as JSON for CI

/goals meta

Run meta-goals only

/goals validate

Validate structure

/goals prune

Remove stale gates

/goals migrate

Migrate YAML to Markdown

Format Support Format File Version Features YAML GOALS.yaml 1-3 Goals with checks, weights, pillars Markdown GOALS.md 4 Goals + mission + north/anti stars + directives When both files exist, GOALS.md takes precedence. Mode Selection Parse the user's input: Input Mode CLI Command /goals , /goals measure , "goal status" measure ao goals measure /goals init , "bootstrap goals" init ao goals init /goals steer , "manage directives" steer ao goals steer /goals add , "add goal" add ao goals add /goals drift , "goal drift" drift ao goals drift /goals history , "goal history" history ao goals history /goals export , "export goals" export ao goals export /goals meta , "meta goals" meta ao goals meta /goals validate , "validate goals" validate ao goals validate /goals prune , "prune goals", "clean goals" prune ao goals prune /goals migrate , "migrate goals" migrate ao goals migrate Measure Mode (default) — Observe Step 1: Run Measurement ao goals measure --json Parse the JSON output. Extract per-goal pass/fail, overall fitness score. Step 2: Directive Gap Assessment (GOALS.md only) If the goals file is GOALS.md format: ao goals measure --directives For each directive, assess whether recent work has addressed it: Check git log for commits mentioning the directive title Check beads/issues related to the directive topic Rate each directive: addressed / partially-addressed / gap Step 3: Report Present fitness dashboard: Fitness: 5/7 passing (71%) Gates: [PASS] build-passing (weight 8) [FAIL] test-passing (weight 7) └─ 3 test failures in pool_test.go Directives: 1. Expand Test Coverage — gap (no recent test additions) 2. Reduce Complexity — partially-addressed (2 refactors this week) Init Mode ao goals init Or with defaults: ao goals init --non-interactive Creates a new GOALS.md with mission, north/anti stars, first directive, and auto-detected gates. Error if file already exists. Steer Mode — Orient/Decide Step 1: Show Current State Run measure mode first to show current fitness and directive status. Step 2: Propose Adjustments Based on measurement: If a directive is fully addressed → suggest removing or replacing If fitness is declining → suggest new gates If idle rate is high → suggest new directives Step 3: Execute Changes Use CLI commands: ao goals steer add "Title" --description = "..." --steer = increase ao goals steer remove 3 ao goals steer prioritize 2 1 Add Mode Add a single goal to the goals file. Format-aware — writes to GOALS.yaml or GOALS.md depending on which format is detected. ao goals add < id

< check-command

--weight

5 --description = "..." --type = health Flag Default Description --weight 5 Goal weight (1-10) --description — Human-readable description --type — Goal type (health, architecture, quality, meta) Example: ao goals add go-coverage-floor "bash scripts/check-coverage.sh" --weight = 3 --description = "Go test coverage above 60%" Drift Mode Compare the latest measurement snapshot against a previous one to detect regressions. ao goals drift

Compare latest vs previous snapshot

Reports which goals improved, regressed, or stayed unchanged. History Mode Show measurement history over time for all goals or a specific goal. ao goals history

All goals, all time

ao goals history --goal go-coverage

Single goal

ao goals history --since 2026 -02-01

Since a specific date

ao goals history --goal go-coverage --since 2026 -02-01

Combined

Useful for spotting trends and identifying oscillating goals. Export Mode Export the latest fitness snapshot as JSON for CI consumption or external tooling. ao goals export Outputs the snapshot to stdout in the fitness snapshot schema (see references/goals-schema.md ). Meta Mode Run only meta-goals (goals that validate the validation system itself). Useful for checking allowlist hygiene, skip-list freshness, and other self-referential checks. ao goals meta --json See references/goals-schema.md for the meta-goal pattern. Validate Mode ao goals validate --json Reports: goal count, version, format, directive count, any structural errors or warnings. Prune Mode ao goals prune --dry-run

List stale gates

ao goals prune

Remove stale gates

Identifies gates whose check commands reference nonexistent paths. Removes them and re-renders the file. Migrate Mode Convert between goal file formats. ao goals migrate --to-md

Convert GOALS.yaml → GOALS.md

ao goals migrate

Migrate GOALS.yaml to latest YAML version

The --to-md flag creates a GOALS.md with mission, north/anti stars sections, and converts existing goals into the Gates table format. The original YAML file is backed up. Examples Checking fitness and directive gaps User says: /goals What happens: Runs ao goals measure --json to get gate results If GOALS.md format, runs ao goals measure --directives to get directive list Assesses each directive against recent work Reports combined fitness + directive gap dashboard Result: Dashboard showing gate pass rates and directive progress. Bootstrapping goals for a new project User says: /goals init What happens: Runs ao goals init which prompts for mission, stars, directives, and auto-detects gates Creates GOALS.md in the project root Result: New GOALS.md ready for /evolve consumption. Adding a new goal after a post-mortem User says: /goals add go-parser-fuzz "cd cli && go test -fuzz=. ./internal/goals/ -fuzztime=10s" --weight=3 --description="Markdown parser survives fuzz testing" What happens: Runs ao goals add with the provided arguments Writes the new goal in the correct format (YAML or Markdown) Result: New goal added, measurable on next /goals run. Troubleshooting Problem Cause Solution "goals file already exists" Init called on existing project Use /goals to measure, or delete file to re-init "directives require GOALS.md format" Tried steer on YAML file Run ao goals migrate --to-md first No directives in measure output GOALS.yaml doesn't support directives Migrate to GOALS.md with ao goals migrate --to-md Gates referencing deleted scripts Scripts were renamed or removed Run /goals prune to clean up Drift shows no history No prior snapshots saved Run ao goals measure at least twice first Export returns empty No snapshot file exists Run ao goals measure to create initial snapshot See Also /evolve — consumes goals for fitness-scored improvement loops references/goals-schema.md — schema definition for both formats references/generation-heuristics.md — goal quality criteria Reference Documents references/generation-heuristics.md references/goals-schema.md