skills/dev/goal-state/SKILL.md

name, description

name	description
goal-state	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

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.