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

| 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 | | /goals scenarios, "directive scenarios", "link a scenario" | scenarios | ao goals scenarios | | /goals trace, "trace lineage", "orphan audit" | trace | ao goals trace | | /goals render, "export gherkin", "feature file" | render | ao goals render |

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:

| Infrastructure | Suggested Gate | |---------------|----------------| | .agents/learnings/ exists | flywheel-compounding — knowledge above escape velocity | | skills/quickstart/ exists | quickstart-under-5min — onboarding time gate | | docs/comparisons/ exists | competitive-freshness — comparison docs updated within 45 days | | PRODUCT.md exists | product-gaps-tracked — Known Gaps section has entries | | ao flywheel status works | flywheel-promotion-rate — learnings promoted above threshold |

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

Steer Mode — Orient/Decide

Step 1