---
name: performance-goal
description: Evaluator-gated performance optimization workflow with durable Omagy artifacts for agy.
argument-hint: "<objective with evaluator command/contract>"
---

# Omagy Performance Goal

Use `/omagy:performance-goal` when the user asks Omagy to optimize speed,
latency, throughput, memory, allocations, benchmark results, or another
measurable performance target and wants a goal-oriented evaluator loop rather
than a one-off review.

## Contract

- Omagy owns durable workflow state under `.omagy/goals/performance/<slug>/`.
- `omagy performance-goal start` emits a model-facing agy handoff; it does not
  secretly mutate a native agy goal.
- agy native goal APIs are not assumed. Until agy exposes a stable native goal
  API, `agy_goal_adapter:"artifact"` and `native_goal_parity:false` are the
  truth.
- Do not complete the performance goal until the evaluator has a passing
  checkpoint and a completion audit proves the objective is done.
- If a host goal snapshot is available, pass it with `--host-goal-json`; if it
  is unavailable, the Omagy artifact state remains the source of truth.

## Commands

```bash
omagy performance-goal create \
  --objective "Reduce startup latency by 20%" \
  --evaluator-command "npm run perf:startup" \
  --evaluator-contract "PASS when p95 startup latency improves by 20% and regression tests pass." \
  --slug startup-latency

omagy performance-goal start --slug startup-latency

omagy performance-goal checkpoint --slug startup-latency --status pass --evidence "benchmark + tests passed"
omagy performance-goal checkpoint --slug startup-latency --status fail --evidence "benchmark regressed"
omagy performance-goal checkpoint --slug startup-latency --status blocked --evidence "missing fixture"

omagy performance-goal complete --slug startup-latency --evidence "final evaluator evidence"
omagy performance-goal complete --slug startup-latency --evidence "final evaluator evidence" --host-goal-json '<json-or-path>'
```

## Workflow

1. Create the performance goal if no workflow exists.
2. Start the goal and follow the handoff. Treat the evaluator command and
   pass/fail contract as the optimization target.
3. Run the evaluator before and after relevant changes. Record every meaningful
   pass, fail, or blocker with `checkpoint`.
4. Iterate until the evaluator passes and the implementation has no known
   correctness regression.
5. Complete only after a passing checkpoint; include the strongest final
   evidence available.

## Completion Gate

A performance goal is incomplete unless
`.omagy/goals/performance/<slug>/state.json` contains
`last_validation.status:"pass"`. Passing ordinary tests alone is not sufficient
unless those tests are the declared evaluator contract.

Task: {{ARGUMENTS}}