feat(plugin-v2): unified goal-loop plugin merging OODA + goal-orchestrator

.github/workflows/plugin-v2-quality.yml

@@ -0,0 +1,33 @@
+name: plugin-v2 quality
+
+on:
+  pull_request:
+    paths:
+      - 'plugin-v2/**'
+      - '.github/workflows/plugin-v2-quality.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'plugin-v2/**'
+      - '.github/workflows/plugin-v2-quality.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  plugin-v2-checks:
+    name: plugin-v2 verify
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Run plugin-v2 check-all.sh
+        run: bash plugin-v2/scripts/check-all.sh

_typos.toml

@@ -28,6 +28,10 @@ AGS = "AGS"          # agentic security checklist item prefix
 
 # Tool / library names
 wrk = "wrk"          # HTTP load-testing tool
+HAX = "HAX"          # Microsoft Human-AI Experience Toolkit (proper noun)
+
+# Researcher surnames cited in docs (real authors of cited works)
+Collisson = "Collisson"  # Penny Collisson, co-author of Microsoft Guidelines for Human-AI Interaction
 
 # Intentional non-words used in prose
 mis = "mis"          # used in compound forms ("mis-typed")

plugin-v2/.claude-plugin/plugin.json

@@ -0,0 +1,67 @@
+{
+  "name": "goal-loop",
+  "version": "2.2.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",
+  "bugs": {
+    "url": "https://github.com/Luis85/agentic-workflow/issues",
+    "security": "https://github.com/Luis85/agentic-workflow/security/advisories"
+  },
+  "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",
+      "agents/goal-critic.md",
+      "agents/signal-deduper.md",
+      "agents/risk-scout.md"
+    ],
+    "skills": [
+      "skills/goal-loop",
+      "skills/set-goal",
+      "skills/observe",
+      "skills/orient",
+      "skills/decide",
+      "skills/act",
+      "skills/review-loop",
+      "skills/acceptance-criteria-helper",
+      "skills/trace-loop",
+      "skills/list-goals",
+      "skills/welcome",
+      "skills/create-goal",
+      "skills/activate-goal",
+      "skills/export-trace"
+    ],
+    "commands": [
+      "commands/goal",
+      "commands/create-goal.md",
+      "commands/set-goal.md"
+    ]
+  },
+  "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"]
+  }
+}

plugin-v2/.codex/README.md

@@ -0,0 +1,25 @@
+---
+title: "Codex"
+folder: "plugin-v2/.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.
+
+> When a Codex operation has no matching file under `.codex/workflows/`, open the corresponding `skills/<name>/SKILL.md` and follow its step-by-step block directly. The Claude-Code-specific dispatch language (`AskUserQuestion`, `Task`) maps to "ask the human" and "delegate to a sub-agent" respectively.
+
+This folder is part of the plugin. Local Codex cache, secrets, or session state should not be committed here.

plugin-v2/.codex/instructions.md

@@ -0,0 +1,67 @@
+# 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).
+
+## How Codex enacts plugin "skills"
+
+The plugin's skill set lives at `skills/<name>/SKILL.md`. Each skill is written for a Claude Code dispatcher, but Codex has no dispatcher. Two substitutes:
+
+1. **Workflows under `.codex/workflows/`** are the Codex-shaped versions of the most-used skills. Run a workflow by opening the file and following its steps verbatim. The workflow names the subagent it consults — Codex roleplays that subagent or sub-dispatches to a downstream agent.
+
+2. **For skills without a Codex workflow**, open the `SKILL.md` file directly. Treat the `## What you do, step by step` block as the script. The `## Boundaries` section is the guardrail you must not violate.
+
+When a workflow conflicts with the underlying `SKILL.md` (it should not — workflows are derived from skills), the `SKILL.md` is authoritative.
+
+## 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/<slug>/` 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/<slug>/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.

plugin-v2/.codex/workflows/daily-brief.md

@@ -0,0 +1,75 @@
+# 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/<slug>/` 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. Observers run **only against declared sources** — never against an undeclared file (the `observe` skill's Boundaries forbid it; see [`../../skills/observe/SKILL.md`](../../skills/observe/SKILL.md) §Boundaries).
+- Each observer writes `goals/<slug>/observations/<iso-timestamp>--<source-slug>.md`. Raw signals only.
+- **Roll-forward handling without violating Observe boundaries.** The prior `brief.md` is NOT itself an observe source. If you want carry-over to surface in this iteration, either (a) declare `brief-archive` as an `observe_sources` entry (`type: archive`, `target: goals/<slug>/archive/`) in `goal-state.md` via `/goal:amend <slug>` so the observer can legitimately scan prior briefs, or (b) let the **orienter** read the prior `brief.md` directly in Step 3 (orient is allowed to read any artifact under `goals/<slug>/` per its contract; it just must not call out into other observe sources itself). The default daily-brief example uses option (b) — the orienter reads `archive/brief/<YYYY-MM-DD>.md` to compute the "what carried over" delta, no Observe boundary violated.
+
+### 3. Orient
+
+- One orienter reads every observation in the window and the prior `orientation.md`.
+- Writes the refreshed `goals/<slug>/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/<slug>/decisions.md`.
+
+### 5. Render the brief
+
+- Read [`../../templates/brief-template.md`](../../templates/brief-template.md). Produce `goals/<slug>/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 (the orienter reconstructs this from the prior `archive/brief/<YYYY-MM-DD>.md`).
+  - **Optional Actions** — proposals weighed but not promoted, surfaced so the human can pull them in.
+- Archive a dated copy at `goals/<slug>/archive/brief/<YYYY-MM-DD>.md`. The current `brief.md` is overwritten on each cadence run; the archive preserves history (matches the Periodic Notes-compatible date-only filename per [`../../docs/cadence-recipes.md`](../../docs/cadence-recipes.md)).
+
+### 6. Act phase — typically skipped for daily briefs
+
+Daily briefs are advisory: the *human* acts, the loop does not. But `review-loop` preflight ([`../../skills/review-loop/SKILL.md`](../../skills/review-loop/SKILL.md) §Step 1) requires either (a) at least one action log under `goals/<slug>/actions/iter-<n>/` for the current iteration, or (b) an explicit `act: skipped` `## History` row recording the skip reason. Skipping Act without the history record leaves Review dead-ended.
+
+- **If every decision-set proposal carries `gate: human`** (the typical daily-brief shape), the `decide` skill's act gate resolves to "Reject all" or "Defer to next iteration", and `decide` then dispatches `goal-orchestrator` to set `current_phase: review` and append an `act: skipped — recommended for human action` row to `## History`. Review then runs cleanly with no action artifacts expected.
+- **If `act_gate: never`** is set on the goal (decisions are surfaced but not executed), the same `act: skipped — policy forbids` row is recorded.
+- **Never** jump straight from brief rendering to Review without one of these two paths — the orchestrator's `## History` row is what makes the skip auditable.
+
+### 7. Review
+
+- One loop-reviewer writes `goals/<slug>/reviews/<iso-timestamp>.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.