Trails Goal Loop

Trails Goal Loop

Turn a substantial Trails objective into a current, executable contract and stay with it through the authorized completion horizon. Keep small, obvious edits small; do not manufacture a packet when the work can be completed and proved directly.

Ground The Goal

Read AGENTS.md, the nearest scoped guidance, and .agents/plans/PLANNING.md. Treat those current repository sources as authoritative for packet shape, Graphite workflow, review policy, release readiness, and stop rules.

Establish live truth before planning:

• inspect the intended baseline and current worktree, branch, and Graphite stack;
• inspect the owning issue, PRs, review threads, and CI when they exist;
• verify whether the requested outcome is already delivered on the relevant baseline or target state;
• separate verified state, inference, and unknowns.

Verified already-done is a valid outcome when named evidence proves the requested horizon. Do not create implementation merely to make a goal appear active.

Choose The Smallest Contract

Use a packet when the work must survive context loss, coordinate multiple issues or agents, shape a stack, or persist through external waits. Create it under:

.agents/plans/{YYYY-MM-DD-slug}/
  PLAN.md
  GOAL.md
  RETRO.md
  REFS.md

Follow .agents/plans/PLANNING.md for each file's current role. Do not make a tracked packet depend on ignored scratch evidence.

For a smaller goal, keep the same contract in the working plan or prompt without creating files. Name:

• one completion horizon;
• what counts as done and explicitly not done;
• authority and boundaries;
• preserved state and scope fences;
• execution and review topology;
• exact verification and evidence;
• external waits, next moves, and true stop rules.

Use a horizon that describes observable state, such as plan-ready, implementation-ready, draft PR, ready PR, merged, released, published, or tracker-only. Changing it requires explicit user or coordinator approval.

Shape Honest Execution

Choose branches and agents from real ownership and dependency facts:

• place each change on its lowest dependency-safe owning branch;
• stack branches only when one change truly depends on another;
• express priority through execution order and gates, not artificial branch ancestry;
• keep unrelated priority work standalone and finish or gate it before starting lower-priority work when focus matters;
• let the coordinating agent assign worktrees, file scope, source-control operations, tracker mutations, and integration ownership.

An agent type or persona grants no operational authority. Record delegated authority precisely enough that another agent can verify it before acting.

Run The Loop

Repeat until the horizon is proved or a stop rule fires:

1. Reconcile live state with the goal contract.
2. Implement the smallest coherent slice on its owning branch.
3. Verify narrowly, then broaden in proportion to risk.
4. Invoke trails-local-review when the repository, coordinator, or goal contract requires a review gate.
5. Fix findings on the owning branch and re-verify affected descendants.
6. Update RETRO.md, tracker, PR, and other truth surfaces when their state materially changes.
7. Settle documentation, governance, generated artifacts, release intent, and migration guidance under the repository's Distribution-Ready Done contract.

Do not weaken the horizon, review gate, verification, or authority boundary silently. Record material amendments in RETRO.md.

Prove Settlement

Finish with evidence that can be checked without the execution chat:

• resulting branches, stack order, and PR state;
• verification commands and summarized results;
• review findings and dispositions;
• open threads, CI, mergeability, release, registry, or runtime state relevant to the horizon;
• skipped gates and why they were not applicable;
• remaining risks or the exact blocker;
• confirmation that no action exceeded delegated authority.

Progress is not completion. A local check is not a ready PR, a ready PR is not merged, merged is not released, and released is not proven operational.