Goals

/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
/goals trace              # Render/audit the executable-spec chain
/goals render             # Export directive scenarios as Gherkin

Format Support

When both files exist, GOALS.md takes precedence.

Mode Selection

Parse the user's input:

ao goals scenarios links each directive to behavioral scenarios (the ao scenario family) so GOALS.md is an executable BDD spec: bare lists every directive's linked scenarios with link health; --create "<goal>" --directive N scaffolds and bidirectionally links a scenario; --lint checks the link graph. See docs/adr/ADR-0003.

ao goals trace and ao goals render render and audit the executable-spec chain; ao goals steer recommend/apply drive the auto re-steer loop. Their contracts are documented in references/executable-spec-chain.md.

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 2b: Scenario Satisfaction (executable-spec fitness)

ao goals measure also gates on scenario satisfaction — the fraction of a directive's linked behavioral scenarios that currently pass. Each directive in the --json / --directives output carries a scenario_satisfaction block:

"scenario_satisfaction": {
  "linked": 4,            // scenarios linked to this directive
  "satisfied": 3,         // scenarios whose latest result is PASS
  "ratio": 0.75,          // satisfied / linked
  "threshold": 0.8,       // directive's required ratio
  "status": "RED"         // GREEN | YELLOW | RED — RED when ratio < threshold
}

A directive below its threshold is RED and drags overall fitness down.

Use --scenarios-only to evaluate just the executable-spec layer and skip the shell gate-command execution — fast feedback while iterating on scenarios:

ao goals measure --scenarios-only -o json

Scenario results are read from the scenario result artifacts (see ao scenario family); the exact aggregation path and exit-code semantics are in references/executable-spec-chain.md.

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.

Post-Init Enrichment

After ao goals init creates the scaffold, enrich it with product-aware content that the CLI cannot auto-detect:

Enrich North Stars with Outcomes

Review the generated north stars. If they are all feature-focused (e.g., "skills work across 4 runtimes"), nudge toward outcome-focused stars:

• Feature-focused (weaker): "Skills work across 4 runtimes"
• Outcome-focused (stronger): "A new user goes from install to first validated workflow in under 5 minutes"

Ask the user: "Your north stars describe features. What user outcome would tell you the product is actually working?" Add at least one outcome-focused star.

Enrich Anti-Stars from Failure Modes

Scan for proven failure patterns: 1. Check .agents/retro/ — extract failure themes from retrospectives 2. Check .agents/council/ or council index — look for FAIL verdicts and their root causes 3. Check .agents/learnings/ — look for learnings tagged as anti-patterns

Convert the top 3 most common failure modes into anti-stars. Examples from real data:

