CLAUDE.md

Entry point for Claude Code in the goal-loop plugin.

Primary context

@AGENTS.md @memory/constitution.md @docs/method.md

What this is

The Goal Loop plugin — a goal-bounded OODA loop for any decision or delivery cycle. The plugin ships a complete subagent + skill + command + template set — full inventory in AGENTS.md. Domain-agnostic.

The method's authoritative definition is docs/method.md. Read it before deviating from the loop.

How to work here

Two equivalent entry points:

• Conversational (recommended): Say "set up a goal loop", "run an OODA loop on X", or "kick off a daily brief" — the goal-loop skill gates with AskUserQuestion and dispatches the right /goal:* command per phase.
• Manual: Run /goal:demo first on a fresh project for a zero-input, one-command first-touch (scaffolds + drives one full hello-loop iteration — one Observe → Orient → Decide → Act → Review pass; see glossary). Then /goal:welcome for the guided walkthrough (tour, hello-world, or docs hand-off). Drive the slash commands in order — /goal:start, /goal:observe, /goal:orient, /goal:decide, /goal:act, /goal:review. Or /goal:run for the full iteration end-to-end. Inspect one goal with /goal:status or /goal:trace; survey the whole portfolio with /goal:list. Amend with /goal:amend. Render a brief with /goal:brief. Close with /goal:close.

State lives at goals/<slug>/goal-state.md (slug — the kebab-case short name like my-goal-slug identifying the goal folder under goals/). The orchestrator updates it on phase completion — don't edit it by hand mid-iteration.

Session goals (cross-tool). For a session-scoped intent that keeps the assistant on rails for one sitting — without the full Goal Loop ceremony — use /create-goal to interview into session-goals/<slug>.md, then /set-goal <slug> to activate (invokes the native /goal stop-hook in Claude Code). Distinct from /goal:start (Goal Loop intake); see docs/session-vs-iteration-goals.md for the side-by-side comparison and docs/session-goal-best-practices.md for shape-by-shape best practices.

Conventions specific to Claude Code

• Subagents live in agents/ with intentionally narrow tool lists. Missing tool = feature, not bug.
• Skills live in skills/ — see the skills README. Auto-trigger from natural language; explicit invoke via /<skill-name>.
• Slash commands live in commands/goal/ — see commands/goal/README.md.
• Templates live in templates/ — one per artifact type.
• Each phase agent writes only its own artifacts. Phase isolation is governed by Article II of the constitution.
• Human gates: the goal gate (the human approval of the goal contract before the first iteration; see glossary) and the act gate (the human approval before Act executes any decision) are non-negotiable. Other gates are opt-in per goal.

What success looks like

A working Goal Loop session typically looks like this:

• The user signs the goal gate after a short clarity-gated intake. The acceptance criteria (falsifiable, observer-checkable conditions that decide "done"; see glossary) are falsifiable and the constraints are explicit.
• Each iteration produces one observation set, one refreshed orientation, one decision set (with the user approving the act-gate), one or more action logs, and one review.
• The review either closes the goal with per-criterion evidence (close-met) or recommends continue with a concrete next observation focus.
• The audit trail under goals/<slug>/ reconstructs every decision the loop made; /goal:trace can walk it criterion-by-criterion.
• Surprises route through ## Open Questions, contradictions, and amendments — never through silent invention.

What not to do

• Don't bypass the act gate for irreversible actions, even on the user's behalf, unless the goal's act_gate policy explicitly authorises it.
• Don't invent acceptance criteria. If the user didn't supply one, the set-goal skill must elicit it.
• Don't introduce software-specific terms into the prompts or templates. The method is domain-agnostic.
• Don't expand the plugin with new phase agents or new state-file fields without amending docs/method.md and the constitution.

Further docs

Beyond the primary context above, the plugin ships:

• docs/first-five-minutes.md — 90-second on-ramp. Install verification → /goal:demo → what landed → where to go next.
• docs/session-vs-iteration-goals.md — side-by-side comparison of /create-goal (session-scoped) vs. /goal:start (iteration-scoped); pick-by-scenario guide.
• docs/domain-model.md — single-read type map of every domain entity. Use to onboard fast.
• docs/glossary.md — 5-minute orientation for domain-neutral readers.
• docs/troubleshooting.md — problem → cause → fix for common blockers.
• docs/usage-patterns.md — the canonical five (six with policy-consultation) patterns the loop drives.
• docs/customizing.md — how adopters extend without forking the baseline.
• docs/tool-adapters.md — Claude Code / Codex / Cursor adapter contract.
• docs/hooks-recipes.md — opt-in Claude Code hook recipes that surface loop state.
• docs/cadence-recipes.md — cron / Actions / systemd recipes for recurring runs.
• docs/maintenance.md — for the plugin maintainer.
• docs/improvement-strategy.md — forward-looking direction for the plugin.