pincer-workflow 0.2.0 → 0.2.2

package/README.md

@@ -18,7 +18,7 @@ cd your-project
 npx pincer-workflow init     # asks which platform(s) you use
 ```
 
-Then follow the chain — identical on every platform:
+Then follow the chain — the same five steps on every platform:
 
 ```
 /pincer-plan <brief>  →  /pincer-narrow  →  /pincer-code  →  /pincer-evaluate  →  /pincer-release
@@ -27,14 +27,39 @@ Then follow the chain — identical on every platform:
 `/pincer-status` shows where the workflow stands at any point (PRD, tickets,
 receipts, elapsed time, next command) — run it first in a new session.
 
-Per-platform notes printed by `init`:
+On Codex CLI the commands are skills, invoked by mention rather than slash:
+`$pincer-plan <brief>` → `$pincer-narrow` → `$pincer-code` → `$pincer-evaluate`
+→ `$pincer-release`, and `$pincer-status`.
 
-- **Claude Code** — works immediately; commands, subagents, permission deny
-  rules, and a destructive-command hook install to `.claude/`.
-- **Codex CLI** — rules load natively from `AGENTS.md`; copy the prompts once:
-  `cp .codex/prompts/*.md ~/.codex/prompts/` (posture notes in `.codex/README.md`).
-- **Copilot (VS Code)** — enable `"chat.promptFiles": true`, then run
-  `/pincer-plan` in chat; `.github/copilot-instructions.md` is wired to `AGENTS.md`.
+### Claude Code
+
+Works immediately: the commands, the two subagents, the `.env` deny rules and
+the destructive-command and ticket-guard hooks install to `.claude/`. Start
+`claude` in the repo and run `/pincer-plan <brief>`.
+
+### Codex CLI
+
+Works immediately as well: `AGENTS.md` loads natively, and the six commands
+install as skills under `.agents/skills/`, which Codex discovers from the repo
+(no copying into your home directory — Codex removed custom prompts and
+`~/.codex/prompts/` in early 2026). Start `codex` in the repo, then type
+`$pincer-plan <brief>`; `$` opens the skill picker and `/skills` lists what
+loaded. Inside the Codex skills every cross-reference already reads
+`$pincer-narrow`, `$pincer-status` and so on.
+
+Codex has no PreToolUse hooks, so the guardrail posture lives in
+`~/.codex/config.toml` instead — `approval_policy = "on-request"` and
+`sandbox_mode = "workspace-write"`; never run with approvals disabled. The
+ticket scripts (`scripts/pincer-ticket.sh`, `scripts/pincer-status.sh`) are
+plain bash and work unchanged; the rule in `AGENTS.md` against hand-editing
+ticket state carries the weight the hook carries on Claude Code, and
+`$pincer-status` flags any ticket marked done without a receipt.
+Full notes in `.codex/README.md`.
+
+### GitHub Copilot (VS Code)
+
+Enable `"chat.promptFiles": true` in VS Code settings, then run `/pincer-plan`
+in chat. `.github/copilot-instructions.md` is wired to `AGENTS.md`.
 
 ## Claude Code plugin (alternative)
 
