@ikon85/agent-workflow-kit 0.10.0

package/.claude/skills/domain-modeling/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/engineering/domain-modeling` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+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.
+```

package/.claude/skills/git-guardrails-claude-code/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: git-guardrails-claude-code
+disable-model-invocation: true
+description: Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.
+---
+
+# Setup Git Guardrails
+
+Sets up a PreToolUse hook that intercepts and blocks dangerous git commands before Claude executes them.
+
+## What Gets Blocked
+
+- `git push` **to `main`/`master`** and any **force-push** (`--force` / `-f` / `--force-with-lease`). A normal feature-branch push (`git push -u origin <feature>`, `git push origin --delete <branch>`) is **allowed** — the git-level `pre-push` hook is the backstop for direct-to-`main` pushes.
+- `git reset --hard`
+- `git clean -f` / `git clean -fd`
+- `git branch -D`
+- `git checkout .` / `git restore .`
+
+When blocked, Claude sees a message telling it that it does not have authority to access these commands.
+
+## Steps
+
+### 1. Ask scope
+
+Ask the user: install for **this project only** (`.claude/settings.json`) or **all projects** (`~/.claude/settings.json`)?
+
+### 2. Copy the hook script
+
+The bundled script is at: [scripts/block-dangerous-git.sh](scripts/block-dangerous-git.sh)
+
+Copy it to the target location based on scope:
+
+- **Project**: `.claude/hooks/block-dangerous-git.sh`
+- **Global**: `~/.claude/hooks/block-dangerous-git.sh`
+
+Make it executable with `chmod +x`.
+
+### 3. Add hook to settings
+
+Add to the appropriate settings file:
+
+**Project** (`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Global** (`~/.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/block-dangerous-git.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If the settings file already exists, merge the hook into existing `hooks.PreToolUse` array — don't overwrite other settings.
+
+### 4. Ask about customization
+
+Ask if user wants to add or remove any patterns from the blocked list. Edit the copied script accordingly.
+
+### 5. Verify
+
+Run a quick test:
+
+```bash
+echo '{"tool_input":{"command":"git push origin main"}}' | <path-to-script>
+```
+
+Should exit with code 2 and print a BLOCKED message to stderr.

package/.claude/skills/git-guardrails-claude-code/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/misc/git-guardrails-claude-code` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+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.
+```

package/.claude/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
+
+# Push is narrowed: only a push to main/master OR a force-push is blocked — a
+# normal feature-branch push is allowed (the git-level .githooks/pre-push hook is
+# the main-push backstop). All other destructive ops stay blocked outright.
+DANGEROUS_PATTERNS=(
+  "git push.*[ :](main|master)([[:space:]]|$)"
+  "git push.*(--force|--force-with-lease|[[:space:]]-f([[:space:]]|$))"
+  "git reset --hard"
+  "git clean -fd"
+  "git clean -f"
+  "git branch -D"
+  "git checkout \."
+  "git restore \."
+  "reset --hard"
+)
+
+for pattern in "${DANGEROUS_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qE "$pattern"; then
+    echo "BLOCKED: '$COMMAND' matches dangerous pattern '$pattern'. The user has prevented you from doing this." >&2
+    exit 2
+  fi
+done
+
+exit 0

package/.claude/skills/git-worktree-recover/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: git-worktree-recover
+description: >-
+  Recovery skill for git branch mix-ups — a commit landed on the wrong branch,
+  the branch switched unexpectedly, or work appears lost. Uses git reflog to find
+  the misplaced commit, moves it to the right branch (git branch -f), optionally
+  resets the wrong branch, and sets up a clean worktree. Triggers: "commit on the
+  wrong branch", "the branch switched on its own", "this commit doesn't belong
+  here", "my work is gone", "I committed to main by accident".
+---
+
+# git-worktree-recover
+
+Recovery skill for branch mix-ups. When two processes share one checkout's global
+`HEAD`, they can clobber each other — a commit lands on the wrong branch. This
+skill is the **reaction** when a prevention layer (a worktree-per-session
+discipline and its guards) didn't stop it.
+
+## When to invoke
+
+- "My commit is on the wrong branch"
+- "The branch switched even though I did nothing"
+- "This commit doesn't belong here"
+- "My work is gone / I can't see my commit anymore"
+- "I accidentally committed to main"
+
+## Precondition
+
+If your project has a prevention layer — a SessionStart warning on active
+worktrees, a pre-edit guard that blocks edits on the wrong branch — this skill
+handles the case where that layer did NOT prevent a misplaced commit. Your project
+layer names those guards (`docs/agents/skills/git-worktree-recover.md`, seeded as
+an empty stub by `/setup-workflow`).
+
+---
+
+## Phase 1 — Assess the situation
+
+Run these four read-only commands (no harm):
+
+```bash
+git branch --show-current
+git log --oneline -10
+git reflog --oneline -20
+git worktree list
+```
+
+**Goal:** identify the misplaced commit SHA + the intended target branch.
+
+### What to look for in the reflog
+
+A line like:
+
+```
+691b655 HEAD@{3}: commit: <your commit message>
+```
+
+...appearing on a branch that is *not* the commit's intended branch. Note the SHA
+and message.
+
+---
+
+## Phase 2 — Safety checks
+
+Before any destructive action:
+
+1. **Is the target branch checked out in another worktree?**
+   ```bash
+   git worktree list
+   ```
+   `git branch -f <branch> <sha>` fails if the branch is checked out elsewhere —
+   that is safe (git refuses it), but check first to get a clear message.
+
+2. **Does the wrong branch have its own commits that must survive?**
+   ```bash
+   git log --oneline <wrong-branch>..origin/main
+   ```
+   If nothing of its own (it is `main`, or carries nothing) → a reset to
+   `origin/main` is safe.
+
+3. **Is the SHA really the right commit?**
+   ```bash
+   git show --stat <sha>
+   ```
+   Check the message + changed files against the intended context.
+
+---
+
+## Phase 3 — Move the commit to the right branch
+
+**Case A: target branch does not exist yet (most common)**
+
+```bash
+git branch <target-branch> <sha>
+git log --oneline <target-branch> -5   # verify
+```
+
+**Case B: target branch exists and the commit is missing there**
+
+```bash
+git branch -f <target-branch> <sha>    # only if NOT checked out elsewhere
+git log --oneline <target-branch> -5   # verify
+```
+
+**Case C: several commits on the wrong branch (stacked mix-up)**
+
+```bash
+git cherry-pick <sha1> <sha2> ...      # run on the correct branch, oldest first
+```
+
+---
+
+## Phase 4 — Clean up the wrong branch (optional, recommended)
+
+Only when:
+
+- the wrong branch is checked out in the main tree (not a worktree), AND
+- the wrong branch is `main` or carries no feature commits of its own.
+
+```bash
+git reset --hard origin/main
+git log --oneline -5   # the misplaced commit must NOT appear here anymore
+```
+
+If the wrong branch is a feature branch with its own state → do **not** reset; drop
+only the one commit (`git rebase --onto`). Rare special case — confirm before doing
+it.
+
+---
+
+## Phase 5 — Set up a worktree
+
+Set the recovered branch up cleanly in its own worktree. If your project has a
+worktree-setup command, use it (it typically runs `git worktree add`, installs
+deps and copies env files); otherwise:
+
+```bash
+git worktree add <path> <recovered-branch>
+```
+
+Your project layer names the exact command and what it copies.
+
+**Verify after setup:**
+
+```bash
+git worktree list
+```
+
+---
+
+## Phase 6 — Final check
+
+```bash
+git log --oneline <target-branch> -5   # SHA must appear here
+git log --oneline <wrong-branch> -3    # SHA must no longer be the top here
+git worktree list                      # clean
+```
+
+---
+
+## Background + cause
+
+`git` keeps ONE global `HEAD` pointer per checkout. If two processes run
+`git checkout`, the second overwrites the first — a commit can then land on the
+wrong branch. Not a bug, a git property. The fix is isolation via `git worktree`
+(one checkout dir per session); this skill is the reaction when a prevention guard
+did not catch it.
+
+**Safety guarantees of `git branch -f`:**
+
+- Refuses to run if the branch is checked out in another worktree (git built-in).
+- No data loss: the commit stays in the object store, only the branch pointer moves.
+- Always reversible via `git reflog`.
+
+## Anti-patterns
+
+- **`git rebase -i` to remove commits from main** — too destructive, risks a
+  force-push to main (a pre-push hook should block it, but avoid it anyway).
+- **`git reset --hard` without the safety check** — only after the worktree-list
+  check and only when the branch has no feature state of its own.
+- **Reflog without SHA verification (`git show`)** — reflog shows checkouts too,
+  not just commits; always `git show <sha>` before acting.

package/.claude/skills/grill-me/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: grill-me
+disable-model-invocation: true
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+
+Do not enact the plan until I confirm we have reached a shared understanding.
+
+## Related skills
+
+**Codebase with `CONTEXT.md`/ADRs present?** → use `grill-with-docs` instead of this skill — same grill, additionally sharpened against the existing domain model, maintains `CONTEXT.md`/ADRs inline.
+
+<!-- mirror-xform:start codex-escalation -->
+**High stakes / hard to reverse** (auth, schema, concurrency, migrations, payments)? → additionally `grill-me-codex` — the same grill plus a cross-model review by Codex afterward (Claude Code surface).
+<!-- mirror-xform:end -->
+
+## Coherence is the default — the grill locks only the deltas
+
+A feature that builds on existing features inherits the existing building blocks by default, across **every** layer: the UI renders the same components, the backend calls the same services and calculations, data flows through the same paths, conventions carry over. Do not interview the user about how such a feature should look or behave where an existing counterpart exists — that is already decided. Lock only:
+
+1. **The deltas:** what is intentionally excluded, restricted, or different (navigation, filters, actions, person data, write access, …). Every delta is an explicit decision with a reason.
+2. **The consumer walk-through:** who consumes the result and what they see/get — walked through from the consumer's side, not the owner's.
+
+A parallel rebuild of something that exists — a simplified UI stand-in, a re-implemented calculation, a second data path — is a defect to surface, never a silent shortcut. (Incident: a share feature shipped rebuilt, simplified renderers across 6 pages because "looks like the page minus chrome" was treated as open design space instead of the default; half the implementation was replaced.)
+
+## Cross-cutting fork — pattern vs. concept (before plan-lock)
+
+Is the change **cross-cutting** (a new pattern OR a new data structure/domain distinction, touching ≥3 places, OR "everywhere / distinguish X of Y / migrate")? Then classify it **during the grill** — don't defer it to the post-spec self-critique (otherwise Codex reviews a plan without it):
+
+- **Pattern** (old→new, e.g. TanStack Query replacing manual loading): the denominator is **grep-able** → put in the plan: a census of all old spots + a `*.guard.test.ts` that stays red as long as old spots exist outside a shrinking allowlist.
+- **Concept** (a new distinction, e.g. Project↔Campaign): `grep` cannot find the **absence** of a concept → put in the plan: a **code-derived** surface list (routes/pages/exports/reports) × a **domain verdict per surface** (counts / N/A / open); "counts" rows become tracked items.
+
+Never claim "complete" from plan/memory — count the denominator fresh, report `X of Y`. Substance, trigger threshold + guard template → the project convention file `docs/conventions/spec-completeness.md` (if present), §Cross-cutting fork.
+
+## Plan-lock — writing PLAN.md
+
+Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root (gitignored since, doesn't travel over git — consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
+
+## Re-grill reconcile — execute-ready (Wave 26)
+
+Applies when you **re-grill an issue that already exists** (a leaf of a grilled epic, or a child of an anchor) — the most common re-grill path, since campaign HITL slices route via `/grill-me → /tdd`. Goal: the rooted sub-graph comes out **execute-ready**, never silent drift. (grill-me has no docs layer — CONTEXT.md/ADR don't apply; core rules identical to grill-with-docs §"Re-Grill Reconcile".)
+
+1. **Read parent-anchor decisions FIRST** — fetch the anchor body + its PRD/key decisions, take the seam decision **from there**. Do not re-derive the architecture from the leaf (lesson: a leaf whose central decision was never read got re-litigated through question rounds). For an atomic leaf, its own body/PRD is the reference.
+2. **Check the leaf for internal contradiction**: a body that contradicts itself ("no new UI" + "build a name field") or the anchor decision → **no execute**. Likewise a leaf that says *"final cut depends on #X"* via `<!-- final-cut-depends-on: #X -->` where **#X is closed** without resolving the cut.
+3. **On drift/contradiction:** update the affected issue(s), re-stamp `plan_revision`, set the correct bucket. Internal contradiction → set the leaf to **HITL**: strip `ready-for-agent` via `python3 scripts/board-sync.py add --bucket hitl --issue <n>` (the helper stays the owner of the workflow labels — no bare `gh issue edit --add-label`), add the `headings.vorBau` heading (board profile `docs/agents/board-sync.md`; <project> currently `## Vor Bau zu klären`). The drift-guard then blocks the build handoff via `target_buildable` — the contradiction flows through existing machinery, no heuristic in the hook.
+4. **Audit, non-blocking:** `python3 scripts/execute-ready-check.py --issue <n> --mode audit` → a visible two-liner. The **blocking** net is the drift-guard at handoff (`.claude/hooks/drift-guard.py`).
+
+**Markers** (HTML comments, grep-able): `<!-- guard-ack: #<n> r<N> reason:<text> by-user -->`, `<!-- final-cut-depends-on: #<n> -->`, `<!-- handoff-intent: build|grill -->`, `<!-- guard-legacy -->`. Canonical table of all markers: module docstring of `scripts/execute-ready-check.py`.

package/.claude/skills/grill-me/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/productivity/grill-me` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+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.
+```

package/.claude/skills/grill-me-codex/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: grill-me-codex
+description: Two-act plan hardening. ACT 1 (you ↔ Claude) — Claude interviews you relentlessly about a plan or design, one question at a time, recommending an answer for each and exploring the codebase when it can answer itself, until every branch of the decision tree is resolved. ACT 2 (Claude ↔ Codex) — Claude writes the locked plan to PLAN.md and OpenAI Codex adversarially reviews it in a read-only sandbox (VERDICT:APPROVED/REVISE), Claude revises and re-submits to the SAME Codex session until APPROVED or a MAX_ROUNDS cap, then you sign off before any code. Use when the user says "/grill-me-codex", "grill me then have codex review", "grill me and stress-test the plan", "interview me about this plan then get a second model on it", or is about to build something high-stakes (auth, schema, concurrency, migrations, payments) and wants both alignment AND a cross-model sanity check before implementation. Builds on Matt Pocock's grill-me (MIT). For the docs-aware variant use /grill-with-docs-codex; if you already have a plan and want only the Codex review use /codex-review. NOT for reviewing already-written code (use /codex:review) and NOT for trivial changes.
+---
+
+# Grill-Me-Codex — Get Grilled, Then Get Reviewed
+
+Two acts, two different jobs:
+
+- **Act 1 fixes the #1 failure mode: building the wrong thing.** Claude interrogates *you* until intent is locked — no guessing at ambiguity. (This act is Matt Pocock's `grill-me`, used under MIT — see `THIRD-PARTY-NOTICES.md`.)
+- **Act 2 fixes the #2 failure mode: a plan that sounds right but breaks.** A *different model* (Codex) adversarially attacks the locked plan. Cross-model = no echo chamber.
+
+You enter at two points only: answering the grill, and signing off the converged plan. Codex is read-only the whole time and never touches a file.
+
+---
+
+## ACT 1 — GRILL (you ↔ Claude)
+
+> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+>
+> Ask the questions one at a time, waiting for my answer before continuing. Asking multiple questions at once is bewildering.
+>
+> If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+>
+> Do not write `PLAN.md` or proceed to Act 2 until I confirm we have reached a shared understanding.
+>
+> **Coherence default:** a feature that builds on existing features inherits the existing building blocks across every layer (UI components, backend services/calculations, data paths, conventions). The grill locks only the deltas (what is intentionally excluded/restricted/different, each with a reason) and the consumer walk-through (what the receiving user sees/gets). A parallel rebuild of something that exists is a defect, not a design option.
+
+### Cross-cutting fork — pattern vs. concept (before plan-lock)
+
+Is the change **cross-cutting** (a new pattern OR a new data structure/domain distinction, touching ≥3 places, OR "everywhere / distinguish X of Y / migrate")? Then classify it **during the grill** — don't defer it to the post-spec self-critique; the classification becomes part of the `PLAN.md` that Codex reviews in Act 2:
+
+- **Pattern** (old→new, e.g. TanStack Query replacing manual loading): the denominator is **grep-able** → put in the plan: a census of all old spots + a `*.guard.test.ts` that stays red as long as old spots exist outside a shrinking allowlist.
+- **Concept** (a new distinction, e.g. Project↔Campaign): `grep` cannot find the **absence** of a concept → put in the plan: a **code-derived** surface list (routes/pages/exports/reports) × a **domain verdict per surface** (counts / N/A / open); "counts" rows become tracked items.
+
+Never claim "complete" from plan/memory — count the denominator fresh, report `X of Y`. Substance, trigger threshold + guard template → the project convention file `docs/conventions/spec-completeness.md` (if present), §Cross-cutting fork.
+
+When the decision tree is resolved and we're aligned, **write the agreed plan to `PLAN.md`** in this structure, then move to Act 2:
+
+> **Where to write it:** `PLAN.md` + `PLAN-REVIEW-LOG.md` are per-session scratch — write them in the working directory the implementing session will actually use, and run Codex from there (`-C <dir>` on the round-1 `exec`; `exec resume` rejects both `-C` and `-s`, so run resume from that cwd and force read-only via `-c sandbox_mode="read-only"`). A project may gitignore these files, so don't rely on git to carry them across checkouts/worktrees. In worktree-based repos, create the issue worktree BEFORE this write and plan inside it.
+
+```markdown
+# Plan: <task>
+_Locked via grill — by Claude + <user>_
+
+## Goal
+<one paragraph — reflects what the grilling actually settled>
+
+## Approach
+<numbered, concrete steps>
+
+## Key decisions & tradeoffs
+<the contestable choices the grill resolved — name them so Codex has something to bite>
+
+## Risks / open questions
+<anything still genuinely open>
+
+## Out of scope
+<bounds the grill established>
+```
+
+Initialize `PLAN-REVIEW-LOG.md`:
+```markdown
+# Plan Review Log: <task>
+Act 1 (grill) complete — plan locked with the user. MAX_ROUNDS=<n>.
+```
+
+---
+
+## ACT 2 — REVIEW (Claude ↔ Codex)
+
+Now hand the locked plan to Codex for adversarial review. Same engine, mechanics verified end-to-end (2026-06-04).
+
+### Prerequisites (verify once, fast)
+- `codex --version` ≥ 0.130 (older CLIs error on the default `gpt-5.5` model).
+- Codex authenticated (prior `codex login`; ChatGPT account is fine). On auth/model error, surface it — don't silently retry.
+- Do NOT pin `-m`. Use the config default. Pinning `gpt-5.x-codex` variants 400s on ChatGPT-account auth.
+- **Echo the active model before Round 1** so the user can confirm: read the `model` line from `~/.codex/config.toml` (absent = "CLI default"); state it alongside the resolved tunables. If the user objects, stop before burning a round.
+
+### Tunables (read from args, else default)
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `MAX_ROUNDS` | `5` | Hard cap on review rounds. The loop ALWAYS terminates here. |
+| `PLAN_FILE` | `PLAN.md` | The plan Act 1 produced. |
+| `LOG_FILE` | `PLAN-REVIEW-LOG.md` | Append-only argument transcript. The artifact. |
+
+If invoked with e.g. `rounds=3`, use that for `MAX_ROUNDS`. Echo resolved values before starting.
+
+### The review prompt (sent each round)
+> You are an adversarial reviewer for an implementation plan. Be skeptical and specific — your job is to find what breaks, not to be agreeable. Read the plan at `PLAN.md` and any repo files you need (you are read-only). Identify concrete flaws: security holes, race conditions, missing edge cases, schema conflicts, wrong assumptions, observability gaps, simpler alternatives. For each, give a one-line fix. Do NOT modify any files. End your reply with EXACTLY one line: `VERDICT: APPROVED` if the plan is sound enough to implement, or `VERDICT: REVISE` if it still has material problems.
+
+### Round 1 — fresh session (capture `thread_id`)
+Stream `--json` to a FILE, never pipe to `grep` — `codex exec --json | grep` deadlocks on codex-cli ≥0.137. **Always launch with `< /dev/null`** — a backgrounded `codex exec … &` without it blocks on stdin and sits at **0 CPU / 0 bytes** forever (the #1 cause of the "silent hang"; verified 2026-06-09). Background it so a **90s liveness probe** still catches a genuine sandbox deadlock.
+```bash
+CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: STABLE across round-1+resume turns, collision-free under parallel sessions
+codex exec -s read-only --json -o $CODEX_TMP/verdict.txt "$(cat REVIEW_PROMPT)" \
+  < /dev/null > $CODEX_TMP/r1.jsonl 2>/dev/null &
+CODEX_PID=$!
+sleep 90                                          # liveness probe (REQUIRED)
+if kill -0 "$CODEX_PID" 2>/dev/null; then
+  CPU=$(ps -o time= -p "$CODEX_PID" 2>/dev/null | tr -dc '0-9:')   # cumulative CPU, e.g. 00:00:00
+  BYTES=$(wc -c < $CODEX_TMP/r1.jsonl 2>/dev/null || echo 0)
+  if [ "${CPU:-00:00:00}" = "00:00:00" ] && [ "${BYTES:-0}" -eq 0 ]; then
+    kill -9 "$CODEX_PID" 2>/dev/null; echo "CODEX-HUNG"   # alive + 0 CPU + 0 bytes = blocked, NOT working
+  fi
+fi
+wait "$CODEX_PID" 2>/dev/null
+THREAD_ID=$(grep -o '"thread_id":"[^"]*"' $CODEX_TMP/r1.jsonl | head -1 | cut -d'"' -f4)
+```
+- **`CODEX-HUNG` printed** (alive + 0 CPU + 0 bytes at 90s) → **first suspect the stdin block**: confirm the launch has `< /dev/null` and retry. That fixes it in nearly every case. **NEVER `pgrep`/`kill` codex procs to "clear contention"** — that murders the user's live, unrelated codex sessions and does **not** fix a stdin hang. Only if `< /dev/null` is present and it still hangs (genuine sandbox deadlock) → **STOP Act 2**: tell the user, offer to sign off without the cross-model review or retry once. Don't touch other codex processes.
+- **Healthy:** CPU climbs past `00:00:00` and/or `$CODEX_TMP/r1.jsonl` grows; `THREAD_ID` parses; critique lands in `$CODEX_TMP/verdict.txt`. `2>/dev/null` hides cosmetic MCP/auth noise.
+- **Clean finish but no verdict file + no `THREAD_ID`** = auth/model failure → stop, tell the user.
+
+### Rounds 2..MAX — resume the SAME session (Codex remembers its prior critiques)
+```bash
+# resume REJECTS -s. Force read-only via -c sandbox_mode, or Codex inherits
+# config.toml (possibly danger-full-access) and could WRITE files. This is the
+# single most important safety line in the skill — verified 2026-06-04.
+CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: STABLE across round-1+resume turns, collision-free under parallel sessions
+codex exec resume "$THREAD_ID" -c sandbox_mode="read-only" --json \
+  -o $CODEX_TMP/verdict.txt \
+  "I revised the plan. Re-review PLAN.md — check whether your prior findings are addressed and flag anything new. End with VERDICT: APPROVED or VERDICT: REVISE." \
+  < /dev/null 2>/dev/null >/dev/null &
+```
+Wrap resume in the **same 90s liveness probe** (background + `wait`). Resume discards the `--json` stream, so probe on the verdict file: `BYTES=$(wc -c < $CODEX_TMP/verdict.txt)` plus the `CPU` check — `00:00:00` CPU + empty verdict at 90s → kill, treat as `CODEX-HUNG`, same STOP path as round 1. Both `codex exec` and `codex exec resume` support `--json` and `-o/--output-last-message`.
+
+**Overall ceiling (both rounds):** the 90s probe catches silent hangs, not long stuck runs. Cap every `codex exec` / `codex exec resume` at **10 minutes** — via Claude Code's Bash tool pass `timeout: 600000` on the tool call (the default 2-minute tool timeout would kill real reviews mid-run); in a plain shell prefix `timeout 600` (macOS: `gtimeout 600` via coreutils). If the ceiling trips, treat it as a failed round: stop and tell the user rather than retrying blind.
+
+### Each round, after Codex returns
+1. Read `$CODEX_TMP/verdict.txt`; append to `LOG_FILE`: `## Round <n> — Codex` + the full critique.
+2. Grep the last line for the verdict:
+   - `VERDICT: APPROVED` → break to Resolution (converged).
+   - `VERDICT: REVISE` → Claude decides **what's actually worth acting on** (Claude is final arbiter — Codex advises, doesn't command). Revise `PLAN_FILE`. Append `### Claude's response` to `LOG_FILE`: what changed, what was rejected, why. Increment round.
+3. If round > `MAX_ROUNDS` → break to Resolution (deadlock).
+
+### Resolution (you sign off — final gate)
+- **APPROVED:** present the final `PLAN_FILE`, a 3-bullet summary of what the two acts improved, and the round count. Ask: *"Grilled + survived N rounds of Codex. Implement it now — Codex builds it (`/codex-build`), Claude builds it, or stop here?"* Code only on a yes. **No code is written during either act.**
+- **MAX_ROUNDS hit without APPROVED (deadlock):** do NOT fake convergence. List each unresolved point + Claude's counter-position; hand it to the user to break the tie. A flagged disagreement beats a false "approved."
+
+### ACT 3 (optional) — BUILD (Codex ↔ Claude, roles flipped)
+
+If the user picks Codex: invoke the `codex-build` skill with `SPEC_FILE=PLAN.md` and the same `LOG_FILE` — it appends `## Act 3 — Build` to the log, so one artifact tells the whole story (grilled → reviewed → built → verified). Roles flip: Codex writes the code in a bounded workspace-write sandbox, Claude reviews the diff and runs the proof. If the user picks Claude, implement directly as usual.
+
+---
+
+## Hard rules
+- Act 1 always precedes Act 2 — don't write `PLAN.md` until the grill has actually resolved the decision tree with the user.
+- Codex is read-only EVERY round — `-s read-only` first call, `-c sandbox_mode="read-only"` on every resume (resume has no `-s`). It never writes.
+- The loop ALWAYS terminates at `MAX_ROUNDS`.
+- Claude is final arbiter on every REVISE — incorporate good critiques, reject bad ones *with a logged reason*. Don't cave to everything (defeats the cross-model check) and don't ignore it (defeats the point).
+- Code only after the user's final sign-off.
+- `LOG_FILE` is the deliverable — keep the whole argument.
+
+## What NOT to do
+- Don't review already-written code — that's `/codex:review`.
+- Don't pin a `-codex` model variant on ChatGPT-account auth — it 400s.
+- Don't let Codex edit files. Read-only, always.
+- Don't skip Act 1 — the grill is half the value.

package/.claude/skills/grill-me-codex/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,32 @@
+# Third-Party Notices
+
+## grill-me (Act 1)
+
+Act 1 of this skill ("GRILL") is adapted from the **grill-me** skill by **Matt Pocock**,
+from https://github.com/mattpocock/skills, used under the MIT License.
+
+Act 2 ("REVIEW" — the Codex adversarial loop) is original work added on top.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+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.
+```