AI Prompt Guide workflows — router (for Claude)

This is the AI Prompt Guide workflows checkout (usually aipg/). This file only routes — it carries no workflow instructions. Each workflow's CLAUDE.md opens with ## 0. Checklist, whose opening lines say how to work it. Pick the match, then read that workflow's CLAUDE.md and follow it exactly (it drives plan mode + approval before the engine runs):

Right-size first: trivial one-liner/rename → just edit, no workflow. Then by intent. Build → author a plan file (one feature block per bounded change, section blocks for one goal spanning many files), refine it, approve it, develop it. Find production defects → audit's defects kind, then develop its fix-mode files. Audit for enhancements (what a working system could do better; human triages) → audit's enhancements kind; diverge (creative options, human judges) → brainstorm; converge (AI concludes among options it generates) → decide; search (the answer already exists; find it and prove it meets fixed criteria) → investigate; provision (copy + curate the docs to build against) → docs. The last five are generative/read-only: no code, no staging, no commit (they honor only the core principles — see WORKFLOW-PRINCIPLES.md "Scope").

Defect vs. enhancement is the sharpest split here. audit's two kinds share one engine and keep their products apart: a defects run ends in a closed issue inventory that develop's fix mode builds, an enhancements run ends in proposals the user triages, and an improvement list never enters the fix inventory, since it would not converge the way the closed inventory does.

Decide vs. investigate is the other one. If you want to trade requirement A off against requirement B, that is decide's weighted matrix. If missing A is simply disqualifying, that is investigate's pass/fail gate.

Into the plan bus. The generative workflows feed develop through plan files you author from their outputs. An enhancements audit's approved proposals map by class: ADOPT → a feature-mode block, a ROADMAP proposal spanning many call sites → a section-mode block, a proposal the verifier flagged is_defect → a hand-authored fix-mode block in the defects verifier's format. brainstorm's picked variation, decide's conclusion, and investigate's determination feed a plan's design section — convention, not tooling. Authored blocks then flow refine → your approval → develop, and a defects audit writes fix-mode blocks develop consumes directly.

Each engine loads by path (no global registry): pass scriptPath = the absolute path to the workflow's .mjs. Its CLAUDE.md covers the full flow, args, and contracts.

Launch from a notification turn. The Workflow runtime copies the user message of the launching turn into every agent's prompt, ahead of its task. That breaks blind placement, and a sonnet agent may follow the message over its task. A turn started by a background task's notification carries no user message. So run the workflow's pre-launch command with run_in_background, and call the Workflow tool in the turn its notification starts. A notification that arrives inside a tool result does not start a new turn, so end the turn after starting the pre-launch command. The pre-launch command is plan-edit.mjs args for develop, plan-block.mjs <planPath> --list for refine, and git -C <target.repo> status --short for the rest (node --version when the run has no target.repo). Agents receive the auto-memory index the session loaded at its start, so a line already loaded stays in every run of that session. A MEMORY.md index line holds settled facts and pointers, and neither it nor a topic file it points to holds the plan or goal of work a run is building, since every agent of the run reads that index (principles/WORKFLOW-PRINCIPLES.md #3).

Two paths, never the same directory: target.repo = the project being worked on (the folder holding its .git); root = where run-state lands (<root>/runs/<runId>/), normally this checkout. Keeping them apart is what keeps the issue files out of reach of the blind reviewer, and is what lets one checkout drive many projects. The engines that write code throw rather than default target.repo — see the root README, "One checkout, many projects".

This repo is also the aipg Claude Code plugin (manifests in .claude-plugin/, entry points in skills/<x>/SKILL.md → /aipg:<x>). Installed, the skills resolve the plugin paths and point root at the plugin's persistent data dir instead of a checkout. The Workflow tool refuses a scriptPath the session cannot already read, and an installed plugin's folder is outside every project. So each skill first runs tools/plugin-access.mjs, which adds one Read rule for the plugin folder once the user agrees. The develop and debug skills run tools/onboard.mjs in its place, which asks for that access together with every other setup answer the repo is missing. Rename an engine, guide, tools/plan-block.mjs, tools/plan-edit.mjs, tools/plugin-access.mjs, tools/onboard.mjs, tools/project-settings.mjs, tools/wt.mjs or workflows/audit/gen-units.mjs and the matching skills/<x>/SKILL.md paths must move with it. The debug and enhance skills both launch workflows/audit/audit.mjs, each with its kind.

Want to see what a run actually does? Each workflow ships a generated FLOW.md beside its engine (workflows/<x>/FLOW.md; audit's are FLOW-defects.md and FLOW-enhancements.md) — every agent, gate, loop and terminal state, drawn from real traced runs. Read one before driving a workflow you have not run before. Edit an engine and you must re-run node tools/gen-flows.mjs, or the suite goes red. The generator and the rest of the repo's own machinery are catalogued in tools/CLAUDE.md.

Want each agent's view of a run? Pass the notes arg, which each workflow guide's args reference describes. Every agent then answers tools/EXIT-SURVEY.md, and tools/survey.mjs gathers the answers.

Changing anything here? Read tests/CLAUDE.md first — the development gotchas. Above all: a defect found in one engine is usually in its siblings too — grep before you call it fixed. Work the §8 steps of tests/CLAUDE.md in order. node tests/run.mjs is the gate, so point a workflow's gates.build/gates.test at it when working on this repo.

House style

Write everything here — prompts, guides, reviews, commits, replies to me — laconic by subtraction (principles/WORKFLOW-PRINCIPLES.md #13): cut filler, what I already know, and the irrelevant; never compress away what I need to act on.