@@ -61,7 +86,7 @@ want the repo-side rules too can copy `AGENTS.md` from the
 npx pincer-workflow@latest update
 ```
 
-Files you never touched are refreshed in place. (Installs older than v0.2.0 gain the ticket state machine, the status report and the ticket-guard hook on update; `.claude/settings.json` conflicts if you edited it — merge the new hook entry from the `.new` file.) Files you edited are left
+Files you never touched are refreshed in place. (Installs older than v0.2.0 gain the ticket state machine, the status report and the ticket-guard hook on update; `.claude/settings.json` conflicts if you edited it — merge the new hook entry from the `.new` file. v0.2.2 replaces the Codex adapter: the commands are now skills in `.agents/skills/` invoked as `$pincer-*`, since Codex no longer loads `~/.codex/prompts/` — you can delete the copies there.) Files you edited are left
 alone — the new version lands next to them as `<file>.new` for a manual merge.
 `npx pincer-workflow doctor` checks the health of an install (hook executable,
 `.gitignore` covering `.env*`, no unmerged `*.new` files, version current).
@@ -76,7 +101,7 @@ alone — the new version lands next to them as `<file>.new` for a manual merge.
 | `scripts/pincer-ticket.sh` | The ticket state machine: `start` (enforces dependency order) → `verify` (runs the ticket's check, stamps a receipt only on green) → `done` (refuses without a matching receipt or with unticked criteria) |
 | `scripts/pincer-status.sh` | Read-only state report: PRD, every ticket with clock-based elapsed time, blocked tickets, build time vs budget, next command |
 | `.claude/hooks/` + `settings.json` | Mechanical guardrails: `.env` files unreadable, destructive commands blocked, ticket state fields writable only through the script |
-| `.codex/` · `.github/` | Generated Codex and Copilot adapters + platform wiring |
+| `.agents/skills/` · `.codex/` · `.github/` | Generated Codex skills and Copilot prompt files + platform wiring (`.codex/README.md` covers the Codex posture) |
 | `scripts/sync-prompts.sh` | Regenerates the adapters after you edit a playbook |
 | `scripts/build-plugin.sh` | Regenerates the Claude Code plugin (`plugin/`) from the template |
 | `docs/dry-run-checklist.md` | The workflow's own test — audited by `/pincer-release` |

package/bin/pincer.js

@@ -23,7 +23,7 @@ const MANIFEST = '.pincer.json';
 const PLATFORM_ROOTS = {
   common: ['AGENTS.md', 'docs/dry-run-checklist.md', 'scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh'],
   claude: ['CLAUDE.md', '.claude'],
-  codex: ['.codex'],
+  codex: ['.codex', '.agents'],
   copilot: ['.github'],
 };
 const EXECUTABLES = ['scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', '.claude/hooks/block-dangerous.sh', '.claude/hooks/ticket-guard.sh'];
@@ -129,13 +129,14 @@ function nextSteps(platforms) {
     console.log('  Claude Code   start `claude` in this repo and run /pincer-plan <brief>');
   }
   if (platforms.includes('codex')) {
-    console.log('  Codex CLI     cp .codex/prompts/*.md ~/.codex/prompts/   (once; posture notes in .codex/README.md)');
+    console.log('  Codex CLI     start `codex` in this repo and type $pincer-plan <brief>  (skills load from .agents/skills/; posture notes in .codex/README.md)');
   }
   if (platforms.includes('copilot')) {
     console.log('  Copilot       enable "chat.promptFiles": true in VS Code settings, then /pincer-plan in chat');
   }
   console.log('  All rules live in AGENTS.md — fill in its Conventions section once you know the stack.');
-  console.log('  Any session     scripts/pincer-status.sh shows where the workflow stands (also /pincer-status)');
+  const statusCmd = platforms.every((p) => p === 'codex') ? '$pincer-status' : platforms.includes('codex') ? '/pincer-status, $pincer-status on Codex' : '/pincer-status';
+  console.log(`  Any session     scripts/pincer-status.sh shows where the workflow stands (also ${statusCmd})`);
 }
 
 async function askPlatforms() {
@@ -180,9 +181,6 @@ async function cmdUpdate() {
   if (!manifest) fail(`no ${MANIFEST} here — run \`pincer init\` first.`);
   console.log(`\nUpdating PINCER ${manifest.version} -> ${VERSION} for: ${manifest.platforms.join(', ')}\n`);
   report(install(dir, manifest.platforms, manifest.files));
