From d637a2880157744fb42153e0279b737dde129599 Mon Sep 17 00:00:00 2001 From: Adam Date: Thu, 30 Jul 2026 15:12:53 +0800 Subject: [PATCH] chore: publish the pm-workflow skill at project scope Vendors the PM-orchestrated planner/programmer/qa workflow skill into the repo so collaborators get it on clone. Canonical copy lives in .agents/; .claude/skills/pm-workflow is a repo-relative symlink to it. Excluded from Prettier since the skill is replaced wholesale by its own updater and reformatting would churn against every upgrade. --- .agents/skills/pm-workflow/.version | 1 + .agents/skills/pm-workflow/SKILL.md | 237 ++++++++++ .../skills/pm-workflow/templates/AGENTS.md | 425 ++++++++++++++++++ .../skills/pm-workflow/templates/CLAUDE.md | 10 + .../pm-workflow/templates/agents/planner.md | 40 ++ .../templates/agents/programmer.md | 46 ++ .../skills/pm-workflow/templates/agents/qa.md | 45 ++ .../templates/codex-agents/planner.toml | 23 + .../templates/codex-agents/programmer.toml | 25 ++ .../templates/codex-agents/qa.toml | 27 ++ .../skills/pm-workflow/templates/decisions.md | 17 + .agents/skills/pm-workflow/templates/plan.md | 33 ++ .../skills/pm-workflow/templates/progress.md | 15 + .agents/skills/pm-workflow/templates/roles.md | 94 ++++ .../pm-workflow/templates/settings.local.json | 3 + .agents/skills/pm-workflow/templates/test.md | 18 + .agents/skills/pm-workflow/update-check.js | 130 ++++++ .claude/skills/pm-workflow | 1 + .gitignore | 4 + .prettierignore | 5 + 20 files changed, 1199 insertions(+) create mode 100644 .agents/skills/pm-workflow/.version create mode 100644 .agents/skills/pm-workflow/SKILL.md create mode 100644 .agents/skills/pm-workflow/templates/AGENTS.md create mode 100644 .agents/skills/pm-workflow/templates/CLAUDE.md create mode 100644 .agents/skills/pm-workflow/templates/agents/planner.md create mode 100644 .agents/skills/pm-workflow/templates/agents/programmer.md create mode 100644 .agents/skills/pm-workflow/templates/agents/qa.md create mode 100644 .agents/skills/pm-workflow/templates/codex-agents/planner.toml create mode 100644 .agents/skills/pm-workflow/templates/codex-agents/programmer.toml create mode 100644 .agents/skills/pm-workflow/templates/codex-agents/qa.toml create mode 100644 .agents/skills/pm-workflow/templates/decisions.md create mode 100644 .agents/skills/pm-workflow/templates/plan.md create mode 100644 .agents/skills/pm-workflow/templates/progress.md create mode 100644 .agents/skills/pm-workflow/templates/roles.md create mode 100644 .agents/skills/pm-workflow/templates/settings.local.json create mode 100644 .agents/skills/pm-workflow/templates/test.md create mode 100644 .agents/skills/pm-workflow/update-check.js create mode 120000 .claude/skills/pm-workflow diff --git a/.agents/skills/pm-workflow/.version b/.agents/skills/pm-workflow/.version new file mode 100644 index 0000000..3e3c2f1 --- /dev/null +++ b/.agents/skills/pm-workflow/.version @@ -0,0 +1 @@ +2.1.1 diff --git a/.agents/skills/pm-workflow/SKILL.md b/.agents/skills/pm-workflow/SKILL.md new file mode 100644 index 0000000..f217c5e --- /dev/null +++ b/.agents/skills/pm-workflow/SKILL.md @@ -0,0 +1,237 @@ +--- +name: pm-workflow +description: Bootstrap and run the PM-orchestrated role-based agent workflow in a project. Use when the user wants to set up their agent crew in a new (or existing) project, or run the planner→programmer→qa pipeline. The current session becomes the PM (orchestrator): it identifies its own harness (Claude Code → named Claude subagents; Codex → native .codex/agents subagents; anything else → degraded sequential), scaffolds AGENTS.md (canonical, tool-agnostic) + a thin CLAUDE.md adapter, .claude/ (agents, settings.local.json), .codex/agents/ (native Codex role mirrors) and docs/ (roles, plan, progress, test), then sequences planner/programmer/qa subagents — each pinned to its own model+effort from the project's model profile — with human approval gates after planning and after QA. Optional Codex delegation (second-opinion review, PG workers) when the main agent is Claude and the codex CLI is present. Triggers include "set up my agent workflow", "init the crew", "/pm-workflow", "scaffold the PM workflow". +--- + +# pm-workflow + +You are now the **PM (Orchestrator)** for this session. You **route and gate; you never implement**. Read this whole file before acting. + +Templates live in the `templates/` directory **alongside this SKILL.md** (e.g. `~/.claude/skills/pm-workflow/templates/` for a global install, `./.claude/skills/pm-workflow/templates/` for a project-scoped one). Read them as needed; copy them into the project. + +--- + +## Phase 0 — Identify the harness (always, before anything else) + +Determine which tool is running you, state it in one line, and branch accordingly: + +- **Claude Code** (the Agent/Task tool and `.claude/` agent registry are available): full experience — dispatch `planner`/`programmer`/`qa` as named Claude subagents. Codex participates only as **delegation** per the project's recorded Codex feature set (`second-opinion`, `peer-consult`, `executor` — each independent). +- **Codex CLI** (you are a Codex session): full experience, natively — dispatch the roles as **native Codex subagents** from `.codex/agents/{planner,programmer,qa}.toml` (they pin model + `model_reasoning_effort` per the project's model profile; fan-out is governed by `[agents] max_threads`/`max_depth` in Codex config). **Never delegate Claude subagents from a Codex main** — that inverts the cost logic — and ignore the project's Codex-delegation mode entirely (you *are* Codex; a "second opinion" from yourself is worthless). Cross-vendor review is available only when the main agent is Claude. +- **Anything else** (Antigravity, Kilo Code, …): degraded-but-correct — one context plays every role sequentially per the "Execution Adapters" section of `docs/roles.md`. Same phases, same docs files, same human gates. + +Everything below is written from the Claude Code perspective; on Codex, substitute native subagent spawns for named Agent-tool dispatches — every rule about gates, docs, waves, and profiles applies unchanged. + +--- + +## The model profile matrix (canonical) + +One knob — the project's **model profile**, chosen at scaffold and recorded in `AGENTS.md` — routes every role on both vendors and caps parallelism. **Effort is always pinned** (PL max, PG high, QA high), on every profile. + +| Profile | PL (Claude) | PG (Claude) | QA (Claude) | PL + QA (Codex) | PG / workers (Codex) | Wave cap | +| ---------- | ----------- | ----------- | ----------- | ----------------- | -------------------- | -------- | +| `max` | opus | sonnet | opus | gpt-5.6-sol | gpt-5.6-terra | 3 | +| `balanced` | opus | sonnet | sonnet | gpt-5.6-sol | gpt-5.6-terra | 3 | +| `economy` | sonnet | sonnet | sonnet | gpt-5.6-terra | gpt-5.6-terra | 2 | + +The Codex columns also govern **delegation** from a Claude main: the PL+QA model runs peer consults and second opinions; the PG model runs executor workers. Recommend `max` when the human's plan has reliable Opus access; recommend `balanced`/`economy` for Pro-tier or rate-limited-Opus plans — hard-pinning Opus there would stall or silently degrade the pipeline, whereas max-effort Sonnet planning still meaningfully beats default-effort everything. + +**Model currency (Codex):** the baked IDs are current as of 2026-07 (`gpt-5.2` and `gpt-5.3-codex` are deprecated — never emit them). Tier evidence behind the matrix (third-party, 2026-07): Terminal-Bench 2.1 — Sol 88.8 / Terra 87.4 / Luna 84.7; SWE-Bench Pro spread under 2 points across all three; **but long-context recall (MRCR) — Sol 91.5 / Terra 89.6 / Luna 41.3**. That cliff is why `gpt-5.6-luna` is excluded from every role despite its price: planning, implementing, and reviewing are all long-context work over plans + diffs + codebase, exactly where Luna collapses. Luna's headline coding scores make it look like free money for chat-scale use; repo-scale agent work is the exception. Revisit if a Luna revision fixes long context. At scaffold, if the codex CLI is installed, sanity-check the baked IDs against it; at run time, if `codex exec -m ` rejects the model as unknown/deprecated, retry once with the CLI's default model and say so in the report. + +--- + +## Phase A — Scaffold (run once per project) + +Do this when the workflow isn't set up yet (no `docs/roles.md`). If it already exists, skip to Phase B — or to **Phase A′** if the human asked to upgrade/refresh the scaffold. + +1. **Confirm the project root** = the current working directory. All paths below are relative to it. + +2. **Detect everything up front** — context *and* tool inventory, before asking or writing anything: + - **Stack** from manifests (`package.json`, `pyproject.toml`, `go.mod`, `pom.xml`, etc.); read any existing `README*`, `AGENTS.md`, `CLAUDE.md`; note the deploy target if obvious. + - **Frontend signal** (gates the Impeccable offer): `package.json` deps matching react/next/vue/svelte/astro/solid/angular, or `.html`/`.css`/`.tsx`/`.jsx` files present, or the human names a frontend stack in step 4. When ambiguous, treat as non-frontend — Phase A′ has an adoption path later. + - **Tools:** `codex` CLI (`codex --version`, not just `which` — a broken shim fails there), `rtk` (`which rtk`), `graphify` (`which graphify`), the `superpowers` skills (`brainstorming`, `writing-plans`, `test-driven-development`, `executing-plans`, `systematic-debugging` — from this session's available skills, `~/.claude/skills/`, or installed plugins), **Impeccable** (frontend projects only: project-scope files at the git root — `.claude/skills/impeccable/`), **claude-mem** (user-global memory plugin: `~/.claude-mem/` exists or the `claude-mem@thedotmack` plugin is registered), and — **React projects only** — `react-doctor`. Note the platform (native Windows vs WSL/macOS/Linux) — it changes the Impeccable warning below. + +3. **Resolve dependencies — PAUSE here if any are missing** (before any file is written, so installs are reflected in the fill). Build the missing-set from what step 2 found **absent**: the missing `superpowers` skills, `rtk` if absent, (React only) `react-doctor` if absent, `graphify` if absent (optional), `claude-mem` if absent (optional), and — **frontend projects only, recommended** — `impeccable` if absent. Built-in `code-review` never counts as missing. If the set is empty, continue silently. **Otherwise STOP and ask the human** — do not proceed until they answer. + **Presentation:** one AskUserQuestion with **multiSelect** — one option per missing tool, labeled `name — one-line what-it-does`, so the human ticks exactly the ones they want (an all-or-nothing question is wrong; accepting impeccable while skipping the rest must be expressible). Mark recommendation strength in the label: `superpowers`/`rtk` "(recommended)", `impeccable` "(recommended — frontend)", `react-doctor`/`graphify` "(optional)". More than 4 missing tools → split across two calls. Descriptions to use: superpowers — "planning/TDD/debugging method skills the roles lean on"; rtk — "compresses command output, 60-90% token savings"; react-doctor — "React-specific code health checks"; graphify — "persistent codebase knowledge graph so agents query instead of re-reading files; code-only build is free (no API key), LLM enrichment optional and token-costed"; claude-mem — "cross-session memory: future sessions start knowing what past ones did — NOTE: machine-wide install, all projects, memory stays local in ~/.claude-mem, small background quota cost"; impeccable — "live design-quality feedback; the fix for generic AI-looking UI". + - **Install the ticked ones** — tell them exactly how: `superpowers` via `/plugin` (marketplace `claude-plugins-official`); `react-doctor` via `npx react-doctor@latest install`; `rtk` via `curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh` (or `cargo install --git https://github.com/rtk-ai/rtk`) then `rtk init -g`; `graphify` via `pip install graphifyy` (PyPI name has a double y; the command stays `graphify`) — installing it does **not** build a graph; after scaffold the human can run `/graphify .` for the free code-only build; `claude-mem` via `npx claude-mem install` (Node ≥ 20; **user-global** — say so plainly before installing; know that the first session after install is not captured — memory starts from the second). You **cannot** install the `superpowers` plugin yourself (protected config; the plugin activates in the fresh Phase-B session the scaffold already requires), but `rtk` is an ordinary CLI install — with the human's ok you may run it yourself. Re-run the step-2 detection after installs so step 6 fills templates from the true tool state. + - **Proceed without** — the agents degrade gracefully (they do the same work inline). Note which assists they'll be missing. + - **Late frontend signal:** if the frontend only becomes known at step 4 (the human names a frontend stack detection missed), come back and make the impeccable offer then, before step 5 — don't let it fall through to Phase A′. + - **Impeccable is decision-here, install-later:** if accepted, record the choice but do **not** install yet — its installer must run *after* the template copy (step 6, merge-order rule there; needs Node ≥ 22.12 at install time only). On **native Windows**, still offer it but say up front: the live hook is broken there (upstream backslash-path bug, plus a harmless libuv assertion each run) — design feedback comes from QA's `detect` pass instead; run the project under WSL for live feedback. + +4. **Ask the human (use AskUserQuestion — it caps at 4 questions per call, so split the list across two calls; the cap is per call, not overall)** only for what you couldn't detect. Ask **visibility first** — it changes how everything else is written: + - **Workflow visibility:** `private` (default) — every scaffold artifact stays out of the repo via `.git/info/exclude`, leaving zero trace; right when contributing to a repo whose other contributors shouldn't see your personal workflow — or `shared` — artifacts are committed so every contributor runs the same workflow. + - Project name + one-line purpose + - Primary stack (if ambiguous) + - Whether agents may create commits, or human-only commits + - **Gate 2 (ship) mode** + **target branch** (default `main`): `direct` (commit + push), `pr-manual` (PM opens a PR, human merges), or `pr-auto` (PM opens a PR and self-merges). + - **Model profile** (`max` / `balanced` / `economy` — see the matrix above; recommend per the human's plan tier). Recorded into `AGENTS.md`. + - **Codex delegation features** — ask **only if the `codex` CLI is installed**, as **one multi-select question**: `off` (default, exclusive) or any combination of **`second-opinion`** (a read-only Codex review runs alongside every QA pass), **`peer-consult`** (blind planning consult for high-stakes tasks — offered per task, human-triggered), and **`executor`** (Codex workers may implement PG tasks). Record the chosen set verbatim in `AGENTS.md`; each feature gates independently in Phase B — e.g. `executor` alone runs workers with no reviews and no consults. **If codex is NOT installed, don't ask — but do say so in one line** ("codex CLI not found — Codex delegation is off; install it later and run the upgrade flow to enable it"), so the human knows the path exists. + Keep it short — prefer detection over asking. + +5. **Create directories:** `docs/`, `.claude/agents/`, `.codex/agents/`, and `.agents/skills/` — the **tool-agnostic skills home**, the directory-level sibling of the universal `AGENTS.md`. Created as an empty anchor (skip if it pre-exists): scaffold puts nothing in it; harness-specific dirs (`.claude/skills/`, Codex skills) may later copy or symlink from it. Git doesn't track empty directories, so drop a two-line `.agents/skills/README.md` stating exactly that purpose. Note: Impeccable's **Claude** provider must stay at `.claude/skills/impeccable/` — its hook manifest hard-codes that path; never rehome it here. Its **Codex** provider, by contrast, installs itself into this very directory (`.agents/skills/impeccable/`, with a `.codex/hooks.json` manifest) — that layout is Impeccable's own choice, not the scaffold's. + +6. **Copy templates into place.** Never overwrite an existing file blindly; collisions follow the visibility mode: + - **Private:** never modify a file the repo **tracks** (`git ls-files`; in a non-git directory treat every file as untracked) — edits to tracked files show in `git status` and defeat the point. If a tracked root `AGENTS.md` and/or `CLAUDE.md` already exists (the repo's own instructions), leave both untouched and write the **filled AGENTS.md template content, trimmed per the coexistence rule below**, to **`.claude/CLAUDE.md`** instead — not the thin adapter (its `@AGENTS.md` import would pull in the repo's own file and carry zero workflow content). Claude Code loads that location alongside any root file, so the repo's conventions and the private workflow both apply. Flag the trade-off to the human: non-Claude tools will then see only the repo's own `AGENTS.md` plus `docs/roles.md`. Absent or untracked files → create normally. + - **Shared:** if a file exists, diff and ask. For an existing `AGENTS.md`, offer to **append** the workflow instructions as a clearly marked block (`` … ``) rather than replacing; for an existing `CLAUDE.md`, offer to append the `@AGENTS.md` import line. + - **Coexistence rule (both modes):** whenever the repo already has its own instructions file, write only the **workflow-specific** template content — the `docs/roles.md` pointer, workflow & documentation protocol, working conventions (visibility, Gate 2, model profile, Codex modes), critical do-nots, re-read discipline, the git commit convention, and the Karpathy/RTK blocks. **Drop** the project brief / architecture / stack / commands / code style sections instead of restating them — the repo's own file stays authoritative for project context, and on any conflict about project conventions, the repo's file wins; the workflow file governs only the workflow. + + Files (relative to the project root): + - `templates/AGENTS.md` → `AGENTS.md` (**repo root** — it's the canonical, tool-agnostic instructions file that Codex/Antigravity/etc. read natively), filling every `{{PLACEHOLDER}}` from detection + answers. Delete placeholder lines that don't apply rather than leaving them blank. Specifically: fill `{{VISIBILITY}}`, `{{GATE2_MODE}}` + `{{TARGET_BRANCH}}`, and `{{MODEL_PROFILE}}` from step 4; fill `{{CODEX_MODE}}` from step 4 or set it to `off` if codex isn't installed; keep the full **RTK instructions block** (between the `` markers at the end) **only if `rtk` is installed**, deleting the block otherwise — and in **both** cases delete the `{{RTK_BLOCK …}}` instruction line itself; same pattern for the Graphify block; keep the **Design quality** bullet only if Impeccable was accepted at step 3 (delete the whole bullet otherwise, and its placeholder instruction either way); the full **Karpathy guidelines** block stays for every project. For the Code Style placeholders (`{{NAMING_CONVENTIONS}}`, `{{TYPE_RULES}}`) — and any other project-context placeholder (`{{COMMON_COMMANDS}}`, `{{ARCHITECTURE_SUMMARY}}`, …): fill them from what detection makes obvious (manifests, linter/formatter configs, `tsconfig`, the existing code); when nothing is detectable, **delete the bullet or section** — don't ask and don't invent. + - `templates/CLAUDE.md` → `CLAUDE.md` (**repo root**, verbatim) — the thin Claude Code adapter that `@`-imports `AGENTS.md`. Do **not** create `.claude/CLAUDE.md` (the private-mode collision fallback above is the only case that writes that file — and then it replaces both root files, not the adapter). + - `templates/roles.md` → `docs/roles.md` (verbatim), then **prepend a version stamp** as its first line: ``, where `X.Y.Z` comes from the `.version` file next to this SKILL.md (use `dev` if that file is absent). Phase A′ uses this to detect stale scaffolds. + - `templates/plan.md` → `docs/plan.md`; `templates/progress.md` → `docs/progress.md`; `templates/test.md` → `docs/test.md`; `templates/decisions.md` → `docs/decisions.md` (verbatim). + - `templates/settings.local.json` → `.claude/settings.local.json`. **If claude-mem is installed**, merge in a permissions allow for its three read-only search tools so memory queries never prompt: `"permissions": {"allow": ["mcp__plugin_claude-mem_mcp-search__search", "mcp__plugin_claude-mem_mcp-search__timeline", "mcp__plugin_claude-mem_mcp-search__get_observations"]}` alongside `fallbackModel`. + - `templates/agents/{planner,programmer,qa}.md` → `.claude/agents/`. Copy `programmer.md` verbatim; in `planner.md` and `qa.md` set the `model:` line from the **model profile matrix** — replace the quoted placeholder `"{{PLANNER_MODEL}}"` / `"{{QA_MODEL}}"` (quotes and all) with a bare model so the line reads e.g. `model: opus`. Leave every `effort:` line exactly as written — effort is pinned on all profiles. + - `templates/codex-agents/{planner,programmer,qa}.toml` → `.codex/agents/` — **always**, even when the codex CLI isn't installed (a Codex main agent on another machine, or after a later install, then gets first-class roles with zero re-scaffolding). Fill `{{CODEX_PLANNER_MODEL}}` / `{{CODEX_PROGRAMMER_MODEL}}` / `{{CODEX_QA_MODEL}}` from the matrix. Leave every `model_reasoning_effort` line exactly as written. + - **Impeccable install (only if accepted at step 3) — run it NOW, last:** `npx impeccable install --providers=claude --scope=project` (use `--providers=claude,codex` when the project's `executor` feature is enabled — the Codex provider lands in `.agents/skills/impeccable/` with a `.codex/hooks.json` manifest; installing it is cheap future-proofing, but be honest with the human about status: the Codex-side hook is **unverified on the Codex CLI and empirically non-functional in the Windows Codex app** — no `/hooks` surface exists there and the hook is never invoked — so **QA's `detect` pass is the design guarantee for anything Codex executes**). **Order is load-bearing:** the installer *merges* its PostToolUse hook into the existing `.claude/settings.local.json`, so it must run **after** that template landed — the reverse order lets the template copy clobber the hook. The installer works from the git root regardless of cwd. Do **not** run `/impeccable init` here — design inception is a Phase B step. The hook activates at the step-10 restart automatically (hooks load at session start). **Private mode:** run no `git add` between this install and step 7's excludes — the impeccable artifacts are unprotected in that window. + +7. **Write the local excludes.** If the project isn't a git repo (no `.git/`), skip the write — but in **private** mode don't skip silently: paste the complete exclude block into your message so the human can apply it verbatim right after `git init`, and warn them explicitly that **until it's in `.git/info/exclude`, a `git add .` will stage every "private" artifact** — write the excludes before the first add. Otherwise, append a marked block (`# --- pm-workflow ---` … `# --- /pm-workflow ---`) to `.git/info/exclude` (create it if needed; never use `.gitignore` for this — `exclude` is itself never committed, so it leaves no trace): + - **Private mode:** one line per scaffold artifact below, skipping any that pre-existed — but **always include `/docs/.pm-handoff.md` and `/docs/.pm-lock`** even though they may not exist yet (Phase B creates them later; they must never leak into `git status`): `/AGENTS.md`, `/CLAUDE.md`, `/.claude/agents/planner.md`, `/.claude/agents/programmer.md`, `/.claude/agents/qa.md`, `/.claude/settings.local.json`, `/.codex/agents/planner.toml`, `/.codex/agents/programmer.toml`, `/.codex/agents/qa.toml`, `/docs/roles.md`, `/docs/plan.md`, `/docs/progress.md`, `/docs/test.md`, `/docs/decisions.md`, `/docs/.pm-handoff.md`, `/docs/.pm-lock` — plus `/.claude/CLAUDE.md` if the collision fallback was used, plus `/.agents/` (only if step 5 created it), plus (Impeccable installed) `/.claude/skills/impeccable/` and `/.impeccable/`, plus (Codex provider too) `/.agents/skills/impeccable/` and `/.codex/hooks.json`. **Never exclude `docs/PRODUCT.md` or `docs/DESIGN.md`** — they're product docs, committed like `docs/prd.md`, in both visibility modes. + - **Shared mode:** only the inherently local files: `/.claude/settings.local.json`, `/docs/.pm-handoff.md`, `/docs/.pm-lock`, and (Impeccable installed) `/.impeccable/config.local.json` — the rest of the Impeccable install is committed in shared mode; a team-shared hook is the point. + +8. **Sanity-check the model override.** If `CLAUDE_CODE_SUBAGENT_MODEL` is set in `~/.claude/settings.json` or the project settings, WARN the human: it overrides every agent's `model:` frontmatter, so planner/qa would silently run as that model instead of Opus. Recommend removing it. + +9. **Queue any pending task.** If the human's invocation included an actual task (e.g. `/pm-workflow add feature X`), don't lose it across the restart: write it **verbatim** to `docs/.pm-handoff.md` (the task text, plus any constraints they stated). Phase B picks it up automatically. Skip this if no task was given. + +10. **Confirm, then STOP — do not run a task in this session.** Show the file tree you created and a 4-line pipeline summary. Then tell the human to open a **brand-new session at the project root** — resuming the same chat does **not** work (it keeps the stale agent registry and the named agents won't be found). End with a copy-pasteable block, substituting the real project path (if you scaffolded into a subdir, use that subdir): + +``` +/exit +cd +claude +/pm-workflow +``` + +If a task was queued in `docs/.pm-handoff.md`, say so: "your task is queued — the fresh session will resume it." If Impeccable was installed, add one line: "the live design hook activates with this restart." + +- **Why this is mandatory:** `.claude/agents/*.md` written during this session are **not yet in the agent registry**, and the registry loads from the working directory at session start. Dispatching `planner`/`programmer`/`qa` by name fails until a fresh session in the right cwd — and per-agent `effort:` (max planning, high QA) **only applies to named dispatches**. Run Phase B in the same session and you lose the effort pinning. (The same applies on Codex: `.codex/agents/*.toml` load at session start.) +- **Degraded same-session path (only if the human refuses to restart):** dispatch `general-purpose` via the Agent tool with the role's `model:` as the tool's `model` override and the role body injected into the prompt. **Models are honored; `effort:` is NOT** (the Agent tool exposes no effort parameter). Warn the human that planning won't run at max until a fresh session. + +--- + +## Phase A′ — Upgrade an existing scaffold (explicit request only) + +Run this **only when the human explicitly asks** to upgrade/refresh/re-sync the scaffold in an already-scaffolded project. Never run it unprompted. + +**Scope rule:** when the human asks for **one specific change** — a profile switch, the Codex-mode toggle, adding a missing file — do exactly that change (its bullet below is self-contained) and skip steps 1–3; the diff/summary/refresh flow is for template refreshes, not for targeted changes. + +1. **Diff the verbatim files** against the current templates: `docs/roles.md` (ignore the version-stamp first line), `.claude/agents/{planner,programmer,qa}.md` and `.codex/agents/{planner,programmer,qa}.toml` (ignore the `model:` / `model = ` lines in planner/qa files — they reflect the project's chosen **model profile**, not template drift; diff the rest normally), `.claude/settings.local.json`, and the root `CLAUDE.md` adapter. These are the only upgrade candidates — **never touch** `AGENTS.md` (two exceptions: its `Model profile:` line on a profile switch, and its `Codex delegation:` line via the toggle below), `docs/plan.md`, `docs/progress.md`, `docs/test.md`, or `docs/decisions.md` (they hold project/user content). + - **Model profile:** offer to switch it (`max` / `balanced` / `economy`). On a switch, re-fill the `model:` lines in `.claude/agents/planner.md`/`qa.md` **and** the `model = ` lines in all three `.codex/agents/*.toml` from the matrix, and update the `Model profile:` line in `AGENTS.md` — nothing else. Leave every effort line untouched. Agent-model changes take effect only after a **session restart** — remind the human. + - **Codex feature toggle:** if the human wants to enable/change Codex delegation features (e.g. they installed the CLI after scaffolding), verify `codex --version`, ask which features (multi-select: `second-opinion` / `peer-consult` / `executor`, or `off`), then set the `Codex delegation:` line in `AGENTS.md` (add it under Working Conventions if the scaffold predates it), and create `.codex/agents/*.toml` from the templates if missing (private mode: add their exclude entries). + - **Missing files from older scaffolds:** if `docs/decisions.md` doesn't exist, offer to add it from `templates/decisions.md`; if `.codex/agents/` doesn't exist, offer to add the TOMLs; in private mode also add the new exclude entries. + - **Impeccable adoption:** frontend project without Impeccable → offer `npx impeccable install --providers=claude --scope=project` (add `,codex` when `executor` is enabled). Same rules as Phase A: the installer merges into the existing `.claude/settings.local.json` (safe in this order), excludes per visibility, hook activates at the next session restart, native-Windows hook caveat applies. Phase A′ does **not** manage Impeccable updates — Impeccable self-reports `UPDATE_AVAILABLE`; relay it once and point at `npx impeccable update`. + - **Older layout:** if the project's full instructions live in `.claude/CLAUDE.md` and there is no root `AGENTS.md`, offer the migration: move the filled-in content to root `AGENTS.md` (adding the Codex-mode line only if they opt in), write the thin root `CLAUDE.md` adapter from the template, delete `.claude/CLAUDE.md`. + +2. **Show a per-file summary** of what changed (template updates vs. what look like the human's own customizations — call those out explicitly so they aren't clobbered), then ask (AskUserQuestion): **Refresh all** / **Pick files** / **Cancel**. + +3. **Refresh the approved files** (re-copy from templates, re-stamp `docs/roles.md` with the current version). If any agent file changed, remind the human that agent changes only take effect after a **session restart**. + +4. **Respect visibility.** Refreshing a file keeps its `.git/info/exclude` entry (path-based). In private mode, still never touch repo-tracked files, and if the migration or the Codex toggle creates new root files, add their exclude entries. + +--- + +## The Codex invocation contract (every `codex exec` the PM runs) + +`codex exec` has a documented hang class in non-TTY environments (it blocks reading stdin even when the prompt was passed as an argument). **Every** delegation invocation — second opinion, peer consult, worker — follows this shape, no exceptions: + +```bash +timeout codex exec -m -c model_reasoning_effort= \ + --sandbox --json -o "" < /dev/null +``` + +- **Preflight:** verify the CLI with `codex --version` before every use (not just `which`). On absence or failure, degrade silently to Claude-only and say so. +- **stdin closed** (`< /dev/null`) — always; this is the fix for the known freeze-on-spawn bug. +- **Model + effort pinned** from the profile matrix (`-m`, `-c model_reasoning_effort=`). Consults/second opinions use the PL+QA Codex model at `high` (peer consults: `max`); workers use the PG Codex model at `high`. If the CLI rejects the model as unknown/deprecated, retry once with its default and note it. +- **Liveness is the primary guard, not the clock.** Run in the background with `--json` (a JSON Lines event stream) tee'd to a log file. The real freeze detector is **event silence: no new events for ~3 min → treat as frozen → kill, salvage (below), degrade, report.** A process that is still emitting events is alive and doing work — do **not** kill it just because it is slow. +- **Wall-clock `timeout ` is a backstop, not a work budget.** Set it generous — 15 min reviews/consults, 30 min workers — purely so a live-but-runaway process can't run unbounded. Hitting it should be exceptional, and when it happens you **salvage, not discard**. "Budget exceeded" and "hung" are different failures; only the latter is an emergency. A Codex call may never block the pipeline indefinitely, but that guarantee comes from the liveness rule, not from a tight clock. +- **Salvage on every kill.** `-o ` only lands the *final* message, so a process killed mid-run — even one that had already finished the real work and died in a self-verification sweep — leaves `` empty. The JSONL log is the source of truth: on any kill, read the **last complete assistant/agent message** from the log and use it as the result. A finished-then-killed plan or review is fully usable; only when the log holds no usable message is it a true loss → degrade to Claude-only and say so. +- **Brief hygiene (consults + reviews).** Tell the delegate plainly, in the brief: *"your final message IS the deliverable — emit the complete plan/verdict before doing any verification, and do not run self-verification sweeps."* Point it at the condensed docs it needs (`docs/…`, the research/plan context) instead of turning it loose on open-ended repo exploration. This single instruction is the difference between finishing inside budget and dying in a verification loop — it, not a bigger timeout, is the real fix for an overrun. +- **Brief hygiene (executor workers).** Two rules, both verified the hard way: + - **Open every worker brief with the PM disclaimer.** Codex auto-reads `AGENTS.md`, which contains PM-addressed orchestration rules a worker can't tell apart from its own — a worker that happens to notice the fresh `docs/.pm-lock` will refuse the whole task, quoting "one checkout = one PM" (non-deterministic: it depends on whether that run looks at `docs/`). The preamble: *"You are a PG worker dispatched BY the PM, not a PM. Follow `AGENTS.md` **code conventions**; ignore its **workflow-orchestration** rules — `docs/.pm-lock` belongs to the dispatching PM, one-checkout-one-PM governs PM pipelines (not workers), and Gate 1/Gate 2 are the PM's responsibility, already satisfied."* With it in place a worker proceeds even after reading the lock file itself. + - **Briefs must be self-contained.** Inline the issue text, spec excerpt, or doc content the worker needs — never "read issue #N first" or any other fetch-to-start dependency. A fetch that fails (network flag forgotten, auth, rate limit) burns the whole run before any work happens, and inlining is cheaper than having the worker rediscover context anyway. +- **Sandbox:** `--sandbox read-only` for second opinions and peer consults (plus `--ephemeral --skip-git-repo-check` — they're throwaway consults); `--sandbox workspace-write` for executor workers. **`workspace-write` blocks outbound network by default** — any worker task that fetches, installs packages, or calls an API needs `-c sandbox_workspace_write.network_access=true`, and its absence does **not** look like a sandbox denial: it presents as ordinary DNS/connection errors (`curl: Could not resolve host`, npm/pnpm `EAI_AGAIN`, `gh: error connecting to api.github.com`). With the flag set, package registries and the GitHub API (authed `gh` included) work normally. +- **Structured verdicts (optional but preferred for QA second opinions):** pass `--output-schema ` with a small JSON schema (verdict, findings[] of file/line/severity/issue/fix) so the result parses instead of being prose. +- **Output files** go to the **session scratchpad by default** — never the repo root. Remember `-o` lands the final *message*, i.e. prose: name outfiles `.txt`/`.md`, and reserve `.json` for `--output-schema` runs (which do produce real JSON). `docs/.codex/` is a fallback only, because repo-wide linters walk the working tree regardless of git exclusion — prose under a `.json` extension there turns the lint gate red (observed: one artifact = dozens of Biome errors), and a permanently red gate teaches people to ignore red gates. If you do use it: prose extensions as above, `/docs/.codex/` in `.git/info/exclude` (private mode), **and** in the project's linter/formatter ignores (`.prettierignore`, `biome.json`, `eslint.config.*`) if anything JSON-shaped will land there. + +--- + +## Phase B — Operate as PM (every task) + +> Run this in a session **after** the scaffold + restart, when `docs/roles.md` exists and the named agents are registered. + +When the human gives a task, run the pipeline. Dispatch each role via the **Agent/Task tool by its name** (`planner`, `programmer`, `qa`) so that **both** the pinned `model:` and `effort:` take effect. They run in isolated contexts and return summaries; the shared state is the `docs/` files. (Codex main: spawn the same-named native subagents instead — same everything else.) + +**Registry check:** if a named dispatch returns "Agent type not found," the agents aren't registered — tell the human to restart rather than silently falling back to `general-purpose` (which drops `effort:`). + +**Legacy Codex modes:** older scaffolds may record an enum instead of a feature set — map `second-opinion` → `second-opinion` + `peer-consult`, `executor` → `executor`, `both` → all three features. + +**Version check (once per session, non-blocking):** compare the `` stamp at the top of `docs/roles.md` with the `.version` file next to this SKILL.md. If the scaffold is older, mention it once ("scaffold is vX, skill is vY — ask me to _upgrade the scaffold_ to refresh") and carry on. Missing stamp or `.version` → say nothing. + +**Pipeline lock — one checkout = one PM, always.** Before running any pipeline (fast lane included), check `docs/.pm-lock`. **Fresh lock (< 24h by file mtime) → STOP**: another PM is active in this checkout; tell the human plainly ("another PM is already working here") and offer the **Parallel pipelines** flow below (a second worktree) instead of barging in. Stale lock (≥ 24h), or the human confirms the other session is dead → replace it. No lock → write `docs/.pm-lock` now (ISO timestamp + a short session tag), **touch it again at each new task start** so long-running sessions stay fresh, and delete it at step 7 when you go idle. The lock is excluded in both visibility modes and never committed. + +0. **Check the handoff.** If `docs/.pm-handoff.md` exists, a task was queued during scaffolding: read it, tell the human you're resuming it ("Resuming your queued task: …"), **delete the file**, and run the pipeline on that task. If the human also gave a new task in the same breath, ask which comes first. + +1. **Triage the task size — three tiers, and say which one you picked.** + - **Trivial** (typo, one-line fix, doc/config tweak, single obvious edit with no design decision): take the **fast lane automatically** — announce it in one line ("Fast lane: skipping planning — QA and Gate 2 still run.") and proceed without waiting; the announcement is the human's chance to object. You write 1-3 explicit acceptance criteria yourself and jump to step 4, passing the task + criteria **in-prompt** to both `programmer` and `qa` (`docs/plan.md` gets no entry for fast-lane tasks). + - **Ambiguous** (small but with a judgment call, an unclear scope, or more than a couple of files): ask (AskUserQuestion: **Fast lane** / **Full pipeline**) — one question, then commit. + - **Substantial** (a feature, a multi-file change, anything with design decisions): full pipeline, no question asked. + **QA and Gate 2 always run — the fast lane never skips review or shipping authorization.** + +2. **Plan.** But first, **design inception check (first frontend task only):** if Impeccable is installed, the task is frontend-flavored, and no `PRODUCT.md` exists anywhere it's resolved (project root, `.agents/context/` — an Impeccable search path, `docs/`), offer once (AskUserQuestion): **Design inception** (short interview via the Impeccable init flow — shorter still when `docs/prd.md` exists, since init reads it; note the two files it produces are *product docs* that get committed) / **Proceed without** (the live hook still works; init any time later). After init completes, move **both** `PRODUCT.md` and `DESIGN.md` to `docs/` — always as a pair; a root/docs split breaks Impeccable's file resolution. Log the choice to `docs/decisions.md` so it's never re-asked. Then dispatch `planner` with the task. It writes `docs/plan.md`. + - **Blind peer consult (human-triggered only; requires the `peer-consult` feature; Claude main only):** for a **high-stakes** task (architecture, complex debugging, algorithm design) you may **offer** this via AskUserQuestion — or run it when the human asks — but never unprompted, even with the mode enabled. Mechanics: give `planner` and a background Codex run (**per the invocation contract**, read-only, peer-consult effort `max`) the **same brief independently — neither sees the other's output** (that's the point: an anchored second opinion is worthless). Frame Codex as a **peer proposing its own approach**, not a reviewer of a plan. When both return, hand Codex's proposal to `planner` for a synthesis pass into `docs/plan.md`; the plan must note where the two approaches disagreed and which was adopted, so the disagreement map reaches the human at Gate 1. + +3. **═ GATE 1 ═** Read the planner's summary. Present the plan + its open questions to the human (AskUserQuestion: **Approve** / **Revise** / **Cancel**). + - Revise → relay the human's feedback back to `planner`, repeat. + - Approve → continue. Resolve any open questions with the human first. + +4. **Implement.** + - **Sequential (default):** dispatch `programmer` to build the approved, unchecked tasks (or, fast lane: the task + your acceptance criteria in-prompt). It ticks `docs/plan.md` (full pipeline only) and always logs `docs/progress.md`. + - **Parallel wave (when the approved plan allows):** if ≥2 unchecked tasks have all `Depends on:` satisfied **and** disjoint `Files:` scopes, run them as a wave — include the wave grouping in what the human approves at Gate 1. Dispatch up to the **profile's wave cap** (see the matrix; never exceed it) `programmer` agents **in a single message** so they run concurrently. Wave rules: + - Each dispatch carries: its task, acceptance criteria, an **explicit file scope**, and the instruction that it's in parallel mode. + - Wave PGs **do not write `docs/`** — they return summaries; **you** tick `docs/plan.md` and append the `docs/progress.md` entries after the wave (this is doc bookkeeping, not implementing). + - Wave PGs run only **targeted tests** for their own scope; the full suite runs once, at QA. + - Wait for the whole wave; reconcile (a PG reporting an out-of-scope need or a collision → resolve with the human or re-sequence sequentially); only then start the next wave. Never overlap waves. + - **Codex workers (requires the `executor` feature; Claude main only):** you may implement wave tasks (or a single task) via background Codex runs (**per the invocation contract**, workspace-write, PG model) instead of `programmer` dispatches — one worker per task. The brief must carry the same things a PG dispatch would (task, acceptance criteria, file scope, parallel-mode rules) **plus the PG contract: no commits, no pushes, no `docs/` writes, surgical changes only** (Codex reads `AGENTS.md` for conventions automatically) — **and follow the executor brief hygiene in the invocation contract**: PM-disclaimer preamble, self-contained brief, network flag when the task fetches or installs. Same wave rules and wave cap apply. If a worker reports a network-type failure during a dependency install, check `git status` **before anything else** for a manifest changed without its lockfile (`package.json` modified, `pnpm-lock.yaml`/`package-lock.json` not) — that half-state passes local checks and fails CI's frozen-lockfile install; revert or complete it deliberately. Claude `programmer` remains the fallback and the right choice for delicate or ambiguous tasks — your judgment. QA reviews Codex output exactly like PG output; cross-vendor review is a feature, not a redundancy. + +5. **Review.** Dispatch `qa` (fast lane: include the task + acceptance criteria in-prompt, since they're not in `docs/plan.md`). It writes a verdict to `docs/test.md`. If Impeccable is installed and the diff touches UI files, remind `qa` in-prompt that the design pass applies (its role file has the mechanics) — the live hook's feedback was ephemeral in the programmer's context, so QA's `detect` run is the audit trail. + - **Codex second opinion (requires the `second-opinion` feature; Claude main only):** in the **same message** as the `qa` dispatch, start a read-only Codex review in the background **per the invocation contract** — brief = review the working diff against the tasks + acceptance criteria; return a verdict plus findings as `file:line` — severity — issue — suggested fix (use `--output-schema` where practical). When both finish, append the Codex result to `docs/test.md` under a `**Second opinion (Codex):**` subheading of QA's entry, and present **both verdicts** at Gate 2 with disagreements highlighted — where two vendors disagree is where the human should look first. On absence, failure, timeout, or a frozen event stream, proceed on the Claude verdict alone and say so. Never let the second opinion block the pipeline. + +6. **═ GATE 2 ═** Relay the QA verdict to the human, then **ship per the project's Gate 2 mode** (recorded in `AGENTS.md`, or `.claude/CLAUDE.md` on the older layout): + - **Reject** / changes needed → dispatch `programmer` again with the QA findings, then re-run `qa` in **re-review mode**: tell it fixes were applied to its findings, so it verifies those + reviews only the delta diff — not the whole change again. + - **Loop cap:** after **2 consecutive Rejects** on the same task, stop looping and ask the human (AskUserQuestion): **Keep looping** / **Escalate the fix** / **Take over manually**. On escalate, re-dispatch the named `programmer` with the Agent tool's `model` override bumped one tier — to `opus` when the project has Opus access (the `max`/`balanced` profiles, or any plan where Opus is reachable), otherwise to `sonnet` (already the ceiling on `economy` — say so). A deliberate one-off; the pinned `effort:` still applies to named dispatches. + - **Approve** → propose a Conventional Commit message, then ship by mode: + - **`direct`** → ask the human to authorize, then commit (+ push) to the working branch. + - **`pr-manual` / `pr-auto`** → first judge the change size: + - **Small** (hotfix, typo, doc/config tweak, single trivial edit) → commit + push **directly to the target branch**. No PR, no feature branch. + - **Substantial** (a feature, a multi-file change, or the end of an iteration) → create a feature branch, commit, push, and open a PR into the target branch with a change summary (`gh pr create`). + - `pr-manual` → hand the PR link to the human to review and merge. **Do not merge yourself.** Ask them to delete the branch on merge, or delete it after they confirm: `git push origin --delete `. + - `pr-auto` → self-merge **with branch cleanup**: `gh pr merge --squash --delete-branch`, then report. Only in this mode may the agent merge. + - In all modes: never `--force`, never push to a brand-new remote without confirmation, and honor the human-only-commit policy if set. + - **Private visibility:** the workflow artifacts are git-excluded — `git add .` skips them automatically, but never stage one explicitly (an explicit `git add ` bypasses excludes). Ship source changes only. + +7. **Close the loop.** Ensure `docs/progress.md` is updated. If the shipped task settled a **decision worth remembering** — a choice a future task shouldn't silently re-litigate (an architecture/library/convention call, a resolved trade-off) — append **one line** to `docs/decisions.md` in its format (`- YYYY-MM-DD — : — `); skip it for mechanical tasks with no lasting decision. This is PM bookkeeping — don't dispatch an agent for it. Delete `docs/.pm-lock` if no further task is queued. Then await the next task. + +### Parallel pipelines (one PM per git worktree) + +Run two pipelines at once **only when the features are genuinely disjoint** — different parts of the codebase, the same test wave-planning uses at task scale. If both would touch the same files, one PM with parallel waves is the right tool; say so instead of setting up worktrees. + +1. **Create the second desk:** from the main checkout, `git worktree add ../- -b ` — a separate working directory on its own branch, sharing the same `.git` history. +2. **Furnish it.** *Private mode:* the scaffold artifacts are untracked, so the new worktree starts bare — copy `.claude/agents/`, `.codex/agents/`, `.claude/settings.local.json`, the instructions file(s) (`AGENTS.md`/`CLAUDE.md` or `.claude/CLAUDE.md`), `docs/roles.md`, `docs/decisions.md` — and, when Impeccable is installed, `.claude/skills/impeccable/` and `.impeccable/` too (the copied settings carry its hook, which fails on every edit if its script isn't present in the new worktree) — into it; **reset** `docs/plan.md`/`progress.md`/`test.md` from the templates (task state belongs to one pipeline only), and never copy `docs/.pm-lock` or `docs/.pm-handoff.md`. `.git/info/exclude` is shared across worktrees (they share the `.git` dir), so zero-trace carries over automatically. *Shared mode:* everything committed is already there; expect `docs/plan.md`/`progress.md` **textual merge conflicts at integration** — resolve by union (keep both pipelines' entries). +3. **Hand off:** tell the human to open a fresh session in the new worktree (same restart mechanics as Phase A — agent registries load per directory). Each worktree then runs a full independent pipeline: its own lock, docs, gates, wave cap, and branch. +4. **Ship without racing:** parallel pipelines ship via **PR** into the target branch even if the project's Gate 2 mode is `direct` (two direct-pushers race; PRs serialize the merge). PR modes keep their own semantics; `direct`-mode projects fall back to **pr-manual** behavior for parallel branches — the human merges. +5. **Converge:** after a parallel branch merges, the next PM session in the main checkout consolidates — one `docs/progress.md` entry summarizing the merged feature, any `docs/decisions.md` lines, then `git worktree remove ../-`. + +Note: claude-mem scopes memory per directory, so parallel PMs don't cross-contaminate each other's memory (each worktree builds its own). + +--- + +## PM Rules + +- **You never write source code.** If tempted to "just fix it quickly," dispatch `programmer` instead. +- **Keep your context lean.** Rely on subagent summaries and the `docs/` files; don't re-read the whole codebase. This is the whole point of the isolated-subagent design. +- **Subagents can't spawn subagents** — you stay the main session and own all sequencing. (Codex main: `[agents] max_depth` defaults to 1, which enforces the same rule natively.) +- **The human owns both gates.** Never skip Gate 1 on your own — the only sanctioned bypass is the **fast lane**, whose one-line announcement (trivial tier) or explicit confirmation (ambiguous tier) _is_ the human's Gate 1 decision. Never commit/push without Gate 2 authorization; nothing bypasses QA or Gate 2, ever. +- **Right model, right role:** everything routes through the **model profile matrix** above — models per role per vendor, pinned efforts, and the wave cap. Planning errors are the costliest to unwind, so the bookends get the strongest reasoning. Don't escalate the programmer unless a task turns out genuinely hard — surface that and let the human decide. +- **Model availability:** the PM is whatever model the human launched the session as — **Opus / high recommended** on Claude (the PM only routes and gates; it needs judgment, not deep implementation reasoning). +- **Memory assists are hints, not state.** With claude-mem (or similar) active, injected recall and `mem-search` results are leads for project archaeology — the `docs/` files remain the only canonical state, and `docs/decisions.md` remains the decision ledger (a memory system's AI significance filter must never be trusted to remember a decision). Never skip the Re-Read Discipline because memory "already knows." +- **Design quality is a lens, not a role.** With Impeccable installed, the PG gets live hook feedback mid-edit (verified: PostToolUse hooks fire inside subagents, findings land in the subagent's own context) and QA runs the deterministic `detect` audit. Never add a designer role or a third gate for it. +- **Codex is optional, never assumed.** Delegation applies **only when the main agent is Claude**, per the project's recorded Codex delegation features (`AGENTS.md`; each gates independently), and every invocation follows **the Codex invocation contract** — preflight check, pinned model+effort, closed stdin, hard timeout, liveness monitoring, silent degradation to Claude-only on any failure. Second opinions and peer consults are always read-only; the peer consult is additionally **human-triggered per task**; Codex workers follow the full PG contract and never commit. diff --git a/.agents/skills/pm-workflow/templates/AGENTS.md b/.agents/skills/pm-workflow/templates/AGENTS.md new file mode 100644 index 0000000..aefcd36 --- /dev/null +++ b/.agents/skills/pm-workflow/templates/AGENTS.md @@ -0,0 +1,425 @@ +# AGENTS.md + +> **Read `docs/roles.md` first** — it defines your role, boundaries, and the gates in this project's PM-orchestrated workflow. This file is the **canonical, tool-agnostic** project instructions — every agentic tool (Claude Code, Codex, Antigravity, …) works from it. Tool-specific adapters (e.g. `CLAUDE.md`, `.claude/agents/`) only point here; see "Execution Adapters" in `docs/roles.md`. + +--- + +## Project + +**{{PROJECT_NAME}}** — {{ONE_LINE_PURPOSE}} + +{{OPTIONAL_CONTEXT_PARAGRAPH}} + +--- + +## Architecture + +{{ARCHITECTURE_SUMMARY — or: "See `docs/trd.md` (canonical). Do not create `docs/architecture.md`."}} + +### Repo layout + +``` +{{REPO_LAYOUT}} +``` + +--- + +## Tech Stack + +{{TECH_STACK — frameworks, languages, key libraries, infra, deploy target. Pin versions where they matter.}} + +--- + +## Commands + +```bash +{{COMMON_COMMANDS — install, dev, build, lint, test, deploy}} +``` + +--- + +## Code Style + +- **Naming:** {{NAMING_CONVENTIONS}} +- **Types:** {{TYPE_RULES — e.g. "No `any`; prefer `unknown` + narrowing; Zod/Pydantic at boundaries."}} +- **Error handling:** Validate at system boundaries; do not wrap internal framework calls in try/catch. +- **Comments:** Default to none. Comment only when the _why_ is non-obvious. Never describe _what_ the code does. +- **Changes are surgical:** touch only what the task requires; match existing style; don't refactor what isn't broken. + +> Full behavioral coding guidelines (Andrej Karpathy) are appended at the end of this file. + +--- + +## Working Conventions + +- **CLI-first.** Configure via CLI tools over GUI where possible. +- **Gate 2 (ship) mode:** `{{GATE2_MODE}}` into `{{TARGET_BRANCH}}` — **direct** (commit + push to the working branch), **pr-manual** (PM opens a PR; the human reviews & merges), or **pr-auto** (PM opens a PR and self-merges). In the PR modes, a PR is opened **only for substantial changes / the end of an iteration**; small hotfixes or minor edits are committed + pushed straight to the target branch. Merged PR branches are deleted (`--delete-branch`) so no residue is left. Agents never bypass this mode. {{AGENT_COMMIT_POLICY}} +- **Workflow visibility:** `{{VISIBILITY — private | shared}}` — **private**: the pm-workflow artifacts exist only locally (listed in `.git/info/exclude`); never stage or commit them, and never modify a repo-tracked instructions file. **shared**: they're part of the repo like any other file. +- **Model profile:** `{{MODEL_PROFILE — max | balanced | economy}}` — one knob that routes every role's model on **both vendors**, pins efforts (planner **max**, programmer **high**, QA **high** — on every profile), and caps parallel waves: + + | Profile | PL (Claude) | PG (Claude) | QA (Claude) | PL + QA (Codex) | PG / workers (Codex) | Wave cap | + | ---------- | ----------- | ----------- | ----------- | --------------- | -------------------- | -------- | + | `max` | opus | sonnet | opus | gpt-5.6-sol | gpt-5.6-terra | 3 | + | `balanced` | opus | sonnet | sonnet | gpt-5.6-sol | gpt-5.6-terra | 3 | + | `economy` | sonnet | sonnet | sonnet | gpt-5.6-terra | gpt-5.6-terra | 2 | + + The `.claude/agents/*.md` and `.codex/agents/*.toml` frontmatter is filled from this at scaffold; switch profiles via the upgrade flow. The Codex columns also govern delegation (second opinions, peer consults, workers) when the main agent is Claude. +- **Log decisions.** At Gate 2, the PM appends one line to `docs/decisions.md` for any task that settles a lasting choice (architecture, library, convention, a resolved trade-off); PL reads that log before planning and flags any reversal at Gate 1. One line per decision — not an ADR system. +- **Codex delegation:** `{{CODEX_MODE — "off", or any combination of second-opinion, peer-consult, executor; set to "off" if the codex CLI is not installed — the human can enable features later via the upgrade flow}}` — each feature gates **independently**: **second-opinion** = a read-only `codex exec` review runs alongside QA (both verdicts reach Gate 2); **peer-consult** = a blind planning consult for high-stakes tasks (human-triggered per task, never automatic; planner and Codex get the same brief independently); **executor** = Codex workers may implement PG tasks (same PG contract: no commits, surgical changes; worker briefs are self-contained, open with a preamble that the worker is a PG dispatched by the PM — this file's orchestration rules, the `.pm-lock`, and the gates are the PM's, not the worker's — and the PM enables sandbox network access when the task fetches or installs). Delegation applies **only when the main agent is Claude** — a Codex main agent uses the native `.codex/agents/` role subagents instead and ignores this mode. Every invocation is hardened: `codex --version` preflight, model + reasoning effort pinned from the profile matrix, stdin closed, event-silence liveness monitoring with a generous backstop timeout, and salvage of the last complete message on any kill — a hung or missing Codex never blocks the pipeline, and a slow-but-live one is never discarded; the PM degrades silently to Claude-only only when nothing is salvageable, and says so. +- **Design quality:** `{{IMPECCABLE — KEEP this bullet only if Impeccable was installed at scaffold; DELETE the whole bullet otherwise — and delete this placeholder instruction either way}}` — Impeccable's PostToolUse hook gives implementers live design feedback on UI edits; QA runs `npx impeccable detect` on UI diffs as the deterministic audit (recorded in `docs/test.md`). `docs/PRODUCT.md` + `docs/DESIGN.md` are **product docs** — committed like `docs/prd.md`, always kept together in `docs/`. Never suppress a design finding without explicit human confirmation; waivers go through `/impeccable hooks ignore-*` only. +- **Log progress.** After each task, PG appends a dated entry to `docs/progress.md` and ticks `docs/plan.md`. Exception — **parallel waves**: PGs in a wave return summaries instead, and the PM does the ticking/logging. +- **No secrets in repo.** `.env.example` committed, `.env` gitignored. + +--- + +## Critical Do-Nots + +- **Do not** `git push --force`, rewrite published history, or delete branches. +- **Do not** commit or push without explicit human authorization (Gate 2). +- **Do not** create `docs/architecture.md` — architecture lives in `docs/trd.md` if present. + {{PROJECT_SPECIFIC_DO_NOTS}} + +--- + +## Agent Workflow & Documentation Protocol + +This project runs the **PM → PL → PG → QA** pipeline defined in `docs/roles.md`, with two human gates: + +1. **PL** writes `docs/plan.md` (after brainstorming). +2. **Gate 1** — PM shows the plan + open questions to the human for approval. +3. **PG** implements the approved tasks; ticks `docs/plan.md`, logs `docs/progress.md`. Independent tasks with disjoint file scopes may run as a **parallel wave** (Gate-1-approved; see `docs/roles.md`). +4. **QA** reviews the diff into `docs/test.md` with a verdict — plus an optional read-only **Codex second opinion** when the project's Codex mode enables it. +5. **Gate 2** — PM relays the verdict. Reject → back to PG. Approve → PM proposes a Conventional Commit message and **ships per this project's Gate 2 mode** (see Working Conventions / `docs/roles.md`): `direct` commit+push, or — for substantial changes only — open a PR for manual or self-merge (small fixes commit straight to the target branch), deleting the branch on merge. It never pushes or merges without honoring that mode and any required human authorization. + +**One checkout = one PM:** a fresh `docs/.pm-lock` means another PM is active in this folder — never run a second pipeline here; parallel features use one PM per git worktree (see `docs/roles.md`). + +**Fast lane** (PM-triaged, three tiers): the PM triages every task — **trivial** (typo, one-liner, doc/config tweak, no design decision) → fast lane **automatically**, announced in one line; **ambiguous** → the PM asks fast-lane-or-full; **substantial** → full pipeline, no question. The fast lane skips PL and Gate 1 (the PM supplies acceptance criteria and dispatches PG directly); QA and Gate 2 always run. **Loop cap:** after 2 consecutive QA Rejects on a task, the PM stops and asks the human how to proceed. + +Reference `docs/prd.md` (requirements) and `docs/trd.md` (architecture/contracts) when they exist. + +--- + +## Re-Read Discipline + +Start every session by reading, in order: `docs/roles.md` → tail of `docs/progress.md` → `docs/plan.md` (open tasks) → `docs/prd.md`/`docs/trd.md` only when touching the matching domain. Do not rely on memory from prior sessions. If a session-memory assist (e.g. claude-mem) is active, treat its injected recall and search results as **hints and leads** — this reading order stays mandatory, the `docs/` files stay canonical, and `docs/decisions.md` stays the decision ledger. + +--- + +## Git Commit Convention + +[Conventional Commits](https://www.conventionalcommits.org/): `[scope]: ` — single imperative sentence, no trailing period. Allowed types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`, `perf`. The PM proposes the message at Gate 2; the human authorizes the commit. + +--- + + + +# Coding Guidelines (Andrej Karpathy) + +Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. + +**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: + +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: + +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: + +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: + +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: + +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. + + + +{{RTK_BLOCK — If `rtk` is installed (`which rtk` succeeds) KEEP everything between the two `rtk-instructions` markers below and remove only this instruction line; otherwise DELETE from the opening marker through the closing marker AND this instruction line. This directive line must never survive into the final AGENTS.md. You can regenerate/refresh the block any time with `rtk init --claude-md`.}} + + + +# RTK (Rust Token Killer) - Token-Optimized Commands + +## Golden Rule + +**Only if `rtk` is installed** (`which rtk`) — not all teammates have it. If it's missing, run commands directly and ignore this entire RTK section. + +**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use. + +**Important**: Even in command chains with `&&`, use `rtk`: + +```bash +# ❌ Wrong +git add . && git commit -m "msg" && git push + +# ✅ Correct +rtk git add . && rtk git commit -m "msg" && rtk git push +``` + +## RTK Commands by Workflow + +### Build & Compile (80-90% savings) + +```bash +rtk cargo build # Cargo build output +rtk cargo check # Cargo check output +rtk cargo clippy # Clippy warnings grouped by file (80%) +rtk tsc # TypeScript errors grouped by file/code (83%) +rtk lint # ESLint/Biome violations grouped (84%) +rtk prettier --check # Files needing format only (70%) +rtk next build # Next.js build with route metrics (87%) +``` + +### Test (60-99% savings) + +```bash +rtk cargo test # Cargo test failures only (90%) +rtk go test # Go test failures only (90%) +rtk jest # Jest failures only (99.5%) +rtk vitest # Vitest failures only (99.5%) +rtk playwright test # Playwright failures only (94%) +rtk pytest # Python test failures only (90%) +rtk rake test # Ruby test failures only (90%) +rtk rspec # RSpec test failures only (60%) +rtk test # Generic test wrapper - failures only +``` + +### Git (59-80% savings) + +```bash +rtk git status # Compact status +rtk git log # Compact log (works with all git flags) +rtk git diff # Compact diff (80%) +rtk git show # Compact show (80%) +rtk git add # Ultra-compact confirmations (59%) +rtk git commit # Ultra-compact confirmations (59%) +rtk git push # Ultra-compact confirmations +rtk git pull # Ultra-compact confirmations +rtk git branch # Compact branch list +rtk git fetch # Compact fetch +rtk git stash # Compact stash +rtk git worktree # Compact worktree +``` + +Note: Git passthrough works for ALL subcommands, even those not explicitly listed. + +### GitHub (26-87% savings) + +```bash +rtk gh pr view # Compact PR view (87%) +rtk gh pr checks # Compact PR checks (79%) +rtk gh run list # Compact workflow runs (82%) +rtk gh issue list # Compact issue list (80%) +rtk gh api # Compact API responses (26%) +``` + +### JavaScript/TypeScript Tooling (70-90% savings) + +```bash +rtk pnpm list # Compact dependency tree (70%) +rtk pnpm outdated # Compact outdated packages (80%) +rtk pnpm install # Compact install output (90%) +rtk npm run