gurix
1474b0c66e
File-based goal tracking (goal-state.yaml) for long or multi-session work. Ordered (Sisyphus) and flexible modes, evidence-gated completion, headless-safe (pi-web): no dialogs, no turn tricks.
77 lines
4.1 KiB
Markdown
77 lines
4.1 KiB
Markdown
---
|
|
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.
|