goals

SKILL.md

/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:

Check .agents/retro/ — extract failure themes from retrospectives

Check .agents/council/ or council index — look for FAIL verdicts and their root causes

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:

"What's your biggest product gap right now?" → directive with steer: decrease

"What user behavior do you want to increase?" → directive with steer: increase

"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: 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

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.

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:

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/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