goals

# goals

A file-backed tracker for real-life goals at `~/code/goals`. One Markdown file
per goal in `goals/`, driven by `~/code/goals/bin/goals`. Full format reference
is in that repo's `README.md`.

This is deliberately not a code-project tracker. It holds things that happen in
the physical world: errands, house work, vendor decisions, obligations with
renewal dates.

## Read before you write

Start with `goals list` and, for anything you are about to touch,
`goals show <id>`. The goal body carries context the frontmatter does not —
sequencing reasons, things to watch for, prior attempts. Acting without reading
it is how you tell someone to cancel a contract that pays for the repair they
have not had yet.

## The commands

```sh
goals                      # next action per open goal — the default view
goals list [--all] [--status S] [--area A]
goals show <id>
goals log <id> "what happened"
goals step <id> <n> [--undo]
goals set <id> field=value [field=value ...]
goals done <id> [--note "..."]
goals add "Title" [--kind K] [--priority N] [--due YYYY-MM-DD] [--next "..."]
goals nudge [--quiet]      # overdue / due soon / gone quiet / blocked
goals agenda               # agent-doable vs. needs-human, across open goals
goals commit [-m msg]
```

Ids match on substring, so `goals show gutters` resolves to `clear-gutters`.

## Answering "where are we"

Run `goals nudge` first, then `goals`. Lead with what is overdue or has gone
quiet — the goal nobody has touched is the one the user needs to hear about,
not the one already moving. Keep it to a few lines. This is a status check, not
a report.

## Logging

Log anything that moved: a call made, a quote received, a decision taken, a
dead end. `goals log <id> "..."` is cheap and it is what makes staleness
detection mean anything. A goal whose last entry is three weeks old reads as
abandoned whether or not it is, so log the non-events too — "called, no answer"
is real information.

When the user mentions in conversation that they did something on a goal,
log it without being asked. That is the main way this tracker stays true.

## The agentic boundary

Every goal declares `agent_can` and `needs_human`. Honour it literally.

You may do the `agent_can` work unattended — build vendor shortlists, draft
messages the user will send, assemble comparison tables, research what a good
version of the job includes, keep the files current.

You may not do `needs_human` work, and you must not route around it. In
particular, never contact a vendor, submit a form, place a call, start a
cancellation, or spend money on the user's behalf — even where a tool would
technically let you. Draft it and hand it over. If a goal seems to need an
action that is not in either list, ask before doing it, and add it to the right
list once the user answers.

## Adding goals

When the user describes a new real-world obligation in passing, offer to add
it — and give it a `next_step` that is a genuine physical action, not a
restatement of the title. A goal without a real next step is the one that will
still be open in six months.

Set `due` only when there is an actual reason for the date. Invented deadlines
train the user to ignore real ones. A renewal date, a season, a notice window:
those are reasons. "Two weeks from now" is not.

## Closing out

`goals done <id> --note "how it ended"`. Do not delete goal files — a closed
goal with its log intact is the record of how long the thing took, what it
cost, and who did it well. That is what makes the next one easier.

Use `status=dropped` for goals abandoned rather than achieved, and log why.