AGENTS.md

Cross-tool root context for AI coding agents using the goal-loop plugin (Claude Code, Codex, Cursor, Aider, Copilot, Gemini, etc.). Tool-specific files (CLAUDE.md, .codex/, .cursor/rules/) @import this file rather than duplicate.

One source of truth, many tools. Change plugin conventions here.

What this plugin is

The Goal Loop plugin is a baseline for goal-bounded OODA loops. It unifies:

• Goal-oriented orchestration — explicit intent, constraints, and falsifiable acceptance criteria (observer-checkable conditions that decide "done"; see glossary).
• OODA loop (Observe → Orient → Decide → Act) — Boyd's decision cycle, gated by humans at the goal gate (the approval of the goal contract before the first iteration) and the act gate (the approval before Act executes any decision). One full pass is one iteration (Observe → Orient → Decide → Act → Review).

The loop runs once for bounded problems and continuously for ongoing situations. It is domain-agnostic — use it for code, content, research, operations, strategy, or any knowledge work. Each goal lives under goals/<slug>/ (slug — a kebab-case short name like my-goal-slug that identifies the goal folder) with declared observe sources (each a feed, repo, inbox, document, person, command, or other input the observer scans).

The authoritative method definition is docs/method.md. Read it first.

Read these first

Just installed? Run docs/first-five-minutes.md before this list. 90 seconds, zero input, one full loop on disk. Then come back here for depth.

1. docs/glossary.md — 5-minute orientation for domain-neutral readers. The canonical enums (status, current_phase, action-log status, per-criterion verdict, loop-closure outcome, reversible) and the load-bearing terms (goal gate, act gate, observe source, iteration, health) all live here. The constitution and the method.md both reference enum values introduced in this doc — read it first or you will hit forward-references for the next four docs.
2. memory/constitution.md — ten governing principles. Override only with explicit human approval and an amendment.
3. docs/method.md — the full Goal Loop method, vocabulary, and state model.
4. docs/domain-model.md — the single-read type map. Read this once; use the targeted docs after. Saves you from chasing cross-references across 20 files to assemble the mental model.
5. docs/goal-orientation.md — what makes a goal worth running and an acceptance criterion falsifiable. Helpful before the first /goal:start.
6. docs/usage-patterns.md — the canonical use-case patterns (issue resolution, daily brief, incident triage, release readiness, continuous awareness).
7. docs/session-vs-iteration-goals.md — pick-by-scenario comparison of /create-goal (session-scoped guardrails) vs. /goal:start (iteration-scoped Goal Loop). Read before deciding which surface to use for a given piece of work.
8. The active goal's goals/<slug>/goal-state.md — current phase, iteration, and history.

Operating rules

• Goal first. No iteration runs without a complete, human-signed goal. set-goal is non-skippable.
• Phase isolation. Each phase subagent writes only its own artifacts under goals/<slug>/. No cross-writes.
• Human gates. The goal gate and act gate (for irreversible actions) are non-negotiable. Other gates are opt-in per goal.
• Evidence-based orientation. Every claim in orientation.md cites observations. No speculation, no extrapolation beyond signals.
• Reversibility bias. Prefer reversible actions. Every irreversible action requires a rollback plan in its action spec.
• Escalate, don't invent. Ambiguity goes to the human. The plugin never silently fills in a missing acceptance criterion, constraint, or source.
• Acceptance trace. Every review references each acceptance criterion explicitly with evidence.
• Domain neutrality. Resist software-only language. The method serves any domain.
• Logged trail. Every decision and action is logged. The trail must reconstruct the reasoning.
• Closure honesty. A loop closes only when acceptance is met or the goal is explicitly abandoned. No silent abandonment.

Subagent roster

Consult-only agents (advise the human or a phase agent at gates; never own phase artifacts):

Skill roster

Shared rules every conductor obeys: skills/_shared/loop-pattern.md. State file contract: skills/_shared/goal-state.md.

Slash-command roster

Session goals (cross-tool)

A session goal is a session-scoped intent that keeps the assistant aligned on what the user wants the current sitting to produce. It is distinct from a Goal Loop iteration goal (below) — no phases, no act gate, no goals/<slug>/ state folder. Session goals live one-file-per-goal under session-goals/ and activate per-tool: native /goal stop-hook in Claude Code, SESSION-GOAL.md in Codex, .cursor/rules/session-goal.mdc in Cursor.

Goal Loop iterations

Repo conventions

• Markdown for all artifacts. Concise; precision over completeness.
• File names = kebab-case. Per-goal work under goals/<slug>/.
• Phase artifacts use ISO-timestamp filenames where multiple are produced per iteration (e.g. observations/2026-05-16T10-00-00.md).
• Templates in templates/ are framework-agnostic Markdown.
• Cross-doc links are relative.

Tool-specific notes

• Claude Code. Subagents (agents/), skills (skills/), commands (commands/), plugin manifest (.claude-plugin/plugin.json) are picked up natively. CLAUDE.md imports this file plus the constitution and method.
• Codex. Primary context = this file. Codex specifics in .codex/. Workflows for Goal Loop iterations under .codex/workflows/.
• Cursor. Primary context = this file. Cursor rule at .cursor/rules/goal-loop.mdc is a thin pointer.
• All tools. Templates in templates/ are framework-agnostic.

When the harness gets in your way

The Goal Loop is process-light. If a check or gate is making you fight the tool, fix the goal definition (often the issue is an under-specified acceptance criterion or a missing observe source) — don't work around the loop.