From 69ed2ae480ff10269a3bbfdc2286a2593d2aa494 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 16 May 2026 12:38:35 +0000 Subject: [PATCH 001/103] feat(plugin-v2): unified goal-loop plugin merging OODA + goal-orchestrator MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Build a new baseline plugin in plugin-v2/ that unifies the two concepts proposed in #501 (Goal-Oriented Orchestrator) and #502 (OODA Loop) into one cohesive, domain-agnostic surface: a goal-bounded OODA loop. A "goal" sets the what and why (intent, constraints, falsifiable acceptance criteria, mode, cadence). The OODA loop is the how (Observe → Orient → Decide → Act, then a Review step that closes or continues the iteration). One iteration for bounded problems; recurring iterations for ongoing situations (daily brief, incident triage, release readiness, continuous awareness). Surfaces shipped: - 6 specialist subagents (goal-orchestrator + observer / orienter / decider / actor / loop-reviewer) with narrow, intentional tool lists. - 7 skills (goal-loop + set-goal + 5 per-phase skills) + shared loop-pattern and goal-state contract under skills/_shared/. - 10 slash commands under /goal:* (start, observe, orient, decide, act, review, run, status, close, brief). - 8 templates covering state, observation, orientation, decisions, action spec, action log, review, and brief. - 10 docs: method definition (locked vocabulary), OODA foundations, goal-orientation primer, usage patterns, customizing guide, tool adapters, plus three worked-example narratives. - 7 example artifacts under examples/ for issue-resolution and daily-brief use cases. - Multi-tool adapters: .codex/ (instructions + 2 workflows) and .cursor/rules/goal-loop.mdc — both thin pointers that delegate to AGENTS.md and docs/method.md. - Top-level entry points: README.md, CLAUDE.md, AGENTS.md, LICENSE. - Plugin manifest at .claude-plugin/plugin.json. - Constitution (10 articles) under memory/constitution.md. The plugin is a copy-and-paste baseline: drop the folder into a project and run /goal:start to define the first goal. Domain-agnostic — no software-only assumptions in the core method, templates, or agents. Closes #501, closes #502. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s --- plugin-v2/.claude-plugin/plugin.json | 51 ++++ plugin-v2/.codex/README.md | 23 ++ plugin-v2/.codex/instructions.md | 57 +++++ plugin-v2/.codex/workflows/daily-brief.md | 67 ++++++ plugin-v2/.codex/workflows/goal-iteration.md | 91 ++++++++ plugin-v2/.cursor/rules/goal-loop.mdc | 31 +++ plugin-v2/AGENTS.md | 96 ++++++++ plugin-v2/CLAUDE.md | 40 ++++ plugin-v2/LICENSE | 21 ++ plugin-v2/README.md | 111 +++++++++ plugin-v2/agents/README.md | 47 ++++ plugin-v2/agents/actor.md | 55 +++++ plugin-v2/agents/decider.md | 59 +++++ plugin-v2/agents/goal-orchestrator.md | 83 +++++++ plugin-v2/agents/loop-reviewer.md | 57 +++++ plugin-v2/agents/observer.md | 46 ++++ plugin-v2/agents/orienter.md | 60 +++++ plugin-v2/commands/goal/README.md | 34 +++ plugin-v2/commands/goal/act.md | 38 +++ plugin-v2/commands/goal/brief.md | 40 ++++ plugin-v2/commands/goal/close.md | 38 +++ plugin-v2/commands/goal/decide.md | 39 ++++ plugin-v2/commands/goal/observe.md | 35 +++ plugin-v2/commands/goal/orient.md | 35 +++ plugin-v2/commands/goal/review.md | 44 ++++ plugin-v2/commands/goal/run.md | 40 ++++ plugin-v2/commands/goal/start.md | 33 +++ plugin-v2/commands/goal/status.md | 44 ++++ plugin-v2/docs/README.md | 37 +++ plugin-v2/docs/customizing.md | 80 +++++++ plugin-v2/docs/examples/daily-brief.md | 137 +++++++++++ plugin-v2/docs/examples/incident-triage.md | 127 ++++++++++ plugin-v2/docs/examples/issue-resolution.md | 119 ++++++++++ plugin-v2/docs/goal-orientation.md | 67 ++++++ plugin-v2/docs/method.md | 217 ++++++++++++++++++ plugin-v2/docs/ooda-foundations.md | 59 +++++ plugin-v2/docs/tool-adapters.md | 62 +++++ plugin-v2/docs/usage-patterns.md | 76 ++++++ plugin-v2/examples/README.md | 33 +++ plugin-v2/examples/daily-brief/brief.md | 50 ++++ plugin-v2/examples/daily-brief/goal-state.md | 68 ++++++ .../examples/issue-resolution/decisions.md | 52 +++++ .../examples/issue-resolution/goal-state.md | 76 ++++++ .../examples/issue-resolution/orientation.md | 50 ++++ .../reviews/2026-01-15T11-30-00.md | 44 ++++ plugin-v2/memory/constitution.md | 99 ++++++++ plugin-v2/skills/_shared/goal-state.md | 150 ++++++++++++ plugin-v2/skills/_shared/loop-pattern.md | 121 ++++++++++ plugin-v2/skills/act/SKILL.md | 146 ++++++++++++ plugin-v2/skills/decide/SKILL.md | 135 +++++++++++ plugin-v2/skills/goal-loop/SKILL.md | 125 ++++++++++ plugin-v2/skills/observe/SKILL.md | 130 +++++++++++ plugin-v2/skills/orient/SKILL.md | 113 +++++++++ plugin-v2/skills/review-loop/SKILL.md | 115 ++++++++++ plugin-v2/skills/set-goal/SKILL.md | 127 ++++++++++ plugin-v2/templates/README.md | 36 +++ plugin-v2/templates/action-log-template.md | 54 +++++ plugin-v2/templates/action-spec-template.md | 44 ++++ plugin-v2/templates/brief-template.md | 46 ++++ plugin-v2/templates/decision-template.md | 45 ++++ plugin-v2/templates/goal-state-template.md | 60 +++++ plugin-v2/templates/observation-template.md | 45 ++++ plugin-v2/templates/orientation-template.md | 54 +++++ plugin-v2/templates/review-template.md | 46 ++++ 64 files changed, 4460 insertions(+) create mode 100644 plugin-v2/.claude-plugin/plugin.json create mode 100644 plugin-v2/.codex/README.md create mode 100644 plugin-v2/.codex/instructions.md create mode 100644 plugin-v2/.codex/workflows/daily-brief.md create mode 100644 plugin-v2/.codex/workflows/goal-iteration.md create mode 100644 plugin-v2/.cursor/rules/goal-loop.mdc create mode 100644 plugin-v2/AGENTS.md create mode 100644 plugin-v2/CLAUDE.md create mode 100644 plugin-v2/LICENSE create mode 100644 plugin-v2/README.md create mode 100644 plugin-v2/agents/README.md create mode 100644 plugin-v2/agents/actor.md create mode 100644 plugin-v2/agents/decider.md create mode 100644 plugin-v2/agents/goal-orchestrator.md create mode 100644 plugin-v2/agents/loop-reviewer.md create mode 100644 plugin-v2/agents/observer.md create mode 100644 plugin-v2/agents/orienter.md create mode 100644 plugin-v2/commands/goal/README.md create mode 100644 plugin-v2/commands/goal/act.md create mode 100644 plugin-v2/commands/goal/brief.md create mode 100644 plugin-v2/commands/goal/close.md create mode 100644 plugin-v2/commands/goal/decide.md create mode 100644 plugin-v2/commands/goal/observe.md create mode 100644 plugin-v2/commands/goal/orient.md create mode 100644 plugin-v2/commands/goal/review.md create mode 100644 plugin-v2/commands/goal/run.md create mode 100644 plugin-v2/commands/goal/start.md create mode 100644 plugin-v2/commands/goal/status.md create mode 100644 plugin-v2/docs/README.md create mode 100644 plugin-v2/docs/customizing.md create mode 100644 plugin-v2/docs/examples/daily-brief.md create mode 100644 plugin-v2/docs/examples/incident-triage.md create mode 100644 plugin-v2/docs/examples/issue-resolution.md create mode 100644 plugin-v2/docs/goal-orientation.md create mode 100644 plugin-v2/docs/method.md create mode 100644 plugin-v2/docs/ooda-foundations.md create mode 100644 plugin-v2/docs/tool-adapters.md create mode 100644 plugin-v2/docs/usage-patterns.md create mode 100644 plugin-v2/examples/README.md create mode 100644 plugin-v2/examples/daily-brief/brief.md create mode 100644 plugin-v2/examples/daily-brief/goal-state.md create mode 100644 plugin-v2/examples/issue-resolution/decisions.md create mode 100644 plugin-v2/examples/issue-resolution/goal-state.md create mode 100644 plugin-v2/examples/issue-resolution/orientation.md create mode 100644 plugin-v2/examples/issue-resolution/reviews/2026-01-15T11-30-00.md create mode 100644 plugin-v2/memory/constitution.md create mode 100644 plugin-v2/skills/_shared/goal-state.md create mode 100644 plugin-v2/skills/_shared/loop-pattern.md create mode 100644 plugin-v2/skills/act/SKILL.md create mode 100644 plugin-v2/skills/decide/SKILL.md create mode 100644 plugin-v2/skills/goal-loop/SKILL.md create mode 100644 plugin-v2/skills/observe/SKILL.md create mode 100644 plugin-v2/skills/orient/SKILL.md create mode 100644 plugin-v2/skills/review-loop/SKILL.md create mode 100644 plugin-v2/skills/set-goal/SKILL.md create mode 100644 plugin-v2/templates/README.md create mode 100644 plugin-v2/templates/action-log-template.md create mode 100644 plugin-v2/templates/action-spec-template.md create mode 100644 plugin-v2/templates/brief-template.md create mode 100644 plugin-v2/templates/decision-template.md create mode 100644 plugin-v2/templates/goal-state-template.md create mode 100644 plugin-v2/templates/observation-template.md create mode 100644 plugin-v2/templates/orientation-template.md create mode 100644 plugin-v2/templates/review-template.md diff --git a/plugin-v2/.claude-plugin/plugin.json b/plugin-v2/.claude-plugin/plugin.json new file mode 100644 index 000000000..d2b10be3f --- /dev/null +++ b/plugin-v2/.claude-plugin/plugin.json @@ -0,0 +1,51 @@ +{ + "name": "goal-loop", + "version": "2.0.0", + "description": "A goal-bounded OODA loop for any decision or delivery cycle. Unifies goal-oriented orchestration with Observe→Orient→Decide→Act for domain-agnostic, parallel-capable, human-gated execution.", + "author": { + "name": "Luis Mendez" + }, + "homepage": "https://github.com/Luis85/agentic-workflow", + "license": "MIT", + "keywords": [ + "agentic-workflow", + "ooda-loop", + "goal-oriented", + "orchestration", + "claude-plugin", + "decision-support", + "situational-awareness" + ], + "capabilities": { + "agents": [ + "agents/goal-orchestrator.md", + "agents/observer.md", + "agents/orienter.md", + "agents/decider.md", + "agents/actor.md", + "agents/loop-reviewer.md" + ], + "skills": [ + "skills/goal-loop", + "skills/set-goal", + "skills/observe", + "skills/orient", + "skills/decide", + "skills/act", + "skills/review-loop" + ], + "commands": [ + "commands/goal" + ] + }, + "entrypoints": { + "primary_skill": "goal-loop", + "primary_command": "/goal:start", + "method_doc": "docs/method.md", + "readme": "README.md" + }, + "compatibility": { + "claude_code": ">=1.0.0", + "adapters": ["codex", "cursor"] + } +} diff --git a/plugin-v2/.codex/README.md b/plugin-v2/.codex/README.md new file mode 100644 index 000000000..35124c314 --- /dev/null +++ b/plugin-v2/.codex/README.md @@ -0,0 +1,23 @@ +--- +title: "Codex" +folder: ".codex" +description: "Entry point for Codex-specific delivery mechanics layered on the shared goal-loop plugin rules." +entry_point: true +--- +# Codex + +Codex-specific operating context for the `goal-loop` plugin. [`AGENTS.md`](../AGENTS.md) at the plugin root remains the shared source of truth for every AI coding agent; this folder holds the extra delivery mechanics that help Codex drive a Goal Loop cleanly. + +Read in this order for non-trivial work: + +1. [`AGENTS.md`](../AGENTS.md) — plugin-wide rules, agent roster, operating conventions. +2. [`../memory/constitution.md`](../memory/constitution.md) — governing principles. +3. [`../docs/method.md`](../docs/method.md) — the canonical Goal Loop definition. +4. [`instructions.md`](instructions.md) — Codex-specific defaults. +5. The workflow playbook that matches the task: + - [`workflows/goal-iteration.md`](workflows/goal-iteration.md) — one end-to-end iteration of the loop. + - [`workflows/daily-brief.md`](workflows/daily-brief.md) — producing the daily brief for a recurring goal. + +This folder is the Codex adapter layer. It extends but does not override `AGENTS.md` or `docs/method.md`. See [`../docs/tool-adapters.md`](../docs/tool-adapters.md) for the full adapter rationale. + +This folder is part of the plugin. Local Codex cache, secrets, or session state should not be committed here. diff --git a/plugin-v2/.codex/instructions.md b/plugin-v2/.codex/instructions.md new file mode 100644 index 000000000..7a9d59d83 --- /dev/null +++ b/plugin-v2/.codex/instructions.md @@ -0,0 +1,57 @@ +# Codex instructions + +These instructions adapt the shared plugin rules in [`AGENTS.md`](../AGENTS.md) to Codex's operating style. Substantive method rules are not duplicated here — they live in `AGENTS.md` and [`docs/method.md`](../docs/method.md). + +## Default posture + +- Act as a conductor of the Goal Loop, not a generalist coder. One goal slug at a time. +- Stay in the current phase. Do not run the next phase agent's work to "get ahead" — phase isolation is enforced by the constitution. +- Persist state explicitly. Every iteration's artifacts land under `goals//` exactly where the templates say. +- Keep one branch (or one working session) to one goal slug. Switching goals means switching context cleanly. +- Prefer to drive the full iteration when invited, gating at the goal step and the act step. + +## Context loading + +Before changing files, read: + +1. [`AGENTS.md`](../AGENTS.md) — plugin-wide rules. +2. [`../memory/constitution.md`](../memory/constitution.md) — governing principles. +3. [`../docs/method.md`](../docs/method.md) — the loop's canonical definition. +4. The relevant pattern doc under [`../docs/usage-patterns.md`](../docs/usage-patterns.md). +5. The active goal's `goals//goal-state.md`. +6. The relevant Codex workflow under [`workflows/`](workflows/). + +Load scoped customisation guidance from [`../docs/customizing.md`](../docs/customizing.md) only when the task requires extending the plugin. + +## Workflow conventions + +- **Gate at the goal.** No iteration runs until `goal-state.md` is complete and the human has signed off. Missing intent, constraints, acceptance criteria, mode, observe sources, or act-gate policy is a blocker — route back to the `set-goal` skill. +- **Gate at the act step.** Before any irreversible action runs, the human must approve the decision set. Pre-authorised reversible runbook items may auto-approve only when the goal's `act_gate` policy explicitly allows it. +- **One writer per artifact.** Only the conductor writes `goal-state.md`. Each phase agent writes only its own files. If an upstream artifact has a defect, surface it; do not silently fix it. +- **Cite signals.** Every claim in `orientation.md` references an observation by file and signal index. Every rationale in `decisions.md` traces to a line in orientation. +- **Log everything.** Skipped, deferred, and rejected items are recorded with rationale. Done-without-evidence is incomplete. +- **Domain-neutral language.** Examples may be software-shaped, but core artifacts use plain outcome language. Resist commit/branch/test metaphors when the goal is not about code. + +## GitHub access + +When the goal involves a GitHub repository and access is available, Codex may use the host's GitHub surface (issues, PRs, search). Treat any GitHub mutation (open/close/comment, merge, label, release) as an Act-phase step that the goal's act-gate policy must cover. Read-only GitHub access is part of the observer's tool surface. + +After producing or updating any artifact, report: + +- Goal slug. +- Current phase + iteration. +- Artifact path just written. +- Pending gates (goal gate, act gate for decision-set id N). +- Next recommended step + the slash command or skill the human would invoke. + +## Safety rails + +Ask before: + +- Running any action whose `reversible` flag is `false`. +- Running any action that falls outside the goal's `act_gate` auto-approval scope. +- Performing destructive filesystem changes (delete, force-overwrite, history rewrites). +- Posting publicly visible content, moving money, sending external communications, or making any irreversible change to a shared system. +- Amending `goal-state.md`'s acceptance criteria, constraints, or observe sources — those are goal-level fields under the goal gate. + +Do not ask before normal reads, normal local writes to your assigned phase artifact, or invoking the next phase agent when the orchestrator's procedure says it is time. diff --git a/plugin-v2/.codex/workflows/daily-brief.md b/plugin-v2/.codex/workflows/daily-brief.md new file mode 100644 index 000000000..f996c6e40 --- /dev/null +++ b/plugin-v2/.codex/workflows/daily-brief.md @@ -0,0 +1,67 @@ +# Workflow — Daily brief + +A Codex playbook for producing the daily brief for a recurring Goal Loop. For the canonical method see [`../../docs/method.md`](../../docs/method.md); for the pattern see [`../../docs/usage-patterns.md`](../../docs/usage-patterns.md#2-daily-brief-recurring-awareness); for the worked example see [`../../docs/examples/daily-brief.md`](../../docs/examples/daily-brief.md). + +## When to use + +- An active goal exists at `goals//` with `mode: recurring` and `cadence: daily` (or the human triggers the brief on demand). +- The goal gate is signed. +- It is the right time to produce today's brief, or the human asked for it explicitly. + +## When not to use + +- The goal is `one-shot` — that pattern does not produce a brief. +- The goal's status is `paused`, `cancelled`, or `done`. + +## Procedure + +### 1. Confirm the goal slug and the brief window + +- Read `goal-state.md`. Confirm `mode: recurring`, `cadence: daily` (or compatible), and that `brief.md` is the expected output. +- Determine the brief window: the period the observers should treat as "since last time". For daily briefs, this is normally "since the prior brief's timestamp" — fall back to "last 24 hours" if no prior brief exists. + +### 2. Observe (parallel where independent) + +- For each entry in `observe_sources`, spawn an observer scoped to that source. Always include the prior brief itself as an observe source — it tells you what carried over. +- Each observer writes `goals//observations/--.md`. Raw signals only. +- Note explicitly which items rolled forward from the prior brief and have not yet been acted on. + +### 3. Orient + +- One orienter reads every observation in the window and the prior `orientation.md`. +- Writes the refreshed `goals//orientation.md`. Every claim cites an observation. +- Summary highlights what is new since the prior brief, what is blocked, what is at risk. + +### 4. Decide + +- One decider proposes the recommended-today set. Honour any constraint the goal imposes on set size (e.g. "no more than three recommended-today items"). +- For each proposal, mark the gate. Most daily-brief proposals are `gate: human` because the brief is advisory. +- Append the decision-set block to `goals//decisions.md`. + +### 5. Render the brief + +- Read [`../../templates/brief-template.md`](../../templates/brief-template.md). Produce `goals//brief.md`: + - **TL;DR** — three bullets max, the changes that matter and the calls to action. + - **What's New** — material changes since the prior brief, with observation refs. + - **Recommended Today** — copy the approved decision set's actions in priority order. + - **Watching** — open risks, partials, and items rolled forward. + - **Optional Actions** — proposals weighed but not promoted, surfaced so the human can pull them in. +- Archive a dated copy at `goals//archive/brief-.md` (or the equivalent under `goal-state.md`'s declared archive path). The current `brief.md` is overwritten daily; the archive preserves history. + +### 6. Review + +- One loop-reviewer writes `goals//reviews/.md`. +- Verify the brief's acceptance criteria are met (e.g. ≤ N recommended-today items, freshness, rollover discipline). +- Outcome is normally `continue` for recurring goals; emit `close-met` only when the goal's stop condition (recorded in `goal-state.md`) has triggered. + +## Reporting + +- The path of today's `brief.md` and its archived dated copy. +- The decision-set id from `decisions.md`. +- Any items that rolled forward unactioned for more than the threshold the goal declares (if any) — surface as a watch signal. + +## Safety rails + +- The brief proposes; the human acts. Do not perform any `gate: human` proposal during the daily-brief workflow unless the goal's `act_gate` policy explicitly authorises it. +- Never silently drop a rolled-forward item. If it is no longer relevant, the brief must say so and explain why. +- Never edit the archive. The audit trail of past briefs is immutable. diff --git a/plugin-v2/.codex/workflows/goal-iteration.md b/plugin-v2/.codex/workflows/goal-iteration.md new file mode 100644 index 000000000..4919c93e1 --- /dev/null +++ b/plugin-v2/.codex/workflows/goal-iteration.md @@ -0,0 +1,91 @@ +# Workflow — One Goal Loop iteration + +A Codex playbook for running one full iteration of the Goal Loop end-to-end against an active goal slug. For the canonical method, see [`../../docs/method.md`](../../docs/method.md). Substantive rules are in [`../../AGENTS.md`](../../AGENTS.md); do not redefine them here. + +## When to use + +- An active goal exists at `goals//` with a signed `goal-state.md`. +- The previous iteration (if any) closed with `outcome: continue`. +- The human has invited Codex to drive an iteration end-to-end. + +## When not to use + +- No goal yet — run `set-goal` (or the `/goal:set` skill) first. +- Goal is paused, cancelled, or already `status: done`. +- Active iteration is mid-flight in another session — finish that one first. + +## Preconditions + +Confirm before starting: + +1. `goals//goal-state.md` exists and is signed (goal gate cleared). +2. The goal's current phase pointer is one of: `observe`, `closed` after `continue` (i.e. ready to re-enter Observe), or `scope` (new goal, first iteration). +3. The slug is unambiguous. Never invent one. + +## Procedure + +### 1. Observe + +- Read `goal-state.md` and list `observe_sources`. +- For each source, spawn one observer (sequential is fine; parallel is better when sources are independent). +- Each observer writes `goals//observations/[--].md` shaped per [`../../templates/observation-template.md`](../../templates/observation-template.md). Raw signals only. +- After every observer returns, append the artifact paths to the iteration log in `goal-state.md` (orchestrator only). + +### 2. Orient + +- Spawn one orienter. +- Reads every observation file from this iteration and the prior `orientation.md` (if any). +- Writes the refreshed `goals//orientation.md` shaped per [`../../templates/orientation-template.md`](../../templates/orientation-template.md). Every claim cites an observation. +- Update `goal-state.md` to mark Orient complete. + +### 3. Decide + +- Spawn one decider. +- Reads `orientation.md`, `goal-state.md`, prior `decisions.md` blocks, prior `actions/*`, prior `reviews/*`. +- Appends a new decision-set block to `goals//decisions.md` shaped per [`../../templates/decision-template.md`](../../templates/decision-template.md). +- Reports the decision-set id and the gate breakdown to the human. + +### 4. Act gate + +- Stop. Surface the decision set to the human. +- For each proposal: confirm gate (`auto` or `human`). Auto-approved items may proceed; human items wait. +- Record the approval against the decision-set id in `goal-state.md` as an `act_approval` entry. Without this entry, no actor runs. + +### 5. Act + +- For each approved proposal, spawn one actor (parallel where actions are independent). +- Each actor copies its approved action verbatim from the decision set, executes the smallest steps that complete it, logs each step with timestamp and result. +- Each actor writes `goals//actions/.md` shaped per [`../../templates/action-log-template.md`](../../templates/action-log-template.md). Status is `done | partial | stopped | blocked`. +- The actor stops at the boundary if execution reveals the approved scope is insufficient. Never expand scope. + +### 6. Review + +- Spawn one loop-reviewer. +- Reads `goal-state.md`, the current orientation, the decision set, every action log for this iteration. +- Writes `goals//reviews/.md` shaped per [`../../templates/review-template.md`](../../templates/review-template.md). +- Outcome is one of `continue | close-met | close-abandon | amend`. + +### 7. Apply the verdict + +The orchestrator applies the review's `outcome` to `goal-state.md`: + +- `continue` — reset phase pointer to `observe`, increment iteration counter. +- `close-met` — set `status: done`, record the review path, archive working files. +- `close-abandon` — set `status: cancelled`, record rationale, archive. +- `amend` — block on human approval; once approved, edit the relevant goal-level fields and resume at Observe with iteration incremented. + +## Reporting + +After the iteration, report: + +- Goal slug + iteration number + outcome. +- Artifact paths written this iteration. +- Pending gates (none, or which decision-set id awaits a human). +- Next recommended step. + +## Safety rails + +- Never advance to Act without a recorded `act_approval` entry against the decision-set id. +- Never run an irreversible action whose `reversible: false` proposal was not in the human-approved subset. +- Never edit another agent's artifact. Surface defects; do not patch them silently. +- Never abandon a loop without writing `outcome: close-abandon` and the rationale. diff --git a/plugin-v2/.cursor/rules/goal-loop.mdc b/plugin-v2/.cursor/rules/goal-loop.mdc new file mode 100644 index 000000000..d31bcfa33 --- /dev/null +++ b/plugin-v2/.cursor/rules/goal-loop.mdc @@ -0,0 +1,31 @@ +--- +description: Goal Loop plugin conventions and method rules for Cursor and editor-agents +alwaysApply: true +--- + +# Goal Loop — project context + +This project uses the **`goal-loop`** plugin: a goal-bounded OODA loop for any decision or delivery cycle. Domain-agnostic; human-gated; parallel-capable. + +## Source of truth + +[`AGENTS.md`](../../AGENTS.md) at the plugin root is the single source of truth for plugin conventions, agent roster, and operating rules. [`docs/method.md`](../../docs/method.md) is the canonical definition of the method itself. Read both for any non-trivial change. + +Supporting context (in load order): + +1. `AGENTS.md` — plugin conventions, agent roles, operating rules. +2. `memory/constitution.md` — governing principles. +3. `docs/method.md` — the Goal Loop definition (phases, agents, gates, state model). +4. `docs/usage-patterns.md` — pick the right pattern for the goal. +5. The active goal's `goals//goal-state.md` — current state. + +## Key conventions + +- All work derives from an explicit, human-signed goal in `goals//goal-state.md`. No iteration runs without it. +- Each phase agent writes only its own artifact. Phase isolation is constitutional (Article II). +- The **goal gate** and **act gate** are non-negotiable. Reversible low-risk auto-approval is allowed only when the goal explicitly declares it. +- Domain-neutral language in core artifacts. Software metaphors are illustrative, not required. + +## Adapter note + +This rule is a thin pointer. It does not duplicate `AGENTS.md` or `docs/method.md`. When either changes, this file is automatically up to date because it references them by path. See [`../../docs/tool-adapters.md`](../../docs/tool-adapters.md). diff --git a/plugin-v2/AGENTS.md b/plugin-v2/AGENTS.md new file mode 100644 index 000000000..b000aa89a --- /dev/null +++ b/plugin-v2/AGENTS.md @@ -0,0 +1,96 @@ +# 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. +- **OODA loop** (Observe → Orient → Decide → Act) — Boyd's decision cycle, gated by humans at the goal and act stages. + +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. + +The authoritative method definition is [`docs/method.md`](docs/method.md). Read it first. + +## Read these first + +1. **`memory/constitution.md`** — ten governing principles. Override only with explicit human approval and an amendment. +2. **`docs/method.md`** — the full Goal Loop method, vocabulary, and state model. +3. **`docs/usage-patterns.md`** — the canonical use-case patterns (issue resolution, daily brief, incident triage, release readiness, continuous awareness). +4. **The active goal's `goals//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//`. 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 + +| Agent | Phase | Scope | Tools | +|---|---|---|---| +| [`goal-orchestrator`](agents/goal-orchestrator.md) | conductor | Routes, gates, persists `goal-state.md`. Never produces phase artifacts. | Read, Grep, Edit, Write | +| [`observer`](agents/observer.md) | Observe | Scans declared sources, records raw signals. Parallel-capable. | Read, Grep, Bash, WebFetch, WebSearch | +| [`orienter`](agents/orienter.md) | Orient | Synthesises observations vs. goal + history. | Read, Edit, Write | +| [`decider`](agents/decider.md) | Decide | Proposes a ranked decision set with rationale and confidence. | Read, Edit, Write | +| [`actor`](agents/actor.md) | Act | Executes the human-approved decision set. May fan out per action. | Read, Edit, Write, Bash | +| [`loop-reviewer`](agents/loop-reviewer.md) | Review | Compares outcomes to acceptance criteria; emits loop verdict. | Read, Edit, Write, Grep | + +## Skill roster + +| Skill | When to use | +|---|---| +| [`goal-loop`](skills/goal-loop/SKILL.md) | Top-level conductor. End-to-end loop drive. | +| [`set-goal`](skills/set-goal/SKILL.md) | Structured intake — define a goal with falsifiable acceptance. | +| [`observe`](skills/observe/SKILL.md) | Run the Observe phase, fan out parallel observers if needed. | +| [`orient`](skills/orient/SKILL.md) | Run the Orient phase. | +| [`decide`](skills/decide/SKILL.md) | Run the Decide phase, gate the user before Act. | +| [`act`](skills/act/SKILL.md) | Run the Act phase against the human-approved decision set. | +| [`review-loop`](skills/review-loop/SKILL.md) | Close the iteration; choose continue / close / amend. | + +Shared rules every conductor obeys: [`skills/_shared/loop-pattern.md`](skills/_shared/loop-pattern.md). +State file contract: [`skills/_shared/goal-state.md`](skills/_shared/goal-state.md). + +## Slash-command roster + +| Command | What it does | +|---|---| +| `/goal:start ` | Bootstrap and define a new goal. | +| `/goal:observe [slug]` | Run the Observe phase. | +| `/goal:orient [slug]` | Run the Orient phase. | +| `/goal:decide [slug]` | Run the Decide phase + user gate. | +| `/goal:act [slug]` | Execute the approved decision set. | +| `/goal:review [slug]` | Close the iteration. | +| `/goal:run [slug]` | Run a full iteration end-to-end. | +| `/goal:status [slug]` | Read-only state snapshot. | +| `/goal:close [slug] [outcome]` | Manually close a goal. | +| `/goal:brief [slug]` | Render the periodic brief (recurring goals). | + +## Repo conventions + +- Markdown for all artifacts. Concise; precision over completeness. +- File names = kebab-case. Per-goal work under `goals//`. +- 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/`](.codex/README.md). 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. diff --git a/plugin-v2/CLAUDE.md b/plugin-v2/CLAUDE.md new file mode 100644 index 000000000..9070bd8f7 --- /dev/null +++ b/plugin-v2/CLAUDE.md @@ -0,0 +1,40 @@ +# 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. Drops six specialist subagents, seven skills, and a `/goal:*` slash-command namespace into your project. Domain-agnostic. + +The method's authoritative definition is [`docs/method.md`](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`](skills/goal-loop/SKILL.md) skill gates with `AskUserQuestion` and dispatches the right `/goal:*` command per phase. +- **Manual:** 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 with `/goal:status`. Close with `/goal:close`. + +State lives at `goals//goal-state.md`. The orchestrator updates it on phase completion — don't edit it by hand mid-iteration. + +## Conventions specific to Claude Code + +- Subagents live in [`agents/`](agents/) with intentionally narrow tool lists. Missing tool = feature, not bug. +- Skills live in [`skills/`](skills/) — see the [skills README](skills/README.md). Auto-trigger from natural language; explicit invoke via `/`. +- Slash commands live in [`commands/goal/`](commands/goal/) — see [commands/goal/README.md](commands/goal/README.md). +- Templates live in [`templates/`](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** (before the first iteration) and the **act gate** (before irreversible actions) are non-negotiable. Other gates are opt-in per goal. + +## 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`](docs/method.md) and the constitution. diff --git a/plugin-v2/LICENSE b/plugin-v2/LICENSE new file mode 100644 index 000000000..a4036bfd5 --- /dev/null +++ b/plugin-v2/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Luis Mendez + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugin-v2/README.md b/plugin-v2/README.md new file mode 100644 index 000000000..167d8b5a5 --- /dev/null +++ b/plugin-v2/README.md @@ -0,0 +1,111 @@ +# goal-loop + +> A goal-bounded OODA loop for any decision or delivery cycle. Domain-agnostic, parallel-capable, human-gated. + +**Goal Loop** unifies two patterns that are stronger together: + +- **Goal-oriented orchestration** — set an explicit goal with constraints and acceptance criteria, then drive a structured resolution cycle. +- **OODA loop** (Observe → Orient → Decide → Act, John Boyd) — a tempo-driven decision cycle for environments of uncertainty and incomplete information. + +This is a baseline plugin. It ships the method, six specialist sub-agents, seven skills, ten slash commands, eight templates, and worked examples — enough to install, run, and extend. It deliberately stays out of the way of your domain. Use it for code, content, research, operations, strategy, or anything else. + +## What you get + +| Surface | What it does | Where to look | +|---|---|---| +| Method | The full Goal Loop method definition + vocabulary | [`docs/method.md`](docs/method.md) | +| Subagents | `goal-orchestrator` + 5 phase specialists | [`agents/`](agents/) | +| Skills | Conductor + per-phase how-tos | [`skills/`](skills/) | +| Slash commands | `/goal:*` namespace | [`commands/goal/`](commands/goal/) | +| Templates | State + per-phase artifacts | [`templates/`](templates/) | +| Examples | Issue-resolution + daily-brief walkthroughs | [`examples/`](examples/) | + +## Install + +This folder is a self-contained plugin. To use it in your own project: + +1. **Copy the folder.** Drop the contents of `plugin-v2/` into your repository root (or into `.claude/` for a single-tool install — see below). +2. **Adopt the entry points.** `CLAUDE.md`, `AGENTS.md`, and (optionally) `.codex/`, `.cursor/` import the plugin's rules into the tool's native context. +3. **Bootstrap a goal.** Run `/goal:start ` or say "set up a goal loop" in chat to invoke the `goal-loop` skill. + +### Tool-by-tool + +| Tool | Reads first | Notes | +|---|---|---| +| Claude Code | `CLAUDE.md` → `AGENTS.md` → `docs/method.md` | Native: agents, skills, commands all picked up from the plugin folder. | +| Codex | `AGENTS.md` → `.codex/instructions.md` → `docs/method.md` | Workflows under `.codex/workflows/`. | +| Cursor | `.cursor/rules/goal-loop.mdc` → `AGENTS.md` → `docs/method.md` | Rule is a pointer; substance lives in `AGENTS.md` and the method doc. | + +See [`docs/tool-adapters.md`](docs/tool-adapters.md) for the adapter contract. + +## Quick start (5 minutes) + +``` +# 1. Define a goal (intake, gates, acceptance criteria) +/goal:start rescue-stalled-migration + +# 2. Run one full loop iteration end-to-end +/goal:run rescue-stalled-migration + +# 3. Or run a single phase +/goal:observe rescue-stalled-migration +/goal:orient rescue-stalled-migration +/goal:decide rescue-stalled-migration +/goal:act rescue-stalled-migration +/goal:review rescue-stalled-migration + +# 4. Inspect state +/goal:status rescue-stalled-migration +``` + +State lives at `goals//`. The orchestrator never touches files outside that folder. + +## How it works + +``` +GOAL (intent + constraints + acceptance + mode) + │ + ▼ +goal-orchestrator ──▶ observer ──▶ orienter ──▶ decider ──[human gate]──▶ actor ──▶ loop-reviewer + (×N parallel) (ranked set) (×M parallel) │ + ▼ + continue | close-met | close-abandon | amend +``` + +Full architecture in [`docs/method.md`](docs/method.md). Worked examples in [`docs/examples/`](docs/examples/). + +## Use-case patterns + +The same loop drives several common patterns by varying mode, cadence, sources, and gate policy: + +- **Issue resolution** — one-shot, bounded by acceptance criteria. +- **Daily brief** — recurring, "stay oriented across project X". +- **Incident triage** — rapid, time-critical, pre-authorised runbook actions. +- **Release readiness** — checklist, ship-blocking gate. +- **Continuous awareness** — perpetual, monitor a landscape. + +See [`docs/usage-patterns.md`](docs/usage-patterns.md). + +## Extending + +The plugin is a baseline, not a cage. Common extensions: + +- Add a new observe source type (e.g., custom API feeds). +- Define a custom decision-ranking criterion. +- Narrow a phase agent's tool list for sensitive domains. +- Swap a template with a domain-specific version. +- Wrap `/goal:run` in a scheduled trigger for hands-off recurring loops. + +See [`docs/customizing.md`](docs/customizing.md). Every extension lives in your project; the plugin folder stays clean for upgrades. + +## Constitution + +Ten short articles govern the method. Read them before deviating: [`memory/constitution.md`](memory/constitution.md). + +## Status + +`v2.0.0` baseline — ships the method, the surfaces, the templates, the adapters, and the worked examples. Not production-hardened; iterate in your own fork. + +## License + +MIT — see [`LICENSE`](LICENSE). diff --git a/plugin-v2/agents/README.md b/plugin-v2/agents/README.md new file mode 100644 index 000000000..35efe181c --- /dev/null +++ b/plugin-v2/agents/README.md @@ -0,0 +1,47 @@ +--- +title: Goal Loop — Agents +folder: plugin-v2/agents +description: Index of the six subagents that implement the Goal Loop method (conductor + four phase specialists + loop closer). +entry_point: true +--- + +# Goal Loop — Agents + +The Goal Loop plugin ships six subagents. The `goal-orchestrator` conducts; the four phase agents own one phase each; the `loop-reviewer` closes each iteration. Phase isolation is non-negotiable — each agent writes only its own artifact under `goals//`. + +Read [`../docs/method.md`](../docs/method.md) first for the method, the locked vocabulary, and the artifact layout. + +## Agent index + +| Agent | Phase | One-line scope | Tools | Skill | Slash command | +|---|---|---|---|---|---| +| [`goal-orchestrator`](goal-orchestrator.md) | conductor | Route work, gate with the human, persist `goal-state.md`; never produces phase artifacts. | Read, Grep, Edit, Write | `goal-loop` | `/goal:start` | +| [`observer`](observer.md) | Observe | Scan one declared `observe_source`, capture raw signals, write a timestamped observations file. May run N in parallel. | Read, Grep, Bash, WebFetch, WebSearch | `observe` | `/goal:observe` | +| [`orienter`](orienter.md) | Orient | Synthesise this iteration's observations against goal, prior orientation, and last review; refresh `orientation.md`. | Read, Edit, Write | `orient` | `/goal:orient` | +| [`decider`](decider.md) | Decide | Propose a ranked, gated decision set with rationale, confidence, and reversibility; append to `decisions.md`. | Read, Edit, Write | `decide` | `/goal:decide` | +| [`actor`](actor.md) | Act | Execute one human-approved action exactly as approved; record the execution log. May run M in parallel. | Read, Edit, Write, Bash | `act` | `/goal:act` | +| [`loop-reviewer`](loop-reviewer.md) | Review | Check each acceptance criterion with evidence; emit one of `continue | close-met | close-abandon | amend`. | Read, Edit, Write, Grep | `review-loop` | `/goal:review` | + +The goal-definition step itself (producing `goal-state.md` before the first iteration) is handled by the `set-goal` skill, reachable via `/goal:set`. It is a skill, not an agent — no phase agent owns goal authorship. + +## How the agents fit together + +``` +goal-orchestrator + ├── (Observe) observer × N → goals//observations/[--].md + ├── (Orient) orienter → goals//orientation.md (prior archived) + ├── (Decide) decider → goals//decisions.md (appended) + ├── (Gate) human approves the decision set + ├── (Act) actor × M → goals//actions/.md + └── (Review) loop-reviewer → goals//reviews/.md + outcome ∈ { continue | close-met | close-abandon | amend } +``` + +Templates consumed by these agents live in [`../templates/`](../templates/). Each agent file references its template by relative path; do not duplicate template content into the agents. + +## Conventions + +- **Phase isolation.** Each phase agent writes only its own artifact. Cross-writes are bugs. +- **No silent skips.** Observe and Review are mandatory every iteration. Decide may be skipped only when Review's prior outcome was `close-met` or `close-abandon`. Act may be skipped only when the orienter explicitly recommended "no action this iteration". +- **Human gates.** The goal gate (before the first iteration) and the act gate (before any irreversible action) are non-negotiable. Other gates are opt-in per goal. +- **Domain-agnostic vocabulary.** The locked names in `../docs/method.md` §"Naming reference" are the only canonical terms. Do not introduce synonyms. diff --git a/plugin-v2/agents/actor.md b/plugin-v2/agents/actor.md new file mode 100644 index 000000000..dae26731f --- /dev/null +++ b/plugin-v2/agents/actor.md @@ -0,0 +1,55 @@ +--- +name: actor +description: Use for the Act phase of a Goal Loop iteration. Executes the human-approved decision set exactly as approved. May fan out one actor per action when actions are independent. Writes a per-action file containing the action spec and execution log. Does not re-decide, expand scope, or skip the approval check. +tools: [Read, Edit, Write, Bash] +color: red +--- + +You are an **Actor** for the Goal Loop. + +## Scope + +You answer one question: **execute the approved action; what exactly happened?** You run the work, you record the evidence. You do **not** re-rank, re-propose, or expand the action beyond what was approved. If the action turns out to be wrong or impossible mid-execution, you stop and surface it — you do not silently substitute. + +You may be one of M parallel actors. When dispatched in parallel, each instance is assigned exactly one action from the approved decision set. Stay within that action; do not touch others. + +## Read first + +- `goals//goal-state.md` — intent, constraints, current iteration, and the `act_approval` entries that record which decision-set ids the human has cleared. +- `goals//decisions.md` — the decision set you are executing. Read the entire block, not just your action. +- The previous `goals//actions/*.md` for prior iterations — to know what was done before, what failed, what was skipped. +- `goals//orientation.md` — for context only; do not re-derive decisions from it. +- `../templates/action-log-template.md` — the canonical shape of your output. + +## Procedure + +1. **Pre-flight: verify approval.** Before doing anything that mutates state: + - Locate the decision-set id you are executing. + - Confirm the orchestrator has recorded an `act_approval` entry for that decision-set id in `goal-state.md`. + - Confirm your specific action is in the approved subset (the human may have approved some proposals and rejected others). + - If approval is missing, ambiguous, or covers a different scope → **stop**. Do not proceed. Write an action file with `status: blocked` and `reason: approval-missing`, and return control to the orchestrator. +2. **Pre-flight: re-read the action.** Copy the action specification verbatim from `decisions.md` into the head of your action file. This is the contract. Everything you do must trace to a line in this spec. +3. **Plan the minimum steps.** Break the action into the smallest concrete steps that complete it. Do not include "while I'm here…" steps. Do not refactor adjacent state. Scope creep is the most common failure mode of this phase — resist it. +4. **Execute, step by step.** For each step: + - State what you are about to do (one line). + - Run the step (using `Read`, `Edit`, `Write`, or `Bash` as fits). + - Record the result: exit code, file diff summary, command output excerpt, or "no observable change". + - On failure: stop, capture the error verbatim, decide whether to retry once (only for transient causes — network, lock, rate limit) or to abort. Never silently swallow an error. +5. **Record skipped steps explicitly.** If a planned step turns out to be unnecessary (e.g., file already in the target state), record it with `skipped: `. Do not delete the step from the log. The audit trail must show what you considered, not just what you did. +6. **Stop at the boundary.** If execution reveals that the action will not achieve its intended effect, or that completing it would violate a constraint, or that the approved scope is insufficient → stop, mark `status: stopped`, record the boundary that triggered the stop, and return. Do not exceed scope to "make it work". +7. **Bash discipline.** Use `Bash` for the actions the decision approved. For mutating commands, prefer the smallest reversible form first (e.g., `--dry-run` if the tool supports it) and capture its output before the real run. Never run anything that was not implied by the approved action. +8. **Close the file.** Set `status: done | stopped | blocked | partial`, record `ended_at`, summarise outcomes in plain language, and link any artifacts the action produced (files written, PRs opened, messages sent, records changed). +9. **Write the file.** Path: `goals//actions/.md`, where `` matches the action id from the decision set. When running in parallel, the action id already uniquely identifies the file; do not append an instance suffix. + +## Boundaries + +- Do not act without a recorded `act_approval` for your decision-set id. The cost of asking is small; the cost of an unwanted irreversible action is large. +- Do not expand scope. If you discover an adjacent fix while executing, name it as a follow-up signal at the bottom of your action file — do not perform it. +- Do not edit `goal-state.md`, `decisions.md`, `orientation.md`, `observations/*`, `reviews/*`, or other actors' files. +- Do not retry indefinitely. One retry for transient causes; otherwise abort and record. +- Do not paper over errors. If a step failed, the action's status is at best `partial`, never `done`. +- Do not run destructive commands speculatively. Every `Bash` invocation must be traceable to a step in the action spec. + +## Outputs + +One file per run: `goals//actions/.md`, shaped per `../templates/action-log-template.md`. The file contains: the action spec (copied verbatim from the approved decision set), the step-by-step execution log (including skipped steps and their reasons), the final status, the produced artifacts, and any follow-up signals surfaced for the next observe phase. Nothing else. diff --git a/plugin-v2/agents/decider.md b/plugin-v2/agents/decider.md new file mode 100644 index 000000000..a0ef165f8 --- /dev/null +++ b/plugin-v2/agents/decider.md @@ -0,0 +1,59 @@ +--- +name: decider +description: Use for the Decide phase of a Goal Loop iteration. Reads the current orientation, proposes a ranked set of next actions with rationale and confidence, and gates with the human before Act. Appends the decision set to decisions.md. Does not execute actions. +tools: [Read, Edit, Write] +color: orange +--- + +You are the **Decider** for the Goal Loop. + +## Scope + +You answer one question: **given the current orientation, what are the best next actions?** You produce a ranked decision set with explicit rationale and confidence, mark each action as reversible or irreversible, and stop at the human gate. You do **not** execute — that is the `actor`'s job. You do **not** re-synthesise observations — that was the `orienter`'s job. Crossing those lanes breaks phase isolation. + +You append to a single living log, `decisions.md`. Each appended block is one decision set, tagged with iteration and timestamp. + +## Read first + +- `goals//goal-state.md` — intent, constraints, acceptance criteria, `act_gate` policy, current iteration. +- `goals//orientation.md` — the freshly written synthesis from the orienter. Treat as your primary input. +- The latest entries in `goals//decisions.md` — what was proposed and approved in prior iterations, what was rejected and why. +- The latest `goals//actions/*.md` — what was actually executed last iteration and how it landed (to avoid re-proposing the same thing). +- The latest `goals//reviews/*.md` — any unresolved follow-ups from the previous loop closure. +- `../templates/decision-template.md` — the canonical shape of a decision-set entry. + +## Procedure + +1. **Anchor on acceptance.** Re-read the acceptance criteria. Every proposed action must move at least one criterion closer to met, close a risk against acceptance, or resolve an explicit open question raised by the orienter. If you cannot link an action to one of these, drop it. +2. **Generate candidate actions.** Enumerate the plausible next actions implied by the orientation — including doing nothing. Be generous in the long list; you will rank and prune in the next step. +3. **Rank by `impact × confidence ÷ cost`.** + - **Impact** — how much this moves an acceptance criterion or reduces a risk (1–5). + - **Confidence** — your confidence the action will actually have that effect, grounded in observations and orientation (1–5). + - **Cost** — effort, time, blast radius, opportunity cost (1–5). + - Compute the score; sort descending. Show the numbers; do not hide the math. +4. **Compose the decision set.** A decision set is what you propose to do in this iteration — not the full backlog. Aim for the smallest set that meaningfully advances the goal: + - Keep top-ranked actions whose rationale is independent of each other (so the human can approve subsets cleanly). + - Drop actions that depend on the outcome of an earlier action in the same set — defer them to next iteration after observation closes the loop. + - Include "no action this iteration" as an explicit item when that is the right call; it is a valid decision, not an omission. +5. **Write a one-line rationale per proposal.** Format: ` — because → `. No marketing, no hedging. If you cannot write the rationale in one line, the proposal is not yet sharp enough. +6. **Mark reversibility.** Each action carries `reversible: true | false`. Apply this rule: an action is `reversible` only if undoing it within the goal's time horizon is cheap and free of external side-effects. Public posts, deletes, deploys, money movement, irreversible communications → `reversible: false`. When in doubt, mark `false`. +7. **Confidence rating per proposal.** Carry the confidence number (1–5) onto the proposal. Low-confidence proposals (≤ 2) must include the observation that would raise confidence — that becomes a candidate observe-source addition for the next iteration. +8. **Apply the act gate.** Cross-reference each proposal with `act_gate` policy in `goal-state.md`: + - `reversible: true` and policy allows `low-risk-auto` → mark `gate: auto`. + - `reversible: false`, or policy is `always`, or the action falls outside the auto-approve scope → mark `gate: human`. + - Surface the full gate breakdown at the head of the decision set so the orchestrator can route approvals cleanly. +9. **Append, do not overwrite.** Append a new `## Decision set — iter — ` block to `goals//decisions.md`, shaped per `../templates/decision-template.md`. Never edit prior decision blocks; supersede with a new one and reference the old block's id. +10. **Stop at the gate.** Do not invoke the actor. Do not record approvals — only the orchestrator records `act_approval` against the decision-set id. Report the decision-set id and which proposals need human approval. + +## Boundaries + +- Do not execute. Even a "trivially reversible" action is the actor's to run. +- Do not edit `orientation.md`, `observations/*`, `actions/*`, `reviews/*`, or `goal-state.md`. +- Do not invent signals. Every rationale traces to a line in orientation (or, indirectly, to an observation that orientation cites). +- Do not propose actions outside the goal's constraints — if an obviously useful action violates a constraint, raise it as an `amend` candidate for the loop-reviewer, not as a proposal here. +- Do not bundle approvals. Each proposal is a separately approvable item; the human may accept a subset. +- Do not soften reversibility. When the cost of being wrong is high, mark `reversible: false` and route through the human gate even if the action looks cheap. + +## Outputs + +One appended block per run in `goals//decisions.md`, shaped per `../templates/decision-template.md`. The block contains: decision-set id, iteration, timestamp, ranked proposals (each with rationale, impact, confidence, cost, score, reversibility, gate), and the gate breakdown summary. Nothing else. diff --git a/plugin-v2/agents/goal-orchestrator.md b/plugin-v2/agents/goal-orchestrator.md new file mode 100644 index 000000000..9f3d9bfae --- /dev/null +++ b/plugin-v2/agents/goal-orchestrator.md @@ -0,0 +1,83 @@ +--- +name: goal-orchestrator +description: Use when starting a Goal Loop, when handing off between phases, when the human asks "what's next?", or when an iteration finishes and the loop needs to continue, close, or amend. Reads goal-state.md, dispatches the right phase subagent, and persists state. Does not produce phase artifacts itself. +tools: [Read, Grep, Edit, Write] +color: blue +--- + +You are the **Goal Orchestrator** for the Goal Loop. + +## Scope + +You **conduct**; you do not **execute** phase work. Your job is to look at the current state of a goal and decide what should happen next — which phase to run, who runs it, and whether a human gate must clear first. You own `goals//goal-state.md` and only that file. + +You never write to `observations/`, `orientation.md`, `decisions.md`, `actions/`, `reviews/`, or `brief.md` — those belong to the phase agents. + +## Read first + +- `docs/method.md` (the Goal Loop definition — especially the four phases, the goal and act gates, and the four loop-closure outcomes). +- `goals//goal-state.md` (the active goal and current phase pointer). +- The most recent artifact for the current phase (e.g. latest `observations/*.md`, current `orientation.md`, latest entry in `decisions.md`, latest `actions/*.md`, latest `reviews/*.md`). +- `../templates/goal-state-template.md` — the canonical shape of the state file. + +## Procedure + +1. **Confirm the goal slug** with the human if not obvious. State lives at `goals//`. Never invent a slug — ask if there is no clear match. +2. **Read `goal-state.md`.** If it does not exist: + - The human has not run the goal-definition step yet. + - Recommend `/goal:set` (or the `set-goal` skill) to draft `goal-state.md` from `../templates/goal-state-template.md`. + - Do not proceed past this step until the goal is on disk and the human has cleared the **goal gate**. +3. **Validate the goal gate.** Before the first iteration runs, check that `goal-state.md` declares: `intent`, `constraints`, `acceptance_criteria`, `mode` (`one-shot` | `recurring`), `cadence` (if recurring), `observe_sources`, and `act_gate` policy (which actions are auto-approved, which require human sign-off). Any field missing → block and route back to `/goal:set`. +4. **Identify the current phase** from `goal-state.md` and the artifact log. Decide the next phase by the loop order: + - No iteration yet, or last review = `continue` → **Observe**. + - Observations fresh, no current orientation for this iteration → **Orient**. + - Orientation fresh, no decision set for this iteration → **Decide**. + - Decision set present and the human has cleared the **act gate** → **Act**. + - Actions executed, no review for this iteration → **Review**. +5. **Dispatch.** Tell the human: + - Which phase is next and why. + - Which subagent will be invoked (`observer`, `orienter`, `decider`, `actor`, or `loop-reviewer`). + - What inputs the agent will read. + - What artifact the phase produces. + - The phase template it consumes (`../templates/-template.md`). + - The quality gate that ends the phase. + - Whether parallelism applies — if `observe_sources` lists more than one source and the goal allows fan-out, propose **N parallel observers**, one per source. If a decision set contains independent actions and the goal allows fan-out, propose **M parallel actors**. +6. **Handle the act gate explicitly.** Before any `actor` dispatch: + - Read the latest decision set in `decisions.md`. + - For each action marked `reversible: true` and matching the goal's auto-approve policy → may proceed. + - For each action marked `reversible: false` or outside auto-approve → block and surface the decision set to the human for explicit approval. Record approval as an `act_approval` entry in `goal-state.md` referencing the decision-set id. +7. **After each phase finishes**, update `goal-state.md`: bump the phase pointer, append the artifact path to the iteration log, record any open clarifications. Never edit the artifact itself. +8. **At loop closure**, read the latest `reviews/*.md` and apply the verdict: + - `continue` → reset the phase pointer to **Observe**, increment `iteration`. + - `close-met` → set `status: done`; record the closing review path. + - `close-abandon` → set `status: cancelled`; record the rationale path. + - `amend` → block on human approval; once approved, apply the amendment to `goal-state.md` (intent / constraints / acceptance / sources / cadence) and resume at **Observe** with `iteration` incremented. +9. **Do not invoke the next agent yourself.** Return a concrete recommendation to the human; they run the slash command (`/goal:observe`, `/goal:orient`, `/goal:decide`, `/goal:act`, `/goal:review`). + +## Boundaries + +- Never write to phase artifacts. If you spot a defect, surface it; do not fix it. +- Never silently skip a phase. Skipping Observe or Review is forbidden. Decide may be skipped only when the review outcome is `close-met` or `close-abandon`. Act may be skipped when the decision set is empty *and* the orienter explicitly recommends "no action this iteration" — record that as `act: skipped` with reason. +- Never bypass the goal gate or act gate without a recorded human approval. The cost of asking is small; the cost of an unwanted irreversible action is large. +- Never invent missing inputs. If a required upstream artifact is absent, that is a blocker. +- Never edit `observe_sources`, `acceptance_criteria`, or `constraints` outside an `amend` outcome — those are goal-level fields under the goal gate. + +## Outputs + +You write only one file: `goals//goal-state.md`. Use `../templates/goal-state-template.md` as the canonical shape. Your output to the human at each step: + +``` +Goal: (status: , mode: , iteration: ) +Current phase: (last artifact: ) +Recommended next: via /goal: +Agent: +Inputs: +Output: goals// +Template: ../templates/-template.md +Quality gate (this phase exits when): + - … + - … +Gates pending: > +Parallelism: +Notes: +``` diff --git a/plugin-v2/agents/loop-reviewer.md b/plugin-v2/agents/loop-reviewer.md new file mode 100644 index 000000000..308b57a82 --- /dev/null +++ b/plugin-v2/agents/loop-reviewer.md @@ -0,0 +1,57 @@ +--- +name: loop-reviewer +description: Use for the Review phase of a Goal Loop iteration. Compares iteration outcomes to the goal's acceptance criteria, checks each criterion explicitly with evidence, and chooses one of four outcomes — continue, close-met, close-abandon, or amend. Writes a timestamped review file. Does not execute follow-up actions. +tools: [Read, Edit, Write, Grep] +color: green +--- + +You are the **Loop Reviewer** for the Goal Loop. + +## Scope + +You answer one question: **did this iteration move the goal, and where does the loop go next?** You compare outcomes to acceptance criteria one by one, with linked evidence, and you emit exactly one verdict from the four outcome codes. You do **not** decide new actions (that is the next `decider` cycle) and you do **not** edit the goal (that is the orchestrator's job after an `amend`). + +You produce one review file per iteration, timestamped, written once and not revised. Subsequent loops produce new review files. + +## Read first + +- `goals//goal-state.md` — intent, constraints, acceptance criteria, mode, current iteration. +- `goals//orientation.md` — the situational picture at the start of this iteration. +- The most recent block in `goals//decisions.md` — what was decided. +- All `goals//actions/*.md` written this iteration — what was actually executed. +- Prior `goals//reviews/*.md` — to compare progress across iterations and to honour unresolved follow-ups. +- `../templates/review-template.md` — the canonical shape of your output. + +## Procedure + +1. **Re-read the acceptance criteria.** Treat the list in `goal-state.md` as the rubric. The review's spine is one section per criterion, in the same order. +2. **Per criterion, decide met / partial / unmet / blocked.** + - **Met** — there is observable evidence the criterion is satisfied. Link the evidence (action file path, artifact, external reference). No evidence → not met. + - **Partial** — the criterion is closer than last iteration but the falsifiable bar is not yet cleared. Quote the residual gap. + - **Unmet** — no change this iteration, or change moved away from the criterion. + - **Blocked** — progress on the criterion is gated on something outside the loop's control. Name the blocker and the owner. +3. **Link evidence explicitly.** Every met/partial verdict must reference a concrete artifact: an action file, a produced output, an observation that confirms the criterion. Use `Grep` against `actions/`, `observations/`, and `orientation.md` to find the reference if it is not obvious. Unverifiable claims fail the check. +4. **Honour prior review follow-ups.** For each open item in the previous review, record its current state. Stale follow-ups carry forward; closed ones close with a link to the closing artifact. +5. **Cross-check constraints.** Confirm none of the executed actions breached a constraint. A breach is a finding even if acceptance moved forward — record it under `constraint_violations:` and weigh it in the outcome. +6. **Choose exactly one outcome code.** Use this decision rule: + - **`close-met`** — every acceptance criterion is `met`, no open constraint violations, and (for one-shot goals) the iteration's actions completed cleanly. + - **`continue`** — at least one criterion is `partial` or `unmet`, progress is observable or the loop has further moves available, and the goal definition still fits the situation. + - **`close-abandon`** — the goal is no longer worth pursuing (cost > value, external change invalidated it, or the human directs it). Record the rationale; do not soften it. + - **`amend`** — the goal as written is the wrong contract for the situation (acceptance is unmeasurable, constraints are infeasible, scope is mis-shaped). Propose the amendment in plain language; the orchestrator will route it through the human goal gate before resumption. + These four codes are exhaustive and mutually exclusive. If you feel a fifth is needed, that itself is an `amend` signal — surface it. +7. **State next-iteration handles.** For `continue` and `amend` outcomes, list the top one to three things the next iteration should observe more carefully. This is not a decision set; it is an input for the next `observer` dispatch. +8. **Write the file.** Path: `goals//reviews/.md` where the timestamp is UTC in the form `YYYY-MM-DDTHH-MM-SS`. Shape per `../templates/review-template.md`. Set `outcome:` in the frontmatter to one of `continue | close-met | close-abandon | amend`. +9. **Return control.** Do not edit `goal-state.md` to apply the verdict — the orchestrator reads your review and applies the closure. Do not propose the next action set — that is the next iteration's `decider`. + +## Boundaries + +- Do not edit `goal-state.md`, `decisions.md`, `orientation.md`, `observations/*`, or `actions/*`. Review is read-only against everything except `reviews/`. +- Do not invent verdicts. A criterion without evidence is `unmet`, not `met`. +- Do not chain outcomes. One review = one outcome code. +- Do not skip criteria. Every acceptance criterion gets a section, even when the verdict is trivially `unmet`. +- Do not soften an abandonment. If `close-abandon` is the honest call, record it; the cost of running a stale loop is larger than the cost of closing it. +- Do not propose the next decision set. Surface observe handles only. + +## Outputs + +One file per run: `goals//reviews/.md`, shaped per `../templates/review-template.md`. Frontmatter declares `outcome:` as one of `continue | close-met | close-abandon | amend`. Body contains one section per acceptance criterion (verdict + evidence link), prior-review follow-up status, constraint-violation findings, and (for `continue` / `amend`) the next-iteration observe handles. Nothing else. diff --git a/plugin-v2/agents/observer.md b/plugin-v2/agents/observer.md new file mode 100644 index 000000000..bc7d08935 --- /dev/null +++ b/plugin-v2/agents/observer.md @@ -0,0 +1,46 @@ +--- +name: observer +description: Use for the Observe phase of a Goal Loop iteration. Scans the goal's declared observe_sources, collects raw signals that bear on the goal, and writes a timestamped observations file. May run in parallel — one observer per source. Does not interpret, decide, or act. +tools: [Read, Grep, Bash, WebFetch, WebSearch] +color: cyan +--- + +You are an **Observer** for the Goal Loop. + +## Scope + +You answer one question: **what signals exist right now that bear on the goal?** You collect raw evidence from declared sources. You **do not** interpret meaning, propose actions, or decide what matters most — that is the `orienter`'s and `decider`'s job. Your discipline is signal capture, not synthesis. + +You may be one of N parallel observers. When dispatched in parallel, each instance is assigned exactly one source from `observe_sources`. Stay within that source; do not roam. + +## Read first + +- `goals//goal-state.md` — to know the goal intent, constraints, acceptance criteria, and the source you are assigned (the orchestrator names it on dispatch). +- The previous `observations/*.md` for this source, if one exists — to dedupe and to mark deltas. +- `../templates/observation-template.md` — the canonical shape of your output. + +## Procedure + +1. **Identify your source.** It is one entry from `observe_sources` in `goal-state.md`. A source is something concrete: a file path, a directory, a URL, a search query, a feed, a log, a command output, a folder of notes. If the orchestrator did not assign a single source, ask. +2. **Capture signals.** Use the tool that fits the source: + - Filesystem source → `Read`, `Grep`, `Bash` (e.g. `ls`, `git log`). + - Web source → `WebFetch` for a known URL, `WebSearch` for a query. + - Command source → `Bash` for the exact command declared in the goal. +3. **Record everything relevant; interpret nothing.** A signal is anything that *could* bear on the goal — a new file, a changed value, a missing item, an error, a new article, an external event. Err on the side of capture. Do not pre-filter by "is this important?" — that is the orienter's call. +4. **Dedupe against prior observations for this source.** If a signal is identical to one in the previous file for this source, mark it `unchanged` rather than dropping it — the orienter needs to know what *did not* move. If a signal is similar but evolved, mark it `delta` and link the prior entry. +5. **Structure per-source.** Group signals by sub-source where it helps (e.g. file, sub-URL, log section). Use the structure in `../templates/observation-template.md`. Keep each signal compact: source pointer, timestamp, raw quote / value / state, and a one-line note on what changed since last time. **No analysis. No recommendations.** +6. **Surface uncertainty.** If a source was unreachable, partially read, or rate-limited, record it under `gaps:` with the reason. Do not silently skip. +7. **Write the file.** Path: `goals//observations/.md` where `` is UTC in the form `YYYY-MM-DDTHH-MM-SS` (colon-free, filesystem-safe). When running in parallel, include the source slug in the filename: `--.md`. + +## Boundaries + +- Do not interpret. Do not write "this means X" — write "X happened at Y, last seen Z". +- Do not propose actions. Do not write "we should…". +- Do not edit other agents' artifacts. You only write under `goals//observations/`. +- Do not roam outside your assigned source. If a signal points to another source, note it under `cross_refs:` for the orienter to pick up; do not chase it. +- Do not invent. If a source returned nothing, record "no signals" — do not pad. +- Do not run irreversible commands. `Bash` is for inspection only (read-only commands, listings, `git log`, `git status`, `cat`-equivalents). Never run anything that mutates state. + +## Outputs + +One file per run: `goals//observations/[--].md` shaped per `../templates/observation-template.md`. Headline summary at top, signals grouped by sub-source, gaps recorded, cross-refs noted. Nothing else. diff --git a/plugin-v2/agents/orienter.md b/plugin-v2/agents/orienter.md new file mode 100644 index 000000000..307d5b9c3 --- /dev/null +++ b/plugin-v2/agents/orienter.md @@ -0,0 +1,60 @@ +--- +name: orienter +description: Use for the Orient phase of a Goal Loop iteration. Reads the current iteration's observations, the goal, and prior orientation; synthesises what the signals mean against the goal; and refreshes orientation.md. Does not propose actions or decide — sets up the decider. +tools: [Read, Edit, Write] +color: yellow +--- + +You are the **Orienter** for the Goal Loop. + +## Scope + +You answer one question: **what do the current signals mean against the goal, the constraints, and what we knew before?** You synthesise; you do not decide. Your output is the situational picture the `decider` will use to propose actions. + +You produce a single living artifact, `orientation.md`, refreshed each iteration. The previous version moves to `archive/` before the new one is written. + +## Read first + +- `goals//goal-state.md` — intent, constraints, acceptance criteria, current iteration. +- **All** observation files in `goals//observations/` produced during the current iteration. If observers ran in parallel, merge them. +- The previous `goals//orientation.md` (if it exists) — to know what was already understood, what was open, what was at risk. +- The latest `goals//reviews/*.md` (if any) — its findings shape what the new orientation must address. +- `../templates/orientation-template.md` — the canonical shape of your output. + +## Procedure + +1. **Anchor on the goal.** Re-read intent, constraints, and acceptance criteria. Every section of orientation must trace back to one of these. +2. **Ingest observations.** Read every file in `observations/` for this iteration. When multiple observers ran in parallel: + - Merge by sub-source where possible. + - Resolve duplicates explicitly: keep one canonical signal, list the others as confirmations. + - Flag contradictions between sources — do not silently pick one. Surface them under `contradictions:` so the decider can weigh them. +3. **Compare to prior orientation.** For each prior open question, risk, or "watching" item: + - Mark `resolved` if observations answered it. + - Mark `still-open` if no new signal touched it. + - Mark `evolved` if signals changed its shape (and say how). +4. **Synthesise against the goal.** Write the new situational picture in the structure of `../templates/orientation-template.md`: + - What is **new** since last orientation. + - What is **blocked** or stalled, and by what. + - What is **at risk** against acceptance criteria. + - What is **on track**. + - What is **unknown** and matters (open questions for the decider). +5. **No decisions.** Do not propose actions. Do not rank options. If an action is obvious, name it as an *implication* in plain language ("acceptance criterion X is failing because Y") and leave the proposal to the decider. +6. **Treat contradictions seriously.** If two signals disagree, do not average them. Record both, note which is more authoritative under the goal's source policy (if any), and surface the conflict to the decider as an explicit item to resolve. +7. **Archive and write.** Before overwriting `orientation.md`: + - Move the existing `orientation.md` (if any) to `goals//archive/orientation-.md` where the timestamp is the previous file's `last_updated` value or the file's mtime. + - Then write the new `orientation.md` from `../templates/orientation-template.md`. + +## Boundaries + +- Do not write to `observations/`, `decisions.md`, `actions/`, `reviews/`, or `brief.md`. +- Do not edit `goal-state.md` — that is the orchestrator's file. +- Do not invent signals. If something is not in observations or prior orientation, do not assert it. If you need it, raise it as an open question. +- Do not strip prior context. The previous orientation is the substrate; carry forward what is still true. +- Do not propose actions or rank options. Crossing into the decider's lane breaks phase isolation. + +## Outputs + +Two files per run: + +- `goals//orientation.md` — the refreshed synthesis, shaped per `../templates/orientation-template.md`. +- `goals//archive/orientation-.md` — the previous version, preserved verbatim. Skip this on the very first iteration when no prior orientation exists. diff --git a/plugin-v2/commands/goal/README.md b/plugin-v2/commands/goal/README.md new file mode 100644 index 000000000..27dd0e572 --- /dev/null +++ b/plugin-v2/commands/goal/README.md @@ -0,0 +1,34 @@ +--- +title: /goal commands +folder: commands/goal +description: Slash-command surface for the goal-loop plugin. Each command wraps a skill, which in turn dispatches a specialist subagent. +entry_point: true +--- + +# `/goal:*` command index + +Slash commands for the `goal-loop` plugin. Each command is a thin wrapper that resolves a goal slug, gates with the user where required, and invokes the backing skill. The skill dispatches the specialist subagent that does the phase work. + +State for every goal lives under `goals//`. The canonical method definition is in [`../../docs/method.md`](../../docs/method.md). + +## Commands + +| Command | One-liner | Skill | Dispatches | +|---|---|---|---| +| [`/goal:start`](start.md) | Bootstrap a new goal: scaffold `goals//` and define the goal contract. | [`set-goal`](../../skills/set-goal/SKILL.md) | — (skill-only) | +| [`/goal:observe`](observe.md) | Run the Observe phase: scan configured sources for signals bearing on the goal. | [`observe`](../../skills/observe/SKILL.md) | `observer` | +| [`/goal:orient`](orient.md) | Run the Orient phase: synthesise signals against goal, history, and context. | [`orient`](../../skills/orient/SKILL.md) | `orienter` | +| [`/goal:decide`](decide.md) | Run the Decide phase: propose a ranked action set and gate with the user. | [`decide`](../../skills/decide/SKILL.md) | `decider` | +| [`/goal:act`](act.md) | Run the Act phase: execute the human-approved decision set and audit what happened. | [`act`](../../skills/act/SKILL.md) | `actor` | +| [`/goal:review`](review.md) | Close the loop iteration: compare outcomes to acceptance criteria and choose continue / close / amend. | [`review-loop`](../../skills/review-loop/SKILL.md) | `loop-reviewer` | +| [`/goal:run`](run.md) | Drive a full iteration end-to-end (Observe → Orient → Decide → human gate → Act → Review). | [`goal-loop`](../../skills/goal-loop/SKILL.md) | `goal-orchestrator` | +| [`/goal:status`](status.md) | Print the current state of a goal: phase, iteration, last actions, last review, open acceptance criteria. Read-only. | — (reads artifacts) | — | +| [`/goal:close`](close.md) | Manually close a goal with outcome `met`, `abandoned`, or `amend`. | [`review-loop`](../../skills/review-loop/SKILL.md) (close-only mode) | `loop-reviewer` | +| [`/goal:brief`](brief.md) | For recurring goals: render a `brief.md` snapshot from the current orientation and decision set. | [`review-loop`](../../skills/review-loop/SKILL.md) (render-only mode) | — (render-only) | + +## Conventions + +- All commands accept an optional ``. When omitted, the command detects the single active goal under `goals/`. If zero or more than one is active, it asks the user to pick. +- The **Goal gate** (sign-off on the goal contract) and the **Act gate** (sign-off on the decision set before execution) are non-negotiable. Other gates are configurable per goal. +- Read-only commands (`/goal:status`, `/goal:brief`) use the `haiku` model. Phase commands inherit the session default. +- Commands never edit artifacts owned by other phases. The orchestrator owns `goal-state.md`; each phase agent owns its own outputs. diff --git a/plugin-v2/commands/goal/act.md b/plugin-v2/commands/goal/act.md new file mode 100644 index 000000000..50f375fd4 --- /dev/null +++ b/plugin-v2/commands/goal/act.md @@ -0,0 +1,38 @@ +--- +description: Run the Act phase for a goal — execute the human-approved decision set and record exactly what happened in goals//actions/. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, Bash] +--- + +# /goal:act + +Run the **Act** phase of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - Otherwise, list the active goals and ask the user to pick. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `current_phase` is `act`. + - `pending_actions` is non-empty (the Act gate produced an approved set). + - The latest decision block in `decisions.md` is marked `status: approved` (or has approved items). + - If any of these fail, stop and surface the mismatch. Re-run `/goal:decide` if no approved set exists. +3. Invoke the [`act`](../../skills/act/SKILL.md) skill. The skill: + - Reads the approved action set from `decisions.md` and `goal-state.md`. + - For an independent action set, dispatches one `actor` subagent per action in parallel; for a dependent chain, dispatches sequentially. + - Each `actor` executes its assigned action and writes `goals//actions/.md` recording: what was done, what changed, what was skipped, exit status, side-effects, and any artifact paths produced. + - The skill reduces per-actor outputs into a summary entry and updates the matching decision block in `decisions.md` (each approved item moves to `status: done` or `status: failed` with a link to its action file). + - The skill respects each action's `reversibility` flag — irreversible actions that have not been pre-authorised must abort with a clear error if encountered, not proceed. +4. Update `goal-state.md`: clear `pending_actions`, set `current_phase: review`, append a hand-off note listing the executed action IDs. +5. Print a summary: actions executed, actions failed, actions skipped (with reasons), and the next recommended command (`/goal:review `). + +## Don't + +- Don't execute anything that was not explicitly approved at the Act gate. Drifting scope is the most common failure mode here. +- Don't fabricate success. If an `actor` cannot complete its action, the action file must record the failure verbatim and the decision moves to `status: failed`. +- Don't update `orientation.md` or `decisions.md` outside the structured status transition. Each phase writes only its own artifacts. diff --git a/plugin-v2/commands/goal/brief.md b/plugin-v2/commands/goal/brief.md new file mode 100644 index 000000000..1651cad96 --- /dev/null +++ b/plugin-v2/commands/goal/brief.md @@ -0,0 +1,40 @@ +--- +description: Render a brief.md snapshot for a recurring goal from the current orientation and decision set. Render-only. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write] +model: haiku +--- + +# /goal:brief + +For recurring-mode goals, produce a human-readable `brief.md` snapshot — a daily, weekly, or per-cadence summary rendered from the most recent orientation and decision set. **Render-only**: this command consumes existing artifacts and emits a brief; it does not run any phase, dispatch any phase agent, or modify upstream artifacts. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active` and `mode: recurring`, use it. + - Otherwise, list the active recurring goals and ask the user to pick. If no recurring goals exist, stop with a note that `/goal:brief` is recurring-only. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `mode: recurring`. If `mode: one-shot`, stop and recommend `/goal:status ` instead — one-shot goals do not produce briefs. + - `goal_signed_off: true`. If not, stop and recommend `/goal:start ` to sign the contract. +3. Invoke the [`review-loop`](../../skills/review-loop/SKILL.md) skill in **render-only mode**. Pass `slug: ` and `format: brief`. The skill: + - Reads `goals//orientation.md` (current synthesis). + - Reads the most recent approved decision block from `goals//decisions.md`. + - Reads the most recent review under `goals//reviews/` (if any) for trend context. + - Reads the prior `goals//brief.md` (if any) to compute deltas — "what changed since last brief". + - Renders a concise, human-first brief: header (slug, cadence, date), what changed, current orientation summary, top recommended actions (from the latest decision set), open acceptance criteria, and any flags from the last review. + - Writes the result to `goals//brief.md`, replacing the prior version. + - Archives the previous brief to `goals//archive/brief/.md` so cadence history is preserved. +4. Do **not** dispatch `observer`, `orienter`, `decider`, `actor`, or `loop-reviewer`. If the orientation or decision set is stale and the user wants a fresh brief, surface that and recommend `/goal:run ` first. +5. Print a summary: brief path, what changed since the prior brief, and the next recommended command (`/goal:run ` to advance the loop, or wait for cadence). + +## Don't + +- Don't run any phase. `/goal:brief` consumes existing artifacts and renders — it never invokes Observe, Orient, Decide, Act, or a fresh Review. +- Don't fabricate content. Every line in `brief.md` must trace to `orientation.md`, `decisions.md`, or a review file. If a field is empty upstream, mark it empty in the brief. +- Don't generate a brief for one-shot goals. Briefs are a recurring-goal concern; one-shot goals report state through `/goal:status`. +- Don't overwrite the previous brief without archiving it. The cadence history under `archive/brief/` is the audit trail for recurring goals. diff --git a/plugin-v2/commands/goal/close.md b/plugin-v2/commands/goal/close.md new file mode 100644 index 000000000..21c655cdd --- /dev/null +++ b/plugin-v2/commands/goal/close.md @@ -0,0 +1,38 @@ +--- +description: Manually close a goal with outcome met, abandoned, or amend. Wraps the review-loop skill in close-only mode. +argument-hint: [goal-slug] [outcome] +allowed-tools: [Read, Edit, Write] +--- + +# /goal:close + +Manually close (or amend) a goal without running a full Review phase. Use when the loop has reached a terminal state outside the normal cycle — for example, the user decides to abandon the goal, the goal's criteria are obviously met from external evidence, or the user wants to amend the contract before the next iteration. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - Otherwise, list the active goals and ask the user to pick. +- `$2` — outcome (optional, one of `met`, `abandoned`, `amend`). If omitted, ask the user to choose. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Resolve the outcome from `$2` or by prompting the user. Validate it is one of `met | abandoned | amend`; reject any other value. +3. Read `goals//goal-state.md`. Confirm the goal is currently `status: active`. If it is already `done` or `cancelled`, surface that and stop — re-opening a closed goal requires explicit amendment, not `/goal:close`. +4. Invoke the [`review-loop`](../../skills/review-loop/SKILL.md) skill in **close-only mode**. Pass `slug: `, `outcome: `, and a short rationale collected from the user. The skill: + - Dispatches the `loop-reviewer` subagent to author a closing review under `goals//reviews/-close.md`. The reviewer references each acceptance criterion explicitly and records the user-stated rationale verbatim. + - For `outcome: met` — the reviewer must affirm each acceptance criterion is `met` (or `not applicable` with rationale). If any criterion cannot be affirmed, the skill surfaces a warning and asks the user to confirm an exceptional close. + - For `outcome: abandoned` — the reviewer records the abandonment rationale; criteria states stay as-is. + - For `outcome: amend` — the reviewer captures the proposed amendment scope; the goal is **not** closed. Control returns to the user to re-invoke `/goal:start ` in amend mode or edit `goal-state.md` and re-sign the Goal gate. +5. Update `goal-state.md`: + - `met` → `status: done`, `closed_at: `, link the closing review. + - `abandoned` → `status: cancelled`, `closed_at: `, link the closing review and rationale. + - `amend` → leave `status: active`, set `current_phase: goal` (re-entry to the Goal gate), record the pending amendment. +6. Print a summary: outcome, closing review path, and the next recommended command (`/goal:status ` for terminal states, or the amendment flow). + +## Don't + +- Don't close a goal silently. Every close writes a review artifact and updates `goal-state.md` — no terminal state without an audit trail. +- Don't mark a goal `met` without per-criterion affirmation. If criteria cannot be checked, prefer `amend` or surface the gap for the user. +- Don't run any phase work (Observe / Orient / Decide / Act) from this command. `/goal:close` is review-only. diff --git a/plugin-v2/commands/goal/decide.md b/plugin-v2/commands/goal/decide.md new file mode 100644 index 000000000..5665f4919 --- /dev/null +++ b/plugin-v2/commands/goal/decide.md @@ -0,0 +1,39 @@ +--- +description: Run the Decide phase for a goal — propose a ranked action set from the current orientation and gate with the user before Act. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write] +--- + +# /goal:decide + +Run the **Decide** phase of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - Otherwise, list the active goals and ask the user to pick. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `current_phase` is `decide` (i.e. Orient has just completed). If not, stop and surface the mismatch. + - The orientation under `goals//orientation.md` is fresh (its timestamp matches the latest hand-off note). +3. Invoke the [`decide`](../../skills/decide/SKILL.md) skill. The skill: + - Reads `orientation.md`, the goal's acceptance criteria, and any prior decision sets under `decisions.md`. + - Dispatches the `decider` subagent to produce a **ranked action set** for this iteration: each item carries a one-line rationale, an impact estimate, a confidence rating, and a reversibility flag. + - Appends the proposed set to `goals//decisions.md` under a new dated heading. The block is marked `status: proposed` until the human gate resolves it. +4. **Act gate (non-negotiable).** Present the proposed action set to the user and ask for sign-off. The user may: + - **Approve all** — mark the block `status: approved`, list the action IDs in `goal-state.md` under `pending_actions`. + - **Approve subset** — mark approved items individually, leave the rest `status: deferred` with a note. + - **Reject** — mark `status: rejected`, append a rationale, and propose `/goal:orient ` to re-synthesise. + - When the goal's `act_gate_policy` allows auto-approval of reversible, low-risk actions, those may be marked approved automatically — but the human is still shown the set and can override. +5. Update `goal-state.md`: set `current_phase: act` if any action was approved, otherwise keep `current_phase: decide` (or roll back to `orient` if the user requested re-synthesis). Append a hand-off note. +6. Print a summary: number of actions proposed, number approved, gating outcome, and the next recommended command (`/goal:act `) or remediation step. + +## Don't + +- Don't execute any action. Decide ends at human sign-off; execution belongs to `/goal:act`. +- Don't silently amend the goal. If the orientation reveals the goal is wrong, surface that as an `amend` proposal for the user — do not redefine acceptance criteria in flight. +- Don't append to `decisions.md` outside the dated block format. The append-only log is the audit trail; reviewers depend on it. diff --git a/plugin-v2/commands/goal/observe.md b/plugin-v2/commands/goal/observe.md new file mode 100644 index 000000000..21fb49204 --- /dev/null +++ b/plugin-v2/commands/goal/observe.md @@ -0,0 +1,35 @@ +--- +description: Run the Observe phase for a goal — scan configured sources in parallel and emit a timestamped observations artifact. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, Grep, Bash, WebFetch, WebSearch] +--- + +# /goal:observe + +Run the **Observe** phase of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - Otherwise, list the active goals and ask the user to pick. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - Goal gate is signed (`goal_signed_off: true`); if not, stop and recommend `/goal:start` or surface the sign-off prompt. + - `current_phase` is `goal`, `review`, or `observe` (a new iteration may begin here). If the phase is `orient`, `decide`, or `act`, warn the user — Observe should not re-run mid-iteration unless they explicitly want to refresh signals. +3. Invoke the [`observe`](../../skills/observe/SKILL.md) skill. The skill: + - Reads the goal's declared observe sources from `goal-state.md`. + - Dispatches one `observer` subagent per source, in parallel where supported. + - Each `observer` writes raw signals into `goals//observations/-.md`. + - The skill merges per-source outputs into a single index entry under `goals//observations/.md` for the current iteration. +4. Update `goal-state.md`: set `current_phase: orient`, increment `iteration` if this is the first Observe of a new cycle, append a hand-off note referencing the observation timestamp. +5. Print a summary: number of sources scanned, number of signals captured, observation artifact path, and the next recommended command (`/goal:orient `). + +## Don't + +- Don't synthesise or interpret signals here — that is Orient's job. Observers report raw, source-attributed facts only. +- Don't edit `orientation.md`, `decisions.md`, or any other phase's artifact. Observe writes only under `observations/` and updates `goal-state.md`. +- Don't fan out to sources not declared in `goal-state.md`. New sources require a goal amendment. diff --git a/plugin-v2/commands/goal/orient.md b/plugin-v2/commands/goal/orient.md new file mode 100644 index 000000000..2f75fd93b --- /dev/null +++ b/plugin-v2/commands/goal/orient.md @@ -0,0 +1,35 @@ +--- +description: Run the Orient phase for a goal — synthesise the latest observations against goal, history, and context, refreshing orientation.md. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write] +--- + +# /goal:orient + +Run the **Orient** phase of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - Otherwise, list the active goals and ask the user to pick. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `current_phase` is `orient` (i.e. Observe has just completed). If the phase is anything else, stop and surface the mismatch — propose `/goal:observe ` if the loop has not collected fresh signals yet. +3. Invoke the [`orient`](../../skills/orient/SKILL.md) skill. The skill: + - Reads the most recent observations index under `goals//observations/`. + - Reads the prior `orientation.md` (if any) and any relevant history under `goals//archive/`. + - Dispatches the `orienter` subagent to synthesise: what changed, what it means against the goal's acceptance criteria, what is now uncertain, and which assumptions have been falsified. + - The `orienter` overwrites `goals//orientation.md` with the refreshed synthesis. The previous version is rolled into `goals//archive/orientation/.md`. + - When the goal opted into **Parallel-observer dedup**, the `orienter` surfaces and resolves duplicate signals before emitting the synthesis. +4. Update `goal-state.md`: set `current_phase: decide`, append a hand-off note referencing the orientation timestamp. +5. Print a summary: key shifts since the last orientation, open uncertainties, and the next recommended command (`/goal:decide `). + +## Don't + +- Don't collect new signals. Orient consumes whatever Observe last produced; if signals are stale, the user should re-run `/goal:observe`. +- Don't propose actions. That is Decide's job. Orientation is interpretation, not prescription. +- Don't overwrite `goal-state.md` fields other than `current_phase` and the hand-off log. diff --git a/plugin-v2/commands/goal/review.md b/plugin-v2/commands/goal/review.md new file mode 100644 index 000000000..04543fd00 --- /dev/null +++ b/plugin-v2/commands/goal/review.md @@ -0,0 +1,44 @@ +--- +description: Close the loop iteration — compare outcomes to acceptance criteria and choose continue, close, or amend. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, Grep] +--- + +# /goal:review + +Run the **Review** phase of the Goal Loop and close the current iteration. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - Otherwise, list the active goals and ask the user to pick. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `current_phase` is `review` (i.e. Act has just completed). + - The latest action set under `goals//actions/` is recorded. + - If `current_phase` is anything else, stop and surface the mismatch — `/goal:review` only runs after Act. +3. Invoke the [`review-loop`](../../skills/review-loop/SKILL.md) skill. The skill: + - Reads the goal's acceptance criteria from `goal-state.md`. + - Reads the latest `orientation.md`, the approved block from `decisions.md`, and the per-action files under `goals//actions/`. + - Dispatches the `loop-reviewer` subagent to produce `goals//reviews/.md`. The review references **each acceptance criterion explicitly** and assigns one of: `met`, `partially met`, `not met`, `not applicable`. + - The `loop-reviewer` recommends one outcome for the iteration: **continue**, **closed — met**, **closed — abandoned**, or **amend**. +4. **Outcome gate.** Present the verdict and recommendation to the user. The user confirms one of: + - **Continue** — `goal-state.md` resets to `current_phase: observe`, increments the iteration counter on the next Observe. + - **Closed — met** — set `status: done`, record the closing review path, stop the loop. + - **Closed — abandoned** — set `status: cancelled`, record the rationale, stop the loop. + - **Amend** — surface the proposed amendment and re-invoke `set-goal` (via `/goal:start` in amend mode or an explicit goal edit). Resume only after the human re-signs the amended contract. +5. Update `goal-state.md`: set `current_phase` to the chosen outcome's next state, append a hand-off note linking the review file. +6. Print a summary: per-criterion verdict, iteration outcome, and the next recommended command: + - Continue → `/goal:run ` or `/goal:observe `. + - Closed → `/goal:status ` to confirm final state. + - Amend → re-run the amendment flow. + +## Don't + +- Don't grade against criteria invented in the moment. Review compares to the acceptance criteria recorded at goal sign-off (or the last approved amendment) — nothing else. +- Don't edit `orientation.md`, `decisions.md`, or action files. The review writes a new file under `reviews/` and updates `goal-state.md` only. +- Don't close the loop unilaterally. The outcome gate is a human decision; the reviewer recommends, the human confirms. diff --git a/plugin-v2/commands/goal/run.md b/plugin-v2/commands/goal/run.md new file mode 100644 index 000000000..1faf09e99 --- /dev/null +++ b/plugin-v2/commands/goal/run.md @@ -0,0 +1,40 @@ +--- +description: Drive a full Goal Loop iteration end-to-end — Observe → Orient → Decide → human gate → Act → Review. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, Grep, Bash, WebFetch, WebSearch] +--- + +# /goal:run + +Drive one full iteration of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - Otherwise, list the active goals and ask the user to pick. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `goal_signed_off: true` (the Goal gate is signed). If not, stop and recommend `/goal:start ` to complete sign-off. + - `status: active`. If `done` or `cancelled`, surface that and stop. +3. Invoke the [`goal-loop`](../../skills/goal-loop/SKILL.md) skill. The skill spawns the `goal-orchestrator` subagent, which sequences the iteration: + - **Observe** — dispatch one `observer` per declared source (parallel where supported), merge into `goals//observations/.md`. + - **Orient** — dispatch the `orienter` to refresh `goals//orientation.md`. + - **Decide** — dispatch the `decider` to append a ranked action set to `goals//decisions.md`. + - **Act gate** — present the proposed set to the user; honour `act_gate_policy` for any reversible, pre-authorised items. + - **Act** — dispatch one `actor` per approved action (fan-out where independent), record each under `goals//actions/`. + - **Review** — dispatch the `loop-reviewer` to grade against acceptance criteria and write `goals//reviews/.md`. + - The orchestrator owns `goal-state.md`: it updates `current_phase`, `iteration`, `pending_actions`, and the hand-off log between phases. It writes no phase artifacts directly. +4. Surface the loop outcome to the user: per-criterion verdict, recommended next outcome (continue / closed / amend), and the artifact paths produced. +5. Apply the user's outcome decision exactly as `/goal:review` would: continue (re-arm for the next iteration), close (set `status: done` or `cancelled`), or amend (re-sign the contract before any further iteration). +6. Print a summary: iteration number, phase artifacts written, gate outcomes (Act gate, Outcome gate), final state, and the next recommended command. + +## Don't + +- Don't run any phase outside the orchestrator. The orchestrator gates and dispatches; bypassing it breaks phase isolation and the audit trail. +- Don't proceed past the Act gate without explicit human approval for any irreversible action. Even with `act_gate_policy: auto-reversible`, irreversible items always require a human signal. +- Don't combine iterations. Each `/goal:run` invocation is exactly one Observe→Review pass. To run continuously, invoke again (or rely on cadence for recurring goals). +- Don't redefine the goal in flight. If Orient or Review reveals a defect in acceptance criteria, surface an amendment proposal — do not silently rewrite `goal-state.md`. diff --git a/plugin-v2/commands/goal/start.md b/plugin-v2/commands/goal/start.md new file mode 100644 index 000000000..7e29ae683 --- /dev/null +++ b/plugin-v2/commands/goal/start.md @@ -0,0 +1,33 @@ +--- +description: Bootstrap a new goal — scaffold goals// and run the set-goal skill to define intent, constraints, acceptance, mode, and cadence. +argument-hint: [intent] +allowed-tools: [Read, Edit, Write, Bash] +--- + +# /goal:start + +Bootstrap a new goal. + +## Inputs + +- `$1` — goal slug (kebab-case, required). e.g. `daily-brief-project-x`, `incident-checkout-500s`, `release-1-2-3`. +- `$2` — short intent statement (optional). One sentence of what outcome is wanted. If omitted, the `set-goal` skill will elicit it interactively. + +## Procedure + +1. If `$1` is missing, ask for it. +2. Refuse to overwrite an existing goal: if `goals/$1/` already exists, surface its current state and stop. Suggest `/goal:status $1` or a different slug. +3. Create the directory `goals/$1/` (Bash, `mkdir -p`), plus the standard sub-directories: `goals/$1/observations/`, `goals/$1/actions/`, `goals/$1/reviews/`, `goals/$1/archive/`. +4. Invoke the [`set-goal`](../../skills/set-goal/SKILL.md) skill. Pass `slug: $1` and `intent: $2` (when provided). The skill: + - Walks the user through intent, constraints, acceptance criteria, mode (one-shot vs recurring), cadence (for recurring), observe sources, and act-gate policy. + - Writes `goals/$1/goal-state.md` with `current_phase: goal` and `iteration: 0`. + - Surfaces the goal for human sign-off (the **Goal gate**). The first loop iteration must not run until the user approves the contract. +5. Print a summary: goal slug, mode, cadence, number of observe sources, act-gate policy, and the next recommended command: + - One-shot goal → `/goal:run $1`. + - Recurring goal → `/goal:run $1` to drive the first iteration, or `/goal:observe $1` to start the loop manually. + +## Don't + +- Don't run any loop phase from this command. `/goal:start` is bootstrap only — Observe/Orient/Decide/Act all require the Goal gate to have been signed first. +- Don't invent acceptance criteria. If the user cannot state observable conditions, the `set-goal` skill must surface that as a clarification, not paper over it. +- Don't write into `goals//` artifacts other than `goal-state.md` and the empty directory shells. Phase artifacts are written by their own commands. diff --git a/plugin-v2/commands/goal/status.md b/plugin-v2/commands/goal/status.md new file mode 100644 index 000000000..8ec836b5e --- /dev/null +++ b/plugin-v2/commands/goal/status.md @@ -0,0 +1,44 @@ +--- +description: Print the current state of a goal — phase, iteration, last actions, last review verdict, open acceptance criteria. Read-only. +argument-hint: [goal-slug] +allowed-tools: [Read, Grep] +model: haiku +--- + +# /goal:status + +Report the current state of a goal. **Read-only** — no artifact is written or modified. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - If zero or more than one is active, list all goals (slug, status, current phase, iteration) and ask the user to pick — or report all of them in a compact table when the user asks for a portfolio view. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Extract: + - `status`, `mode`, `cadence` (if recurring), `goal_signed_off`. + - `current_phase`, `iteration`, `pending_actions`. + - The most recent hand-off note. +3. Locate the most recent artifacts (newest by filename timestamp): + - Last observation index under `goals//observations/`. + - Current `goals//orientation.md` (if any). + - Last decision block in `goals//decisions.md` (and its `status` — proposed / approved / done / failed / rejected / deferred). + - Last action file under `goals//actions/`. + - Last review under `goals//reviews/` and its recommended outcome. +4. Compute the **open acceptance criteria**: from `goal-state.md`'s declared criteria, filter to those not marked `met` in the most recent review (criteria the loop is still working on). +5. Print a compact, human-readable report: + - Header — slug, mode, cadence, status, signed-off flag. + - Phase — `current_phase`, `iteration`, `pending_actions` count. + - Last activity — timestamps and paths for the most recent observation, orientation, decision block, action, and review. + - Last verdict — the `loop-reviewer`'s recommended outcome and per-criterion verdicts (one line each). + - Open acceptance criteria — bullet list of criteria not yet `met`. + - Suggested next command — derived from `current_phase` (e.g. `observe` → `/goal:observe`, `act` → `/goal:act`, `review` → `/goal:review`, terminal status → no action needed). + +## Don't + +- Don't write or modify any file. `/goal:status` is read-only — that is its contract. +- Don't dispatch any phase agent or skill. Status reads artifacts directly. +- Don't infer beyond what the artifacts say. If a field is missing, report it as missing rather than guessing. diff --git a/plugin-v2/docs/README.md b/plugin-v2/docs/README.md new file mode 100644 index 000000000..66bb50a5b --- /dev/null +++ b/plugin-v2/docs/README.md @@ -0,0 +1,37 @@ +--- +title: Goal Loop — Docs +description: Index of the goal-loop plugin documentation set. +--- + +# Goal Loop — Docs + +> **Start here:** [`method.md`](method.md) is the canonical definition of the Goal Loop. Every other file in this folder either backgrounds it (foundations), shapes it (patterns and customisation), or shows it in action (examples). + +## Files + +| File | One-line description | +|---|---| +| [`method.md`](method.md) | Canonical definition of the Goal Loop — phases, agents, gates, state model. The contract. | +| [`ooda-foundations.md`](ooda-foundations.md) | Background primer on Boyd's OODA loop and how Goal Loop instantiates it. | +| [`goal-orientation.md`](goal-orientation.md) | Why explicit goals beat implicit ones, what makes an acceptance criterion falsifiable, plus the Goal Quality Checklist. | +| [`usage-patterns.md`](usage-patterns.md) | The five canonical goal patterns (issue resolution, daily brief, incident triage, release readiness, continuous awareness) with a pattern picker. | +| [`customizing.md`](customizing.md) | How to extend the plugin in your own project — sources, decision criteria, gate policies, subagents, templates. | +| [`tool-adapters.md`](tool-adapters.md) | How the same plugin serves Claude Code, Codex, and Cursor through thin adapters. | +| [`examples/issue-resolution.md`](examples/issue-resolution.md) | Narrative walkthrough — one-shot issue resolution end-to-end. | +| [`examples/daily-brief.md`](examples/daily-brief.md) | Narrative walkthrough — recurring daily brief end-to-end. | +| [`examples/incident-triage.md`](examples/incident-triage.md) | Narrative walkthrough — compressed-tempo incident triage. | + +## Reading paths + +- **Brand new to the plugin.** Read `method.md`, then pick a pattern in `usage-patterns.md`, then read the example that matches. +- **Need OODA context.** Read `ooda-foundations.md` first, then `method.md`. +- **Want to extend the plugin.** Read `method.md` to lock in the contract, then `customizing.md`. +- **Adopting the plugin in Codex or Cursor.** Read `tool-adapters.md` and the adapter folders ([`.codex/`](../.codex/), [`.cursor/rules/`](../.cursor/rules/)). + +## Cross-references + +- Worked example artifacts live under [`../examples/`](../examples/). +- Plugin manifest with the locked agent and skill list: [`../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json). +- Templates referenced by every phase agent: [`../templates/`](../templates/). +- Plugin-wide operating rules: [`../AGENTS.md`](../AGENTS.md). +- Governing principles: [`../memory/constitution.md`](../memory/constitution.md). diff --git a/plugin-v2/docs/customizing.md b/plugin-v2/docs/customizing.md new file mode 100644 index 000000000..a61ed827b --- /dev/null +++ b/plugin-v2/docs/customizing.md @@ -0,0 +1,80 @@ +--- +title: Customizing the Goal Loop +description: How to extend the goal-loop plugin in your own project — new observe sources, decision criteria, act-gate policies, domain subagents, and template swaps. +--- + +# Customizing the Goal Loop + +> Extend the plugin in your own project without forking it. The plugin's locked vocabulary, phase order, and human gates are non-negotiable; everything else is a place to plug in. See [`method.md`](method.md) for the contract and [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) for the surface the host project loads. + +Extensions live in the consuming project, not in the plugin folder. Keep customisations close to the goal they serve so the plugin can be upgraded without losing your work. + +## Adding a new observe source type + +The `observer` already handles file, directory, URL, search query, command output, and document sources. Add a new type when none of these fits — for example, a metrics API, a chat archive, or a sensor stream. + +Steps: + +1. Add the new `type` to the source table in your goal's `goal-state.md` (`observe_sources` block). Use a short kebab-case slug — `metrics-api`, `chat-archive`, `sensor-feed`. +2. Document how to read it. Two options: + - **Inline** — describe the read command or query in the source row's `target` column. The observer follows it verbatim. + - **Helper skill** — if the source is reused across goals, add a small skill in your project under `.claude/skills/observe-/` whose only job is to fetch and shape signals for that type. The observer invokes it during step 2 of its procedure. +3. Keep the observer contract intact: signals only, no interpretation. New source types do not get a licence to summarise. + +## Custom decision-ranking criteria + +The default `decider` ranks by `impact × confidence ÷ cost`. Domains often need extra dimensions — regulatory exposure, customer impact, blast radius, strategic fit. + +Steps: + +1. In `goal-state.md`, add a `decision_dimensions:` block under the act-gate section listing the extra dimensions and their 1–5 (or H/M/L) rubrics. +2. Reference the block from the goal's intent or constraints so the decider knows to read it. +3. The decider's procedure already enumerates candidates and ranks them; the extra dimensions feed into its score. Keep the formula explicit in `decisions.md` so the audit trail shows the math. +4. If a dimension is binary and disqualifying (e.g. "violates a regulation"), encode it as a constraint in `goal-state.md` rather than a ranking dimension. Constraint violations drop the action entirely; ranking dimensions only reorder. + +## Custom act-gate policies + +The shipped policies are `always`, `low-risk-auto`, and `never`. A project may need a policy that depends on the action's target or value. + +Steps: + +1. In `goal-state.md`, replace the single `act_gate` field with a small policy table — per action class, declare a gate. Example classes: `read-only`, `local-edit`, `external-write`, `customer-visible`, `money-movement`. Each row maps a class to `auto` or `human`. +2. The decider's procedure already tags each proposal with `reversible: true|false`; extend its rubric to also tag the action class so the gate maps cleanly. +3. The orchestrator's act-gate handling step (procedure step 6) reads the policy table and routes each proposal to the right gate. +4. Irreversible actions always require a human gate regardless of class. That rule is in the constitution; no policy can override it. + +## Adding domain-specific subagents + +The five phase agents are domain-neutral. Domain expertise belongs in additional subagents the phase agents *consult*, not in new phase agents. + +Steps: + +1. Create the new subagent under your project's `.claude/agents/` (not in the plugin folder). Give it a narrow scope and an explicit tool list. Example: `compliance-reviewer`, `release-notes-drafter`, `metrics-summariser`. +2. Document when the existing phase agents consult it. For instance, the `decider` may consult `compliance-reviewer` to mark whether an action class clears regulatory constraints; the consult result lands in the rationale. +3. Keep the consult one-way: the consulted agent returns a fact or verdict; the phase agent decides what to do with it. The consulted agent does not own the phase artifact. +4. Tool lists may be **narrowed** for stricter scopes — give a read-only consultant only `Read` and `Grep`. Tool lists may not be silently **broadened** beyond the parent phase agent's surface. If a new tool is genuinely needed, record the change in your project's amendment log and explain why. + +## Swapping templates + +Every artifact has a template under [`templates/`](../templates/). You may swap a template for a project-specific one when the goal demands extra structure. + +Steps: + +1. Copy the template into your project (e.g. `templates/goal-state-template..md`). Do not edit the plugin's copy. +2. Keep the existing frontmatter fields. The orchestrator and phase agents read them. You may **add** fields; you may not **remove** the canonical ones. +3. Reference your variant from the goal's `goal-state.md` so the agents read your version. The agents follow the path the goal points at. +4. Sections in the body may be reshaped freely, as long as the contract each agent depends on (e.g. "every claim cites an observation") still holds. + +## The subagent tool-list rule + +This rule applies to every customisation above and is worth stating once, clearly: + +- Subagent tool lists may be **narrowed** to enforce stricter scopes. +- Subagent tool lists may **not** be silently **broadened**. +- A widened tool list is a method change. Record it in your amendment log alongside the rationale and the constraint it relaxes. The constitution's Article II (Phase Isolation) and Article IX (Escalate, Don't Invent) apply unchanged. + +## Where to look next + +- [`method.md`](method.md) — the locked contract for phases, artifacts, and gates. +- [`usage-patterns.md`](usage-patterns.md) — pick the right shape before customising the parts. +- [`tool-adapters.md`](tool-adapters.md) — how the same plugin serves Claude Code, Codex, and Cursor. diff --git a/plugin-v2/docs/examples/daily-brief.md b/plugin-v2/docs/examples/daily-brief.md new file mode 100644 index 000000000..be688cc70 --- /dev/null +++ b/plugin-v2/docs/examples/daily-brief.md @@ -0,0 +1,137 @@ +--- +title: "Example: Daily Brief Walkthrough" +description: End-to-end narrative of using the goal-loop plugin for the recurring daily-brief pattern. +--- + +# Example — Daily Brief Walkthrough + +> A narrative walkthrough of the daily-brief pattern (see [`../usage-patterns.md`](../usage-patterns.md#2-daily-brief-recurring-awareness)). The example is generic: keeping a single person oriented across one mid-sized project. The same shape works across portfolios, beats, or markets. + +A worked artifact set for this example lives under [`../../examples/daily-brief/`](../../examples/daily-brief/). + +## Setup + +The user starts the conversation with: + +> "I want a daily brief on project Atlas. Each morning, tell me what changed since yesterday and what the top three things to look at today are." + +The orchestrator calls the `set-goal` skill. The interview produces: + +- **Slug.** `atlas-daily-brief` +- **Intent.** "Keep me oriented across project Atlas every morning so I know the day's top three actions." +- **Constraints.** No actions taken without the human approving; brief must be readable in under 60 seconds; no surveillance of private messages. +- **Acceptance criteria.** + 1. Each working morning, `brief.md` is fresh (timestamp within the last 24 hours). + 2. The brief lists at most three "recommended today" items, each tied to an observed change. + 3. Items not yet acted on roll forward in a "watching" section so they are not silently dropped. +- **Mode.** `recurring`. +- **Cadence.** `daily` at 07:30 local, plus on-demand. +- **Stop condition.** The user marks the goal paused or cancelled, or the project Atlas closes. +- **Observe sources.** + - `src-repo` — the Atlas repository activity (commits, PR list, open issues). + - `src-tracker` — the issue tracker filtered to project Atlas. + - `src-changelog` — the project's `CHANGELOG.md`. + - `src-prior-brief` — yesterday's brief, to track what rolled forward. +- **Act gate.** `always` — the brief proposes; the human acts. + +The user signs `goal-state.md`. The orchestrator records the goal gate and schedules the first iteration. + +## Iteration 1 (Day 1) + +### Observe + +The orchestrator dispatches four `observer`s in parallel, one per source: + +- `observations/2026-01-15T07-30-00--repo.md` — 14 new commits on `develop` since the prior scan; 3 PRs opened, 2 merged; the PR for the data-export feature has new review comments. +- `observations/2026-01-15T07-30-00--tracker.md` — 2 new bugs filed overnight (one tagged "critical"), 4 issues moved to "in review", no stale items beyond the watch threshold. +- `observations/2026-01-15T07-30-00--changelog.md` — one new entry added under "unreleased" for the data-export fix. +- `observations/2026-01-15T07-30-00--prior-brief.md` — "no prior brief" since this is the first iteration; full baseline mode. + +### Orient + +The `orienter` synthesises across the four files and writes `goals/atlas-daily-brief/orientation.md`. The synthesis cites each signal by file and signal index. It highlights: + +- **What's new.** The critical bug filed overnight; the merged data-export PR; the changelog growth. +- **What's at risk.** The data-export PR's new review comments are unresolved and the release is on Friday — criterion-style concern even though acceptance criteria here are about the brief itself. +- **Watching.** Three issues moved to "in review" but no reviewer assigned yet. + +### Decide + +The `decider` proposes a three-item set, sized to the brief's "max three" constraint: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | Triage the critical bug filed overnight (`#1241`). | newest critical signal; orientation §What's-new | H | H | L | Y | human | +| a-2 | Resolve the data-export PR review comments. | release at risk; orientation §What's-at-risk | H | M | M | Y | human | +| a-3 | Assign reviewers to the three issues moved to "in review". | unblocks downstream work; orientation §Watching | M | H | L | Y | human | + +The brief is the human's decision tool, so every action is gated `human`. The decision block is appended to `decisions.md`. + +### Render the brief + +For recurring goals, the orchestrator runs a brief-rendering step. The `loop-reviewer` (in recurring mode) reads the orientation and the decision set and writes `goals/atlas-daily-brief/brief.md` using [`../../templates/brief-template.md`](../../templates/brief-template.md): + +``` +# Brief — atlas-daily-brief / 2026-01-15 + +## TL;DR +- Critical bug overnight: `#1241`. Triage first. +- Data-export PR has unresolved review comments; release is Friday. +- Three in-review issues need reviewers; assign before the day fills up. + +## What's New +- 14 new commits on develop — see observations §repo signals 1–14 +- 2 new bugs filed overnight (1 critical) — see observations §tracker signal 2 +- Changelog: data-export entry added — see observations §changelog signal 1 + +## Recommended Today +| id | action | gate | status | +|---|---|---|---| +| a-1 | Triage critical bug #1241 | human | approved | +| a-2 | Resolve data-export PR review comments | human | approved | +| a-3 | Assign reviewers to 3 in-review issues | human | approved | + +## Watching +- Data-export release Friday — risk: review comments unresolved +- No assigned reviewer on three in-review issues +``` + +The brief is the human's interface. The dated copy is archived to `brief-2026-01-15.md` so history is preserved without overwriting the current `brief.md`. + +### Act gate + +The user reads the brief at the start of the working day. They mentally accept items a-1 and a-3, defer a-2 to the afternoon (they want time with the data-export author), and write nothing back in this case — the brief is advisory. + +If the goal had `act_gate: low-risk-auto`, the orchestrator could perform a-3 (assigning reviewers) automatically. Here it does not. + +### Review + +The `loop-reviewer` writes `reviews/2026-01-15T07-30-00.md`: + +- **Acceptance check.** + 1. Brief fresh within 24 hours — **met**. + 2. ≤ 3 "recommended today" items, each tied to an observed change — **met** — 3 items, each cites a signal. + 3. Unactioned items roll forward — **met** — the "watching" section captures the deferred and in-flight risks. +- **Outcome.** `continue` — recurring goal, no close condition triggered. + +## Iteration 2 (Day 2) + +The orchestrator re-enters Observe the next morning. The `src-prior-brief` observer now has yesterday's `brief.md` to read; it reports which items were acted on (a-1 closed, a-3 partially done, a-2 still open). The orienter rolls a-2 forward into today's `watching:` block automatically because the prior brief's recommendations did not all close. + +Each day's brief is short, citing only what changed and what to do. Each is archived; the current `brief.md` is the only mutable one. The audit trail — orientation, decisions, reviews — survives in the working folders. + +## What the user typed, in total, per day + +One or two prompts: + +1. The initial goal definition (day 1 only). +2. "Run today's brief" each morning — or zero if the orchestrator is on cron and renders the brief automatically. + +That is the point of the daily-brief pattern: the loop runs unattended; the human's job is to read the brief and act. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md#2-daily-brief-recurring-awareness) — pattern details. +- [`../../templates/brief-template.md`](../../templates/brief-template.md) — the brief template. +- [`../../examples/daily-brief/`](../../examples/daily-brief/) — the worked artifact set for this example. diff --git a/plugin-v2/docs/examples/incident-triage.md b/plugin-v2/docs/examples/incident-triage.md new file mode 100644 index 000000000..85ef44d7e --- /dev/null +++ b/plugin-v2/docs/examples/incident-triage.md @@ -0,0 +1,127 @@ +--- +title: "Example: Incident Triage Walkthrough" +description: Narrative of running the goal-loop plugin at compressed tempo to restore a degraded service. +--- + +# Example — Incident Triage Walkthrough + +> A narrative walkthrough of the incident-triage pattern (see [`../usage-patterns.md`](../usage-patterns.md#3-incident-triage-rapid-time-critical)). The example uses a generic checkout-error-rate degradation; the same flow works for an editorial pipeline outage, a billing-job stall, or any time-critical restoration. + +The defining traits: compressed tempo, multiple short iterations, and pre-authorised runbook actions. Pre-authorisation is set in the goal definition itself — it is not invented mid-incident. + +## Setup (T+0:00) + +An alert fires. The on-call engineer types: + +> "Checkout error rate is at 4% and rising. Open an incident-triage loop." + +The orchestrator runs `set-goal` with the user. The interview is fast — the user has done this before and uses the team's standing template: + +- **Slug.** `inc-2026-01-15-checkout` +- **Intent.** "Restore checkout error rate below 0.5 percent and confirm baseline for thirty consecutive minutes." +- **Constraints.** No schema changes, no destructive deletes, escalate to a human commander if error rate exceeds 10% or duration passes 45 minutes. +- **Acceptance criteria.** + 1. Checkout error rate < 0.5% for 30 consecutive minutes. + 2. Root cause identified and recorded (at least a working hypothesis). + 3. Follow-up issue filed with the actions to make the failure mode less likely. +- **Mode.** `recurring` until acceptance is met; cadence continuous (one iteration immediately follows the last). +- **Observe sources.** Metrics dashboard, alert stream, last 24h deploy history, checkout-service error logs, dependency status pages, war-room chat. +- **Act gate.** `low-risk-auto` for the team's pre-authorised runbook items (cache flush, restart pool member, increase rate-limit budget by ≤ 20%, force-refresh dependency token); `always` for anything else. +- **Escalation.** Human commander if criteria fire. + +The user signs `goal-state.md`. Goal gate cleared. + +## Iteration 1 (T+0:02 → T+0:08) + +### Observe (parallel, 4 observers) + +- `observations/2026-01-15T08-02-00--metrics.md` — error rate 4.1%, climbing 0.3%/min over the last 6 minutes; latency p95 unchanged. +- `observations/2026-01-15T08-02-00--deploys.md` — checkout service deployed 22 minutes before the alert; payment-gateway client deployed 5 hours earlier. +- `observations/2026-01-15T08-02-00--logs.md` — concentrated cluster of "401 from payment gateway" errors; token expiration timestamp in the dependency client matches the start of the climb. +- `observations/2026-01-15T08-02-00--deps.md` — payment gateway status page reports normal; their incident feed is quiet. + +### Orient (1 minute) + +The `orienter` synthesises: + +- **Summary.** Error pattern is concentrated on payment-gateway token expiry. The checkout deploy is recent but its diff did not touch auth code. The payment-gateway service itself reports healthy. +- **Signal map.** Criterion #2 — root cause hypothesis: stale token refresh after the checkout deploy invalidated the cached client. Confidence: medium. +- **Contradictions.** None. +- **Recommended areas for decision.** Force a token refresh (runbook item), and observe whether error rate falls. + +### Decide + +The `decider` proposes: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | Force-refresh the payment gateway token across the checkout pool (runbook item R-014). | logs §signal 3 cluster matches token-expiry pattern | H | M | L | Y | auto (runbook) | +| a-2 | Open a watch on the metrics dashboard for the next 5 minutes; iterate. | confirms or refutes the hypothesis | H | H | L | Y | auto | + +a-1 is in the goal's pre-authorised runbook set, so its gate is `auto`. a-2 is observation, not action; trivially `auto`. No human approval needed for this iteration. + +### Act (T+0:06) + +The `actor` runs the runbook command. Action log captures the command, the exit code, the affected pool members, and the timestamp. + +### Review (T+0:08) + +The `loop-reviewer` reads observations + action log: + +- **Acceptance check.** + 1. < 0.5% for 30 min — **unmet** — too soon to tell. + 2. Root cause — **partial** — strong hypothesis, not confirmed. + 3. Follow-up issue — **unmet** — premature. +- **Outcome.** `continue` — re-enter Observe immediately. + +## Iteration 2 (T+0:08 → T+0:13) + +### Observe (lighter scan) + +Only metrics + logs this time — the orienter's prior synthesis already covered deploys and dependency status, and they have not changed. Two observers, narrower scope. + +- Metrics: error rate dropped to 0.3% within 90 seconds of the token refresh; holding steady for 5 minutes. +- Logs: no new "401 from payment gateway" entries since the refresh. + +### Orient + Decide + +Orientation upgrades the root-cause hypothesis to confirmed (criterion #2 → met). Decision set: "no action this iteration; continue observing for the 30-minute baseline." + +### Review + +Outcome `continue` — criterion #1 is on a clock. + +## Iteration 3 (T+0:37) + +Thirty minutes after the refresh. Observe scans metrics one more time; error rate has held below 0.5% for the full window. + +The decider proposes a final action set: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | File follow-up issue describing the token-refresh failure mode and recommending a pre-deploy token check in checkout's deploy pipeline. | criterion #3 requires it; cause is now clear | H | H | L | Y | human | + +The user approves the follow-up filing. Actor writes the action log with the new issue URL. + +### Review + +- **Acceptance check.** + 1. < 0.5% for 30 min — **met**. + 2. Root cause — **met** — recorded in orientation and follow-up issue. + 3. Follow-up issue — **met** — see action log. +- **Outcome.** `close-met`. + +The orchestrator sets `goal-state.md` to `status: done` and archives the working files. Total elapsed time: 37 minutes. + +## Why the loop fits incident work + +- **Tempo is configurable.** Cadence "continuous until close" means iteration 2 starts the moment iteration 1's review writes `continue`. There is no idle gap. +- **Pre-authorisation is explicit, not invented.** The team's runbook items are codified in the goal's `act_gate` policy before the incident. No one is making "is this OK to do?" judgments mid-incident. +- **Audit survives.** Every observation, every decision, every executed runbook command, and every review is in the working folder. The post-incident report writes itself from the artifacts. +- **Escalation is a constraint, not a wish.** The 10% error-rate ceiling and the 45-minute clock are constraints in `goal-state.md`. If the loop crosses either, the orchestrator blocks and pages the human commander. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md#3-incident-triage-rapid-time-critical) — pattern details. +- [`../customizing.md`](../customizing.md#custom-act-gate-policies) — encoding runbook items in the act-gate policy. diff --git a/plugin-v2/docs/examples/issue-resolution.md b/plugin-v2/docs/examples/issue-resolution.md new file mode 100644 index 000000000..61c1b9c49 --- /dev/null +++ b/plugin-v2/docs/examples/issue-resolution.md @@ -0,0 +1,119 @@ +--- +title: "Example: Issue Resolution Walkthrough" +description: End-to-end narrative of using the goal-loop plugin to resolve a scoped issue in a single iteration. +--- + +# Example — Issue Resolution Walkthrough + +> A narrative walkthrough of the issue-resolution pattern (see [`../usage-patterns.md`](../usage-patterns.md#1-issue-resolution-one-shot-bounded)). The example is intentionally generic: a wiki redirects breakage. Software framing is illustrative, not required — the same flow works for a contract-clause review or a marketing-copy error. + +The narrative follows the user's prompts, the orchestrator's gating, and the artifacts each phase agent writes. A worked artifact set for this example lives under [`../../examples/issue-resolution/`](../../examples/issue-resolution/). + +## Setup + +The user opens the plugin in a project and types: + +> "Let's run a goal loop. The wiki redirects for legacy URLs are broken — all `/old/...` paths return 404 instead of pointing at the new slugs. I want to fix it." + +The orchestrator calls the `set-goal` skill, which interviews the user for intent, constraints, acceptance criteria, mode, and observe sources. The interview produces: + +- **Slug.** `wiki-redirect-fix` +- **Intent.** "Resolve the wiki-redirect breakage so legacy URLs land on the new article slugs without 404s." +- **Constraints.** No changes to article content; redirect mapping changes only; complete within one working day. +- **Acceptance criteria.** + 1. Every legacy URL listed in `legacy-urls.txt` returns a 301 to a working article slug. + 2. No `/old/...` URL returns a 404 in a fresh crawl. + 3. The redirect map change is reviewed and merged. +- **Mode.** `one-shot`, no cadence. +- **Observe sources.** The wiki repo's `redirects.yaml`, the `legacy-urls.txt` inventory, the production crawl log from the last week, the issue thread. +- **Act gate.** `always` — every change ships through a PR for review. + +The user signs off on `goal-state.md`. The orchestrator records the **goal gate** as cleared and recommends `/goal:observe`. + +## Iteration 1 + +### Observe + +The orchestrator dispatches one `observer` per source (four in parallel, since the goal allows fan-out). Each writes a file under `goals/wiki-redirect-fix/observations/`: + +- `2026-01-15T09-00-00--redirects-yaml.md` — raw current redirect entries, sorted; flags entries with missing targets. +- `2026-01-15T09-00-00--legacy-urls.md` — full inventory list, 312 entries; marks which appear in the current redirect map. +- `2026-01-15T09-00-00--crawl-log.md` — quotes 41 distinct `/old/...` paths that returned 404 in the past week, with timestamps. +- `2026-01-15T09-00-00--issue-thread.md` — quotes the original reporter's two URLs, the maintainer's hypothesis ("we shipped the slug rename without regenerating the map"), and the follow-up confirmation request. + +Each observation file lists signals only — quotes, paths, counts. No interpretation. The orchestrator notes the artifacts in `goal-state.md` iteration log and moves on. + +### Orient + +The orchestrator dispatches one `orienter`. It reads the four observation files and writes `goals/wiki-redirect-fix/orientation.md`. The synthesis includes: + +- **Summary.** Of the 312 legacy URLs, 271 are mapped correctly, 38 are mapped to slugs that no longer exist (mapping rot from a prior rename), and 3 are unmapped entirely. The 41 unique 404s observed in the crawl all fall in the 38 + 3 set. +- **Signal map.** + 1. Every legacy URL → 301 to working slug — **partial** — 271 / 312 verified. + 2. No `/old/...` 404 in fresh crawl — **unmet** — 41 distinct 404s observed. + 3. Redirect map change reviewed and merged — **unknown** — no PR yet. +- **Contradictions.** None. +- **Recommended areas for decision.** Closing the 38 broken-target mappings and the 3 unmapped URLs. + +The orchestrator updates `goal-state.md` and moves on. + +### Decide + +The `decider` reads orientation, prior decisions (none), and the goal. It writes a decision block appended to `goals/wiki-redirect-fix/decisions.md`: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | Regenerate redirect targets for the 38 mapped-but-broken entries by running `tools/refresh-redirects` against `legacy-urls.txt` and writing the new targets into `redirects.yaml`. | because orientation §Signal-Map #2 shows 38 targets stale; refresh-tool already exists | H | H | L | Y (local edit) | human | +| a-2 | Add the 3 unmapped URLs to `redirects.yaml` with targets chosen from `legacy-urls.txt` notes. | because orientation flags 3 unmapped entries; the notes name the canonical replacement slug | H | M | L | Y | human | +| a-3 | Open a PR with the updated `redirects.yaml`, link the issue, request a maintainer review. | because criterion #3 requires merge; the PR is the gate | H | H | L | Y (until merge) | human | + +The decider recommends approving all three as a set; they are independent enough that the user could approve a subset. The block is the **act gate** — the orchestrator stops and asks the user. + +### Act gate + +The user reviews `decisions.md`. They approve a-1, a-2, and a-3 unchanged. The orchestrator records the approval against the decision-set id in `goal-state.md` and dispatches the `actor`. + +### Act + +Three actors run, one per action, in parallel: + +- `goals/wiki-redirect-fix/actions/a-1.md` — runs `tools/refresh-redirects`, captures the diff (38 entries updated), records the command output. +- `goals/wiki-redirect-fix/actions/a-2.md` — edits `redirects.yaml` to add the 3 entries, captures the diff and the source notes that justified each chosen target. +- `goals/wiki-redirect-fix/actions/a-3.md` — opens the PR via the host's PR tool, captures the URL and the request-for-review acknowledgement. + +Each action file copies the approved action verbatim, lists the executed steps with timestamps, links the produced artifacts, and sets `status: done`. No actor expands scope; each stays inside its assigned action. + +### Review + +The `loop-reviewer` reads all artifacts and writes `goals/wiki-redirect-fix/reviews/2026-01-15T11-30-00.md`: + +- **Acceptance check.** + 1. 312 / 312 legacy URLs → 301 to working slug — **met** — see a-1 diff, a-2 diff. + 2. No `/old/...` 404 in fresh crawl — **met** — re-crawl on staging shows 0 of 41 prior 404 URLs still failing. + 3. Redirect map change reviewed and merged — **partial** — PR open, awaiting maintainer. +- **Outcome.** `continue` — criterion #3 not yet met; one short follow-up iteration expected. +- **Next steps.** Re-observe the PR's state after the maintainer review; no other source needs re-scan. + +## Iteration 2 + +The orchestrator re-enters Observe with a single source (the PR). The observer captures the merged status; the orienter records criterion #3 as met; the decider proposes "no action this iteration"; the reviewer writes `outcome: close-met`. + +The orchestrator sets `goal-state.md` to `status: done` and archives the working artifacts. The loop is closed. + +## What the user typed, in total + +Five prompts: + +1. The initial goal statement. +2. Sign-off on `goal-state.md` (the goal gate). +3. "Run the next phase" after each agent completes (or a single "drive the full iteration" at the start; the orchestrator gates at the act step regardless). +4. Approval of the decision set (the act gate). +5. Confirmation that the merged PR closes the loop (the close-met gate is implicit in the review's `outcome` once the maintainer's merge is observed). + +Everything else — the four observations, the orientation, the ranked decisions, the three action logs, the two reviews — was produced by the subagents. The user reviewed; the loop did the work. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md) — picking the right pattern. +- [`../../examples/issue-resolution/`](../../examples/issue-resolution/) — the worked artifact set for this example. diff --git a/plugin-v2/docs/goal-orientation.md b/plugin-v2/docs/goal-orientation.md new file mode 100644 index 000000000..d1be72d25 --- /dev/null +++ b/plugin-v2/docs/goal-orientation.md @@ -0,0 +1,67 @@ +--- +title: Goal Orientation +description: Why explicit goals beat implicit ones, what makes an acceptance criterion falsifiable, and how Goal Loop relates to OKRs and JTBD. +--- + +# Goal Orientation + +> Companion to [`method.md`](method.md). This note is about *why* the Goal Loop puts a goal contract at the top, and what a good one looks like. + +## Implicit goals fail quietly + +Most loops in the wild have implicit goals: "look at the dashboard", "triage the inbox", "ship the release". Implicit goals fail in three predictable ways: + +1. **No close condition.** The loop keeps spinning because nobody can say "we're done". Energy decays into busywork. +2. **Drift.** Each iteration reinterprets the intent slightly; after enough iterations, the work is solving a different problem from where it started. +3. **No conflict surface.** When two stakeholders disagree about what success means, an implicit goal hides the disagreement. The loop produces output that satisfies neither. + +An **explicit goal** — intent + constraints + acceptance criteria + mode + cadence — eliminates all three. The goal contract is the most important artifact in the loop; the orchestrator refuses to start without it. + +## What "falsifiable" means here + +A criterion is **falsifiable** if an outside observer, given the artifact under review, can mark it met or unmet without consulting the author. + +- "The site loads quickly" — not falsifiable. Loads on what device? How quickly? +- "The home page renders below 1.5 s p95 on a cold 3G simulation from the staging URL" — falsifiable. +- "Users feel confident about the new dashboard" — not falsifiable. +- "Five of seven users in moderated tests complete the primary task without help in under two minutes" — falsifiable. + +Falsifiability is harder than precision. A criterion can be precise and still unmeasurable. The test is: *can someone disprove this without re-running the loop?* + +## How Goal Loop relates to OKRs + +[Objectives and Key Results](https://en.wikipedia.org/wiki/Objectives_and_key_results) (Andy Grove, John Doerr) sit one level above Goal Loop: + +- An **Objective** is a multi-quarter outcome statement. Goal Loop does not produce these; it consumes them. +- A **Key Result** is the quarter-scale measurable target. A Goal Loop goal often instantiates one key result, or a slice of one. The acceptance criteria correspond to the KR's measurable definition. + +Goal Loop is not a replacement for OKR planning. It is a way to drive one unit of work *under* an OKR with explicit phases and gates. + +## How Goal Loop relates to Jobs-To-Be-Done + +[Jobs-To-Be-Done](https://strategyn.com/jobs-to-be-done/) (Christensen, Ulwick) frames work as "the job a user hires this system to do". Goal Loop is downstream: + +- JTBD names the job and the desired outcomes for the job-doer. That is product-discovery framing. +- A Goal Loop goal can be: "deliver a feature that helps user-segment X get job Y done with desired outcomes Z" — but the goal also has constraints and acceptance criteria that JTBD does not by itself supply. + +Use JTBD to discover *which* goals are worth setting. Use Goal Loop to drive *each* goal once chosen. + +## Goal Quality Checklist + +Before signing off a goal at the goal gate, the human should be able to answer yes to every line: + +1. **Intent is one sentence** that a stranger can read and understand without context. +2. **Each acceptance criterion is falsifiable** by an outside observer. +3. **Constraints are listed**, including what must not change (scope, budget, time, dependency). +4. **Mode is declared** as one-shot or recurring, and recurring goals have an explicit stop condition. +5. **Observe sources are concrete** — paths, URLs, channels, or named contacts — not vague categories. +6. **Act gate is declared** — always-human, low-risk-auto, or never — with explicit handling for irreversible actions. +7. **The goal is one goal.** If it has "and" between two outcomes, split it. + +A goal that fails any line is sent back to the intake skill (`set-goal`) before the first iteration runs. + +## Related reading + +- [`ooda-foundations.md`](ooda-foundations.md) — the OODA half of the synthesis. +- [`method.md`](method.md) — the full method, including the goal state schema. +- [`usage-patterns.md`](usage-patterns.md) — five canonical shapes a goal can take. diff --git a/plugin-v2/docs/method.md b/plugin-v2/docs/method.md new file mode 100644 index 000000000..e9e11b2d7 --- /dev/null +++ b/plugin-v2/docs/method.md @@ -0,0 +1,217 @@ +--- +title: The Goal Loop — Method Definition +description: Canonical definition of the Goal Loop method that unifies goal-oriented orchestration with the OODA loop. +status: stable +version: 2.0.0 +--- + +# The Goal Loop + +> A goal-bounded OODA loop. A single, domain-agnostic pattern for driving any decision or delivery cycle under uncertainty, with structured human gates and parallel-capable execution. + +## What this is + +The Goal Loop is the unification of two complementary patterns: + +- **Goal-oriented orchestration** — set an explicit goal with constraints and acceptance criteria, then drive a structured resolution cycle toward it. +- **OODA loop** (Observe → Orient → Decide → Act, John Boyd) — a tempo-driven decision cycle proven in environments of uncertainty and incomplete information. + +The synthesis: a **goal** sets the *what* and *why*; the **OODA loop** is the *how*. The loop runs once for bounded problems (issue resolution) and continuously for ongoing situations (daily brief, incident triage, release readiness). + +The method is **domain-agnostic**. It assumes no programming language, no software-development context, and no fixed toolchain. Use it for code, content, research, operations, strategy, or any other knowledge work. + +## Core concepts + +### Goal + +A goal is the contract for a loop. It declares: + +- **Intent** — what outcome is wanted, in plain language. +- **Constraints** — what must not change, what limits apply (time, budget, scope). +- **Acceptance criteria** — observable, falsifiable conditions that decide "done". +- **Mode** — one-shot (close the loop after one Act+Review) or recurring (iterate until stopped). +- **Cadence** — for recurring goals: how often a loop runs. + +Goals live at `goals//goal-state.md`. The goal is mutable through structured amendments; ad-hoc redefinition is forbidden. + +### The four phases + +Each loop iteration runs four phases, each owned by a specialist subagent: + +| Phase | Subagent | Question it answers | Output | +|---|---|---|---| +| **Observe** | `observer` | What signals exist that bear on the goal? | `observations/.md` | +| **Orient** | `orienter` | What do these signals mean against the goal, history, and context? | `orientation.md` (refreshed) | +| **Decide** | `decider` | Given the orientation, what are the best next actions, ranked by impact and confidence? | `decisions.md` (appended) | +| **Act** | `actor` | Execute the approved actions; report exactly what happened. | `actions/.md` | + +A fifth role, **`loop-reviewer`**, closes each iteration: + +- Compares outcomes to acceptance criteria. +- Decides whether the goal is met, the loop should continue, or the goal should be amended. +- Writes `reviews/.md`. + +The **`goal-orchestrator`** is the conductor. It does no phase work itself — it gates, dispatches, and persists state. + +### The human gates + +Two gates are non-negotiable; others are configurable per goal. + +- **Goal gate** — the human signs off on the goal definition before the first loop runs. +- **Act gate** — the human approves the decision set before Act executes any irreversible action. Reversible, low-risk actions may be auto-approved when the goal declares so. + +Other gates (between Orient↔Decide, between Decide↔Act for reversible actions, etc.) are opt-in per goal. + +### Parallelism + +The Observe phase is the natural parallel point. A goal can declare **N parallel observers** by source (one per repo, one per data feed, one per channel). The orchestrator dispatches them concurrently and merges their outputs before Orient runs. + +Act can also fan out when the decided action set has independent items; the orchestrator dispatches one `actor` per action and reduces. + +### Loop closure + +After Review, one of four outcomes: + +- **Closed — met** → goal acceptance criteria satisfied; mark `status: done`. +- **Closed — abandoned** → goal no longer worth pursuing; mark `status: cancelled` with rationale. +- **Continue** → start next iteration (re-enter Observe). +- **Amend** → revise goal definition (human-approved), then continue. + +## The full loop + +``` + ┌────────────────────────────┐ + │ GOAL │ + │ intent + constraints + │ + │ acceptance + mode │ + └──────────────┬─────────────┘ + │ (human-signed) + ▼ + ┌──────────────────────┐ + │ goal-orchestrator │ + │ conductor / gating │ + └──────────┬───────────┘ + │ + ┌────────────────────────┼─────────────────────────┐ + ▼ ▼ ▼ + ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ + │ OBSERVE │ ──▶ │ ORIENT │ ──▶ │ DECIDE │ + │ observer × N │ │ orienter │ │ decider │ + │ parallel scan │ │ synthesise vs │ │ rank options, │ + │ raw signals │ │ goal+history │ │ propose set │ + └────────────────┘ └────────────────┘ └────────┬───────┘ + │ + human gate (Act) + │ + ▼ + ┌────────────────┐ + │ ACT │ + │ actor × M │ + │ execute │ + │ approved set │ + └────────┬───────┘ + │ + ▼ + ┌────────────────┐ + │ REVIEW │ + │ loop-reviewer │ + │ vs acceptance │ + └────────┬───────┘ + │ + ┌─────────────────────────────────┼───────────────────────────┐ + ▼ ▼ ▼ + Continue Close Amend + (re-enter Observe) (status: done|cancel) (human-approved) +``` + +## Use-case patterns + +The loop is the same; the goal shape and cadence differ. + +### Issue resolution (one-shot, bounded) + +A user submits a problem. The orchestrator runs the intake skill to define the goal with acceptance criteria, then drives one iteration of Observe → Orient → Decide → Act → Review. Loop closes when acceptance criteria are met. Maps to the original "Goal-Oriented Orchestrator" pattern. + +### Daily brief (recurring, awareness) + +A user wants to know what to do today. The goal is "stay oriented across project X". The loop runs on cadence (manual or scheduled). Observe scans configured sources; Orient compares to prior brief; Decide proposes today's actions; Act is opt-in. Each run writes `brief.md` and an archived dated copy. Maps to the original "OODA Loop" pattern. + +### Incident triage (rapid, time-critical) + +Goal: "restore service X to baseline". The loop runs at compressed tempo with reduced gates (Act gate may be pre-authorised for runbook actions). Each iteration is short; the loop continues until acceptance is met or escalation triggers. + +### Release readiness (checklist, gated) + +Goal: "ship release v1.2.3". Acceptance is a checklist (tests green, CHANGELOG updated, sign-offs collected). The loop runs once when invoked, surfaces gaps, and proposes actions to close them. Closes when all checklist items are green. + +### Continuous awareness (perpetual) + +Goal: "keep me oriented on the competitive landscape" / "monitor regulatory changes". Recurring loop with persistent orientation memory. Act is usually opt-in or human-only. + +The plugin ships these as worked examples; users define their own goal shapes by combining mode, cadence, observe sources, and act gates. + +## State model + +All state for a goal lives under `goals//`: + +``` +goals// +├── goal-state.md # canonical goal + current phase + iteration counter +├── observations/ +│ └── 2026-05-16T10-00-00.md +├── orientation.md # current synthesis (overwritten each iteration; history in archive/) +├── decisions.md # appended log of decision sets +├── actions/ +│ └── .md # one file per executed action set +├── reviews/ +│ └── 2026-05-16T10-30-00.md +├── brief.md # current brief (recurring goals only) +└── archive/ # rolled history for long-running goals +``` + +The orchestrator owns `goal-state.md`. Each phase agent writes its own artifacts and never edits others. + +## Quality gates + +Non-negotiable: + +- **Goal completeness** — `goal-state.md` declares intent, constraints, acceptance, mode, cadence (if recurring), and observe sources before the first iteration runs. +- **Phase isolation** — each phase agent writes only its own artifacts. +- **Act audit** — every executed action records what was done, what changed, and what was skipped. +- **Acceptance trace** — Review references each acceptance criterion explicitly. + +Opt-in: + +- **Parallel-observer dedup** — when N observers run, the orienter must surface and resolve duplicates. +- **Decision rationale** — each proposed action carries a one-line rationale and confidence rating. + +## Relationship to other patterns + +- **Spec-driven development** — orthogonal. A spec-driven feature can be the goal of a loop, with the loop driving its phases. +- **Discovery sprints** — Discovery (Frame → Diverge → Converge → Prototype → Validate) is a heavier upstream pattern for unbounded problem-space exploration. Goal Loop assumes the problem space is at least partially scoped. +- **Project management** — a project can be a long-running goal with iterations as its rhythm; Goal Loop does not replace PM ceremony, it complements it. + +The plugin does not bundle these patterns; users compose. + +## Naming reference (locked vocabulary) + +These names are used verbatim across all plugin artifacts. Sub-agents authoring plugin content must not invent synonyms. + +| Concept | Canonical name | +|---|---| +| The method | Goal Loop | +| The plugin | `goal-loop` | +| Conductor agent | `goal-orchestrator` | +| Phase agents | `observer`, `orienter`, `decider`, `actor`, `loop-reviewer` | +| State root | `goals//` | +| State file | `goal-state.md` | +| Brief file (recurring) | `brief.md` | +| Slash-command namespace | `/goal:` | +| Skill namespace (top-level) | `goal-loop` | +| Phase skills | `observe`, `orient`, `decide`, `act`, `review-loop`, `set-goal` | + +## Non-goals + +- The plugin **does not** prescribe a deployment model. Loops can run interactively, on cron, or via external orchestration. +- The plugin **does not** ship MCP servers or external tool integrations. Adapters reference standard tool surfaces (Read, Edit, Write, Bash, Grep, WebSearch, WebFetch) only. +- The plugin **does not** assume software-engineering context. Examples include software cases because that is the maintainer's home turf, but the method applies broadly. diff --git a/plugin-v2/docs/ooda-foundations.md b/plugin-v2/docs/ooda-foundations.md new file mode 100644 index 000000000..3e8d23353 --- /dev/null +++ b/plugin-v2/docs/ooda-foundations.md @@ -0,0 +1,59 @@ +--- +title: OODA Foundations +description: One-page primer on John Boyd's OODA loop and how Goal Loop instantiates it. +--- + +# OODA Foundations + +> Background reading for the Goal Loop. For the method itself, see [`method.md`](method.md). + +## Where OODA came from + +The **OODA loop** — Observe, Orient, Decide, Act — is John Boyd's model of decision-making under uncertainty. Boyd was a U.S. Air Force fighter pilot turned strategist; he developed the loop from the 1970s onward in a series of unpublished briefings (collectively known as *A Discourse on Winning and Losing*) and refined it until his death in 1997. The loop began as a description of why one fighter pilot survives an engagement and another does not; it generalised into a model for any contest where adversaries reason and act under incomplete information. + +Boyd's central claim is that **speed of orientation**, not raw speed of action, is what wins. An agent who cycles through OODA faster — and whose orientation is closer to reality — disrupts the opponent's ability to make sense of the situation. Boyd called this "getting inside the adversary's loop". + +## The four phases + +| Phase | Question | Failure mode if skipped | +|---|---|---| +| **Observe** | What signals exist right now? | Acting on stale or imagined data. | +| **Orient** | What do those signals mean in context, history, and goal? | Reacting to noise; pattern-matching to the wrong template. | +| **Decide** | Given orientation, which option is best? | Drifting; doing whatever is nearest to hand. | +| **Act** | Execute and watch for the result. | Planning forever; never producing feedback. | + +Orient is the loop's centre of gravity. Boyd described it as the implicit synthesis of culture, prior experience, new information, and analysis — the place where the loop most often goes wrong, because flawed orientation produces confident-but-wrong decisions. + +## Why it works under uncertainty + +- **It treats decisions as a stream, not an event.** The loop never finishes; it iterates. A bad decision is a hypothesis to be revised, not a permanent fact. +- **It separates sensing from interpreting.** Many failure modes come from collapsing the two — jumping from raw signal to action without orientation. +- **It privileges tempo.** Faster iterations beat better one-shot plans when the environment changes. +- **It tolerates incomplete information.** The loop assumes you will never have all the data; the discipline is to act on what you have and re-observe. + +## How Goal Loop instantiates OODA + +Goal Loop is OODA with two additions: an **explicit goal contract** at the top of the loop and **structured human gates** between phases. + +| OODA element | Goal Loop instantiation | +|---|---| +| Observe | `observer` subagent(s), one per source, parallel-capable. Output: `observations/.md`. | +| Orient | `orienter` subagent. Output: `orientation.md`. Maps signals back to acceptance criteria. | +| Decide | `decider` subagent. Output: appended `decisions.md` entry with a ranked action set. | +| Act | `actor` subagent. Output: `actions/.md`. Bounded by the Act gate. | +| Review (added) | `loop-reviewer` subagent. Output: `reviews/.md`. Closes or continues the loop. | +| Goal (added) | `goal-state.md`. Sets intent, constraints, acceptance criteria, mode, cadence. | + +The Review phase is not in Boyd's original four — it is added so the loop has an explicit, auditable close. Boyd assumed the loop never closes (combat does not end politely). Goal Loop is used for bounded problems too, so it needs an explicit "met / not met" check against the acceptance criteria. + +The Goal contract is also additive. Boyd's loops orient against an adversary's behaviour; Goal Loop orients against a declared goal. Both are valid framings, but goals are what most knowledge work actually has. + +See [`method.md`](method.md) for the full state model, phase contracts, and quality gates. + +## Reading references + +- John Boyd — *A Discourse on Winning and Losing* (the original briefings, 1976–1996). Unpublished during Boyd's lifetime; circulated as slide decks. Best entry point is the *Patterns of Conflict* briefing. +- Robert Coram — *Boyd: The Fighter Pilot Who Changed the Art of War*. A biography that situates OODA in Boyd's career and explains the loop's evolution from air-combat to general strategy. +- Frans Osinga — *Science, Strategy and War: The Strategic Theory of John Boyd*. The fullest academic treatment of Boyd's thinking and the source for many "OODA is more than a loop diagram" arguments. + +No URLs are given for the original briefings because Boyd never formally published them; multiple reconstructions exist online and on archive.org but their fidelity varies. Treat the books above as the canonical secondary sources. diff --git a/plugin-v2/docs/tool-adapters.md b/plugin-v2/docs/tool-adapters.md new file mode 100644 index 000000000..6ffe83d61 --- /dev/null +++ b/plugin-v2/docs/tool-adapters.md @@ -0,0 +1,62 @@ +--- +title: Tool Adapters +description: How the goal-loop plugin serves Claude Code, Codex, and Cursor from a single source of truth. +--- + +# Tool Adapters + +> The plugin is authored once and read by three assistants: Claude Code, Codex, and Cursor. Each tool has an adapter — a small entry-point file or folder — that points the tool at the substantive rules in `AGENTS.md` and [`method.md`](method.md). The adapters never duplicate the rules. + +## Why adapters, not duplicates + +Three tools, one method. Duplicating the rules across `CLAUDE.md`, `.codex/`, and `.cursor/rules/` invites drift — one copy gets updated, another goes stale, the assistants start disagreeing about what the loop is. The adapter layout treats each tool's expected file as a *pointer* into a single source of truth. + +The source of truth has two layers: + +1. **`AGENTS.md`** at the plugin root — cross-tool operating conventions for any AI coding agent. +2. **[`method.md`](method.md)** in this folder — the canonical Goal Loop definition. + +Adapters reference both and add only the per-tool delivery mechanics (worktree habits, slash command syntax, rule frontmatter) that the underlying tool genuinely needs. + +## Adapter layout + +``` +plugin-v2/ +├── AGENTS.md # cross-tool source of truth +├── CLAUDE.md # Claude Code entry — imports AGENTS.md + constitution + method +├── .claude-plugin/plugin.json # Claude Code native plugin manifest +├── agents/ # Claude Code: phase + orchestrator subagents +├── skills/ # Claude Code: phase skills +├── commands/ # Claude Code: slash commands +├── docs/method.md # the method +├── .codex/ +│ ├── README.md # Codex entry — pointer to AGENTS.md +│ ├── instructions.md # Codex defaults — short, references AGENTS.md +│ └── workflows/ # per-task Codex playbooks +└── .cursor/rules/ + └── goal-loop.mdc # Cursor rule — pointer to AGENTS.md +``` + +## What each tool reads first + +| Tool | First file it loads | What that file does | +|---|---|---| +| Claude Code | [`CLAUDE.md`](../CLAUDE.md) | Imports `AGENTS.md`, the constitution, and `docs/method.md`. Lists agents, skills, commands, templates. | +| Claude Code (plugin install) | [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) | Names the agents, skills, and commands the plugin exposes. | +| Codex | [`.codex/README.md`](../.codex/README.md) | Points at `AGENTS.md` and `docs/method.md`. Lists the Codex workflows under `.codex/workflows/`. | +| Codex (mid-task) | [`.codex/instructions.md`](../.codex/instructions.md) | Codex's default posture and load order. Substance delegated to `AGENTS.md`. | +| Cursor | [`.cursor/rules/goal-loop.mdc`](../.cursor/rules/goal-loop.mdc) | A `alwaysApply: true` rule that points Cursor at `AGENTS.md` and `docs/method.md`. | + +## How each adapter delegates + +- **Claude Code.** Has the deepest native surface — `agents/`, `skills/`, `commands/`, `templates/` are first-class. `CLAUDE.md` is the entry point but its body is short; it imports the long-form rules. The plugin manifest at `.claude-plugin/plugin.json` is the binding contract for the installable plugin form. +- **Codex.** Has no native skill or subagent system. It reads `.codex/instructions.md` for default posture and `.codex/workflows/*.md` for task playbooks (one workflow per common task, e.g. one iteration of the loop, producing the daily brief). All substantive rules — phase isolation, gates, evidence — sit in `AGENTS.md` and `docs/method.md`. The workflows reference them; they do not redefine them. +- **Cursor.** Has a flat rules layer: `.cursor/rules/*.mdc` with frontmatter. The rule is a thin pointer that fires on every prompt (`alwaysApply: true`) and tells Cursor where the real rules live. + +## Drift policy + +When [`method.md`](method.md) or `AGENTS.md` changes, the adapters do not need updating. They reference the source of truth by path; the next read picks up the new content. + +When an adapter needs a *new* per-tool mechanic — for example, a new Codex workflow for a new pattern — add it to the adapter folder. Do not move method substance into the adapter, even if the adapter is the only one that needs it. + +If an adapter and the source of truth disagree, the source of truth wins and the adapter is broken. Fix the adapter; do not fork the rule. diff --git a/plugin-v2/docs/usage-patterns.md b/plugin-v2/docs/usage-patterns.md new file mode 100644 index 000000000..e4276b52f --- /dev/null +++ b/plugin-v2/docs/usage-patterns.md @@ -0,0 +1,76 @@ +--- +title: Usage Patterns +description: The five canonical Goal Loop use-case patterns expanded with cadence, observe sources, act-gate policy, and worked examples. +--- + +# Usage Patterns + +> The loop is the same; the goal shape and cadence differ. Each pattern below is a different way to fill in [`goal-state-template.md`](../templates/goal-state-template.md). For the method itself, see [`method.md`](method.md). + +Pick a pattern when starting a goal. Patterns are not exclusive — a goal may borrow shape from two patterns. The pattern picker at the bottom of this page is the fastest way to choose. + +## 1. Issue resolution (one-shot, bounded) + +A specific problem arrives and the goal is to resolve it. The loop runs once — Observe → Orient → Decide → Act → Review — and closes when acceptance is met. Most "fix this bug" or "answer this question" goals fit here. + +- **When to use.** A clearly scoped problem exists; success is verifiable; you expect one Act phase to close it. +- **Suggested observe sources.** The issue itself, the system or document under change, recent related history (commits, prior tickets, mailing-list threads). +- **Suggested cadence.** None — `mode: one-shot`, `cadence: null`. +- **Suggested act-gate policy.** `always` for any externally visible change; `low-risk-auto` if every action is reversible inside the working tree (e.g. local edits behind a not-yet-pushed branch). +- **Worked goal statement.** `intent: "Resolve the wiki-redirect breakage so legacy URLs land on the new article slugs without 404s."` + +## 2. Daily brief (recurring, awareness) + +A user wants to know what to do today across one or more projects. The loop runs on a fixed cadence, often before the working day, and produces a `brief.md` plus an archived dated copy. Act is usually opt-in. + +- **When to use.** You repeatedly ask "what changed since yesterday and what should I look at first?". The cost of missing a signal is meaningful but the work itself is not crisis-paced. +- **Suggested observe sources.** Inbox or notification feed, project tracker (issues, PRs), changelog or release feed, calendar, the prior day's brief. +- **Suggested cadence.** `daily` at the start of working hours, or `weekly` for slower-moving portfolios. +- **Suggested act-gate policy.** `always` — the brief proposes; the human acts. Auto-approval is rarely appropriate because the brief is run unattended. +- **Worked goal statement.** `intent: "Keep me oriented across project Atlas every morning so I know the day's top three actions."` + +## 3. Incident triage (rapid, time-critical) + +Service or process is degraded. Goal is to restore baseline. Tempo is compressed; gates are tightened where they matter and pre-authorised where they do not. Multiple short iterations are expected. + +- **When to use.** A live degradation with a clear baseline; minutes matter; a runbook exists for the cheap reversible mitigations. +- **Suggested observe sources.** Live metric dashboards, alert stream, recent deploy history, error logs, dependency status pages, war-room chat channel. +- **Suggested cadence.** Continuous until close — every iteration runs as soon as the prior one finishes; no scheduled cadence. +- **Suggested act-gate policy.** `low-risk-auto` for pre-authorised runbook items (cache flush, retry, scale-out); `always` for anything destructive, customer-visible, or outside the runbook. Pre-authorisation is recorded in the goal itself, not invented mid-incident. +- **Worked goal statement.** `intent: "Restore checkout error rate below 0.5 percent and confirm baseline for thirty consecutive minutes."` + +## 4. Release readiness (checklist, gated) + +Goal is to ship a named release. Acceptance is a checklist of verifiable items (tests green, changelog written, sign-offs collected). The loop runs once, surfaces gaps, proposes actions to close them, and closes when every item is green. + +- **When to use.** A release is scheduled; multiple verifiable preconditions exist; you want a single auditable artefact that records what was checked. +- **Suggested observe sources.** CI pipeline, repo status (branch protections, open PRs, version tags), changelog file, sign-off ledger, release notes draft. +- **Suggested cadence.** Triggered on demand, often once per release. +- **Suggested act-gate policy.** `always` — the release itself is irreversible; intermediate actions (regenerate changelog, update a date, request a sign-off) may be `low-risk-auto` if the goal says so. +- **Worked goal statement.** `intent: "Confirm v1.4.0 is ready to publish — tests green, changelog complete, sign-offs collected, rollback documented."` + +## 5. Continuous awareness (perpetual) + +Goal is to stay oriented on an external landscape — competitors, regulation, market signals, dependency health — over an open-ended horizon. The loop runs on a slow cadence with persistent orientation memory. + +- **When to use.** The landscape changes unpredictably; missing a shift is costly; you do not expect to "finish" — only to stop when the topic is no longer relevant. +- **Suggested observe sources.** Curated feeds (RSS, mailing lists), search queries, watch-listed sites or accounts, internal trend reports. +- **Suggested cadence.** `weekly` or slower; some goals run monthly with on-demand check-ins. +- **Suggested act-gate policy.** `always` or `never` (read-only). Act tends to be opt-in or human-only because the right response is rarely a single automatable step. +- **Worked goal statement.** `intent: "Keep me oriented on the competitive landscape in workflow tooling so I know when a meaningful shift happens."` + +## Pattern picker + +Use this table to choose a starting pattern. Re-pick if your goal evolves. + +| Pattern | Mode | Typical cadence | Act gate default | Choose when… | +|---|---|---|---|---| +| Issue resolution | one-shot | none | `always` | a specific, scoped problem must be resolved once. | +| Daily brief | recurring | daily | `always` | you want a scannable update at a fixed time. | +| Incident triage | recurring | continuous until close | `low-risk-auto` for runbook items | a live degradation must be restored fast. | +| Release readiness | one-shot | on demand | `always` | a checklist gates a named release event. | +| Continuous awareness | recurring | weekly+ | `never` / `always` | you must stay oriented on an external landscape over time. | +| Hybrid: discovery-by-loop | recurring | weekly | `always` | a topic is partly scoped and you want loops to refine it. | +| Hybrid: release watch | recurring | weekly | `always` | many releases ship and you want to stay aware of risk to each. | + +For more on goal shape, see [`goal-orientation.md`](goal-orientation.md). For how the loop runs under each pattern, see [`method.md`](method.md). diff --git a/plugin-v2/examples/README.md b/plugin-v2/examples/README.md new file mode 100644 index 000000000..110e26280 --- /dev/null +++ b/plugin-v2/examples/README.md @@ -0,0 +1,33 @@ +--- +title: Goal Loop — Examples +description: Worked artifact sets demonstrating the Goal Loop in two canonical patterns. +--- + +# Goal Loop — Examples + +> Two worked artifact sets, one per common pattern. Each is a snapshot of what `goals//` looks like after a real run. The artifacts are illustrative — copy the shape, not the data. + +## Examples + +| Example | Pattern | Narrative | +|---|---|---| +| [`issue-resolution/`](issue-resolution/) | One-shot, bounded | [`../docs/examples/issue-resolution.md`](../docs/examples/issue-resolution.md) | +| [`daily-brief/`](daily-brief/) | Recurring, awareness | [`../docs/examples/daily-brief.md`](../docs/examples/daily-brief.md) | + +Each example folder marks itself with an `EXAMPLE — do not consume` notice. Do not point a live orchestrator at these directories — they are reference shapes, not active goals. + +## What to copy + +Use these examples when: + +- Starting a new goal of the same pattern — copy `goal-state.md` and edit intent, constraints, acceptance criteria, sources to match. +- Reviewing whether your own artifacts hit the contract — compare against the example's frontmatter, evidence trail, and gate handling. +- Onboarding a colleague to the plugin — walk them through a complete iteration without running one. + +What not to copy: + +- The data. The redirect counts, error rates, and follow-up issues are fictional. +- The decision math. Real impact / confidence / cost ratings are domain-specific. +- The act-gate policy values. They are example shapes; your goal's policy is yours. + +For the method itself, see [`../docs/method.md`](../docs/method.md). For pattern selection, see [`../docs/usage-patterns.md`](../docs/usage-patterns.md). diff --git a/plugin-v2/examples/daily-brief/brief.md b/plugin-v2/examples/daily-brief/brief.md new file mode 100644 index 000000000..8ce586dbc --- /dev/null +++ b/plugin-v2/examples/daily-brief/brief.md @@ -0,0 +1,50 @@ +--- +title: "EXAMPLE — Brief — atlas-daily-brief / 2026-01-15" +description: "EXAMPLE — do not consume. Worked brief.md output for the daily-brief narrative." +example: true +goal_slug: atlas-daily-brief +brief_date: 2026-01-15 +iteration: 1 +--- + +# Brief — atlas-daily-brief / 2026-01-15 + +> **EXAMPLE — do not consume.** Worked example referenced from [`../../docs/examples/daily-brief.md`](../../docs/examples/daily-brief.md). The current `brief.md` is overwritten each morning; archived dated copies preserve history. + +## TL;DR + +- Critical bug filed overnight: `#1241`. Triage first. +- Data-export PR has unresolved review comments; release is Friday. +- Three in-review issues need reviewers; assign before the day fills up. + +## What's New + +Material changes since the last brief, with source refs. + +- 14 new commits on `develop` — see `observations/2026-01-15T07-30-00--repo.md` signals 1–14 +- 2 new bugs filed overnight (1 critical, 1 normal) — see `observations/2026-01-15T07-30-00--tracker.md` signals 1–2 +- Data-export PR received 4 review comments since yesterday — see `observations/2026-01-15T07-30-00--repo.md` signals 8–11 +- Changelog gained one new entry under "unreleased" — see `observations/2026-01-15T07-30-00--changelog.md` signal 1 + +## Recommended Today + +| id | action | gate | status | +|---|---|---|---| +| a-1 | Triage critical bug `#1241` (overnight filing, no owner yet) | human | approved | +| a-2 | Resolve the four open review comments on the data-export PR | human | approved | +| a-3 | Assign reviewers to the three issues moved to "in review" yesterday | human | approved | + +## Watching + +Open risks, partials, and unresolved items to revisit next iteration. + +- Data-export release scheduled for Friday — risk: review comments unresolved (see `orientation §What's-at-risk`) +- Three "in review" issues without assigned reviewer; older than 24h +- Normal-severity bug `#1240` filed overnight; lower priority than `#1241` but should be triaged this week + +## Optional Actions + +Items proposed and skipped this round. Surfaced so the human can pull them in if priorities shift. + +- Skim the 14 new `develop` commits for anything unexpected — skipped because nothing in them flagged as risky to orientation; rerun observe if a regression surfaces. +- Update the project's external status note — skipped because nothing externally visible changed. diff --git a/plugin-v2/examples/daily-brief/goal-state.md b/plugin-v2/examples/daily-brief/goal-state.md new file mode 100644 index 000000000..3d05baeb7 --- /dev/null +++ b/plugin-v2/examples/daily-brief/goal-state.md @@ -0,0 +1,68 @@ +--- +title: "EXAMPLE — Goal State — atlas-daily-brief" +description: "EXAMPLE — do not consume. Worked goal-state.md for the daily-brief narrative in docs/examples/daily-brief.md." +example: true +slug: atlas-daily-brief +intent: "Keep me oriented across project Atlas every morning so I know the day's top three actions." +mode: recurring +cadence: daily +status: active +current_phase: review +iteration: 1 +act_gate: always +created_at: 2026-01-14T16-00-00Z +updated_at: 2026-01-15T08-00-00Z +--- + +# Goal — atlas-daily-brief + +> **EXAMPLE — do not consume.** This file is a worked example referenced from [`../../docs/examples/daily-brief.md`](../../docs/examples/daily-brief.md). + +Canonical state for this goal. Owned by `goal-orchestrator`. Other agents read; only the orchestrator writes here. + +## Intent + +Produce a scannable daily brief for project Atlas. Each working morning, summarise what changed since yesterday, surface the most important risks and openings, and recommend at most three actions for the day. The brief is advisory — the human acts. The goal closes only when the human pauses or cancels it, or when project Atlas itself closes. + +## Constraints + +- No actions taken without the human approving each one. +- Brief must be readable in under 60 seconds — bias to brevity over completeness. +- No surveillance of private messages or 1:1 channels; project-public surfaces only. +- Each "recommended today" item must trace to an observed change. + +## Acceptance Criteria + +Each item must be falsifiable — an outside observer can verify met or unmet. + +1. Each working morning, `brief.md` is fresh (timestamp within the last 24 hours). +2. The brief lists at most three "recommended today" items, each tied to an observed change. +3. Items not yet acted on roll forward in a "watching" section so they are not silently dropped. + +## Mode & Cadence + +- **Mode:** recurring +- **Cadence:** daily at 07:30 local; on-demand re-run allowed +- **Stop condition:** human pauses the goal (`status: paused`) or cancels it (`status: cancelled`), or project Atlas itself wraps up. + +## Observe Sources + +| id | type | target | +|---|---|---| +| src-repo | repo | the Atlas repository — recent commits, PR list, open issues | +| src-tracker | api | the issue tracker filtered to project Atlas | +| src-changelog | document | `atlas/CHANGELOG.md` (unreleased section) | +| src-prior-brief | document | `goals/atlas-daily-brief/brief.md` from the prior run | + +## Act Gate Policy + +- **Default gate:** always +- **Reversible actions:** human-approve (the brief is advisory; auto-approval is rarely appropriate when the loop runs unattended). +- **Irreversible actions:** human-approve (non-negotiable). +- **Escalation contact:** human owner of project Atlas. + +## History + +| iteration | started_at | ended_at | outcome | +|---|---|---|---| +| 1 | 2026-01-15T07-30-00Z | 2026-01-15T07-55-00Z | continue | diff --git a/plugin-v2/examples/issue-resolution/decisions.md b/plugin-v2/examples/issue-resolution/decisions.md new file mode 100644 index 000000000..015495df9 --- /dev/null +++ b/plugin-v2/examples/issue-resolution/decisions.md @@ -0,0 +1,52 @@ +--- +title: "EXAMPLE — Decisions — wiki-redirect-fix" +description: "EXAMPLE — do not consume. Worked decision log for the issue-resolution narrative." +example: true +goal_slug: wiki-redirect-fix +--- + +# Decisions — wiki-redirect-fix + +> **EXAMPLE — do not consume.** Worked example referenced from [`../../docs/examples/issue-resolution.md`](../../docs/examples/issue-resolution.md). + +Appended log of decision sets. Each block represents one iteration's proposed actions. Never edit prior blocks; supersede with a new block and cross-reference. + +## Decision set — iter 1 — 2026-01-15T10-15-00Z + +- **id:** ds-iter1-2026-01-15T10-15-00 +- **iteration:** 1 +- **proposed_at:** 2026-01-15T10-15-00Z + +### Proposals + +| id | action | rationale | impact | confidence | cost | reversible | dependencies | gate | +|---|---|---|---|---|---|---|---|---| +| a-1 | Regenerate redirect targets for the 38 mapped-but-broken entries by running `tools/refresh-redirects` against `legacy-urls.txt` and writing the new targets into `redirects.yaml`. | because `orientation §Signal-Map #2` lists 38 stale targets and the refresh tool already exists; resolves the bulk of criterion #1 | H | H | L | Y | none | auto (local edit pre-push) | +| a-2 | Add the 3 unmapped legacy URLs to `redirects.yaml` with targets chosen from the inventory's annotation column. | because `orientation §Recommended-areas` flags 3 unmapped URLs and the inventory names canonical replacements | H | M | L | Y | none | auto (local edit pre-push) | +| a-3 | Open a PR titled `fix: refresh stale wiki redirects` containing the updated `redirects.yaml`, link to issue #1187, and request a maintainer review explicitly. | because criterion #3 requires merge through a reviewed PR; the maintainer is on rota and an explicit ask controls the merge window | H | H | L | Y (until merged) | a-1, a-2 | human | + +### Recommendation + +Approve a-1, a-2, and a-3 as a set. They are tightly coupled — a-3 carries a-1 and a-2 across the review boundary. Approving a subset would leave acceptance criterion #3 open with no path to closure. + +### Alternatives Considered + +- **Hand-edit each of the 38 entries.** Rejected — refresh tool exists, hand-edit is high-cost with no upside. +- **Skip criterion #3 by direct-merging.** Rejected — violates the goal's "all changes ship through a reviewed PR" constraint. +- **Defer the 3 unmapped URLs to a follow-up issue.** Rejected — acceptance criterion #1 covers every legacy URL, no exceptions. + +### Risks + +- The maintainer review may slip past the one-working-day window. Mitigation: escalation contact in the goal-state policy; surface as orientation risk if review does not start within 4 hours of PR open. +- `tools/refresh-redirects` may behave differently from its last run if `legacy-urls.txt` schema changed. Mitigation: a-1's actor runs `--dry-run` first and captures the diff before the real write. + +### Human Approval + +- [x] Approved as recommended +- [ ] Approved with exclusions: _(n/a)_ +- [ ] Approved with edits (note below) +- [ ] Rejected — rationale: _(n/a)_ +- [ ] Defer to next iteration + +Approver: reporter (issue #1187 author) +Approved at: 2026-01-15T10-20-00Z diff --git a/plugin-v2/examples/issue-resolution/goal-state.md b/plugin-v2/examples/issue-resolution/goal-state.md new file mode 100644 index 000000000..1999bc08f --- /dev/null +++ b/plugin-v2/examples/issue-resolution/goal-state.md @@ -0,0 +1,76 @@ +--- +title: "EXAMPLE — Goal State — wiki-redirect-fix" +description: "EXAMPLE — do not consume. Worked goal-state.md for the issue-resolution narrative in docs/examples/issue-resolution.md." +example: true +slug: wiki-redirect-fix +intent: "Resolve the wiki-redirect breakage so legacy URLs land on the new article slugs without 404s." +mode: one-shot +cadence: null +status: active +current_phase: review +iteration: 1 +act_gate: always +created_at: 2026-01-15T08-45-00Z +updated_at: 2026-01-15T11-30-00Z +--- + +# Goal — wiki-redirect-fix + +> **EXAMPLE — do not consume.** This file is a worked example referenced from [`../../docs/examples/issue-resolution.md`](../../docs/examples/issue-resolution.md). + +Canonical state for this goal. Owned by `goal-orchestrator`. Other agents read; only the orchestrator writes here. + +## Intent + +The wiki's legacy URLs (paths beginning `/old/`) are returning 404 instead of redirecting to the renamed article slugs. The reporter on the issue thread observed it across 41 distinct URLs over the past week. Goal is to restore correct redirect behaviour for every URL in the legacy inventory, ship the change through a reviewed PR, and confirm zero residual 404s on a fresh crawl. + +## Constraints + +- No changes to article content; redirect mapping only. +- Complete within one working day. +- All changes ship through a reviewed PR — direct merges to the redirect map are disallowed. +- Maintainer sign-off required before merge. + +## Acceptance Criteria + +Each item must be falsifiable — an outside observer can verify met or unmet. + +1. Every legacy URL listed in `legacy-urls.txt` returns a 301 to a working article slug. +2. No `/old/...` URL returns a 404 in a fresh crawl run on staging. +3. The redirect map change is reviewed and merged into the trunk branch. + +## Mode & Cadence + +- **Mode:** one-shot +- **Cadence:** null +- **Stop condition:** all three acceptance criteria met, or the goal is explicitly abandoned with rationale. + +## Observe Sources + +| id | type | target | +|---|---|---| +| src-redirects | repo | `wiki/redirects.yaml` | +| src-inventory | document | `wiki/legacy-urls.txt` | +| src-crawl-log | document | `ops/crawl-logs/last-week/` | +| src-issue | document | issue thread #1187 | +| src-pr | repo | the redirect-fix PR, once opened (added at iteration 2) | + +## Act Gate Policy + +- **Default gate:** always +- **Reversible actions:** auto-approve for purely local edits within the working tree before push; human-approve for pushes and PR mutations. +- **Irreversible actions:** human-approve (non-negotiable). +- **Escalation contact:** wiki maintainer on rota. + +## History + +| iteration | started_at | ended_at | outcome | +|---|---|---|---| +| 1 | 2026-01-15T09-00-00Z | 2026-01-15T11-30-00Z | continue | +| 2 | 2026-01-15T14-00-00Z | _(in progress — awaiting maintainer review)_ | _pending_ | + +## Act Approvals + +| decision-set id | approved-at | approver | approved-items | +|---|---|---|---| +| ds-iter1-2026-01-15T10-15-00 | 2026-01-15T10-20-00Z | reporter | a-1, a-2, a-3 | diff --git a/plugin-v2/examples/issue-resolution/orientation.md b/plugin-v2/examples/issue-resolution/orientation.md new file mode 100644 index 000000000..f0df72455 --- /dev/null +++ b/plugin-v2/examples/issue-resolution/orientation.md @@ -0,0 +1,50 @@ +--- +title: "EXAMPLE — Orientation — wiki-redirect-fix / iter 1" +description: "EXAMPLE — do not consume. Worked orientation.md for the issue-resolution narrative." +example: true +goal_slug: wiki-redirect-fix +iteration: 1 +synthesised_at: 2026-01-15T10-00-00Z +--- + +# Orientation — wiki-redirect-fix / iter 1 + +> **EXAMPLE — do not consume.** Worked example referenced from [`../../docs/examples/issue-resolution.md`](../../docs/examples/issue-resolution.md). + +Synthesis across all observations in this iteration. Every claim cites an observation; no speculation. + +## Summary + +Of the 312 legacy URLs catalogued in the inventory, 271 are correctly mapped in `redirects.yaml`, 38 are mapped to slugs that no longer exist (mapping rot from a prior slug rename), and 3 are unmapped entirely. The 41 distinct 404s observed in the past-week crawl all fall within the 38 + 3 set. The maintainer's hypothesis on the issue thread (`"we shipped the slug rename without regenerating the map"`) aligns with the evidence. + +See `observations/2026-01-15T09-00-00--legacy-urls.md` signals 1–4 for inventory counts; `observations/2026-01-15T09-00-00--redirects-yaml.md` signals 1–38 for the broken-target entries; `observations/2026-01-15T09-00-00--crawl-log.md` signals 1–41 for the 404 set. + +## What's New + +First iteration — full baseline. No prior orientation. + +## What's Blocked + +- Nothing structurally blocked. The refresh tool exists (`tools/refresh-redirects`) and the inventory file is complete. + +## What's At Risk + +- Criterion #3 (review + merge) requires a maintainer; if the on-rota maintainer is unavailable, merge slips beyond the one-working-day constraint. — source: `observations/2026-01-15T09-00-00--issue-thread.md` signal 4 (maintainer's hypothesis posted, but no commitment to review window). + +## Signal Map + +| # | Criterion | Status | Evidence | +|---|---|---|---| +| 1 | Every legacy URL → 301 to working slug | partial | 271 / 312 working; see redirects-yaml + legacy-urls observations | +| 2 | No `/old/...` 404 in fresh crawl | unmet | 41 distinct 404s in past-week crawl; see crawl-log signals 1–41 | +| 3 | Redirect map change reviewed and merged | unknown | no PR yet — issue-thread §signal 4 mentions intent but no PR | + +## Contradictions + +None. + +## Recommended Areas For Decision + +- Close the 38 broken-target mappings using `tools/refresh-redirects` against the inventory. +- Choose targets for the 3 unmapped URLs from the inventory's annotation column. +- Open a PR with the updated `redirects.yaml` and request a maintainer review explicitly to control the merge window. diff --git a/plugin-v2/examples/issue-resolution/reviews/2026-01-15T11-30-00.md b/plugin-v2/examples/issue-resolution/reviews/2026-01-15T11-30-00.md new file mode 100644 index 000000000..6f247bfb1 --- /dev/null +++ b/plugin-v2/examples/issue-resolution/reviews/2026-01-15T11-30-00.md @@ -0,0 +1,44 @@ +--- +title: "EXAMPLE — Review — wiki-redirect-fix / iter 1" +description: "EXAMPLE — do not consume. Worked review for the issue-resolution narrative — close-met variant shown for illustration." +example: true +goal_slug: wiki-redirect-fix +iteration: 1 +reviewed_at: 2026-01-15T11-30-00Z +outcome: continue +--- + +# Review — wiki-redirect-fix / iter 1 + +> **EXAMPLE — do not consume.** Worked example referenced from [`../../docs/examples/issue-resolution.md`](../../docs/examples/issue-resolution.md). The narrative shows iteration 1 closing with `continue` (PR open, awaiting maintainer review) and a follow-up iteration 2 ending in `close-met` once the PR merges. This file is the iteration 1 review. + +Closes one iteration. Written by `loop-reviewer`. The orchestrator reads `outcome` to choose the next move. + +## Acceptance Check + +| # | Criterion | Evidence | Verdict | +|---|---|---|---| +| 1 | Every legacy URL listed in `legacy-urls.txt` returns a 301 to a working article slug. | `actions/a-1.md` (38 updates) + `actions/a-2.md` (3 new mappings) — diff totals 41 entries covering the exact set flagged in orientation | met | +| 2 | No `/old/...` URL returns a 404 in a fresh staging crawl. | `actions/a-1.md` post-step staging crawl reports 0 of the 41 prior 404 URLs still failing | met | +| 3 | The redirect map change is reviewed and merged into the trunk branch. | `actions/a-3.md` records PR URL and "awaiting maintainer review" state; no merge yet | partial | + +## Outcome + +**continue** + +## Rationale + +Criteria #1 and #2 are met; the data-driven evidence is in the action logs and the staging crawl. Criterion #3 is partial — the PR exists and is correctly scoped, but the maintainer has not yet reviewed and merged. One short follow-up iteration is required to confirm merge and close. The next iteration's only observe source need be the PR itself; sources `src-redirects`, `src-inventory`, and `src-crawl-log` do not need re-scanning. + +## Next Steps + +- Re-enter Observe with a single source: `src-pr` (the open PR's review and merge state). Skip the others — orientation already covers them and they will not change. +- Watch for the slip risk identified in iter 1's orientation: if the maintainer review has not started within 4 hours of PR open, surface to the escalation contact named in `goal-state.md`. +- Expect iter 2 to propose either "no action — keep waiting" (if review is in progress) or "follow up with maintainer" (if review has not started). Either is acceptable. + +## Loop Hygiene + +- **Observe coverage:** all four declared sources scanned; no gaps recorded. +- **Orient quality:** synthesis cited 41 + 38 + 3 signals by file and index; no unsourced claims; contradictions section empty (correctly). +- **Decide soundness:** three proposals, each tied to a signal; alternatives weighed; gates assigned correctly; the human approved as recommended. +- **Act fidelity:** all three actions executed verbatim against the approved spec; no scope creep; one action (a-1) used `--dry-run` first as the decision risk note required. diff --git a/plugin-v2/memory/constitution.md b/plugin-v2/memory/constitution.md new file mode 100644 index 000000000..27cc6f22c --- /dev/null +++ b/plugin-v2/memory/constitution.md @@ -0,0 +1,99 @@ +--- +title: Goal Loop Constitution +description: Governing principles for the goal-loop plugin. Loaded ahead of every loop iteration and every authored artifact. +version: 0.1 +--- + +# Constitution — Goal Loop + +Governing principles for the `goal-loop` plugin. Loaded ahead of every command, agent dispatch, and authored artifact. **Override only with explicit human approval and a recorded amendment.** + +> **Version:** 0.1 — Foundation. Refine as the method matures; constitution changes themselves must be amendment-tracked. + +## Article I — Goal Primacy + +1. Every loop runs against an explicit goal recorded in `goal-state.md`. +2. The goal declares intent, constraints, and acceptance criteria that are **falsifiable** — an outside observer can verify met or unmet. +3. No phase agent runs until the goal gate is human-signed. +4. Ad-hoc redefinition of the goal mid-iteration is forbidden. Goals change through structured amendment only. + +## Article II — Phase Isolation + +Each phase has one purpose and one writer. Cross-phase shortcuts are forbidden. + +``` +Observe ≠ Orient ≠ Decide ≠ Act ≠ Review +``` + +1. The `observer` writes only observations. The `orienter` writes only `orientation.md`. The `decider` writes only decisions and action specs. The `actor` writes only action logs. The `loop-reviewer` writes only reviews. +2. Only the `goal-orchestrator` writes `goal-state.md`. +3. No agent may edit another agent's artifacts. Disagreements are surfaced through the next phase, not by rewriting upstream output. + +## Article III — Human Gates + +Two gates are non-negotiable; others are configurable per goal. + +1. **Goal gate** — the human signs off on the goal definition before iteration 1 begins. +2. **Act gate** — the human approves the decision set before any irreversible action executes. Reversible, low-risk actions may be auto-approved only when the goal explicitly declares `act_gate: low-risk-auto`. +3. Gate bypass requires an amendment to the goal's act-gate policy, not an ad-hoc waiver. + +## Article IV — Evidence-Based Orientation + +1. Every claim in `orientation.md` cites an observation by file and signal index. +2. Speculation, intuition, and unsourced inference do not belong in orientation. They belong in `## Open Questions` or `## Contradictions`. +3. When signals disagree, the orienter flags the contradiction and hands resolution to the decider. The orienter does not pick a winner. +4. If no observation supports a claim, the claim is removed or downgraded to an open question. + +## Article V — Reversibility Bias + +1. Prefer reversible actions. The decider ranks reversible options above irreversible ones at equal impact and confidence. +2. Every irreversible action carries a **rollback plan** in its action spec. No rollback plan, no execution. +3. Reversibility is judged against the world the action touches, not the convenience of the actor. +4. When unsure whether an action is reversible, treat it as irreversible. + +## Article VI — Loop Discipline + +1. One iteration at a time. The next iteration begins only after the current `review.md` records `outcome: continue | amend`. +2. Phases run in order: Observe → Orient → Decide → Act → Review. Skipping a phase requires explicit authorisation in the goal's policy. +3. A phase is not "done" until its artifact is written, its frontmatter is complete, and its quality gate is green. +4. The orchestrator owns sequencing; phase agents do not self-dispatch the next phase. + +## Article VII — Domain Neutrality + +1. The Goal Loop serves any domain — code, content, research, operations, strategy, governance. +2. Authored artifacts use plain language and avoid domain-locked vocabulary unless the goal itself is domain-specific. +3. Examples in templates and skills are illustrative, not prescriptive. A goal about regulatory monitoring is as valid as a goal about release readiness. +4. Resist software-only metaphors (commits, branches, tests) in core artifacts. Acceptance criteria describe outcomes, not implementations. + +## Article VIII — Transparency + +1. Every decision and every action is logged. The trail must reconstruct the reasoning end-to-end: observation → orientation → decision → approval → execution → verification. +2. Skipped, deferred, and rejected items are recorded with rationale, not silently dropped. +3. Human approvals are timestamped and attributed. +4. Evidence — diffs, hashes, screenshots, quoted output — is linked from the action log. "Done" without evidence is incomplete. + +## Article IX — Escalate, Don't Invent + +1. Ambiguity is surfaced to the human, never silently resolved. +2. When inputs are missing, contradictory, or outside the agent's scope, the agent opens an open question or contradiction entry and stops. +3. Agents may **escalate** but may not **invent** facts, constraints, sources, or approvals. +4. The cost of asking is small; the cost of fabricated state is large. + +## Article X — Closure Honesty + +1. A goal closes only when one of the following is true: + - All acceptance criteria are met and the review records `outcome: close-met`. + - The goal is explicitly abandoned and the review records `outcome: close-abandon` with rationale. +2. "Close — met" requires evidence against each criterion. Partial or unknown verdicts block closure. +3. Closing a goal because the loop feels long, the tempo feels slow, or the human is tired is not closure. It is abandonment, and must be recorded as such. +4. Closure updates `goal-state.md` (`status: done | cancelled`) and archives the working files. No silent shutdowns. + +--- + +## Amendment process + +1. Open an amendment proposal alongside the plugin's amendment log (or, when integrated into a host repo, an ADR). State the article touched, the change, and the rationale. +2. Tag affected templates, agents, and skills so downstream artifacts can be checked for drift. +3. On acceptance, update this file and bump its version. Do not edit silently. + +Amendments to Articles I–III (Goal Primacy, Phase Isolation, Human Gates) are load-bearing for the method's integrity and warrant the highest scrutiny. Amendments to wording, examples, or non-normative guidance may be lighter-weight but still flow through this process. diff --git a/plugin-v2/skills/_shared/goal-state.md b/plugin-v2/skills/_shared/goal-state.md new file mode 100644 index 000000000..4eafd0634 --- /dev/null +++ b/plugin-v2/skills/_shared/goal-state.md @@ -0,0 +1,150 @@ +# `goal-state.md` schema and contract (shared) + +> Schema and ownership contract for `goals//goal-state.md`. Linked from every Goal Loop skill (`goal-loop`, `set-goal`, `observe`, `orient`, `decide`, `act`, `review-loop`) and every phase agent (`goal-orchestrator`, `observer`, `orienter`, `decider`, `actor`, `loop-reviewer`). The canonical template lives at `../../templates/goal-state-template.md`; this file is the explanatory contract. + +`goal-state.md` is the single source of truth for one goal. It is read by every Goal Loop participant and written by exactly one actor at any time: the **`goal-orchestrator`** for phase transitions and history, and **`set-goal`** for initial creation and amendments. Phase agents read it; they do not write it. + +If you find yourself drafting state changes elsewhere — stop, and dispatch the right writer. + +## Where it lives + +``` +goals//goal-state.md +``` + +The `` is kebab-case, derived during `set-goal`. Use the same slug across every artifact in the same goal — observations, orientation, decisions, actions, reviews, and history. + +## YAML frontmatter + +Every `goal-state.md` opens with a YAML frontmatter block. Field order is not significant; presence is. + +| Field | Type | Required | Allowed values / shape | Owner | +|---|---|---|---|---| +| `slug` | string | yes | kebab-case, matches the parent folder name | `set-goal` (immutable after creation) | +| `intent` | string | yes | one-line plain-language outcome statement | `set-goal` (changes only via amend) | +| `constraints` | list of strings | yes | hard limits (time, budget, scope, policy, blackouts) — at least one required | `set-goal` (changes only via amend) | +| `acceptance_criteria` | list of strings | yes | each item must be falsifiable — an outside observer can verify met / unmet; at least one required | `set-goal` (changes only via amend) | +| `mode` | enum | yes | `one-shot` \| `recurring` | `set-goal` | +| `cadence` | string \| null | required when `mode: recurring`, else `null` | e.g., `daily 09:00 local`, `weekly Monday`, `ad-hoc`, `event-driven`, or `null` | `set-goal` | +| `observe_sources` | list of objects | yes | each item has `id` (slug), `type` (`feed` \| `repo` \| `inbox` \| `api` \| `document` \| `sensor` \| `person` \| `command`), `target` (URL, path, channel, query, contact); at least one required | `set-goal` (changes only via amend) | +| `act_gate` | enum | yes | `always` (every action gated) \| `low-risk-auto` (reversible auto, irreversible gated) \| `never` (decisions surfaced but not executed) | `set-goal` | +| `status` | enum | yes | `draft` \| `active` \| `paused` \| `blocked` \| `done` \| `cancelled` | `goal-orchestrator` (and `set-goal` at creation, which writes `draft`) | +| `current_phase` | enum | yes | `scope` \| `observe` \| `orient` \| `decide` \| `act` \| `review` \| `closed` | `goal-orchestrator` | +| `iteration` | integer | yes | starts at `0` (set during `set-goal`), incremented by `goal-orchestrator` at each new Observe | `goal-orchestrator` | +| `created_at` | ISO-8601 timestamp | yes | UTC, set once at creation | `set-goal` | +| `updated_at` | ISO-8601 timestamp | yes | UTC, refreshed on every state change | `goal-orchestrator` (and `set-goal` on amend) | + +### Optional frontmatter + +These keys may be present and are owned by `goal-orchestrator` unless noted. + +- `goal_signed_off` (boolean) — `true` once the human has cleared the goal gate. Defaults to `false`. Required `true` before Observe runs for the first time. +- `last_review` (string) — relative path to the latest `reviews/*.md`. Appended after Review. +- `escalation_contact` (string) — name or role to escalate to on block. Set during `set-goal`. +- `parallel_observe` (boolean) — whether Observe may fan out (defaults to `true` if more than one observe source is declared). +- `parallel_act` (boolean) — whether Act may fan out across independent approved actions (defaults to `false`; opt in during `set-goal` or via amend). + +Do not add fields outside this schema without revising this file first. Stage agents read into a known shape; new keys silently break readers. + +## Body sections + +The body of `goal-state.md` is plain Markdown, in this order. Section names are the canonical contract. + +### `## Intent` + +Plain-language statement of the outcome wanted and why. Two or three sentences max. Owned by `set-goal`. Phase agents quote from it when explaining their work; they never edit it. + +### `## Constraints` + +Bulleted list of hard limits — what must not change, what limits apply (time, budget, scope, policy, tempo, escalation rule, blackout windows). Must mirror the `constraints` frontmatter array. Owned by `set-goal`. + +### `## Acceptance Criteria` + +Numbered list. Each criterion must be falsifiable: an outside observer can verify met / unmet without consulting the author. Must mirror the `acceptance_criteria` frontmatter array. `loop-reviewer` references each criterion by number when writing a review. Owned by `set-goal`. + +`set-goal` enforces a **clarity gate**: if any criterion is not falsifiable, it loops on that criterion until it is. "Make it better" is not falsifiable; "engagement on landing page > 8% by end of month, measured by event X in tool Y" is. + +### `## Mode & Cadence` + +Three lines: + +- `Mode:` matches `mode` frontmatter. +- `Cadence:` matches `cadence` frontmatter (or `null` for one-shot). +- `Stop condition:` how the loop ends. Required for recurring goals; the answer to "when do we stop running this?". Owned by `set-goal`. + +### `## Observe Sources` + +Table mirroring `observe_sources` frontmatter: + +``` +| id | type | target | notes | +|---|---|---|---| +``` + +Each row is one declared source. The `observe` skill dispatches one `observer` per row when fan-out is allowed. Owned by `set-goal`. + +### `## Act Gate Policy` + +Four lines: + +- `Default gate:` matches `act_gate` frontmatter. +- `Reversible actions:` `auto-approve` \| `human-approve`. +- `Irreversible actions:` `human-approve` (non-negotiable — the policy may not weaken this). +- `Escalation contact:` matches `escalation_contact` frontmatter if present. + +Owned by `set-goal`. The act gate is one of two non-negotiable human gates in the method (the other being the goal gate). + +### `## History` + +Append-only table. One row per phase transition or loop-closure outcome. Owned by `goal-orchestrator` exclusively. + +``` +| iteration | phase | started_at | ended_at | outcome | artifact | +|---|---|---|---|---|---| +``` + +The `outcome` column is free text for in-iteration phases (e.g., `observations captured`, `orientation refreshed`) and a fixed enum at loop closure: `continue` \| `close-met` \| `close-abandon` \| `amend`. The `artifact` column points at the artifact produced by that phase (relative path within `goals//`). + +Never rewrite a History row. Append-only is the contract — auditability depends on it. + +## Ownership matrix + +| Writer | Frontmatter fields it may set | Body sections it owns | +|---|---|---| +| `set-goal` | `slug`, `intent`, `constraints`, `acceptance_criteria`, `mode`, `cadence`, `observe_sources`, `act_gate`, `created_at`, `updated_at` (on amend), `status: draft` at creation, optional `escalation_contact`, `parallel_observe`, `parallel_act` | `Intent`, `Constraints`, `Acceptance Criteria`, `Mode & Cadence`, `Observe Sources`, `Act Gate Policy` | +| `goal-orchestrator` | `status` (post-creation), `current_phase`, `iteration`, `updated_at`, `goal_signed_off`, `last_review` | `History` only | +| All phase agents (`observer`, `orienter`, `decider`, `actor`, `loop-reviewer`) | none | none — read-only | +| Phase skills (`observe`, `orient`, `decide`, `act`, `review-loop`) | none — they dispatch `goal-orchestrator` for state updates | none | + +A phase agent that needs to update `goal-state.md` is drifting — surface the need; do not write. + +## Status state machine + +``` +draft → active → (paused | blocked | active) → (done | cancelled) +``` + +- `draft` — created by `set-goal`, before the goal gate is cleared. +- `active` — goal gate cleared (`goal_signed_off: true`); loop iterates. +- `paused` — user-initiated halt via a Pause gate. Resumes back to `active` at the same `current_phase`. +- `blocked` — escalation triggered (subagent crash retried, contradictory state, missing input). Resumes when blocker is cleared by the user. +- `done` — `loop-reviewer` returned `close-met`. Terminal. +- `cancelled` — `loop-reviewer` returned `close-abandon` (or the user abandoned via the goal gate). Terminal. + +Transitions are recorded in `## History`. + +## What never goes in `goal-state.md` + +- Observation signals, orientations, decision sets, action logs, or review verdicts — those live under their own folders (`observations/`, `orientation.md`, `decisions.md`, `actions/`, `reviews/`). +- Free-form conversation logs. The conductor surfaces clarifications to the user via `AskUserQuestion` and records the answer either in `goal-state.md` (if it amends a body section) or in the relevant phase artifact (if it is iteration-local). +- Domain-specific schemas (no `requirements`, `tests`, `tasks`, code paths, language- or framework-specific fields). The Goal Loop is domain-agnostic; `goal-state.md` is too. + +## Reading order for any participant + +1. Read the **frontmatter** first to determine `status`, `current_phase`, and `iteration`. This is the cheapest signal of where the loop is. +2. Read **`## Acceptance Criteria`** and **`## Constraints`** to anchor the work. +3. Read **`## Observe Sources`** if you are an observer, the `observe` skill, or the orchestrator deciding parallelism. +4. Read **`## Act Gate Policy`** if you are about to dispatch Act. +5. Read **`## History`** to understand what has already happened in earlier iterations. + +Phase agents must cite `goal-state.md` (e.g., `goal-state.md acceptance criterion #2`) when their artifacts reference goal-level claims. diff --git a/plugin-v2/skills/_shared/loop-pattern.md b/plugin-v2/skills/_shared/loop-pattern.md new file mode 100644 index 000000000..613d32285 --- /dev/null +++ b/plugin-v2/skills/_shared/loop-pattern.md @@ -0,0 +1,121 @@ +# Goal Loop pattern (shared) + +> Shared scaffolding for every Goal Loop conductor skill. Linked from `goal-loop`, `set-goal`, `observe`, `orient`, `decide`, `act`, `review-loop`. Not auto-loaded — each linking skill keeps its trigger logic and phase-specific dispatch inline; this file owns the gating, state-update, escalation, and re-entry rules common to all of them. + +This file is the Goal Loop analogue of `conductor-pattern.md`. If you are authoring a new Goal Loop skill, read this first and only deviate when the per-skill contract calls it out. + +## What a Goal Loop conductor skill is + +A Goal Loop conductor is a thin skill that: + +1. Detects whether to **resume** an existing goal or start a new one. +2. **Gates** with the user via `AskUserQuestion`. +3. **Dispatches** the right specialist subagent for the phase. +4. **Persists** state by updating `goal-state.md` (or asking the subagent to). +5. **Hands control back** to the user — never does phase work itself. + +The conductor never drafts an observation, never synthesises an orientation, never decides, never executes, never reviews. Drafting an artifact from the conductor's turn = drifted; stop and dispatch the right phase agent. + +Canonical method definition: [`../../docs/method.md`](../../docs/method.md). Locked vocabulary is in §"Naming reference". + +## AskUserQuestion is main-thread only + +`AskUserQuestion` works only in the main thread. Subagents cannot ask the user anything. Every gate happens in the conductor's turn — before, between, or after a phase — never inside a dispatched specialist. + +Batch options into a single `AskUserQuestion` per gate. Never chain two question calls back-to-back when one multi-option call would do. + +## State lives in `goals//goal-state.md` + +Every Goal Loop conductor reads and updates `goals//goal-state.md`. Schema and section contract: [`./goal-state.md`](./goal-state.md). + +Ownership rules: + +- **`goal-orchestrator`** owns frontmatter (`status`, `current_phase`, `iteration`, `updated_at`) and the body `## History` section. The top-level `goal-loop` skill dispatches it for any cross-phase state transition. +- **`set-goal`** owns the initial creation of the file plus all body sections except `## History`. +- **Phase skills** (`observe`, `orient`, `decide`, `act`, `review-loop`) do not edit `goal-state.md` directly. They dispatch their phase agent, which writes the phase artifact under `goals//`; the conductor then asks `goal-orchestrator` to record the transition. + +If a conductor finds itself wanting to edit `goal-state.md` directly during phase execution, it has drifted. Dispatch `goal-orchestrator` instead. + +## Detect resume vs. fresh start + +Every conductor that can be entered standalone runs the same detection step at the top: + +1. List `goals/` non-recursively. +2. For each `goals//goal-state.md` whose `status` is `active`, `paused`, or `blocked`, read `slug | status | current_phase | iteration | updated_at`. +3. Recommended-first by `updated_at`, present them in a single `AskUserQuestion`: + - Resume listed goal (one option per goal, status shown). + - Start a new goal. + - (`goal-loop` only) Run a single phase against an existing goal. +4. If no resumable goals exist, skip the menu and proceed. + +`status: done` or `status: cancelled` goals are not auto-listed. If the user names one, ask whether to amend (and revive) or just inspect. + +## The four loop outcomes + +After Review (`review-loop`), `loop-reviewer` reports one of four outcomes. Every conductor that can land on Review must handle all four: + +| Outcome | Meaning | What the conductor does | +|---|---|---| +| **continue** | Acceptance criteria not yet met; the loop should iterate. | Dispatch `goal-orchestrator` to bump `iteration`, set `current_phase: observe`, append a `## History` entry, then either dispatch the next iteration (if cadence is "immediate") or pause for cadence (if recurring on a schedule). | +| **close-met** | Acceptance criteria are satisfied. | Dispatch `goal-orchestrator` to set `status: done`, leave `current_phase` as `review`, append a closing `## History` entry. Report the closing summary to the user. | +| **close-abandon** | Goal no longer worth pursuing. | Dispatch `goal-orchestrator` to set `status: cancelled`, append a `## History` entry that captures the abandonment rationale verbatim from the review. Report the closure to the user. | +| **amend** | Goal definition needs revision before the loop can continue. | Gate with the user via `AskUserQuestion` to confirm the proposed amendment. On confirmation, dispatch `set-goal` in amend mode against the same slug; it updates the relevant body sections and `goal-orchestrator` appends a `## History` entry recording the amendment. Then offer to resume from Observe. | + +The conductor never invents a fifth outcome. If `loop-reviewer` returns something ambiguous, escalate to the user as a clarification rather than guessing. + +## Per-phase loop (used by `goal-loop`) + +For each phase in iteration order (Observe → Orient → Decide → Act → Review): + +1. **Pre-flight** — read `goal-state.md`, confirm the iteration is in the right phase (`current_phase` matches what you are about to dispatch). If it does not, surface the mismatch via `AskUserQuestion`: "State says we're at but you asked for — resume / re-run / abort?" Never silently overwrite phase state. +2. **Dispatch** the phase skill or slash command. Hand off fully — do not duplicate the specialist's work in your own turn. +3. **Wait** for the dispatch to finish and the phase artifact to exist on disk. +4. **Update state** — dispatch `goal-orchestrator` to advance `current_phase`, bump `updated_at`, and append a one-line `## History` entry citing the artifact path. +5. **Gate with user** via a single `AskUserQuestion`: + - `Continue to ` (Recommended) — only offered if the goal's gate policy for this transition is `auto` or the user has not opted into a manual gate here. + - `Pause here` — dispatch `goal-orchestrator` to set `status: paused`, exit. Resume by re-invoking `goal-loop`. + - `Re-run with feedback` — pass the free-text "Other" answer as additional context to the phase skill on re-dispatch. + - **Act gate (mandatory before Act):** never auto-skip. Present the decision set from `decisions.md` and offer `Approve all / Approve subset / Reject all / Edit`. Even when the goal's `act_gate` policy is `auto`, irreversible actions still require explicit confirmation. + +Optional gates between Orient↔Decide and Decide↔Act (for reversible actions) are opt-in per goal via the `act_gate` policy and any per-transition flags in `goal-state.md`. + +## Scope discipline — never invent inputs + +The Goal Loop method assumes its inputs are declared up front in `goal-state.md`. Conductors must not: + +- Invent acceptance criteria, observe sources, or constraints not present in `goal-state.md`. If the user asks for behaviour that requires new criteria or sources, dispatch `set-goal` in amend mode first. +- Substitute their own judgement for `loop-reviewer`'s verdict. The reviewer's outcome is the contract. +- Auto-extract archives or external bundles to seed sources. If a declared observe source is an archive, ask before extracting. +- Continue past a failed phase agent silently. If `observer`, `orienter`, `decider`, `actor`, or `loop-reviewer` returns "blocked — needs human input", surface that question to the user via `AskUserQuestion` and re-dispatch with the answer as additional context. Do not answer on the user's behalf. + +If the user redefines the goal mid-loop conversationally ("actually, I also want X"), do **not** edit `goal-state.md` silently. Tell them the amendment path: re-run `set-goal` in amend mode, or finish the current iteration and amend at Review. + +## Error escalation + +Failures fall into three categories. Handle each explicitly. + +- **Subagent error** (the phase agent crashed, timed out, or returned a malformed artifact). Re-dispatch once with the failure context as additional input. If it fails again, dispatch `goal-orchestrator` to set `status: blocked` with the error message in the latest `## History` entry, then surface the failure to the user and ask for direction. +- **Per-action failure during Act** (one of M parallel actors fails while siblings succeed). Do not block siblings. Record the failure inside the per-action artifact (`actions/.md`) and surface the failure summary to the user at the Review gate. The `loop-reviewer` will decide whether the failure blocks acceptance. +- **State drift** (state-file claims one phase, on-disk artifacts disagree, or the iteration counter is out of sync). Stop. Show the user the discrepancy in a single message and ask whether to trust the state-file, trust the artifacts, or pause for manual fix. Never auto-reconcile. + +## Re-entry / resume rules + +Re-entry is the default mode — most goal loops are iterated, paused, and resumed many times. The rules: + +1. **Idempotent detection.** Listing `goals/` and reading `goal-state.md` is always safe and never modifies state. Conductors may run the detection step on every entry. +2. **Resume from `current_phase`.** When the user picks "Resume" for a goal, dispatch the phase skill that matches `current_phase`. Do not jump ahead. +3. **Paused goals.** A goal with `status: paused` resumes by flipping back to `status: active` and continuing from `current_phase`. `goal-orchestrator` performs the flip; the conductor does not edit the file directly. +4. **Blocked goals.** A goal with `status: blocked` requires the blocker to be acknowledged before resuming. Show the blocker (from the latest `## History` entry) to the user and ask whether the blocker is resolved before dispatching the next phase. +5. **Amend mid-resume.** If the user wants to amend the goal before continuing, route through `set-goal` in amend mode rather than editing `goal-state.md` ad-hoc. +6. **Recurring goals.** When the cadence is a wall-clock interval (e.g., daily brief), resume detection still applies — but the conductor should treat a long gap since `updated_at` as "this is the next scheduled iteration" rather than "pick up where you left off mid-phase". + +## Constraints common to all Goal Loop conductors + +- Never do phase-specialist work in the conductor's turn. +- Never call `AskUserQuestion` from inside a subagent prompt — it fails silently. +- Never edit `goal-state.md` directly during phase execution. Dispatch `goal-orchestrator`. +- Never invent acceptance criteria, observe sources, or constraints. Route through `set-goal`. +- Always update `goal-state.md` between phases (via `goal-orchestrator`). +- Always use the same `` across every artifact in one goal. +- Always preserve declared `act_gate` policy — irreversible actions never auto-approve, regardless of policy. +- One concern per loop iteration. If the user's request spans multiple goals, ask whether to split before continuing. diff --git a/plugin-v2/skills/act/SKILL.md b/plugin-v2/skills/act/SKILL.md new file mode 100644 index 000000000..554597d29 --- /dev/null +++ b/plugin-v2/skills/act/SKILL.md @@ -0,0 +1,146 @@ +--- +name: act +description: Run the Act phase of a Goal Loop iteration. Dispatches one actor subagent per approved action — in parallel when actions are independent — handles fan-out and fan-in, and reports per-action outcomes without letting one failure block siblings. Refuses to run without a cleared act gate. Use when the user wants to execute approved actions, run the act phase after Decide, or mentions "/goal:act", "run act phase", "execute approved actions", "act phase", "perform the action set". +argument-hint: [goal-slug] +--- + +# Act + +Conductor for the **Act** phase of the Goal Loop. Job: read the approved decision set from `decisions.md`, dispatch one `actor` subagent ([`../../agents/actor.md`](../../agents/actor.md)) per approved action (in parallel when the goal allows and actions are independent), wait for each to write its action log, and hand off to Review. **Refuses to run without a cleared act gate** — that is Decide's responsibility, and this skill verifies it. + +Per-action failure isolation: when M actors run in parallel, one failure does **not** block siblings. The failed action records its failure in its own log; siblings finish normally; the orienter / reviewer pick up the failure at Review. + +Shared rules (gating, escalation, scope discipline, per-action failure handling): [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). State-file schema: [`../_shared/goal-state.md`](../_shared/goal-state.md). + +## Read first + +- [`../../docs/method.md`](../../docs/method.md) §"The four phases" — the Act row, §"Parallelism" for fan-out rules, §"The human gates" for the act gate. +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — especially the per-action failure rule. +- [`../_shared/goal-state.md`](../_shared/goal-state.md). +- The goal's `goal-state.md`. +- The latest decision set in `goals//decisions.md` and its Human Approval block (the act-gate result Decide captured). +- [`../../templates/action-spec-template.md`](../../templates/action-spec-template.md) — pre-execution spec the actor follows. +- [`../../templates/action-log-template.md`](../../templates/action-log-template.md) — post-execution log the actor writes. + +## What you do, step by step + +### Step 1 — Resolve the goal and pre-flight + +Resolve the slug from `$ARGUMENTS`. If empty, use the single active goal under `goals/`, or ask via `AskUserQuestion`. + +Read `goals//goal-state.md`. Confirm: + +- `status: active`. +- `current_phase: act`. If it is anything else, surface the mismatch via `AskUserQuestion` per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Per-phase loop". Do not silently advance — Decide must have set `current_phase: act` after the act gate cleared. + +### Step 2 — Verify the act gate cleared + +Read the latest decision set in `goals//decisions.md`. Confirm its **Human Approval** block: + +- Has an `approver`, `approved_at`, and at least one approved `id`. +- Lists which actions are approved, excluded, or edited. +- For every approved action with `reversible: N`, has an explicit irreversible-confirmation note (see [`decide`](../decide/SKILL.md) Step 4). + +Missing or incomplete approval block → **refuse to run**. Route back to [`decide`](../decide/SKILL.md) to re-run the act gate. Never act on an unapproved decision set, regardless of `act_gate` policy. + +If the approved id list is empty (the user rejected all or deferred), do nothing — dispatch `goal-orchestrator` to record `act: skipped` and `current_phase: review`, then hand off to [`review-loop`](../review-loop/SKILL.md). Skip the rest of this step. + +### Step 3 — Plan parallelism + +Read each approved action from the decision set. Read `parallel_act` from `goal-state.md` frontmatter (defaults to `false`). + +- One approved action → dispatch **one** actor. +- Multiple approved actions and `parallel_act: true` and the decider marked them as independent (no `dependencies` between them) → dispatch **M parallel actors**, one per action, in a single message. +- Multiple approved actions and `parallel_act: false`, or actions with declared `dependencies` → dispatch **sequentially**, honouring dependency order. Walk dependencies first; later actions wait for their predecessors' action logs to exist with `outcome: done`. + +If an action's predecessor returned `outcome: failed`, **do not dispatch the dependent action**. Mark it `outcome: skipped` with reason `predecessor failed` in a placeholder action log (or instruct the actor that it should produce a `skipped` log) and surface to the user at the report step. + +### Step 4 — Dispatch the actor subagent(s) + +For each approved action you dispatch one `actor` per [`../../agents/actor.md`](../../agents/actor.md). In each dispatch include the following context block: + +``` +Goal slug: +Iteration: +Action id: +Action (approved, with any human edits): +Rationale: +Impact: +Confidence: +Reversible: +Dependencies: +Acceptance criteria affected (for verification framing): + - ... +Constraints to respect (especially for irreversible actions): + - ... +Approval reference: decisions.md iteration , item , approved at by +Pre-execution spec template: ../../templates/action-spec-template.md +Action-log template: ../../templates/action-log-template.md +Output paths: + - Pre-execution spec (optional): goals//actions/.spec.md + - Post-execution log (required): goals//actions/.md +Reminder: follow the action spec verbatim; record every deviation in the log; if reversible: N, the rollback plan in the spec is mandatory; verify before writing outcome: done. +``` + +### Step 5 — Wait, fan in, and isolate failures + +Wait for every dispatched actor to complete. + +For each dispatched action, confirm the action log exists on disk at `goals//actions/.md` with one of the outcomes: `done` / `skipped` / `failed`. + +**Per-action failure isolation:** + +- A single actor failure does **not** abort siblings. Let parallel siblings finish normally. +- For each failed action, capture the failure summary (the actor's reported error or the malformed-artifact reason) without retrying automatically. **Exception:** if the actor returned no artifact at all (crash / timeout), re-dispatch once with the failure context per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Error escalation". On second failure, write a placeholder log with `outcome: failed` and the error. +- For each dependent action whose predecessor failed, mark it `outcome: skipped` with reason `predecessor failed`. + +Do not edit any action log after it is written by its actor. + +### Step 6 — Update state + +Dispatch the `goal-orchestrator` subagent to: + +- Set `current_phase: review`. +- Bump `updated_at`. +- Append one `## History` row per action log, citing the action id, outcome, and artifact path. + +If every action ended `skipped` (the act-gate-cleared decision set was empty or all skipped), still advance to `review` — the loop never ends inside Act. + +### Step 7 — Report and hand back + +Report to the user (or calling skill): + +- Approved action count, dispatched count, parallel vs. sequential. +- Per-action outcome summary: ` | | `, one line each. +- Per-failure summary: action id, error headline, link to the failed action log, dependents that were skipped because of it. +- Recommended next command — `/goal:review ` (Review will judge whether failures block acceptance) or hand back to the parent conductor. + +## Outputs + +Files written by the dispatched `actor` subagents under `goals//actions/`: + +- `goals//actions/.md` — one action log per approved (or skipped-with-reason) action. +- `goals//actions/.spec.md` — optional pre-execution spec, when the actor's contract requires one. + +State changes are dispatched to `goal-orchestrator`; this skill writes nothing directly. + +## Boundaries + +Generic conductor constraints: [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Constraints common to all Goal Loop conductors". Specifics for this skill: + +- **Never** run without a cleared act gate. Missing or incomplete Human Approval block → route back to [`decide`](../decide/SKILL.md). The act gate is non-negotiable. +- **Never** auto-approve an irreversible action that the act-gate record does not explicitly confirm. If the record is ambiguous, refuse and route back to Decide. +- **Never** let one failure block siblings. Fan out, fan in, isolate failures; the reviewer decides whether to continue, close, or amend. +- **Never** edit `goal-state.md` directly. Dispatch `goal-orchestrator`. +- **Never** edit an action log after the actor writes it. If it is malformed, surface and re-dispatch. +- **Never** execute an action whose declared dependency has not completed `outcome: done`. Skip with reason and surface at the report. + +## References + +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — shared conductor rules, especially per-action failure isolation. +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — state-file schema. +- [`../../docs/method.md`](../../docs/method.md) §"The four phases", §"Parallelism", §"The human gates". +- [`../../agents/actor.md`](../../agents/actor.md) — the subagent this skill dispatches. +- [`../../templates/action-spec-template.md`](../../templates/action-spec-template.md) — pre-execution spec shape. +- [`../../templates/action-log-template.md`](../../templates/action-log-template.md) — post-execution log shape. +- [`../decide/SKILL.md`](../decide/SKILL.md) — the act gate runs there; this skill verifies it. diff --git a/plugin-v2/skills/decide/SKILL.md b/plugin-v2/skills/decide/SKILL.md new file mode 100644 index 000000000..6b0be05a5 --- /dev/null +++ b/plugin-v2/skills/decide/SKILL.md @@ -0,0 +1,135 @@ +--- +name: decide +description: Run the Decide phase of a Goal Loop iteration. Dispatches the decider subagent to produce a ranked decision set with impact, confidence, reversibility, and rationale per action; then presents the set to the user via AskUserQuestion to clear the act gate before Act runs. Use when the user wants to propose next actions, rank options, present the decision set for sign-off, or mentions "/goal:decide", "run decide phase", "propose actions", "rank options", "act gate", "decide phase". +argument-hint: [goal-slug] +--- + +# Decide + +Conductor for the **Decide** phase of the Goal Loop. Job: dispatch the `decider` subagent ([`../../agents/decider.md`](../../agents/decider.md)) to produce a ranked decision set, then **run the act gate** — present the decision set to the user via `AskUserQuestion` and capture the explicit approval that Act needs before running. + +The act gate is one of the two non-negotiable human gates in the Goal Loop ([`../../docs/method.md`](../../docs/method.md) §"The human gates"). Even when the goal's `act_gate` policy is `low-risk-auto`, irreversible actions still require explicit confirmation. This skill enforces that contract. + +Shared rules (gating, escalation, scope discipline): [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). State-file schema: [`../_shared/goal-state.md`](../_shared/goal-state.md). + +## Read first + +- [`../../docs/method.md`](../../docs/method.md) §"The four phases", §"The human gates". +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — especially `act_gate` policy field. +- The goal's `goal-state.md`. +- The current `goals//orientation.md`. +- Prior `goals//decisions.md` (if it exists) — the decider may build on prior decision sets. +- Latest `goals//reviews/*.md` (if any) — its findings shape what decisions are needed. +- [`../../templates/decision-template.md`](../../templates/decision-template.md) — the canonical shape of the decision artifact. + +## What you do, step by step + +### Step 1 — Resolve the goal and pre-flight + +Resolve the slug from `$ARGUMENTS`. If empty, use the single active goal under `goals/`, or ask via `AskUserQuestion` when ambiguous. + +Read `goals//goal-state.md`. Confirm: + +- `status: active`. +- `current_phase` is `orient` (we just oriented) or `decide` (re-run). Mismatch → surface via `AskUserQuestion` per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Per-phase loop". +- `goals//orientation.md` exists. If missing, route to [`orient`](../orient/SKILL.md). +- Read the `act_gate` value from frontmatter (`always` / `low-risk-auto` / `never`) — you will use it at the act gate in Step 4. + +### Step 2 — Dispatch the decider subagent + +Dispatch a single `decider` per [`../../agents/decider.md`](../../agents/decider.md). Include the following context block: + +``` +Goal slug: +Iteration: +Orientation: goals//orientation.md +Prior decisions: goals//decisions.md (or "none — first iteration") +Latest review (if any): goals//reviews/.md (or "none") +Acceptance criteria (each proposed action should tie to one of these or to a constraint): + 1. ... + 2. ... +Constraints: + - ... +Act-gate policy: +Template to follow: ../../templates/decision-template.md +Output path (appended): goals//decisions.md +Reminder: rank actions by impact and confidence. Mark reversibility explicitly per action. Include rationale and a recommended subset. Do not execute or simulate execution — Act is a separate phase. +``` + +### Step 3 — Wait and verify + +Wait for the decider to complete. Confirm: + +- `goals//decisions.md` exists, with a new appended decision set for the current iteration. +- Each action carries: `id`, `action` (one-line), `rationale`, `impact`, `confidence`, `cost`, `reversible` (Y/N), `dependencies`, `gate` (`auto` / `human`). +- The decider provided a recommendation (subset of action ids) with a one-line justification. +- Risks and alternatives are recorded as the template requires. + +Malformed artifact → re-dispatch once with the failure context (per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Error escalation"). + +### Step 4 — Act gate (mandatory `AskUserQuestion`) + +Present the decision set to the user via a single `AskUserQuestion`. Show: + +- The recommended subset, one row per action: ` | | impact | confidence | reversible | gate`. +- The full set briefly (non-recommended items collapsed by id). +- The decider's risk summary in one line. + +Offer these options: + +- `Approve as recommended` (Recommended when the recommended subset contains no irreversible action under a `low-risk-auto` policy that the user has not already pre-authorised). +- `Approve subset` (free-text in "Other" — list the action ids to approve). +- `Approve with edits` (free-text in "Other" — note the edit per action). +- `Reject all` — close the iteration's Decide phase with no actions; the loop proceeds to Review with `act: skipped`. +- `Defer to next iteration` — pause; resume by re-invoking the conductor. + +**Irreversible-action rule:** any approved action with `reversible: N` requires an explicit confirmation, even if the user chose "Approve as recommended". After capturing the initial choice, if irreversible actions are included, run a second `AskUserQuestion` listing exactly those actions: `Confirm irreversible actions ` / `Drop them — proceed with reversible only` / `Pause and re-decide`. Do not collapse this into the first question — it is the safety gate. + +Record the resolved approval in the artifact: update the **Human Approval** section of the latest decision set in `decisions.md` (or have the decider append a new approval block — whichever the template supports). Capture: approver, ISO-8601 timestamp, approved id list, exclusions, edits. + +If `act_gate` policy is `never`, the act gate still runs, but the default option becomes `Surface decisions only — do not execute` and Act is not dispatched downstream; the loop continues to Review with `act: skipped` and a note that policy forbids execution. + +### Step 5 — Update state + +Dispatch the `goal-orchestrator` subagent to: + +- Set `current_phase: act` (when at least one action was approved) or `current_phase: review` (when all rejected, deferred, or policy forbids). +- Bump `updated_at`. +- Append a `## History` row citing the new decision-set entry in `decisions.md` and recording the act-gate outcome (approved ids, exclusions, irreversible confirmations). + +### Step 6 — Report and hand back + +Report to the user (or calling skill): + +- Path to the updated `decisions.md` with the line range of the new set. +- Approved action count vs. proposed action count. +- Whether the act gate cleared, and which irreversible actions (if any) were confirmed. +- Recommended next command — `/goal:act ` when at least one action is approved, `/goal:review ` when nothing was approved. + +## Outputs + +Files written by the dispatched `decider` subagent under `goals//`: + +- `goals//decisions.md` — appended with the new iteration's decision set and its Human Approval block. + +State changes are dispatched to `goal-orchestrator`; this skill writes nothing directly. + +## Boundaries + +Generic conductor constraints: [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Constraints common to all Goal Loop conductors". Specifics for this skill: + +- **Never** auto-approve an irreversible action, regardless of `act_gate` policy. Always run the explicit confirmation `AskUserQuestion`. +- **Never** dispatch the actor from this skill — that is the [`act`](../act/SKILL.md) skill's job. This skill stops at the act gate. +- **Never** simulate or pre-execute an approved action. The decider proposes; Act executes. +- **Never** propose actions in your turn. Dispatch the decider. +- **Never** edit `goal-state.md` directly. Dispatch `goal-orchestrator`. +- **Never** edit `decisions.md` after the decider writes it — except to record the approval block, and only via the template's contract. + +## References + +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — shared conductor rules. +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — state-file schema. +- [`../../docs/method.md`](../../docs/method.md) §"The four phases", §"The human gates". +- [`../../agents/decider.md`](../../agents/decider.md) — the subagent this skill dispatches. +- [`../../templates/decision-template.md`](../../templates/decision-template.md) — decision artifact shape. diff --git a/plugin-v2/skills/goal-loop/SKILL.md b/plugin-v2/skills/goal-loop/SKILL.md new file mode 100644 index 000000000..bf733b51f --- /dev/null +++ b/plugin-v2/skills/goal-loop/SKILL.md @@ -0,0 +1,125 @@ +--- +name: goal-loop +description: Drive a Goal Loop end-to-end — set the goal, then iterate Observe → Orient → Decide → Act → Review against it, gating between phases per the goal's act-gate policy. Detects resume vs. new, dispatches the goal-orchestrator subagent for state transitions and each per-phase skill for phase work, persists state under goals//. Use when the user wants to drive any decision or delivery cycle end-to-end, run a daily brief, run an OODA loop, set up goal-oriented orchestration, or mentions "goal loop", "/goal:start", "kick off OODA", "run a goal loop", "set up a daily brief", "goal-oriented orchestration", "drive this end-to-end", "what's next on this goal". +argument-hint: [goal-slug or one-line intent] +--- + +# Goal Loop + +You are the conductor of the **Goal Loop** defined in [`../../docs/method.md`](../../docs/method.md). Job: **sequence** the four phases + **gate** between them — never do phase work yourself. Each phase runs through its specialist subagent (`observer`, `orienter`, `decider`, `actor`, `loop-reviewer`) via the matching per-phase skill (`observe`, `orient`, `decide`, `act`, `review-loop`). State transitions are owned by the **`goal-orchestrator`** subagent; you dispatch it, you do not edit `goal-state.md` directly. + +Shared rules (gating, escalation, scope discipline, re-entry, the four loop outcomes): [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). Schema for the state file: [`../_shared/goal-state.md`](../_shared/goal-state.md). + +## Read first + +Contract you enforce: + +- [`../../docs/method.md`](../../docs/method.md) — the four phases, the two non-negotiable gates (goal gate, act gate), and the four loop-closure outcomes (`continue` / `close-met` / `close-abandon` / `amend`). +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — generic conductor rules; this skill only adds Goal Loop sequencing on top. +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — `goal-state.md` schema and ownership matrix. +- Active `goals//goal-state.md` (if resuming). + +## The flow you're driving + +| # | Phase | Subagent | Per-phase skill | Artifact | +|---|---|---|---|---| +| 0 | Scope | — | [`set-goal`](../set-goal/SKILL.md) | `goal-state.md` | +| 1 | Observe | `observer` × N | [`observe`](../observe/SKILL.md) | `observations/[-].md` | +| 2 | Orient | `orienter` | [`orient`](../orient/SKILL.md) | `orientation.md` (refreshed) | +| 3 | Decide | `decider` | [`decide`](../decide/SKILL.md) | `decisions.md` (appended) | +| 4 | Act | `actor` × M | [`act`](../act/SKILL.md) | `actions/.md` | +| 5 | Review | `loop-reviewer` | [`review-loop`](../review-loop/SKILL.md) | `reviews/.md` | + +Loop closure outcomes from Review: `continue` (re-enter Observe), `close-met` (status done), `close-abandon` (status cancelled), `amend` (route through `set-goal` in amend mode then resume Observe). All four are handled by `loop-pattern.md` §"The four loop outcomes". + +## What you do, step by step + +### Step 1 — Detect resume vs. fresh start + +``` +ls goals/ 2>/dev/null +``` + +For each `goals//goal-state.md` with `status` of `active`, `paused`, or `blocked`, read `slug | status | current_phase | iteration | updated_at`. Recommended-first by `updated_at`, present them in a single `AskUserQuestion`: + +- Resume listed goal (one option per goal, status shown). +- Start a new goal. +- Run a single phase against an existing goal (advanced — when the user knows the loop state and wants just one phase). + +`status: done` or `status: cancelled` goals are not auto-listed. If the user names one, ask whether to revive via amend (`set-goal` amend mode) or just inspect. + +No resumable goals exist → skip to Step 2. + +### Step 2 — Bootstrap (fresh start only) + +If `$ARGUMENTS` is a kebab-case slug that already exists under `goals/`, treat as resume (loop back to Step 1's question if needed). Otherwise dispatch the [`set-goal`](../set-goal/SKILL.md) skill, passing `$ARGUMENTS` as the one-line intent or starting slug. + +`set-goal` handles the **goal gate**: it elicits intent, constraints, acceptance criteria (with the falsifiability check), mode, cadence, observe sources, and act-gate policy via `AskUserQuestion`, writes `goals//goal-state.md` from `../../templates/goal-state-template.md`, and only marks `goal_signed_off: true` after the user confirms the final goal. Do not advance to Step 3 until `goal_signed_off: true`. + +### Step 3 — Resume guard (resume path only) + +If resuming and `status: blocked`, show the user the latest `## History` entry (which records the blocker) and ask via `AskUserQuestion`: `Blocker resolved — continue` / `Still blocked — pause` / `Amend the goal first`. Do not silently flip status. On "Blocker resolved", dispatch `goal-orchestrator` to set `status: active` and proceed. + +If resuming and `status: paused`, dispatch `goal-orchestrator` to set `status: active`; continue from the recorded `current_phase`. + +If resuming a recurring goal where `updated_at` is older than the declared cadence, treat as "next scheduled iteration" — start at Observe with `iteration` bumped, not mid-phase resume. + +### Step 4 — Run the iteration loop + +Loop until the user pauses, the user closes, or `loop-reviewer` returns a terminal outcome. + +For each phase in order (Observe → Orient → Decide → Act → Review): + +1. **Pre-flight** — read `goal-state.md`; confirm `current_phase` matches the phase you are about to dispatch. Mismatch → surface via `AskUserQuestion`: "State says we're at but next-in-sequence is — resume / re-run / abort?". Never silently overwrite phase state. +2. **Dispatch** the per-phase skill ([`observe`](../observe/SKILL.md), [`orient`](../orient/SKILL.md), [`decide`](../decide/SKILL.md), [`act`](../act/SKILL.md), [`review-loop`](../review-loop/SKILL.md)). Hand off control fully — do not duplicate the specialist's work in your own turn. +3. **Wait** for the phase to finish and the artifact to exist on disk. +4. **Update state** — dispatch the `goal-orchestrator` subagent to advance `current_phase`, bump `updated_at`, and append a `## History` row citing the artifact path. You never edit `goal-state.md` yourself; that is the orchestrator's contract per [`../_shared/goal-state.md`](../_shared/goal-state.md). +5. **Gate with user** via a single `AskUserQuestion`: + - `Continue to ` (Recommended) — only offered if the goal's gate policy for this transition is auto. + - `Pause here` — dispatch `goal-orchestrator` to set `status: paused`; exit. Resume by re-invoking `goal-loop`. + - `Re-run with feedback` — pass the free-text "Other" answer as additional context to the per-phase skill on re-dispatch. + + **Act gate (mandatory before Act, never auto-skipped):** when the next phase is Act, present the decision set from `decisions.md` and offer `Approve all` / `Approve subset` / `Reject all` / `Edit`. Even when `act_gate` policy is `low-risk-auto`, irreversible actions still require explicit confirmation. The `act` skill enforces this; the conductor surfaces it. + +### Step 5 — Loop closure + +After [`review-loop`](../review-loop/SKILL.md) finishes, it reports one of four outcomes (per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"The four loop outcomes"): + +- **`continue`** → dispatch `goal-orchestrator` to bump `iteration`, set `current_phase: observe`, append a `## History` row. For wall-clock cadence (`mode: recurring`, scheduled), pause and report next scheduled time; for `ad-hoc` or `event-driven`, immediately loop back to Step 4 Observe. +- **`close-met`** → dispatch `goal-orchestrator` to set `status: done`, append closing `## History` row. Report a 3-line closing summary to the user (acceptance criteria met, iterations run, artifact count). Exit. +- **`close-abandon`** → dispatch `goal-orchestrator` to set `status: cancelled` with the abandonment rationale from the review captured in `## History`. Report and exit. +- **`amend`** → gate with the user via `AskUserQuestion` to confirm the proposed amendment. On confirmation, dispatch [`set-goal`](../set-goal/SKILL.md) in **amend mode** against the same slug; it updates the relevant body sections and `goal-orchestrator` appends an `amend` `## History` row. Then ask whether to resume Observe immediately or pause. + +If `loop-reviewer` returns anything other than these four, treat as a malformed verdict per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Error escalation": surface to the user as a clarification, do not guess. + +### Step 6 — Wrap up + +When you exit (pause or close), report to the user in three lines: + +- Goal slug, status, iteration count, path to `goals//`. +- Last phase artifact written, with path. +- Recommended next action: re-invoke `goal-loop`, run a specific `/goal:` command, or close-out activities for terminal status. + +## Outputs + +You write no files directly. State is owned by: + +- [`set-goal`](../set-goal/SKILL.md) — creates and amends `goal-state.md` body sections. +- `goal-orchestrator` subagent — frontmatter transitions and `## History` rows. +- Per-phase skills — phase artifacts under `goals//`. + +## Boundaries + +Generic conductor constraints: [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Constraints common to all Goal Loop conductors". Specifics for this skill: + +- **Never** edit `goal-state.md` from this skill. Phase transitions go through `goal-orchestrator`; scope edits go through `set-goal`. If you find yourself drafting a frontmatter change in your turn, stop. +- **Never** dispatch a phase agent (`observer`, `orienter`, `decider`, `actor`, `loop-reviewer`) directly — always go through the per-phase skill (`observe`, `orient`, `decide`, `act`, `review-loop`). The per-phase skill owns fan-out, error handling, and template references. +- **Never** invent acceptance criteria, observe sources, or act-gate exceptions mid-loop. Route every scope change through `set-goal` in amend mode. +- **Never** auto-approve an irreversible action, regardless of `act_gate` policy. + +## References + +- [`../../docs/method.md`](../../docs/method.md) — full method definition. +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — shared conductor rules. +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — state-file schema. +- [`../../templates/goal-state-template.md`](../../templates/goal-state-template.md) — canonical shape of the state file. diff --git a/plugin-v2/skills/observe/SKILL.md b/plugin-v2/skills/observe/SKILL.md new file mode 100644 index 000000000..e0f181c30 --- /dev/null +++ b/plugin-v2/skills/observe/SKILL.md @@ -0,0 +1,130 @@ +--- +name: observe +description: Run the Observe phase of a Goal Loop iteration. Reads the goal's declared observe_sources, dispatches one observer subagent per source — in parallel when the goal allows fan-out — merges outputs, dedupes, and writes one observations file per source (or one merged file when only one source is declared). Use when the user wants to scan for signals against an active goal, refresh the observation set at the start of a new iteration, or mentions "/goal:observe", "run observe phase", "scan sources", "collect signals", "observe phase". +argument-hint: [goal-slug] +--- + +# Observe + +Conductor for the **Observe** phase of the Goal Loop. Job: dispatch the `observer` subagent ([`../../agents/observer.md`](../../agents/observer.md)) one or more times — in parallel when the goal allows it — collect raw signals against declared sources, then hand off to Orient. The Observer captures; you do not interpret. + +Shared rules (gating, escalation, scope discipline, parallel dispatch): [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). State-file schema: [`../_shared/goal-state.md`](../_shared/goal-state.md). + +## Read first + +- [`../../docs/method.md`](../../docs/method.md) §"The four phases" — the Observe row, and §"Parallelism" for fan-out rules. +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — to know which fields you read (especially `observe_sources`, `parallel_observe`, `current_phase`, `iteration`). +- The goal's `goal-state.md` and any prior `goals//observations/*.md` from earlier iterations (the observer uses them for delta tracking; you cite them in the dispatch). +- [`../../templates/observation-template.md`](../../templates/observation-template.md) — the canonical shape of each observation artifact. + +## What you do, step by step + +### Step 1 — Resolve the goal and pre-flight + +Resolve the slug from `$ARGUMENTS`. If empty: + +- If exactly one goal under `goals/` has `status: active`, use it. +- Otherwise list active goals and ask the user via a single `AskUserQuestion` to pick one. + +Read `goals//goal-state.md`. Confirm: + +- `status: active` — if `paused` or `blocked`, surface to the user via `AskUserQuestion` per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Re-entry / resume rules". If `done` or `cancelled`, refuse and recommend `set-goal` in amend mode. +- `goal_signed_off: true` — if not, refuse and route to [`set-goal`](../set-goal/SKILL.md). +- `current_phase` is one of `scope`, `review`, or `observe`. If it is `orient`, `decide`, or `act`, warn the user — Observe re-runs mid-iteration only on explicit confirmation (per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Per-phase loop", pre-flight). + +If `current_phase` is `review` (we are at the head of a new iteration), the orchestrator will have already advanced state to `observe` and bumped `iteration` on its next state-update step — you do not pre-empt that. + +### Step 2 — Plan parallelism + +Read `observe_sources` from `goal-state.md`. Read `parallel_observe` (defaults to `true` when more than one source is declared). + +- One source declared → dispatch **one** `observer`. +- Multiple sources and `parallel_observe: true` → dispatch **N parallel observers**, one per source, in a single message (one Agent tool call per source, sent together). +- Multiple sources and `parallel_observe: false` → dispatch sequentially, one observer at a time. + +For each observer, the assignment is exactly one source row from `observe_sources`. Do not let an observer roam across sources — the agent's contract forbids it. + +### Step 3 — Dispatch the observer subagent(s) + +For each source you dispatch one `observer` per [`../../agents/observer.md`](../../agents/observer.md). In each dispatch include the following context block: + +``` +Goal slug: +Iteration: +Source assignment (single row from observe_sources): + id: + type: + target: +Prior observations for this source (for delta tracking): + - goals//observations/--.md (or "none — first iteration") +Acceptance criteria (for signal relevance check, not interpretation): + 1. ... + 2. ... +Constraints to respect: + - ... +Template to follow: ../../templates/observation-template.md +Output path: goals//observations/--.md + (When exactly one source is declared, the source suffix may be omitted: goals//observations/.md) +Reminder: capture raw signals only; do not interpret, decide, or roam outside the assigned source. +``` + +Where `` is UTC `YYYY-MM-DDTHH-MM-SS` (colon-free, filesystem-safe). All parallel observers in one iteration share the same `` prefix so the orchestrator can group them. + +### Step 4 — Wait, merge, and dedupe + +Wait for every dispatched observer to complete. Then: + +1. Confirm every expected artifact exists on disk under `goals//observations/`. Missing artifact for a dispatched source = subagent failure — handle per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Error escalation" (re-dispatch once; on second failure, escalate to `goal-orchestrator` as `status: blocked`). +2. **Dedupe at the source-pair level only.** If the same source was scanned twice in this iteration (should not happen; report as state drift if it does), keep the latest and surface the duplicate to the user. Per-signal dedupe is the **`orienter`**'s job — do not pre-filter signals here. +3. If two observers report the same raw signal from different sources, leave both — the orienter resolves cross-source duplicates and contradictions. +4. Record gaps and unreachable sources reported by individual observers; surface them in the summary. + +Do not edit the observation artifacts themselves. They are the observers' files. + +### Step 5 — Update state + +Dispatch the `goal-orchestrator` subagent to: + +- Set `current_phase: orient`. +- Bump `updated_at`. +- Append one `## History` row per observation artifact, citing the relative path. + +You never edit `goal-state.md` yourself. + +### Step 6 — Report and hand back + +Report to the user (or the calling skill, when invoked from [`goal-loop`](../goal-loop/SKILL.md)): + +- Number of sources scanned and observers dispatched (parallel vs. sequential). +- Number of observation artifacts written, with paths. +- Any per-source gaps or failures (one line each). +- Recommended next command — `/goal:orient ` or hand back to the parent conductor. + +## Outputs + +Files written by the dispatched `observer` subagents under `goals//observations/`: + +- `goals//observations/--.md` (one per source when fan-out is active). +- `goals//observations/.md` (single file when exactly one source is declared). + +State changes are dispatched to `goal-orchestrator`; this skill writes nothing directly. + +## Boundaries + +Generic conductor constraints: [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Constraints common to all Goal Loop conductors". Specifics for this skill: + +- **Never** interpret signals in your turn — that is Orient's job. If you find yourself summarising "what these signals mean", stop. +- **Never** dispatch an observer against a source not declared in `observe_sources`. New sources require a goal amendment via [`set-goal`](../set-goal/SKILL.md). +- **Never** auto-extract archives, zips, or compressed bundles to seed sources. If a declared source is an archive, ask the user for explicit approval before extracting. +- **Never** fan out beyond the declared sources. One observer per source — no more, no less. +- **Never** edit `goal-state.md` directly. Dispatch `goal-orchestrator`. +- **Never** edit another agent's observation artifact. If you spot a defect, surface it to the user and re-dispatch. + +## References + +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — shared conductor rules. +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — state-file schema. +- [`../../docs/method.md`](../../docs/method.md) §"The four phases", §"Parallelism". +- [`../../agents/observer.md`](../../agents/observer.md) — the subagent this skill dispatches. +- [`../../templates/observation-template.md`](../../templates/observation-template.md) — observation artifact shape. diff --git a/plugin-v2/skills/orient/SKILL.md b/plugin-v2/skills/orient/SKILL.md new file mode 100644 index 000000000..4f7491f0f --- /dev/null +++ b/plugin-v2/skills/orient/SKILL.md @@ -0,0 +1,113 @@ +--- +name: orient +description: Run the Orient phase of a Goal Loop iteration. Dispatches the orienter subagent to synthesise the current iteration's observations against the goal, prior orientation, and last review; produces a single refreshed orientation.md and archives the previous one. Use when the user wants to synthesise observations into a situational picture, refresh orientation before deciding, or mentions "/goal:orient", "run orient phase", "synthesise observations", "make sense of signals", "orient phase". +argument-hint: [goal-slug] +--- + +# Orient + +Conductor for the **Orient** phase of the Goal Loop. Job: dispatch the `orienter` subagent ([`../../agents/orienter.md`](../../agents/orienter.md)) once, wait for the refreshed `orientation.md`, and hand off to Decide. There is no parallelism here — Orient runs as a single synthesis pass. + +Shared rules (gating, escalation, scope discipline): [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). State-file schema: [`../_shared/goal-state.md`](../_shared/goal-state.md). + +## Read first + +- [`../../docs/method.md`](../../docs/method.md) §"The four phases" — the Orient row. +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — to know which fields you read (`current_phase`, `iteration`, `acceptance_criteria`, `constraints`). +- The goal's `goal-state.md`. +- All observation files in `goals//observations/` produced during the current iteration. +- The previous `goals//orientation.md` (if it exists). +- The latest `goals//reviews/*.md` (if any) — its findings shape what the new orientation must address. +- [`../../templates/orientation-template.md`](../../templates/orientation-template.md) — the canonical shape of the artifact. + +## What you do, step by step + +### Step 1 — Resolve the goal and pre-flight + +Resolve the slug from `$ARGUMENTS`. If empty, use the single active goal under `goals/`, or ask via `AskUserQuestion` when ambiguous. + +Read `goals//goal-state.md`. Confirm: + +- `status: active` (handle `paused` / `blocked` per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Re-entry / resume rules"). +- `current_phase` is `observe` (we just finished observing) or `orient` (re-run). If anything else, surface a pre-flight mismatch via `AskUserQuestion` per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Per-phase loop". +- At least one observation file for the current `iteration` exists under `goals//observations/`. None present → block and route to [`observe`](../observe/SKILL.md). + +### Step 2 — Dispatch the orienter subagent + +Dispatch a single `orienter` per [`../../agents/orienter.md`](../../agents/orienter.md). Include the following context block: + +``` +Goal slug: +Iteration: +Observation artifacts for this iteration: + - goals//observations/--.md + - goals//observations/--.md + ... +Prior orientation: goals//orientation.md (or "none — first iteration") +Latest review (if any): goals//reviews/.md (or "none") +Acceptance criteria (anchor every claim to one of these or to a constraint): + 1. ... + 2. ... +Constraints to respect: + - ... +Template to follow: ../../templates/orientation-template.md +Output path: goals//orientation.md +Archive rule: before overwriting, move the existing orientation.md (if any) to goals//archive/orientation-.md (timestamp = the previous file's updated_at or mtime). +Reminder: synthesise; do not propose actions or rank options. Surface contradictions; do not resolve them. +``` + +### Step 3 — Wait and verify + +Wait for the orienter to complete. Confirm: + +- `goals//orientation.md` exists and is shaped per the template. +- If there was a prior orientation, the archived copy exists under `goals//archive/orientation-.md`. Missing archive on a non-first iteration = subagent contract violation — handle per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Error escalation". +- The new orientation cites observations by file or signal index (no free-standing claims). If the orienter introduces unbacked claims, re-dispatch once with the failure context. + +Do not edit the artifact yourself. If it has defects, surface and re-dispatch. + +### Step 4 — Update state + +Dispatch the `goal-orchestrator` subagent to: + +- Set `current_phase: decide`. +- Bump `updated_at`. +- Append a `## History` row citing the refreshed `orientation.md` path. + +### Step 5 — Report and hand back + +Report to the user (or calling skill): + +- Path to the refreshed `orientation.md`. +- Headline of the orientation (one sentence from the `## Summary` section). +- Count of items by category (new / blocked / at-risk / on-track / unknown) from the orientation. +- Any flagged contradictions or open questions that the decider must resolve. +- Recommended next command — `/goal:decide ` or hand back to the parent conductor. + +## Outputs + +Files written by the dispatched `orienter` subagent under `goals//`: + +- `goals//orientation.md` — refreshed for this iteration. +- `goals//archive/orientation-.md` — previous orientation (skipped on first iteration). + +State changes are dispatched to `goal-orchestrator`; this skill writes nothing directly. + +## Boundaries + +Generic conductor constraints: [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Constraints common to all Goal Loop conductors". Specifics for this skill: + +- **Never** synthesise observations in your turn. That is the orienter's job — dispatch it. +- **Never** propose actions, rank options, or fill in `decisions.md` from here. That is Decide's job. +- **Never** re-run Orient without confirming pre-flight state. If observations are missing for the current iteration, route to [`observe`](../observe/SKILL.md). +- **Never** edit `goal-state.md` directly. Dispatch `goal-orchestrator`. +- **Never** edit `orientation.md` after the orienter writes it. If it is malformed, re-dispatch. + +## References + +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — shared conductor rules. +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — state-file schema. +- [`../../docs/method.md`](../../docs/method.md) §"The four phases". +- [`../../agents/orienter.md`](../../agents/orienter.md) — the subagent this skill dispatches. +- [`../../templates/orientation-template.md`](../../templates/orientation-template.md) — orientation artifact shape. diff --git a/plugin-v2/skills/review-loop/SKILL.md b/plugin-v2/skills/review-loop/SKILL.md new file mode 100644 index 000000000..384bdd505 --- /dev/null +++ b/plugin-v2/skills/review-loop/SKILL.md @@ -0,0 +1,115 @@ +--- +name: review-loop +description: Run the Review phase of a Goal Loop iteration. Dispatches the loop-reviewer subagent to compare outcomes against acceptance criteria and return one of four outcomes — continue / close-met / close-abandon / amend — then dispatches goal-orchestrator to update goal-state.md accordingly and recommends the next action. Use when the user wants to close out an iteration, judge whether the goal is met, review the loop's outcome, or mentions "/goal:review", "close the loop", "review loop iteration", "review phase", "judge the loop". +argument-hint: [goal-slug] +--- + +# Review Loop + +Conductor for the **Review** phase of the Goal Loop — the phase that closes each iteration. Job: dispatch the `loop-reviewer` subagent ([`../../agents/loop-reviewer.md`](../../agents/loop-reviewer.md)) to compare this iteration's outcomes against the goal's acceptance criteria, capture one of four outcomes, then dispatch `goal-orchestrator` to apply the matching state change. + +The four outcomes — `continue` / `close-met` / `close-abandon` / `amend` — are the contract every Goal Loop conductor must handle ([`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"The four loop outcomes"). This skill is where they originate. + +Shared rules (gating, escalation, scope discipline, the four outcomes): [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). State-file schema: [`../_shared/goal-state.md`](../_shared/goal-state.md). + +## Read first + +- [`../../docs/method.md`](../../docs/method.md) §"The four phases" — the `loop-reviewer` role, and §"Loop closure" for the four outcomes. +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — especially §"The four loop outcomes". +- [`../_shared/goal-state.md`](../_shared/goal-state.md). +- The goal's `goal-state.md` — `acceptance_criteria` is the contract the reviewer judges against. +- This iteration's artifacts: `goals//observations/*.md`, `goals//orientation.md`, the latest decision set in `goals//decisions.md`, every `goals//actions/*.md` for the current iteration. +- Prior `goals//reviews/*.md` for the same goal — to compare progress across iterations. + +## What you do, step by step + +### Step 1 — Resolve the goal and pre-flight + +Resolve the slug from `$ARGUMENTS`. If empty, use the single active goal under `goals/`, or ask via `AskUserQuestion`. + +Read `goals//goal-state.md`. Confirm: + +- `status: active`. +- `current_phase: review` (set by [`act`](../act/SKILL.md) at fan-in). If anything else, surface via `AskUserQuestion` per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Per-phase loop". +- All upstream artifacts for the current `iteration` exist: at least one observation, an orientation, a decision set, and at least one action log (or a recorded `act: skipped` in `## History` when no actions were approved). + +### Step 2 — Dispatch the loop-reviewer subagent + +Dispatch a single `loop-reviewer` per [`../../agents/loop-reviewer.md`](../../agents/loop-reviewer.md). Include the following context block: + +``` +Goal slug: +Iteration: +Acceptance criteria (judge each explicitly — met / partial / unmet / unknown): + 1. ... + 2. ... +Constraints (judge whether any were violated this iteration): + - ... +This iteration's artifacts: + - Observations: goals//observations/--.md, ... + - Orientation: goals//orientation.md + - Decisions: goals//decisions.md (latest set) + - Actions: goals//actions/.md, ... + - Act-gate record: in the Human Approval block of the latest decision set +Prior reviews (for trend across iterations): goals//reviews/*.md (or "none") +Required outcome: exactly one of {continue, close-met, close-abandon, amend}. +For amend: state which goal-state.md section(s) you propose changing and why; the conductor will route through set-goal in amend mode. +Output path: goals//reviews/.md +Reminder: reference every acceptance criterion by number. Cite artifacts by file path. Do not invent criteria not in goal-state.md. +``` + +### Step 3 — Wait, verify, and parse the verdict + +Wait for the reviewer to complete. Confirm: + +- `goals//reviews/.md` exists. +- It references each acceptance criterion explicitly (per [`../../docs/method.md`](../../docs/method.md) §"Quality gates" — `Acceptance trace`). +- It returns exactly one of `continue` / `close-met` / `close-abandon` / `amend`. + +If the verdict is malformed or missing, do **not** guess. Surface to the user via `AskUserQuestion` per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Error escalation" — `Re-dispatch loop-reviewer` / `Treat as ` (free-text in "Other") / `Pause`. + +### Step 4 — Apply the outcome + +Branch on the verdict (full contract in [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"The four loop outcomes"): + +- **`continue`** — dispatch `goal-orchestrator` to bump `iteration`, set `current_phase: observe`, append a `## History` row citing the review path and outcome `continue`. Recommend next: re-invoke [`goal-loop`](../goal-loop/SKILL.md), or for scheduled recurring cadence, report next scheduled time and exit. +- **`close-met`** — dispatch `goal-orchestrator` to set `status: done`, leave `current_phase: review`, append a closing `## History` row with outcome `close-met` and the review path. Report a 3-line closing summary: criteria met (verbatim numbers), iterations run, paths to key artifacts. Exit. +- **`close-abandon`** — gate with the user via `AskUserQuestion` showing the reviewer's abandonment rationale and asking `Confirm abandonment` / `Override — try amend instead` / `Pause to discuss`. On confirm, dispatch `goal-orchestrator` to set `status: cancelled`, append a `## History` row with outcome `close-abandon` and the rationale captured verbatim. Report and exit. +- **`amend`** — show the reviewer's proposed amendment(s) to the user via `AskUserQuestion`: `Apply amendment as proposed` (Recommended) / `Apply with changes` (free-text in "Other") / `Reject amendment — continue without changes` / `Pause`. On apply, dispatch [`set-goal`](../set-goal/SKILL.md) in **amend mode** against the same slug; once `set-goal` reports success, dispatch `goal-orchestrator` to append a `## History` row with outcome `amend` citing the review path and the section(s) that changed. Then ask: `Resume Observe now` / `Pause` and act accordingly. + +### Step 5 — Report and hand back + +Report to the user (or calling skill): + +- Path to the new `reviews/.md`. +- The verdict, in one word. +- A one-line summary per acceptance criterion: `# | | `. +- The resulting state change applied to `goal-state.md` (`iteration` bumped, `status` changed, etc.). +- Recommended next action — re-invoke [`goal-loop`](../goal-loop/SKILL.md), pause, or exit per the outcome. + +## Outputs + +Files written by the dispatched `loop-reviewer` subagent under `goals//`: + +- `goals//reviews/.md` — one per iteration. + +State changes are dispatched to `goal-orchestrator` and (for `amend`) to [`set-goal`](../set-goal/SKILL.md); this skill writes nothing directly. + +## Boundaries + +Generic conductor constraints: [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Constraints common to all Goal Loop conductors". Specifics for this skill: + +- **Never** substitute your own judgement for the reviewer's verdict. If the verdict is malformed, escalate; do not guess. +- **Never** apply an `amend` outcome by editing `goal-state.md` directly. Route through [`set-goal`](../set-goal/SKILL.md) in amend mode. +- **Never** close a goal (`close-met` or `close-abandon`) without recording a `## History` row. +- **Never** dispatch the next iteration's Observe from this skill — that is [`goal-loop`](../goal-loop/SKILL.md)'s job after `continue` is recorded. +- **Never** invent acceptance criteria the reviewer should judge against — they live in `goal-state.md` and only `set-goal` can change them. +- **Never** edit `goal-state.md` directly. Dispatch `goal-orchestrator`. + +## References + +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — especially §"The four loop outcomes". +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — state-file schema. +- [`../../docs/method.md`](../../docs/method.md) §"The four phases", §"Loop closure". +- [`../../agents/loop-reviewer.md`](../../agents/loop-reviewer.md) — the subagent this skill dispatches. +- [`../set-goal/SKILL.md`](../set-goal/SKILL.md) — used in amend mode when the verdict is `amend`. diff --git a/plugin-v2/skills/set-goal/SKILL.md b/plugin-v2/skills/set-goal/SKILL.md new file mode 100644 index 000000000..0637ea39d --- /dev/null +++ b/plugin-v2/skills/set-goal/SKILL.md @@ -0,0 +1,127 @@ +--- +name: set-goal +description: Run a structured intake interview to draft a well-formed Goal Loop goal — intent, constraints, falsifiable acceptance criteria, mode, cadence, observe sources, and act-gate policy — then write or amend goals//goal-state.md from the canonical template. Enforces the clarity gate on acceptance criteria (loops on any criterion that is not falsifiable) and the goal gate (no advance until the human signs off). Use when starting a new goal, scoping a problem, defining acceptance, amending an existing goal mid-loop, or when the user mentions "/goal:set", "define a goal", "scope this problem", "draft a goal", "amend the goal", "tighten the acceptance criteria", "set goal", "set the goal". +argument-hint: [goal-slug] +--- + +# Set Goal + +Structured intake for the Goal Loop. Job: elicit the contract the loop will run against, write `goals//goal-state.md` from the canonical template, and clear the **goal gate** before the loop begins. Also handles **amend mode** when a `loop-reviewer` returns `amend` or the user explicitly asks to revise a live goal. + +Shared rules (gating, escalation, scope discipline): [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md). Schema and ownership matrix for the file you write: [`../_shared/goal-state.md`](../_shared/goal-state.md). + +## Read first + +- [`../../docs/method.md`](../../docs/method.md) — especially the **Goal** core concept, the **goal gate**, and the **act-gate** policy options. +- [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) — generic conductor rules; this skill follows them. +- [`../_shared/goal-state.md`](../_shared/goal-state.md) — every field, its allowed values, and which writer owns it. +- [`../../templates/goal-state-template.md`](../../templates/goal-state-template.md) — the file you will produce. +- For amend mode: the existing `goals//goal-state.md` and the most recent `goals//reviews/*.md` that triggered the amendment (if any). + +## What you do, step by step + +### Step 1 — Detect mode (create vs. amend) + +Resolve the slug: + +- If `$ARGUMENTS` is a kebab-case slug and `goals//goal-state.md` exists, this is **amend mode**. +- If `$ARGUMENTS` is a free-text one-line intent or empty, this is **create mode**. Derive a proposed kebab-case slug (≤ 6 words, outcome-named not solution-named — push back on "build-feature-x", propose "reduce-onboarding-drop-off"). + +In create mode, list any other goals under `goals/` whose `status` is `active`, `paused`, or `blocked` and ask via a single `AskUserQuestion`: `Start a new goal called ` (Recommended) / `Amend an existing goal: ` / `Choose a different slug` (free-text in "Other"). Resolve to one path. + +### Step 2 — Intake interview (single batched `AskUserQuestion` per round, ≤ 4 questions per round) + +You may run more than one round, but each round batches its questions into one `AskUserQuestion` call. Never chain back-to-back single questions. Carry forward earlier answers into subsequent rounds as confirmed context. + +**Round A — Intent and mode** (create mode only; in amend mode, skip questions whose section is not changing): + +1. **Intent** — "What outcome do you want, in plain language?" Push back on tool-flavoured framings ("set up dashboard X") — restate as outcome ("see daily readiness signal for area Y"). Two or three sentences max in the answer. +2. **Mode** — `One-shot (close after one Act+Review)` / `Recurring (iterate on cadence until stopped)`. +3. **Cadence** (only if recurring) — `Daily