Manage persistent goals and sub-goals across agent sessions using the goals-app CLI. Use this when you need to track, plan, or update work items that span multiple conversations, or when the user mentions goals, tasks, planning, or tracking progress.
The goals app is a persistent goal tracker backed by a SQLite database. Goals survive across agent sessions -- you can create goals in one conversation and pick them up in another. This makes it ideal for project-level work that spans multiple agent contexts.
Goals support hierarchy: a goal can have sub-goals via parent_id, letting you break down large objectives into smaller, trackable pieces.
| Field | Type | Required | Notes |
|---|---|---|---|
| id | integer | auto | Auto-generated identifier |
| title | string | yes | Short goal summary |
| description | string | yes | Detailed description |
| state | string | no | todo (default), in_progress, or completed |
| priority |
| string |
| no |
low, medium (default), or high |
| assignee | string | no | Person or agent responsible |
| parent_id | integer | no | ID of parent goal; null for top-level goals |
| created_at | string | auto | ISO 8601 timestamp |
| updated_at | string | auto | ISO 8601 timestamp |
State transitions: todo -> in_progress -> completed
You interact with goals by running spec commands from the goals-app directory. All commands below assume that working directory.
Important: Use spec -j (JSON output flag) when you need to parse command output programmatically.
spec goals list # all goals
spec goals list --state in_progress # filter by state
spec goals list --state todo # filter by state
spec goals list --assignee alice # filter by assignee
spec goals list --parent_id none # top-level goals only
spec goals list --parent_id 5 # sub-goals of goal 5
spec goals get --id 3
spec goals create --title "Implement auth" --description "Add JWT-based authentication to the API" --priority high
spec goals create --title "Write auth tests" --description "Unit tests for JWT validation" --parent_id 3
Only provide fields you want to change:
spec goals update --id 3 --state in_progress
spec goals update --id 3 --state completed
spec goals update --id 3 --title "New title" --priority low
Deleting a parent goal also deletes all its sub-goals.
spec goals delete --id 3
Use --help to see available subcommands and their parameters:
spec --help goals # list all subcommands
spec --help goals create # show parameters for create
SpecScript is a YAML-based scripting tool. The spec command runs .spec.yaml files. Directories act as command groups with subcommands.
spec [global options] directory subcommand [--param value]
.spec.yaml extension can be omittedspec -j outputs JSON; spec -o outputs YAMLspec --help <path> shows help without running anything--name valueFollow this workflow when using goals across sessions:
Start of session: List pending work before doing anything else.
spec goals list --state todo
spec goals list --state in_progress
Claim work: Mark a goal as in_progress before you start on it.
Complete work: Mark a goal as completed when done.
Create new goals as you discover work that needs doing.
Goals may be read by a different agent or model in a future session. Write them so they stand alone without prior conversation context.
Self-contained titles. Not "fix the bug" -- instead "Fix null pointer in UserService.getProfile when email is null".
Full context in descriptions. Include file paths, function names, error messages, acceptance criteria. Write as if for a colleague who has zero context.
Use hierarchy. Top-level goal for the objective; sub-goals for each concrete step:
Keep state current. A future agent relies on state fields to know what is done and what is not.
Use assignee. Set it when multiple agents or people are involved, so ownership is unambiguous.