-  if (manifest.platforms.includes('codex')) {
-    console.log('\n  Codex uses global prompts — re-run: cp .codex/prompts/*.md ~/.codex/prompts/');
-  }
 }
 
 function cmdDoctor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pincer-workflow",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "PINCER — a PRD-driven agentic delivery workflow for Claude Code, Codex CLI, and GitHub Copilot. Plan · Investigate · Narrow · Code · Evaluate · Release.",
   "bin": {
     "pincer": "bin/pincer.js"

package/template/{.codex/prompts/pincer-code.md → .agents/skills/pincer-code/SKILL.md}

@@ -1,12 +1,16 @@
+---
+name: pincer-code
+description: "Implement tickets sequentially with verification and one commit per ticket"
+---
 <!-- Generated from .claude/commands/pincer-code.md by scripts/sync-prompts.sh — edit the source, not this file -->
 
 
-# /pincer-code — Ticket Implementation
+# $pincer-code — Ticket Implementation
 
 You are implementing the tickets in `tickets/` sequentially. Mostly autonomous: after the
 user confirms the starting point, run continuously and report progress between tickets.
 
-**Initial request:** $ARGUMENTS
+**Initial request:** the text that follows the `$pincer-code` mention in the user's message (ask for it if there is none)
 
 Ticket state lives in the ticket file's frontmatter and is written **only** by
 `scripts/pincer-ticket.sh` (`start` → `verify` → `done`). `verify` runs the ticket's
@@ -67,4 +71,4 @@ from wherever the receipt says you are. Confirm the starting point with the user
 ## When all tickets are done
 
 Update the PRD to `status: built`, then finish with:
-"All tickets built. Run `/pincer-evaluate` for a final quality pass."
+"All tickets built. Run `$pincer-evaluate` for a final quality pass."

package/template/{.codex/prompts/pincer-evaluate.md → .agents/skills/pincer-evaluate/SKILL.md}

@@ -1,7 +1,11 @@
+---
+name: pincer-evaluate
+description: "Final quality pass over everything built — high-confidence findings only"
+---
 <!-- Generated from .claude/commands/pincer-evaluate.md by scripts/sync-prompts.sh — edit the source, not this file -->
 
 
-# /pincer-evaluate — Final Quality Pass
+# $pincer-evaluate — Final Quality Pass
 
 You are reviewing all work built this session against the PRD and tickets. Autonomous —
 run the pipeline, then present results.
@@ -10,7 +14,7 @@ run the pipeline, then present results.
 
 1. Run `scripts/pincer-status.sh`. Every ticket should be `done` with a receipt; if one
    is still open or in progress, stop and ask whether it was cut (then it goes in the
-   PRD's Out of Scope) or should be finished first via `/pincer-code`. Then get the full
+   PRD's Out of Scope) or should be finished first via `$pincer-code`. Then get the full
    diff of the session: `git log --oneline` and `git diff <first-commit>..HEAD`.
 2. Dispatch a `code-quality-reviewer` agent with: the diff, the PRD's Success Criteria and
    Scope sections, and the list of tickets. If the diff is large, split by area and
@@ -44,5 +48,5 @@ run the pipeline, then present results.
    its place, and what breaks first as the code ages (the riskiest assumption, the
    least-tested path). Commit it. This is the first document a reviewer of this repo
    should read.
-10. Suggest `/pincer-release` as the final step: "Run `/pincer-release` for a pass/fail audit of the
+10. Suggest `$pincer-release` as the final step: "Run `$pincer-release` for a pass/fail audit of the
    whole workflow's artifacts."

package/template/{.codex/prompts/pincer-narrow.md → .agents/skills/pincer-narrow/SKILL.md}

@@ -1,19 +1,23 @@
+---
+name: pincer-narrow
+description: "Turn the approved PRD into local, AI-ready ticket files"
+---
 <!-- Generated from .claude/commands/pincer-narrow.md by scripts/sync-prompts.sh — edit the source, not this file -->
 
 
-# /pincer-narrow — PRD to Local Tickets
+# $pincer-narrow — PRD to Local Tickets
 
 You are decomposing the PRD into small, independently verifiable tickets stored as local
 markdown files (no external tracker needed). Target: 4–7 tickets that fit a ~75-minute
 build window.
 
-**Initial request:** $ARGUMENTS
+**Initial request:** the text that follows the `$pincer-narrow` mention in the user's message (ask for it if there is none)
 
 ## Steps
 
 1. Run `scripts/pincer-status.sh`. If tickets already exist, ask before adding to them —
    new tickets continue the numbering, existing ones are never renumbered. Then read the
-   PRD (`$ARGUMENTS` or the latest `.prd/prd-v*.md`). If its status isn't `draft`, ask
+   PRD (`the text that follows the `$pincer-narrow` mention in the user's message (ask for it if there is none)` or the latest `.prd/prd-v*.md`). If its status isn't `draft`, ask
    which PRD to use.
 2. Decompose into tickets. Rules:
    - Each ticket is one coherent unit: sized S or M, never L. Split anything larger.
@@ -46,4 +50,4 @@ build window.
 
 5. After approval, update the PRD frontmatter to `status: ticketed`, commit the tickets
    (`git add .prd tickets && git commit`), and finish with:
-   "Tickets ready in `tickets/`. Run `/pincer-code` to start implementing."
+   "Tickets ready in `tickets/`. Run `$pincer-code` to start implementing."

package/template/{.codex/prompts/pincer-plan.md → .agents/skills/pincer-plan/SKILL.md}

@@ -1,21 +1,25 @@
+---
+name: pincer-plan
+description: "Create a PRD through brief discovery, codebase scan, and an architecture gate"
+---
 <!-- Generated from .claude/commands/pincer-plan.md by scripts/sync-prompts.sh — edit the source, not this file -->
 
 
-# /pincer-plan — PRD Creation
+# $pincer-plan — PRD Creation
 
 You are turning a task brief into a compact PRD. This runs inside a short delivery
 timebox (~2 hours total), so discovery is brief and the PRD is lean. The PRD feeds
-`/pincer-narrow` next.
+`$pincer-narrow` next.
 
-**Initial request:** $ARGUMENTS
+**Initial request:** the text that follows the `$pincer-plan` mention in the user's message (ask for it if there is none)
 
 First run `scripts/pincer-status.sh`. If a PRD already exists, say so and ask whether
 this is a new version of it (`.prd/prd-v{N+1}.md` — old versions are never overwritten)
-or a fresh start; if tickets are in progress, stop and point at `/pincer-code` instead.
+or a fresh start; if tickets are in progress, stop and point at `$pincer-code` instead.
 
 ## Phase 1: Discovery (~5 min)
 
-1. If `$ARGUMENTS` contains the brief, extract what you can before asking anything.
+1. If `the text that follows the `$pincer-plan` mention in the user's message (ask for it if there is none)` contains the brief, extract what you can before asking anything.
    Never ask a question the brief already answers.
 2. Ask only the questions whose answers would change the architecture or scope.
    Batch them (max 3–4 at once). Typical ones:
@@ -74,4 +78,4 @@ Propose the architecture: components, data flow, integration points, and key dec
 4. If `.git/` doesn't exist, run `git init` and make an initial commit containing the
    PRD and this `.claude/` setup — planning should be visible in the history.
 
-Finish with: "PRD saved to `.prd/prd-v1.md`. Run `/pincer-narrow` to break it into work items."
+Finish with: "PRD saved to `.prd/prd-v1.md`. Run `$pincer-narrow` to break it into work items."

package/template/{.codex/prompts/pincer-release.md → .agents/skills/pincer-release/SKILL.md}

@@ -1,18 +1,22 @@
+---
+name: pincer-release
+description: "Audit the repo against the workflow checklist — pass/fail per item, no fixes"
+---
 <!-- Generated from .claude/commands/pincer-release.md by scripts/sync-prompts.sh — edit the source, not this file -->
 
 
-# /pincer-release — Workflow Audit
+# $pincer-release — Workflow Audit
 
 You are auditing the current repo state against `docs/dry-run-checklist.md`. Read-only:
 report pass/fail, never fix anything — fixes belong to the stage commands.
 
-**Requested stage:** $ARGUMENTS
+**Requested stage:** the text that follows the `$pincer-release` mention in the user's message (ask for it if there is none)
 
 ## Steps
 
 1. Read `docs/dry-run-checklist.md` — it is the source of truth for what to check.
 2. Run `scripts/pincer-status.sh` to determine which stages have run (it reads `.prd/`,
-   `tickets/`, `NOTES.md`; add `git log`). If `$ARGUMENTS` names a stage, check only up
+   `tickets/`, `NOTES.md`; add `git log`). If `the text that follows the `$pincer-release` mention in the user's message (ask for it if there is none)` names a stage, check only up
    to that stage.
 3. Check every applicable item mechanically where possible:
    - File existence and frontmatter: read the files.

package/template/{.codex/prompts/pincer-status.md → .agents/skills/pincer-status/SKILL.md}

@@ -1,7 +1,11 @@
+---
+name: pincer-status
+description: "Where the workflow stands — PRD, tickets, receipts, elapsed time, next action"
+---
 <!-- Generated from .claude/commands/pincer-status.md by scripts/sync-prompts.sh — edit the source, not this file -->
 
 
-# /pincer-status — Where are we?
+# $pincer-status — Where are we?
 
 You are orienting in a repo that uses PINCER, typically after a context reset or at the
 start of a session. Read-only: change nothing.
@@ -15,5 +19,5 @@ start of a session. Read-only: change nothing.
 2. Report in three lines: where the workflow is, what is in progress or blocked, and the
    next command. Quote the `Next` line as-is.
 3. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
-   `/pincer-code T-{NN}`. If the script printed a warning, surface it — a done ticket
+   `$pincer-code T-{NN}`. If the script printed a warning, surface it — a done ticket
    without a receipt was marked by hand and needs `scripts/pincer-ticket.sh verify T-{NN}`.

package/template/.codex/README.md

@@ -1,17 +1,26 @@
 # PINCER on Codex CLI
 
 Codex reads `AGENTS.md` at the repo root natively — the project rules apply
-with no setup. The workflow commands need one install step, because Codex
-loads custom prompts from your home directory, not the repo:
+with no setup. The workflow commands ship as **skills** in `.agents/skills/`,
+which Codex discovers from the repo on its own (Codex removed custom prompts
+and `~/.codex/prompts/` in early 2026 — openai/codex#16115 — so there is
+nothing to copy into your home directory).
 
-```bash
-cp .codex/prompts/*.md ~/.codex/prompts/
+Skills are invoked by mention: type `$` and pick from the list, or write the
+name directly:
+
+```
+$pincer-plan <brief>
+$pincer-narrow   →   $pincer-code   →   $pincer-evaluate   →   $pincer-release
+$pincer-status
 ```
 
-Then `/pincer-plan`, `/pincer-narrow`, `/pincer-code`, `/pincer-evaluate`,
-and `/pincer-release` are available in any Codex session. These files are
-generated from `.claude/commands/` by `scripts/sync-prompts.sh` — edit the
-source playbooks, not these copies, and re-copy after a re-sync.
+`/skills` lists what Codex has loaded — the six `pincer-*` entries should be
+there whenever you start `codex` inside this repo. The skills are generated
+from `.claude/commands/` by `scripts/sync-prompts.sh` (cross-references are
+rewritten from `/pincer-*` to `$pincer-*`, and the argument placeholder becomes
+"the text after the mention") — edit the source playbooks, re-run the script,
+commit the result.
 
 ## Recommended posture (`~/.codex/config.toml`)
 
@@ -26,10 +35,10 @@ sandbox_mode   = "workspace-write" # writes confined to the repo; no network by
 The ticket scripts are plain bash and work here unchanged:
 `scripts/pincer-ticket.sh start|verify|done T-NN` and `scripts/pincer-status.sh`.
 What Codex lacks is the hook that stops an agent hand-editing ticket state, so the
-rule in `AGENTS.md` carries that weight; `/pincer-status` warns about any ticket
+rule in `AGENTS.md` carries that weight; `$pincer-status` warns about any ticket
 marked done without a receipt.
 
 Never run with approvals disabled. The destructive-command rule in `AGENTS.md`
 (no force-pushes, absolute-path deletes, or `curl | sh` by an agent) applies as
-a standing instruction here; `/pincer-release` audits the git artifacts
+a standing instruction here; `$pincer-release` audits the git artifacts
 afterwards, which is platform-independent by design.

package/template/AGENTS.md

@@ -22,7 +22,7 @@ the next command — run it first in any new session. Do not write feature code
 a PRD exists and tickets are approved.
 
 The commands live as playbooks in `.claude/commands/` (canonical), with
-generated adapters in `.codex/prompts/` and `.github/prompts/`. If your
+generated adapters in `.agents/skills/` (Codex) and `.github/prompts/` (Copilot). If your
 platform has no slash commands, read the playbook file and follow it directly.
 
 ## Conventions

package/template/docs/dry-run-checklist.md

@@ -72,7 +72,7 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
 - [ ] Brownfield only: untested load-bearing code got a characterization test
       before being modified
 - [ ] Platform adapters in sync: `scripts/sync-prompts.sh` then `git status`
-      shows no changes in `.codex/prompts/` or `.github/prompts/`
+      shows no changes in `.agents/skills/` or `.github/prompts/`
 - [ ] `scripts/pincer-status.sh` says `Next /pincer-release` and its build elapsed
       figure fit the ~75-minute build budget (note where time went if not)
 - [ ] Total wall-clock time fit the ~2-hour budget

package/template/scripts/sync-prompts.sh

@@ -3,14 +3,16 @@
 # PINCER playbooks in .claude/commands/. The playbooks are the single source
 # of truth: edit them, re-run this script, commit the result.
 #
-#   .codex/prompts/pincer-*.md          — Codex CLI custom prompts
-#                                         (install: cp .codex/prompts/*.md ~/.codex/prompts/)
+#   .agents/skills/pincer-*/SKILL.md    — Codex CLI skills (repo-local; Codex
+#                                         removed custom prompts in 0.9x, see
+#                                         openai/codex#16115). Invoke by typing
+#                                         $pincer-plan <brief> in a Codex session.
 #   .github/prompts/pincer-*.prompt.md  — VS Code Copilot prompt files
 #                                         (enable: "chat.promptFiles": true)
 set -euo pipefail
 cd "$(dirname "$0")/.."
 
-mkdir -p .codex/prompts .github/prompts
+mkdir -p .agents/skills .github/prompts
 
 count=0
 for src in .claude/commands/pincer-*.md; do
@@ -18,11 +20,18 @@ for src in .claude/commands/pincer-*.md; do
   desc=$(sed -n 's/^description: *"\{0,1\}\([^"]*\)"\{0,1\}$/\1/p' "$src" | head -1)
   body=$(awk 'flag; /^---$/ { if (++c == 2) flag = 1 }' "$src")
 
-  # Codex: plain markdown prompt; $ARGUMENTS is supported natively.
+  # Codex: one skill directory per playbook. Skills have no $ARGUMENTS
+  # substitution and are invoked as $name mentions, so the argument placeholder
+  # becomes prose and cross-references to /pincer-* become $pincer-* (the
+  # leading-context guard keeps paths like scripts/pincer-status.sh intact).
+  mkdir -p ".agents/skills/$name"
   {
+    printf -- '---\nname: %s\ndescription: "%s"\n---\n' "$name" "$desc"
     printf '<!-- Generated from %s by scripts/sync-prompts.sh — edit the source, not this file -->\n\n' "$src"
-    printf '%s\n' "$body"
-  } > ".codex/prompts/$name.md"
+    printf '%s\n' "$body" \
+      | sed "s/\$ARGUMENTS/the text that follows the \`\$$name\` mention in the user's message (ask for it if there is none)/g" \
+      | sed -e 's#^/pincer-\([a-z]*\)#$pincer-\1#' -e 's#\([^A-Za-z0-9_./]\)/pincer-\([a-z]*\)#\1$pincer-\2#g'
+  } > ".agents/skills/$name/SKILL.md"
 
   # Copilot: prompt-file frontmatter; $ARGUMENTS becomes an input variable.
   {
@@ -34,4 +43,4 @@ for src in .claude/commands/pincer-*.md; do
   count=$((count + 1))
 done
 
-echo "Synced $count playbooks -> .codex/prompts/ and .github/prompts/"
+echo "Synced $count playbooks -> .agents/skills/ and .github/prompts/"