• "Product promises with no automated verification" (from council FAILs where claims had no gates)
• "Goals that measure code metrics instead of user outcomes" (from retros where passing gates didn't improve product)
• "Capture without compounding" (from flywheel analysis where knowledge was stored but never retrieved)

If no .agents/ data exists, use the defaults from ao goals init.

Add Product Directives

The CLI generates engineering-flavored directives (test coverage, complexity, lint). After init, also suggest product/growth directives by asking:

1. "What's your biggest product gap right now?" → directive with steer: decrease 2. "What user behavior do you want to increase?" → directive with steer: increase 3. "What metric would tell you the product is working?" → directive with measurable target

Product directives sit alongside engineering ones in the same ## Directives section. See references/generation-heuristics.md for product directive patterns.

Add Product Gates

Check what product infrastructure exists and suggest appropriate gates:

Only suggest gates for infrastructure that actually exists. Don't create gates for aspirational features.

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

Product-aware steering: Also check for product dimension gaps:

• If all directives are engineering-flavored (test, lint, build, refactor) → suggest at least one product/growth directive
• If no directive cites a specific metric → flag: "Vague directives are a smell. Can any of these reference a specific number?"
• If .agents/retro/ has new failure patterns not represented in anti-stars → suggest adding them
• If PRODUCT.md has Known Gaps not covered by any directive → suggest a directive to close the gap

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

Step 4: Auto Re-Steer (F5) — chronic failure mutates the directive

When a directive's scenarios fail chronically, the re-steer engine recommends a directive mutation from the verdict ledger:

ao goals steer recommend                 # show recommendations; GOALS.md untouched
ao goals steer apply                     # apply the top recommendation (human-gated)
ao goals steer apply --auto --yes        # non-interactive consent for scripts
ao goals steer apply --policy docs/re-steer-policy.json

recommend is read-only — it runs the policy engine over the verdict ledger and prints recommended mutations plus skip reasons. apply mutates GOALS.md only when the policy's auto_apply is true and the operator confirms (interactive prompt, or --auto/--yes for scripts). Every mutation routes through the non-lossy directive-block patcher — never a full re-render. Policy, ledger, and human-gate semantics: references/executable-spec-chain.md and docs/adr/ADR-0006.

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

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.

Trace Mode (F4) — render and audit the executable-spec chain

ao goals trace renders the directive → scenario → bead → verdict → learning lineage and audits it for defects:

ao goals trace --from d-fitness-gate-bdd        # lineage tree from a directive
ao goals trace --from s-2026-05-17-001 -o json  # line-delimited JSON graph
ao goals trace --orphans                         # whole-chain gap audit
ao goals trace --orphans --strict                # warnings also fail (exit 1)

• --from <id> roots the trace at any directive, scenario, or bead ID.
• --orphans audits the whole chain: broken references are errors (always

non-zero exit), missing yields are warnings.

• --strict escalates warning-class defects to a non-zero exit (ADR-0005 §4.2).

Stable directive IDs (d-...) are the link anchors — never display numbers. The link grammar is docs/adr/ADR-0005.

Render Mode (F4) — export Gherkin feature files

ao goals render exports the directive-linked scenarios as a Gherkin feature file so the executable spec can be consumed by external BDD tooling:

ao goals render                       # print Gherkin to stdout
ao goals render --out spec.feature     # write Gherkin to a file

Examples

Checking fitness and directive gaps

User says: /goals

What happens: 1. Runs ao goals measure --json to get gate results 2. If GOALS.md format, runs ao goals measure --directives to get directive list 3. Assesses each directive against recent work 4. 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: 1. Runs ao goals init which prompts for mission, stars, directives, and auto-detects gates 2. 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: 1. Runs ao goals add with the provided arguments 2. Writes the new goal in the correct format (YAML or Markdown)

Result: New goal added, measurable on next /goals run.

Troubleshooting

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/goals.feature — Executable spec: measure gates → verdict, directives steering, GOALS.md source-of-truth, measurement-root (soc-qk4b)
• references/generation-heuristics.md
• references/goals-schema.md
• references/executable-spec-chain.md

Executable-Spec Chain — Reference

Detailed contracts for the executable-spec layer of ao goals: scenario satisfaction (F2), trace/render (F4), and auto re-steer (F5). The goals SKILL.md links here; this file holds the precise schemas and exit-code rules.

Scenario satisfaction (F2)

ao goals measure aggregates the latest result of every behavioral scenario linked to a directive and computes a satisfaction ratio. The producer reads scenario result artifacts written by the ao scenario family.

scenario_satisfaction JSON shape

Every directive object in ao goals measure --json and ao goals measure --directives carries:

"scenario_satisfaction": {
  "linked": 4,         // count of scenarios linked to the directive
  "satisfied": 3,      // count whose latest result artifact is PASS
  "ratio": 0.75,       // satisfied / linked (0.0 when linked == 0)
  "threshold": 0.8,    // directive's required ratio (default in policy)
  "status": "RED"      // GREEN (ratio >= threshold)
                       // YELLOW (linked == 0 — nothing to satisfy yet)
                       // RED (ratio < threshold)
}

--scenarios-only

ao goals measure --scenarios-only evaluates ONLY the executable-spec layer and skips shell gate-command execution. Use it for fast iteration on scenarios without paying for the full gate suite. Combine with -o json for CI.

Result-artifact resolution order

Scenario results are resolved from result artifacts (ADR-0003 durability contract):

1. Promoted spec scenarios — tracked spec/scenarios/. 2. Ad hoc holdout scenarios — .agents/holdout/<id>.json.

Exit-code semantics

Trace and render (F4)

ao goals trace

Renders and audits the directive → scenario → bead → verdict → learning chain.

• --from <id> — render the lineage tree rooted at a directive (d-...),

scenario (s-...), or bead ID. Add -o json for a line-delimited JSON graph.

• --orphans — audit the whole chain. Broken references are errors;

missing downstream yields (e.g. a scenario with no verdict) are warnings.

• --strict — escalate warning-class defects to a non-zero exit (ADR-0005

§4.2). Errors always exit non-zero regardless of --strict.

Link anchors are stable directive IDs (^d-[a-z0-9][a-z0-9-]*$) — never the display numbers, which are not stable across edits. The full link grammar and defect taxonomy are in docs/adr/ADR-0005.

ao goals render

Exports directive-linked scenarios as a Gherkin .feature file:

• bare — print Gherkin to stdout.
• --out <path> — write the Gherkin to a file instead.

Auto re-steer (F5)

When a directive's scenarios fail chronically, the re-steer engine recommends a directive mutation. This is the last and most safety-gated part of the chain.

ao goals steer recommend

Read-only. Runs the re-steer policy engine over the verdict ledger and prints recommended directive mutations plus skip reasons. GOALS.md is never modified.

ao goals steer apply

Applies the top recommendation to GOALS.md. Two conditions must BOTH hold:

1. The policy's auto_apply is true. 2. The operator confirms — interactive prompt, or --auto / --yes for non-interactive scripted consent.

A run without confirmation never changes GOALS.md. Every mutation routes through the non-lossy directive-block patcher (cli/internal/goals/patcher.go) — never RenderGoalsMD / WriteMDGoals, which are lossy full re-renders.

• --policy <path> — re-steer policy file (default docs/re-steer-policy.json).
• --auto / --yes — pre-confirm for non-interactive use.

Policy schema, verdict-ledger format, mutation-safety invariants, and the human-gate contract are in docs/adr/ADR-0006.

Goal Generation Heuristics

Goal Quality Criteria

A good goal:

1. Mechanically verifiable — check is a shell command that exits 0 (pass) or non-zero (fail). No human judgment required. 2. Descriptive — description says what it measures, not how. "Go CLI compiles without errors" not "run go build". 3. Weighted by impact — 5 = build/test integrity, 3-4 = feature fitness, 1-2 = hygiene. 4. Pillar-mapped — Maps to one of: knowledge-compounding, validated-acceleration, goal-driven-automation, zero-friction-workflow. Infrastructure goals omit pillar. 5. Not trivially true — Check can actually fail in a realistic scenario. test -f README.md is trivially true. 6. Not duplicative — No two goals test the same thing. Check existing IDs before proposing.

Scan Sources

Theoretical Pillar Coverage

Generate mode should check that all 4 theoretical pillars have goals:

1. Systems Theory (Meadows)

Targets leverage points #3-#6 (information flows, rules, self-organization, goals). Goals should verify that the system operates at these leverage points rather than lower ones (parameters, buffers).

2. DevOps (Three Ways)

• Flow maps to zero-friction-workflow and goal-driven-automation
• Feedback maps to validated-acceleration
• Continual Learning maps to knowledge-compounding

Goals should cover all three ways.

3. Brownian Ratchet

The pattern: chaos + filter + ratchet = directional progress from undirected energy. Goals should verify:

• Chaos source exists (agent sessions generate varied outputs)
• Filter exists (council validates, vibe checks)
• Ratchet exists (knowledge flywheel captures and persists gains)

4. Knowledge Flywheel

Escape velocity condition: signal_rate x retrieval_rate > decay_rate (informally: you learn faster than you forget). Goals should verify:

• Signal generation (extract, forge, retro produce learnings)
• Retrieval (inject loads learnings into sessions)
• Decay resistance (learnings are persisted, not just in-memory)

Weight Guidelines

ID Conventions

• Use kebab-case: go-cli-builds, readme-compounding-hero
• Prefix with domain: readme-, go-, skill-, hook-
• Keep under 40 characters
• Must be unique across all goals

Directive Quality Criteria

When generating or evaluating directives for GOALS.md:

1. Actionable — Describes work that can be decomposed into issues. "Expand test coverage" not "Be better at testing." 2. Steerable — Has a clear direction (increase/decrease/hold/explore). If you can't assign a steer, it's too vague. 3. Measurable progress — You can tell whether work addressed it (even if not fully completed). 4. Not a gate — Directives describe intent, not pass/fail thresholds. "Reduce complexity" is a directive; "complexity < 15" is a gate. 5. Prioritized — Lower number = higher priority. Directive 1 is worked before directive 2. 6. Evidence-grounded — Every directive SHOULD cite a specific metric or finding that motivated it. Vague directives ("improve testing") are a smell. Good: "Close the multi-runtime promise gap — runtime-specific tests are quarantined (8 dirs in tests/_quarantine/)". Bad: "Ship more tests." 7. Balanced across dimensions — A healthy directive set includes both engineering directives (test, build, refactor) and product/growth directives (onboarding, adoption, user outcomes). If all directives are engineering-flavored, the goals file is incomplete.

Steer Values

Directive-Gate Relationship

Directives generate gates over time:

• Directive "Expand test coverage" → Gate test-coverage-floor (check: coverage > 80%)
• Directive "Reduce complexity" → Gate complexity-budget (check: gocyclo -over 15 = 0 findings)

When a directive is fully addressed (gate exists and passes), consider removing the directive and keeping the gate.

Product Directive Patterns

Engineering directives target code quality. Product directives target user outcomes. A complete GOALS.md needs both.

Product Directive Examples

How to Generate Product Directives

1. Check PRODUCT.md — if Known Gaps section exists, each gap is a candidate directive 2. Check install/onboarding paths — untested install = highest-risk product gap 3. Check user-facing promises — README claims without verification = directive candidates 4. Check retention infrastructure — knowledge flywheel, session handoff, learning retrieval 5. Ask the user — "What's your biggest product gap?" and "What metric would tell you the product is working?"

Evidence Sources for Grounding Directives

When writing directives, cite specific data when available:

Anti-Star Generation

Anti-stars define what the project explicitly avoids. The best anti-stars come from proven failure modes, not hypothetical bad practices.

Auto-Discovery

Scan these sources for failure patterns to convert into anti-stars:

1. `.agents/retro/` — recurring themes in retrospectives (e.g., "scope bundling caused 3 failed epics") 2. Council FAIL verdicts — root causes from .agents/council/ or council index (e.g., "missing mechanical verification" → anti-star: "Product promises with no automated verification") 3. `.agents/learnings/` — learnings tagged as anti-patterns or mistakes

Conversion Pattern

Fallback

If no .agents/ data exists, use generic anti-stars:

• "Shipping without validation"
• "Measuring activity instead of outcomes"
• "Optimizing for metrics that don't correlate with user value"

North Star Quality

North stars should describe outcomes, not features.

When reviewing north stars, ask: "If this star is achieved, does a user's life actually improve?" If the answer is "only if other things also happen," the star is too narrow.

Product Gate Patterns

Product gates verify product health alongside code health. Suggest gates based on what infrastructure exists:

Only suggest product gates for infrastructure that actually exists in the project. Don't create aspirational gates — they'll just fail and get ignored.

GOALS.yaml Schema

version: 1
mission: "What this repo does"

goals:
  - id: unique-identifier
    description: "Human-readable description"
    check: "shell command — exit 0 = pass, non-zero = fail"
    weight: 1-10  # Higher = fix first

Goals are checked in weight order (highest first). The first failing goal with the highest weight is selected for improvement.

Fitness Snapshot Format

Each cycle writes a fitness snapshot with continuous values (not just pass/fail):

{
  "cycle": 1,
  "timestamp": "2026-02-12T15:45:00-05:00",
  "cycle_start_sha": "abc1234",
  "goals": [
    {
      "id": "go-coverage-floor",
      "result": "pass",
      "weight": 2,
      "value": 86.1,
      "threshold": 80
    },
    {
      "id": "doc-coverage",
      "result": "pass",
      "weight": 2,
      "value": 20,
      "threshold": 16
    },
    {
      "id": "go-cli-builds",
      "result": "pass",
      "weight": 5,
      "value": null,
      "threshold": null
    }
  ]
}

• value: The continuous metric extracted from the check command (null for binary-only goals)
• threshold: The pass/fail threshold (null for binary-only goals)
• cycle_start_sha: Git SHA at cycle start, used for multi-commit revert on regression

Pre-cycle snapshot: fitness-latest.json (rolling, overwritten each cycle) Post-cycle snapshot: fitness-latest-post.json (rolling, for regression comparison)

Cycle-0 Baseline

Before the first improvement cycle in a goal era runs, evolve captures a baseline fitness snapshot under .agents/evolve/fitness-baselines/goals-<hash>/, where <hash> is derived from the active GOALS.md or GOALS.yaml content. This serves as the comparison anchor for measuring session-wide progress.

The baseline includes:

• All goals from GOALS.yaml, measured in their initial state
• Cycle-0 report (cycle-0-report.md) — summary of which goals are failing and their weights
• No regression comparisons — this is the starting point

When the session ends (at Teardown), the system computes the session fitness trajectory by comparing the baseline against the final cycle snapshot. This produces session-fitness-delta.md, which shows which goals improved, regressed, or stayed unchanged over the entire /evolve session.

Meta-Goals

Meta-goals validate the validation system itself. Use them to prevent exception lists (allowlists, skip lists) from accumulating stale entries unnoticed.

# Meta-goals validate the validation system itself
goals:
  - id: allowlist-hygiene
    description: "Every dead-code allowlist entry should have 0 non-test callers"
    check: "bash scripts/check-allowlist-hygiene.sh"
    weight: 7

  - id: skip-list-hygiene
    description: "Every skip-list entry should still reference an existing test"
    check: "bash scripts/check-skip-list-hygiene.sh"
    weight: 5

When to add a meta-goal: After pruning any allowlist or exception list, always add a corresponding meta-goal that fails if entries have callers/references. Allowlists without meta-goals are technical debt magnets — they grow silently across epics.

Maintaining GOALS.yaml

Use /goals to maintain the fitness specification:

• /goals — run all checks, report pass/fail by pillar
• /goals generate — scan repo for uncovered areas, propose new goals
• /goals prune — find stale/broken goals, propose removals or updates

GOALS.md Format (Version 4)

GOALS.md extends the YAML format with strategic intent sections:

# Goals

<Mission statement — one sentence. Describes outcomes, not features.>

## North Stars

- <Outcome-focused aspiration — what improves for users if this is achieved>
- <At least one star should describe a measurable user outcome>

## Anti Stars

- <What we explicitly avoid — best when derived from proven failure modes>
- <Each anti-star should reference a real failure pattern if .agents/ data exists>

## Directives

### 1. <Title — evidence-grounded>

<Description citing specific metrics or findings that motivated this directive.
 Good: "Close the multi-runtime promise gap — 8 test dirs quarantined in tests/_quarantine/"
 Bad: "Improve test coverage">

**Steer:** increase | decrease | hold | explore
<Steer target should name the specific metric being steered, e.g., "increase (install scripts with smoke tests)">

### 2. <Title>

<Description — mix of engineering AND product/growth directives>

**Steer:** <direction> (<metric being steered>)

## Gates

| ID | Check | Weight | Description |
|----|-------|--------|-------------|
| build-passing | `cd cli && make build` | 8 | CLI builds without errors |
| test-passing | `cd cli && make test` | 7 | All unit tests pass |

Directive Dimensions

A healthy GOALS.md includes directives across multiple dimensions:

If all directives fall in one dimension, the goals file is incomplete.

Gate Dimensions

Similarly, gates should cover both code health and product health:

Key Differences from YAML

CLI Commands

ao goals measure                  # Measure gates (both formats)
ao goals measure --directives     # Output directives as JSON
ao goals validate                 # Validate structure
ao goals init                     # Bootstrap GOALS.md interactively
ao goals steer add <title>        # Add directive
ao goals steer remove <number>    # Remove directive
ao goals steer prioritize <n> <p> # Reorder directive
ao goals migrate --to-md          # Convert YAML → Markdown
ao goals prune                    # Remove stale gates

Format Auto-Detection

LoadGoals() auto-detects format: 1. .md extension → markdown parser 2. .yaml/.yml extension → check if GOALS.md exists alongside → prefer markdown 3. Default GOALS.yaml path → check if GOALS.md exists → prefer markdown