pincer-workflow 0.2.0 → 0.2.1

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,47 @@ 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 same commands carry the `/prompts:` prefix Codex gives every
+custom prompt: `/prompts:pincer-plan <brief>` → `/prompts:pincer-narrow` →
+`/prompts:pincer-code` → `/prompts:pincer-evaluate` → `/prompts:pincer-release`,
+and `/prompts: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
+
+`AGENTS.md` loads natively, so the rules apply with no setup. Codex reads
+custom prompts only from `~/.codex/prompts/` (there is no repo-local location)
+and does not create that directory itself, so install the prompts once:
+
+```bash
+mkdir -p ~/.codex/prompts && cp .codex/prompts/*.md ~/.codex/prompts/
+codex
+```
+
+Then `/prompts:pincer-plan <brief>` and the rest of the chain are available in
+every Codex session. The playbooks refer to each other by their short names
+(`/pincer-narrow` etc.) — read those as `/prompts:pincer-narrow` in Codex.
+Re-run the copy after `npx pincer-workflow@latest update` or after editing a
+playbook; `update` prints the reminder.
+
+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
+`/prompts: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 +94,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.1 corrects the Codex install step: `~/.codex/prompts/` must be created first, and the commands are invoked as `/prompts:pincer-*`.) 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 +109,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 |
+| `.codex/` · `.github/` | Generated Codex and Copilot adapters + platform wiring (`.codex/README.md` covers the Codex install and 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

@@ -123,13 +123,18 @@ function report({ written, skipped, conflicted }) {
   }
 }
 
+// Codex loads custom prompts from ~/.codex/prompts/ only and never creates that
+// directory itself — a bare `cp` there fails with "Not a directory" on a fresh machine.
+const CODEX_INSTALL = 'mkdir -p ~/.codex/prompts && cp .codex/prompts/*.md ~/.codex/prompts/';
+
 function nextSteps(platforms) {
   console.log('\nNext steps:');
   if (platforms.includes('claude')) {
     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     ${CODEX_INSTALL}`);
+    console.log('                (once; Codex has no repo-local prompts) then `codex` and /prompts:pincer-plan <brief> — 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');
@@ -181,7 +186,7 @@ async function cmdUpdate() {
   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/');
+    console.log(`\n  Codex uses global prompts — re-run: ${CODEX_INSTALL}`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pincer-workflow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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/README.md

@@ -5,11 +5,20 @@ with no setup. The workflow commands need one install step, because Codex
 loads custom prompts from your home directory, not the repo:
 
 ```bash
-cp .codex/prompts/*.md ~/.codex/prompts/
+mkdir -p ~/.codex/prompts && cp .codex/prompts/*.md ~/.codex/prompts/
 ```
 
-Then `/pincer-plan`, `/pincer-narrow`, `/pincer-code`, `/pincer-evaluate`,
-and `/pincer-release` are available in any Codex session. These files are
+(`mkdir -p` matters: Codex does not create `~/.codex/prompts/` on its own, and
+`cp` into a missing directory fails with "Not a directory".) Codex exposes custom
+prompts under a `/prompts:` prefix, so the commands are `/prompts:pincer-plan`,
+`/prompts:pincer-narrow`, `/prompts:pincer-code`, `/prompts:pincer-evaluate`,
+`/prompts:pincer-release` and `/prompts:pincer-status` in any Codex session.
+The playbooks refer to each other by their short names (`/pincer-narrow` etc.);
+read those as `/prompts:pincer-narrow` here.
+
+The copy is not tracked by `pincer update`: after `npx pincer-workflow@latest update`
+(or after editing a playbook and re-running `scripts/sync-prompts.sh`), run the
+`mkdir -p … && cp …` line again so `~/.codex/prompts/` matches the repo. 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.
 

package/template/scripts/sync-prompts.sh

@@ -4,7 +4,8 @@
 # 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/)
+#                                         (install: mkdir -p ~/.codex/prompts && cp .codex/prompts/*.md ~/.codex/prompts/;
+#                                          invoked as /prompts:pincer-*)
 #   .github/prompts/pincer-*.prompt.md  — VS Code Copilot prompt files
 #                                         (enable: "chat.promptFiles": true)
 set -euo pipefail