Goals

A no-nonsense workflow engine for long-running agent loops. Goals keeps the
plan, decisions, and proof in files you own so you can trust, verify, fix, and
resume the work.

Just say what you want — for example:

• "build me a weight-loss tracking app"
• "make a web app that resizes and tags my photos"
• "add login and payments to my site"
• "clean up and document this messy codebase"

What Goals does

• Trust the loop. State, decisions, evidence, and history stay readable while
  the work keeps moving.
• Verify before done. Checks actually run before a step is accepted, so "done"
  is earned instead of asserted.
• Fix what breaks. Failed verification points to the next repair instead of
  vague retrying.
• Reuse proven loops. Import an external loop or catalog, answer only the
  missing details, and let Goals validate it before it becomes your workflow.
• Resume without losing the thread. Portable files survive /clear, new
  sessions, and agent switches.

Who it's for

Anyone using AI to get real work done:

• If you don't code — you describe the goal and approve decisions in plain English;
  your AI assistant does the heavy lifting, and Goals keeps it on track.
• If you do code — a durable, scriptable workflow layer that keeps long AI tasks on
  the rails, with evidence, gates, and a readable audit trail.

How it works

   you say the goal
         │
         ▼
   Goals breaks it into clear steps  ──▶   the AI agent does the next step
         ▲                                             │
         │            you say yes   ◀──── plain decision + proof it works
         └─────────  repeat until done — with a record of everything  ◀─┘

Goals runs the workflow; your AI assistant (Claude Code, Codex, …) does the work.
Goals is the part that keeps it organized, legible, and accountable.

Under the hood it's a small CLI plus a plugin, working over plain files in
your own project — so the goal, the decisions, and the proof are yours and
survive a /clear or a brand-new session. The assess step follows PACERS, a
method for solving problems without rushing.

Here's the whole loop — each step in plain English, with the command behind it
(click to enlarge):

And you never lose the thread: a dashboard anyone can read shows status,
decisions, and proof at a glance (click to view full size):

_{Diagram source: docs/assets/lifecycle.mmd — regenerate with npx -y @mermaid-js/mermaid-cli -i docs/assets/lifecycle.mmd -o docs/assets/lifecycle.png -b white -s 2.}

See docs/architecture.md for the full set: system
architecture, the goal lifecycle, skill-first discovery + capability gaps, and the
portability layer that lets a goal survive /clear.

Get started

Claude Code

Two lines — that's the whole install:

/plugin marketplace add ShivamGupta42/goals
/plugin install goals@goals

The first session installs the goals CLI for you (macOS/Linux): the plugin
ships its own source and bootstraps it on first run — no separate step. Prefer
the terminal? goals setup --agent claude does the same.

Codex

goals setup --agent codex

Codex picks up Goals' skills from ~/.agents/skills; run goals context sync in a
project to expose the goal in AGENTS.md.

Manual / Windows

Install the CLI directly — one line — then goals setup --agent both:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ShivamGupta42/goals/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ShivamGupta42/goals/main/install.ps1 | iex

That's it. Now just talk to it in Claude Code:

Import a loop

Have a loop library, catalog file, or reusable workflow from another project?
Import it directly from Claude Code:

/goals:import https://signals.forwardfuture.ai/loop-library/

If the source contains multiple loops or placeholders, Goals asks Claude Code to
ask you the missing questions, then reruns with --select and repeated
--answer KEY=value flags. It writes the loop design, portable goal files, and
HTML preview into the loop output directory, records source hashes/provenance,
and runs goals loop check --target-agent claude before you activate it.

Terminal equivalent:

goals loop import https://signals.forwardfuture.ai/loop-library/ --out .goals --no-prompt
goals loop check --out .goals --target-agent claude
goals loop activate --out .goals --agent claude

See Importing Loops for supported source shapes,
selection, answers, provenance, and validation profiles.

Prefer the terminal? Use goals start "…", then goals next and goals check — see
The command set.

# needs uv (https://astral.sh/uv): curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install git+https://github.com/ShivamGupta42/goals.git
goals setup --agent both

Why Goals exists

AI agents wander. They skip steps, make quiet decisions, and after a while you've lost
track of what they did. When they do turn to you to decide, it's hard — the choice
comes wrapped in jargon you shouldn't have to decode. And once it's built, they often
can't clearly tell you what they made or how.

Goals fixes that. Tell it what you want in plain English. It breaks that into a clear
plan, keeps your AI on track step by step, puts every decision to you in plain words
you can actually answer, and won't say "done" until there's proof. Works whether you
write code or not.

The command set

Most people only need these:

For developers

Under the hood, Goals is a small CLI + Claude Code / Codex plugin. It keeps goal state,
evidence, decisions, and an append-only history as plain files in your repo, plus a
portable spec any agent can pick up. On main it works in an isolated git worktree so
your checkout stays clean. goals check --json gives agents a machine-readable view.

Loop imports are intentionally adapter-shaped: a source reader loads URLs/files,
a catalog adapter parses JSON/YAML/HTML fallbacks/builder scripts, and the normalizer
turns one selected loop into Goals' durable loop-design.json. Validation profiles
such as imported-loop, browser-ux-loop, and benchmark-loop live in
registries/profiles.yml and expand reusable proof requirements during export,
activation, and checking without hiding missing authored stop conditions.

Note: goals start runs in a git project (it makes a safe, isolated copy to work in).
Run goals --help for the full CLI, portability commands, and the visual loop builder.

Show you use Goals

Running a project with Goals? Add the badge to your README:

[![tracked with Goals](https://img.shields.io/badge/tracked%20with-Goals-6B50FF)](https://github.com/ShivamGupta42/goals)

Contributing

Issues and PRs welcome. See CONTRIBUTING.md for dev setup, the
checks to run, and the project conventions.

License

MIT