---
name: goal-state
description: Persistent, evidence-based goal tracking for long or multi-session work via a goal-state.yaml file in the project. Use when the user says "goal", "/goal", "setze ein Ziel", "track this as a goal", wants ordered step-by-step execution with done criteria (Sisyphus mode), or when a goal-state.yaml already exists. Works headless (pi-web) — file-based, no dialogs or TUI needed.
---

# Goal State

Track a goal in `goal-state.yaml` in the project root. The file is the single source of truth: it survives sessions, compaction, and crashes. Every claim of progress needs recorded evidence.

## The state file

```yaml
version: 1
status: active            # active | paused | complete | cancelled
mode: ordered             # ordered | flexible
objective: >
  One-sentence outcome.
requirements:             # the goal is only complete when ALL are met
  - id: R1
    text: Verifiable completion requirement.
    met: false
    evidence: ""          # how it was verified (command, output, file path)
steps:
  - id: S1
    text: What to do.
    done_when: How to verify this step is done.
    status: pending       # pending | in_progress | done | skipped
    evidence: ""
next: S1                  # ordered mode only: the one step to work on
log:                      # newest last, keep at most 20 entries
  - "2026-01-15T10:00Z goal created"
```

- **ordered** (Sisyphus): steps are executed strictly in order, one at a time. `next` names the only step that may be worked on.
- **flexible**: steps may be done in any order; requirements still gate completion.

## Starting a goal

1. Discuss the objective. Derive **requirements** — each must be independently verifiable (test suite passes, file exists, report contains section X, command exits 0).
2. For ordered mode, break the work into numbered steps, each with a concrete `done_when`. For flexible mode, steps are optional — requirements alone are fine for small goals.
3. Show the proposed file to the user and **wait for confirmation**. Then write `goal-state.yaml` and log the creation.

Shortcut: if the user gives a complete objective with explicit steps, propose immediately without a long discussion.

## Working on a goal

1. Read `goal-state.yaml` before doing anything else.
2. **Ordered:** set the `next` step to `in_progress`, do it, verify its `done_when`. **Flexible:** pick any pending step.
3. Record evidence and set `status: done`, advance `next`, append a log line — **write the file immediately after each step** (crash safety).
4. Blocked? Set `status: paused` with the reason in the log and tell the user what is needed.
5. If the project uses the dev-workflow, each step gets its own commit, per that workflow.

## Evidence rules

- `met: true` / `status: done` **only with evidence recorded**: the command that was run and its result, a file path, or a test name. "I am confident" is not evidence.
- When unsure whether something still holds, re-run the verification instead of trusting the file.
- Evidence from earlier sessions counts only if the file records it.

## Resuming

- If a session starts (or the skill is loaded) and `goal-state.yaml` has `status: active`, give a two-line status (objective, next step) and continue with `next` — ask only if the situation is ambiguous.
- `goal status` → print a compact view from the file: status, requirements (met/unmet), steps (done/pending), next step. No narration beyond that.

## Completing, changing, cancelling

- **Complete:** only when every requirement has `met: true` with evidence. Set `status: complete`, log it, and report a summary of objective + evidence to the user. Suggest `mv goal-state.yaml goal-state-done-<date>.yaml` (or deletion).
- **Change:** adjust steps/requirements, append a log entry describing what changed and why.
- **Cancel:** set `status: cancelled`, keep the file unless the user wants it deleted.

## Rules

- One active goal per project.
- Never skip steps in ordered mode; never work ahead of `next`.
- Never claim completion without evidence in the file.
- Write the file after every mutation — the file, not memory, is the progress.
- Keep the file small: log capped at 20 entries, no prose beyond the objective.