Cursor plugin · check-backed autonomy

Goal Loop

A small /goal command that keeps agents working until a shell check passes — not until the model decides it looks done.

bodecloud/goal-loop v0.1.0 Node 18+

Installation

Load the plugin from a local clone (proven path) or from the marketplace once published. Unattended continuation needs Cursor Agent Auto-run.

Local plugin install

Terminal

git clone https://github.com/bodecloud/goal-loop.git
cd goal-loop
cursor-agent --plugin-dir "$PWD" --workspace /path/to/project

Optional project defaults

Commit a shared baseline check when the repo has one:

.cursor/goal/defaults.json

{
  "verify": {
    "commands": ["npm run build"],
    "cwd": ".",
    "timeout_ms": 600000
  },
  "limits": {
    "max_iterations": 20,
    "max_wall_ms": 7200000
  }
}

This site is served at bodecloud.github.io/goal-loop/. Marketplace availability is not proven by this repository alone.

Quick start

Start with one clear objective and one real check:

Cursor Agent

/goal "Fix build" --verify "npm run build"

Writes .cursor/goal/active.json
Agent works the objective
Stop hook runs after each finished turn
Check commands run in the shell
Failure → log-backed followup_message
Success → completed and {}

Support commands

/plan [objective]: Draft objective + check without activating the loop.
/goal-status: Inspect objective, iteration, check, and last log path.
/goal-abort: Stop the loop; optionally remove state.

Why it exists

Stops too early

Agents often stop when work merely looks done. Goal Loop moves the "is it done?" decision into a shell check.

Manual “continue”

With Auto-run, a failed check becomes the next instruction automatically.

Inspectable state

Contract and run logs live in the project, so every loop stays reviewable and portable.

Goal contract

One project-local JSON file is the state machine shared by the command, hook, and agent.

.cursor/goal/active.json

{
  "version": 1,
  "status": "active",
  "objective": "Fix the app build",
  "verify": {
    "commands": ["npm run build"],
    "cwd": ".",
    "timeout_ms": 600000
  },
  "limits": {
    "max_iterations": 20,
    "max_wall_ms": 7200000
  },
  "completion_promise": null,
  "started_at": "2026-06-30T00:00:00.000Z",
  "iteration": 0,
  "last_verify": null
}

Field	Purpose
`objective`	Human target the agent works toward.
`verify.commands`	Shell commands rerun after each finished turn.
`verify.cwd`	Working directory for the check.
`limits`	Guardrails against runaway looping.
`last_verify`	Latest result, exit codes, and log path.

How to choose a check

Good traits

Repeatable
Relevant to the real request
Cheap enough to rerun often
Strong enough to prove the outcome

Good fits

npm run build
npm test -- --testPathPattern=auth
scripts/smoke-check.sh
test -f generated/report.json

Bad fits

Lint for a runtime bug, file existence for a meaning rewrite, or a flaky network probe for a local, repeatable fix.

Stop conditions

Success

All check commands exit 0 → status completed, hook returns {}.

Continue

Failure writes a run log, updates last_verify, returns followup_message.

Abort

/goal-abort, max iterations, or max wall time.

Fail-open

Unexpected hook errors log to hook-errors.log and return {}.

Troubleshooting

Inspect state first

.cursor/goal/active.json
.cursor/goal/defaults.json
.cursor/goal/runs/
last_verify.log_path

Stops after one failure

Enable Cursor Agent Auto-run so the follow-up is submitted automatically.

Check passes, you are unhappy

Usually the check was too weak for the request — not a loop bug.

Docs map

Using it in Cursor

Cursor guide → how to choose a check → examples.

Understanding the contract

Goal contract + check design explain structure and who decides done.

Evaluating adoption

Decision guide and FAQ: does this check model fit your workflow?

Checklists

Before starting

Bounded objective, matching check, Auto-run if unattended.

When it keeps failing

Read active contract, defaults, run logs, and hook-errors before changing tactics.

When pass feels wrong

Re-check whether the check proved the request or only a narrow proxy.

Review

Objective

Bounded and aligned — not a vague catch-all.

Check

Proves the request; produces actionable failure output.

Success claims

A passing check proves only what that check covers.

Evidence

Claims map to code

Docs tie behavior to hook, contract, CLI, and plugin files.

Critical paths have tests

Pass, fail, abort, and fail-open are covered in the current suite.

Limits stay explicit

Evidence map marks what the docs do not prove.

Authoring

Evidence over tone

Traceable to current behavior; explicit about gaps.

Judgment over filler

Teach how to choose and debug checks.

Fewer claims, better defended

Smaller product claims, clearer guidance for you.

Adoption

Start small

Build repair, focused tests, or simple file-proof tasks first.

Defaults deliberately

Commit defaults only for a true shared baseline; else use --verify.

State treatment

Commit conventions; ignore live loop state and run logs.

Examples

Build repair

/goal "Fix build" --verify "npm run build"

Targeted regression

/goal "Repair auth tests" --verify "npm test -- --testPathPattern=auth"

Sequential proof

/goal "Finish release fix" --verify "npm test" --verify "npm run build"

Bootstrapping proof

/goal "Create proof file" --verify "test -f .cursor/goal/proof.txt"

What it does not do

No new agent platform or multi-agent system
No dashboard or workflow marketplace
No claim that a passing check proves anything outside what that check covers
No promise that a weak check becomes trustworthy by repetition