AI Prompt Guide Workflows

aipromptguide.com · A collection of production-grade Claude Code dynamic workflows and the design principles they're built to. The workflows hold the prompts and orchestration that guide the AI through real engineering work.

Each workflow is a background Workflow engine (a .mjs script) paired with a CLAUDE.md operator guide. The guide is the prompt. It drives plan mode and the human approval gate outside the engine, then runs the engine to do the work. The build workflows leave the result test-verified, wired in, and staged for you to commit. The generative ones leave cited files for you to use. Either way, nothing is ever committed for you.

The workflows

Workflow	Trigger	Flow	Use it for
develop	/aipg:develop	map	Build the blocks of an approved plan file. Each block is one bounded feature, one slice of a migration across many call sites, or one triaged issue inventory. Each accepted block is staged.
refine	/aipg:refine	map	Review a plan file before develop builds it. A critic checks each block against the code for defects only, and an editor folds each gap into the plan. It stops after one clean round.
debug	/aipg:debug	map	Find production defects in a repo or change. Each unit's issues are written as a fix-mode plan file that develop builds once you triage it. An inventory from manual testing or bug reports works the same way.
enhance	/aipg:enhance	map	Audit: what a working system could do better. One lens per angle → verified, impact-scored proposals you triage. Nothing auto-applied.
brainstorm	/aipg:brainstorm	map	Diverge: one fully-committed variation per lens (designs, ideas) for you to pick or combine. No AI verdict.
decide	/aipg:decide	map	Converge: lensed analysis → a weighted decision matrix → a justified conclusion, adversarially reviewed.
investigate	/aipg:investigate	map	Search: find an answer that already exists and qualify it against fixed pass/fail criteria, until nothing qualifying is left unsearched.
docs	/aipg:docs	map	Provision: copy the docs a project needs verbatim (web/repo/files) → curate + index into a folder the LLM builds against.

develop is the one build workflow. It writes the code, reviews it and stages it. refine and debug produce the plan files develop builds. The last five are generative and read only. They produce proposals, creative options, a decision, a determination, or a curated doc set, with no code and nothing staged or committed.

Two pairs are worth keeping straight. For debug and enhance, something the system gets wrong is a defect, which debug fixes. Something it could do better is an enhancement, which enhance proposes and you decide on. For decide and investigate, decide fits when no established answer exists and the work is weighing trade-offs. Investigate fits when the answer is already out there and the work is finding it and proving it fits. The tell is whether missing a requirement is a trade-off or disqualifying.

All eight share the design rules in principles/, the fifteen Workflow Principles (lean, file bus, no busy work).

The Flow column is a diagram of what a run does. It shows every agent, gate, loop and terminal state, rendered inline by GitHub. Read one before starting a run you have not done before. The terminal states are the part most worth knowing in advance, since "ran out of rounds" and "proved there is no answer" are different results that look alike in a summary.

Those maps are generated, never hand-drawn. tools/gen-flows.mjs runs each engine against scripted agent replies and watches which agents it spawns, so a diagram can only ever show a path that really runs. So the generator is also a linter. It fails node tests/run.mjs when a map goes stale, when an engine grows a branch no scenario reaches, or when meta.phases stops matching the phases the agents run under.

Why it's built this way

This repo is a Claude Code plugin (aipg), and its skills are thin and stable. Each carries no workflow prompt, only the install's resolved paths and a pointer to the matching workflows/<x>/CLAUDE.md. That split is deliberate:

• The prompt lives in the workflow, not the skill. Plan mode (and its approval gate) must run outside a background Workflow, so the CLAUDE.md guide, not the engine, drives it. Loading a workflow the ordinary way wouldn't include that prompt. Pointing at the CLAUDE.md does.
• One update moves everything together. Skills, guides, engines and the plan-block tool ship as one plugin version, so there is nothing to copy or drift.

You run /aipg:develop  →  Claude reads the plugin's workflows/develop/CLAUDE.md  →  plan mode, the
refine review, then your approval  →  runs develop-cycle.mjs by path  →  staged result you review
and commit

Install (plugin)

/plugin marketplace add Blakeem/aipromptguide-workflows
/plugin install aipg@aipromptguide

The workflows land in the plugin cache, and run state goes to the plugin's persistent data dir (~/.claude/plugins/data/…), outside every project. Then run one, such as /aipg:develop add a search_docs MCP tool. Plan it first.

Since Claude Code only starts a workflow from a folder the session can read, the first run asks if Claude can read the plugin folder. Say yes and a Read rule is added to your user settings. It stays in place when the plugin updates.

Install (checkout, for development or driving workflows by path)

1. Clone it anywhere (in a project, gitignore it):

   git clone https://github.com/Blakeem/aipromptguide-workflows.git aipg
   echo "aipg/" >> .gitignore

2. Open the checkout in Claude Code. The root CLAUDE.md routes to each workflow's guide, with root = the checkout. To use the plugin's skills against a local clone, add it as a local marketplace instead, with /plugin marketplace add ./aipg and then /plugin install aipg@aipromptguide.

One checkout, many projects

Every engine takes two separate paths, and they are deliberately not the same directory:

E:/myproject/          ← target.repo   the project itself, the folder holding .git
├── .git/
├── src/
└── aipg/              ← root          run-state lands at aipg/runs/<runId>/
    └── workflows/

• target.repo is the repo being worked on. Agents run git -C <target.repo> … against it, and it is the only place code is ever changed or staged.
• root is the base the run-state hangs off. <root>/runs/<runId>/ holds the review files, the ledgers, and any parked patch. Normally the checkout's own folder, so nothing lands in your project.

Keeping them apart is what makes the blind review work. The issue files live outside the repo under review, so a reviewer that is supposed to judge a diff on its own merits cannot wander into them. The develop, refine and debug engines warn if you point run-state inside the target repo. develop and refine also warn when a plan file resolves inside it.

It also means one checkout can drive any number of projects. Point target.repo at each in turn and give each its own runId. The run-state stacks up under root, so you can queue work across several repos and still read every trail in one place:

aipg/runs/api-v2-migration/     ← target.repo E:/work/api
aipg/runs/dashboard-search/     ← target.repo E:/work/dashboard

You never type these yourself. Tell Claude which project you mean and it fills them in as pre-run setup. There is no default for target.repo on the engines that write code, because guessing wrong would point a build, or a park's git checkout, at the wrong repo. They fail loudly instead.

Installed as the plugin, the same two-path rule holds. Only root moves. The plugin install dir is version-swapped on every update, so run-state cannot live beside the engines there. The skills point root at the plugin's persistent data dir instead, and everything stacks up the same way, still outside every project:

~/.claude/plugins/cache/aipromptguide/aipg/<version>/   ← the engines (read-only, swapped on update)
~/.claude/plugins/data/aipg-aipromptguide/              ← root: runs/<runId>/ + plans/<runId>/

Updating

Plugin: /plugin → Installed → aipg → update (auto-update lives under Marketplaces, off by default). Skills, guides and engines move together, and every commit is a new version (plugin.json carries no version field, so the git commit SHA is the version). Checkout:

cd aipg && git pull        # refreshes every workflow's CLAUDE.md + engine

Changelog

What's changed, newest first: new workflows, changes to how they work, and bugs worth knowing about.

2026-10-08

• develop sets a dirty tree aside without touching the staged work. The guide and the dirty-baseline halt no longer use git stash -u, which also stashed the accepted blocks in the index. The set-aside saves the unstaged work to a patch under the run's state dir before it clears anything. A plain git apply restores it unstaged.
• A parked block keeps its work in one patch. The park saves new files in the same patch as the edits. A second park of the same block keeps the earlier patch as parked-<id>.prev<n>.patch. The park note's restore command is a plain git apply. Before, its git apply --3way staged unreviewed work.
• develop can continue a parked block. Add continueParked: ["<id>"] to the launch args. The block's first developer restores its patch, and the work goes through full review.
• develop writes each new issue to its source block's own file. The file is plans/<runId>/NEW-ISSUES-<block id>.md, a fix-mode plan file develop builds as it is. Before, new issues went to one NEW-ISSUES.md that you moved and renamed before the next run.
• develop's relaunch steps run in a working order. The guide and the engine's hand-back say to run plan-edit.mjs args, set the block back to todo, then run plan-edit.mjs args again for the launch args. Before, the block was set to todo first, so the status fold marked it parked or blocked again.
• A fix pass that reports a regression and stages nothing stays open. Before, it marked its block done and its fixes fixed.
• plan-block.mjs --list rejects a todo fix block with no ### [<id>] entry. Before, develop halted on that block in round 1.
• develop's blind reviewer runs at most one targeted test. It is told the gates already ran.
• develop's agents read the plan block from a file. They redirect the plan-block.mjs output to a file, since the Bash display cuts long output.
• develop's acceptance counts a doc sentence the cycle made false as a regression. This covers a comment or doc sentence that was true before the cycle. A line number another file cites does not count, since every edit moves lines.
• debug's guide ends with triage and one handoff to develop. The develop guide holds the build steps. The return's nextStep names the failed units to re-review before triage, since a re-review rewrites each re-reviewed unit's issue file.
• debug review returns counts only. The issues index is gone from the return, so triage reads the issue files. The verifier no longer writes a - theme: line. Issue files written before still parse.
• gen-units takes one --unit-loc flag. It replaces --cap-loc, --big-file and --pack-loc. --no-pack turns packing off. A retired flag exits 1 and names its replacement. Any other unknown flag exits 1.
• enhance's verifier applies the impact floor. It rejects a proposal below the floor in the lens file's ## Rejected section, and the return no longer carries belowFloor. A defect the verifier finds goes under a new ## Defects to route section, for the debug workflow.
• docs scrubs only web captures. Repo and local file captures are not scrubbed. A gap-fill round spot-checks only the files it captured. INDEX.md lists the files that failed the spot-check and the sources it could not reach.
• decide and investigate take the rubric as a file. Pass its path as planPath. The inline requirements and criteria args are gone.
• decide halts when the decider or reviewer does not confirm its write. Before, the next stage read that path, which could hold an earlier run's file. The hand-back that says to raise maxRounds also says to pass resumeFromRunId, so the relaunch keeps the finished rounds.
• investigate re-judges earlier verdicts on resume. The first critic of a resumed run re-judges every option file and re-opens every ledger line the current criteria no longer disqualify. So a criteria edit between runs reaches every earlier verdict. A resume after an investigator's escalation re-runs that round, so its investigator reads the review it was handed.
• investigate keeps an unlisted option out of options. A verified option that a later critic neither lists nor disqualifies stays out of the answer set, and the log names it. A later critic that lists it restores it. The return no longer counts near misses. The determination's NEAR MISSES section lists them.
• A relaunch keeps its runId. A runId names one piece of work. A relaunch of that work keeps the runId and passes no resumeFromRunId. A replay also passes resumeFromRunId, so the finished agents return from cache. New work takes a new runId. No guide says to clear run-state. Its ledgers keep the earlier dismissals that a relaunch reads.
• The guides defer the hand-back to the return's nextStep. This covers brainstorm, debug, decide, docs, enhance and investigate. Each nextStep now carries the counts and steps its guide held.
• The refine guide and README name where to read each halt. For needs-answers, they point at the QUESTIONS section of the last critique. For dismissal-contested, they point at the newest entries in NEEDS-USER.md, since that file keeps every earlier halt's entries.
• refine's critic grades every wrong instruction major or higher. Before, a wrong instruction the gate would catch went ungraded. Two instructions in one block that cannot both hold count as a wrong instruction. Each critique re-lists every below-floor item that still holds, so the last critique lists all of them.
• develop's guide says how to resolve an acceptance-regression halt. That halt leaves the block staged but marks it blocked and its fixed issues needs-attention. The guide gives the steps to keep or reject the work. The halt reason no longer says to relaunch with startAt, which would skip a rejected block.
• A relaunch with nothing to build says when the coverage sweep did not run. The goal-coverage sweep runs only at the end of a run that builds a block. So after a halt you resolve by hand, the relaunch says to check coverage against the goal yourself.
• develop's fixer adds a piece the plan's text left out without an amendment. An amendment is only for a plan instruction that is itself wrong.
• debug's verifier writes a Fix that covers every file its issue calls wrong. Before, a Fix could tell the fixer to leave such a file unchanged.
• docs says which files a rerun may delete. A run into a folder that already holds a set re-curates that set under the new brief and may delete from it. Only content that is neither a source capture nor a file the curator wrote is left untouched and reported.
• The READMEs and skill descriptions follow the house style. They have no mid-sentence colons or filler words, and every fact is kept.

2026-10-07

• develop's fix acceptance records an older, separate harm as a new issue. A harm an issue entry lists whose cause shares no code path with the fix's root cause no longer counts against the fix. The verifier appends it to NEW-ISSUES.md for your triage, and the return counts it in newIssues. Before, the verifier had no rule for that harm, so it could fail a fix whose own root cause was closed.
• investigate reads its answer set from the option files. The critic writes its verdict as the first line of each option file it judges, verdict: upheld rN or verdict: disqualified rN. The return's options is the list of upheld options from the latest critic that attested its review file, so a resumed run keeps the options earlier runs verified. options is null when that set is unknown. A run's first round runs the critic unless its investigator stops the run first, so the critic judges any option file an interrupted round left unjudged. After a critic's unattested write, you no longer move its review file aside before the relaunch. The stalled status no longer ends with stopped unverified, since a stall in a run's first round still ran the critic.

2026-10-04

• develop halts when a reviewer breaks its contract. An acceptance verifier that fails a block but stages it halts the run as rejected-staged. A quality or acceptance reviewer that fails a block without confirming its review file halts it as review-unwritten. Before, rejected work could stay in the accepted baseline. The next developer could also read a review file nobody wrote.
• develop checks staging before a needs-user escalation. A developer that escalates without confirming its work stayed unstaged halts the run. Before, an unordered run parked the block and continued over the self-staged work.
• A fix block that reports STALE beside SKIPPED entries in round 1 reaches acceptance. It lands done once acceptance confirms each STALE claim. Before, it ended blocked and no relaunch could land it.
• develop's reviews miss less. A round that answers a failed acceptance gets a blind review. Feature and section acceptance fails any change no blind reviewer judged. A quality verdict of clean beside a finding or contest count goes back to the developer. A fix the developer reverted and reported FAILED no longer holds its block open.
• develop flags more of its own contradictions. An acceptance pass that counts gaps is flagged. The followups name a park that confirmed no clear, so they never call that block's work nothing to save.
• develop keeps long block ids apart in its run-state files. An id past 60 characters keeps a hash of the whole id in each file name. Before, two ids that shared their first 60 characters shared one DISMISSED ledger, one parked patch and the same review files.
• develop blocks may edit documentation. Acceptance judges a doc edit only against its block's criteria or fix entries. The blind reviewer checks a doc hunk the way it checks a comment hunk. Before, the develop guide kept hand-written docs out of blocks.
• debug review records every gap in its coverage. failed also lists a clean unit whose reviewer wrote no marker and a unit whose verifier missed or miscopied a finding id. gen-units.mjs skips symlinks and junctions, as git does, so a dangling or cyclic link no longer crashes it.
• decide reports what its agreement rests on. The return carries failed (lenses left out of the decision), contradicted (the reviewer agreed while listing gaps) and meetsAllRequirements (the decider's own rubric check). chosen and shortlist come from the latest round only. A run of one round no longer gets an UNDER-SPECIFIED diagnosis it has no evidence for.
• enhance never reports a path or a count it cannot back. A verifier that did not confirm its proposal file lands its lens in failed. A lens whose candidates all sat below the floor reports file: null. summary.unjudged counts candidates the verifier returned no verdict for. A run where every lens failed says nothing was audited.
• docs returns gatherFailed and scrubFailed. The hand-back warns first when a gatherer or a scrubber returned nothing.
• investigate halts on an unattested write. An investigator or critic that does not confirm writing its files ends the run BLOCKED before its output is used. The critic counts the candidates it flags for reopening in reopened. Any flag keeps a termination claim from ending the run. An invalid phase throws. The hand-back of a run that spent its round budget no longer calls a determination partial when it asserts a claim the critic rejected.
• investigate continues its round numbers on a resume. phase:"run" requires priorRounds, which is 0 for a new search and the value the last return's nextStep names on a resume. The first resumed investigator reads the last run's review. Before, a resume restarted at round 1, wrote over the earlier review files and repeated the r<N> labels in SEARCHED.md.
• refine gives a contested dismissal its own status. The editor's escalation halts as dismissal-contested. A USER-RULED: line in DISMISSED-PLAN.md records the user's ruling. No later critic contests it.
• wt's hook self-test never pops your own stash. prep stashes its probe file with --all, so a repo that ignores the probe still exercises the hook. When git makes no stash entry, prep exits 40 and says the hook was never exercised. Before, git stashed nothing when the repo ignored the probe. The self-test then popped your own top stash into the new chain worktree.
• wt land refuses work that was not accepted. After it commits a chain's accepted index, land exits 40 while the chain worktree still holds unstaged or untracked work. Its message says to stage that work when it passed review, or to save it outside the tree. Before, the gate judged that work while the land merged only the commit, so a green gate could rest on a change that never landed. land also sees untracked files when status.showUntrackedFiles is no.
• wt init refuses a relative core.hooksPath. Git resolves a relative hooks path inside each worktree, so one hook cannot guard every chain. init exits 40 before it creates any worktree, and its message asks for an absolute path. Before, init wrote the hook inside the integration worktree only, and every prep then failed with advice to re-run init.
• A flow map counts a loop into a fan-out once per round. Before, a back edge into a fan-out of several lanes counted one traversal per lane, so a loop of two rounds could read ×3.
• The enhance and debug flow maps give a dead agent its own terminal. A dead enhance finder ends at a terminal that says its lens was not audited. A dead debug reviewer ends at a terminal that says to re-review its unit. Before, both maps drew the dead agent onto the terminal for a lens or unit with nothing to report.

2026-10-03

• refine grades a gap by its impact. A crash, lost or corrupted data, or wrong output on an input the repo or the plan accepts is its own defect class. It grades major unless the block's gate catches it, and the size of the fix never lowers a grade. Before, a crash on half of a valid seed range was graded minor and never folded.
• refine counts its FYI items. The return carries belowFloor, so a converged plan with unfolded findings says so.
• debug grades on a written impact scale. Its reviewer and verifier share one definition of critical, high, medium and low. A crash or wrong output on an accepted input is high, and lost or corrupted data is critical, so the default medium floor never drops either.
• develop's acceptance verifier counts every defect it writes. A regression the block prescribes or no current caller reaches is a gap. The developer fixes it, or escalates it to you when the fix needs major changes outside the block's scope. Before, the verifier could pass a block and list real regressions as notes.
• Principle #14 covers severity scales and uncounted findings. A severity scale grades by impact, and a judge counts every defect it writes.
• Principle #4 covers an agent's attention. A tool or runtime limit is fixed in the tool or the engine, so no prompt carries a workaround for it.
• decide's reviewer counts every concern it writes. A concern blocks agreement, so none reaches the user unread in an agreeing review.
• develop's status lines stay under the runtime's log cap. A block with many issue edits logs them over several lines. Before, the runtime could cut one long line, and plan-edit.mjs args then failed with a JSON parse error on that run's record, whatever the run's status.
• develop keeps room for its status lines inside the runtime's first 1,000 log lines. Progress lines stop at 900. A run of several hundred blocks stops before a block once no room for a status line is left, and a relaunch builds the rest. A block whose status lines overrun the cap halts the next block, or skips the goal-coverage sweep when it was the last block.
• investigate counts the defects its critic finds in the determination. The return carries determinationDefects. The hand-back of an exhaustive, no-solution or saturated run says how many there are and where to read them.

2026-09-30

• Leaner prompts. Each engine's agent prompts are 6 to 14 percent shorter, and so are the skill descriptions Claude keeps loaded. The concision pass changed no rule.
• docs drops a superseded recapture. The round-2 curator reads the previous INDEX.md. When a gap-fill file recaptures a flagged source, the curator deletes the superseded file and drops it from the index.
• A parked block's resume step names the status flip. Park's note and develop's followups tell you to flip the block to todo before you relaunch it with runOnly. runOnly selects only todo blocks.
• A dirty tree at launch never parks your edits. develop now checks for a clean tree before it checks the plan. Before, a developer that stopped at the tree check was reported as unable to read its plan, and park moved your own edits into a patch.
• Park leaves a clean tree. It saves a block's new files even when the block changed no tracked file, and it removes git add -N entries along with their files.
• investigate reports a verified no-solution as one. A no-solution that rests on criteria nothing can meet no longer ends as blocked on you.
• The plugin grant follows links. When the plugin folder is reached through a link, plugin-access.mjs adds a rule for both paths. A skill skips the question when its working directory is the plugin folder or a folder that contains it.

2026-09-29

• Installed skills launch their engines from any project. Before this, a skill run outside this checkout failed with "scriptPath must be a script path this tool returned, or a file you can already read". Each skill now runs tools/plugin-access.mjs first, which adds one Read rule for the plugin folder once you agree. See Install (plugin).

2026-09-26

• Statuses reach the plan file on their own. plan-edit.mjs args <plan> is the step before every develop launch. It applies the statuses of every finished develop run from the run records Claude Code keeps, then prints develop's args. This works for a run that failed or was stopped too, and the sync command is gone.
• Small fix blocks share one pass. plan-edit.mjs args --pack <repo> groups triaged issue files into passes of up to 5000 lines of touched code, so one developer, one reviewer and one verifier build several small blocks. Each block keeps its own file and statuses.
• enhance rejects a proposal whose risk outweighs it, and counts them in summary.tooRisky.
• Prompt snapshots. tests/snapshots/<engine>.prompts.md holds every distinct prompt each engine sends, so a prompt change shows in the diff under every mode and round it reaches.
• tools/freeze-notes.mjs copies an engine for a live test in which every agent reports what in the workflow was unclear or wasteful. It now reaches every agent, including brainstorm's.
• A question for the user no longer stops an unordered develop run. The block is parked and marked blocked, and the remaining blocks continue. An ordered run still stops there.
• Launch every workflow from a notification turn. Claude Code copies the launching turn's user message into every agent's prompt, so a run is now launched in the turn a background pre-launch command's notification starts. develop's sweep runs on opus for the same reason.
• refine flags a block that relies on text outside itself, since develop hands each agent only its own block.

2026-09-25

• feature, migrate and debug's resolve are retired, and develop replaces all three. A block's mode picks the job. feature builds one bounded change, section converts one slice of a migration, and fix works a triaged issue inventory. refine replaces feature's refine phase. A plan written for feature or migrate needs ## Plan: headers with a preamble gate: line.
• gauntlet is retired with no successor.
• plan-block.mjs has one keyword. --kind now fails with a message, and a ## Gate heading is body text. Every block is ## Plan: with its gate in the preamble.
• develop returns statusSync, every block and issue status a run decided. A fix block that did not land marks its fixed issues needs-attention, never fixed.
• Section files default to suite: scoped, so a migration's intentionally red suite no longer fails a green gate. A sweep: goal-coverage file needs a goal: line.
• develop carries the failure-path tests of the three engines it replaced, including dead reviewers, the plan amendment protocol and fix-mode agent deaths.
• develop's acceptance confirms every STALE claim. A fix block whose developer calls every entry stale now goes to acceptance, and a refuted claim never syncs stale. A block that passed but was left unstaged syncs done, so the documented recovery is to stage it and relaunch.
• debug review keeps every finding. Distinct findings in one file and category all reach the verifier, which folds true duplicates. A dead reviewer or verifier is returned in failed and is never counted as a clean unit. Colliding unit ids and an invalid reviewSeverity fail at launch.
• Agent prompts were tightened from the agents' own reports. Live runs asked every agent to note workflow problems from its seat. Those notes fixed the blind reviewer's scope and gate commands, refine's grading and one-fix-per-gap rules, and review's dangling marker and context-read rules.

2026-08-29

• develop gained fix mode, and debug's verifier writes plan-bus fix blocks. Each issues/<unit>.md is now a ## Plan: fix-mode block develop builds directly: its fix worker verifies each ### [<id>] entry still exists (vanished = stale), fixes ACTIONABLE decisions only, and returns per-issue results the operator syncs back into the file's - status: lines with plan-edit.mjs. Two new round-1 terminals: an all-stale block is done without reviewers, and an all-skipped block is blocked, never silently done. resolve-cycle still works unchanged during the transition.
• New engine: refine, a converging plan review replacing feature's phase:"refine" (which never converged, since five runs on one plan kept adding detail). A read-only critic judges every todo block under a fixed defect bar and severity floor, writing findings to a critique file. A minimal-fold editor changes nothing a gap does not name, declines to a ledger, and re-validates the plan through plan-block.mjs after every fold. One clean round ends the loop. Structural findings (block order, an oversized block, a gap in an already-built block) come back as questions instead of edits.
• New engine: develop, the merged successor to feature's build phase and migrate's run phase. It builds the status: todo blocks of one approved plan file, each block's mode picking the engine-held frame (feature or section), with the file keys (ordered, suite, sweep, goal) deciding park semantics, suite strictness, and the whole-goal sweep. New hardening over its parents: a missing unstaged attestation now halts, and a flagged block is re-reviewed even when a later round produces no changes (migrate received the same fix). feature and migrate stay runnable during the transition.
• plan-block.mjs reads the plan-bus metadata grammar. First step of the plan-bus rework (one develop engine consuming plans every workflow produces). The default kind now parses file keys (goal, ordered, suite, sweep), a block preamble (mode, gate, status), and ### [<id>] issue entries in fix-mode blocks. --list emits one object, the file keys plus a blocks array, instead of the old array. --kind section and --kind component are unchanged transition aliases. Unknown keys, illegal values, and duplicate ids across the block and issue namespaces all fail loudly.
• New tools/plan-edit.mjs, the one tool that writes plan files. set upserts one block or issue metadata line. move relocates an issue entry between blocks or files (a cut, never a copy). A separate file from the read-only tool agents run, so the run-time allowlist rule never covers a write.
• feature throws on a malformed plans arg. A plans present but not a non-empty array used to fall through to the single-plan path and build the whole roadmap as one plan at exit 0.

2026-08-06

• Every blind reviewer is now blind by placement (feature, migrate, debug's resolve, following gauntlet's precedent). The blind prompt's only run-state paths point into runs/<runId>/gate/ (its review files + DISMISSED-* ledgers). NEEDS-USER, AMENDED, critiques and debug's issue files all live outside it. This closes a real leak, where the AMENDED pointer line in NEEDS-USER.md handed the blind reviewer a route to verbatim plan text. It also closes debug's documented instruction-only-blindness gap. Principle #5 amended to match (blind stage reads the gate-scoped ledger, and acceptance reads ledger + user notes). Breaking only for in-flight runs resumed from the old layout.
• Agent-reported preconditions are value-guarded in feature/migrate/resolve. The Number() / ?? -1 coercion on baseline_dirty_files (and resolve's issue_entries_found) is replaced by the typeof guard gauntlet shipped. null/false/''/[] now warn ("precondition was NOT verified") instead of silently reading as a clean tree. Resolve's schema now requires both fields.
• Flow maps: at most one label per node pair, ever. The second labeled edge of a boundary+back pair carries a bounded E<n> marker with its full conditions in a new ## Edges table, and the boundary edge of a marked pair renders caption-less (the table's fixed sentence carries the next-item advance). Mermaid places both labels of a pair at the same midpoint, so one label per pair is the only shape that cannot collide. All 10 maps measured overlap-free with tools/render-flows.mjs. Also: plan-block.mjs + wt.mjs CLI entry detection is symlink-proof.
• New workflow: gauntlet (/aipg:gauntlet) adapts the Gauntlet Loop pattern (builder + fresh blind critic vs. an inspectable exemplar) to the house principles. phase:"mvp" builds an approved COMPONENTS.md decomposition to a working, code-sound alpha. Each component goes builder → blind code gate (defects AND structural debt) → staged. A component that cannot pass parks and STOPS. phase:"refine" is also the entry point for an existing product. It climbs the staged product toward BAR.md in waves. In each wave, one fresh critic per open quality aspect observes the RUNNING product with its own persistent testbed/ tooling, A/Bs it blind against the exemplar, and names ONE largest gap with evidence. An improver closes only that gap. Then the wave diff is blind-reviewed and staged. cycles (the wave budget) is required with no default, since you are the brake. Every stop lands on a staged clean tree, so resume = buy more waves (startWave). No mid-run user escalation by design. Agents settle judgment calls via decision matrix into SETTLED.md, the end-of-run audit. Only environment faults halt. Ships with plan-block.mjs --kind component, 49 flow scenarios, and full dead-agent coverage. A rendering overlap noted here at ship time was closed the same day (see the flow-maps bullet above).

2026-08-02

• All eight skills are model-invocable, and the auditor agent is gone. The three build skills' disable-model-invocation flag also hid them from Claude's context, so calling one out by name ("use the aipg feature workflow") only worked as a slash command. The flag was dropped. The opt-in gate is each description's "only when the user explicitly asks" clause, which tests/skills.test.mjs now enforces in the new direction. The workflow-principles-auditor agent, which registered in every project a user-level install touched, was deleted. Audit an engine by running debug with principles/WORKFLOW-PRINCIPLES.md as a lens, keeping the principles doc the single source of truth.
• Principle #15 is now machine-checked, and the plan-defect wedge is closed (batch h2, phased). tests/dead-agent.test.mjs kills every agent role once per engine and demands a visibly different outcome. Building it exposed and fixed four real launderers (feature-cycle's dead develop/quality/ acceptance read as done (staged), and docs-cycle's dead scrubber logged ✓ scrubbed: 0 file(s)). And a blind-review finding that indicts the PLAN's own text is no longer a dead end: a developer that VERIFIES the defect fixes it and records the override in AMENDED-<id>.md (read by acceptance, never the blind reviewer), so the wt-land-style wedge cannot recur.
• First live parallel batch shipped two hardening features (planpath-guard + attestation-scoping), built simultaneously in worktrees and landed through aipg/int-h1. This was the wt.mjs lifecycle's own shakedown. In the first, feature + migrate now warn when a plan file resolves inside target.repo (blindness by placement made structural). In the second, the attestation sweep binds each schema's consumer check to its agent() call's receiver variable (closing the shared-field-name mask, and three previously-hidden dead notes fields got real consumers).
• Every code-review role now runs on opus (feature/migrate/resolve blind quality critics + debug's review finder). Measured on the wt-tooling build: the fast tier surfaced one deep-verified defect per round on large diffs, serializing discovery across rounds and burning the round budget.

2026-08-01

• Parallel runs via batch worktrees: tools/wt.mjs + docs/worktree-batches.md. Run several engine runs at once, each chain in its own git worktree (init/prep), landed one at a time into a per-batch integration branch (land: index-only accept commit → sync → gate on the merged state → merge, serialized by a heartbeat-liveness lock) and cleaned without --force so unlanded work is refused, not deleted. A reference-transaction hook refuses git stash inside aipg-* worktrees, since refs/stash is the one stack every worktree shares. A stray pop would inject one chain's work into a sibling's blind-review diff. Built from the worktree-parallelism-1 decide run (E-c). The engines are unchanged, since a worktree is just a different target.repo.
• New principle #15: "A missing result is its own outcome." A dead/null agent must never be conflatable with success, a clean verdict, or an empty result. Every agent() consumption site states its death policy (solo critical → throw, build loop → park, auxiliary → log + record), write-attestations must be consumed, and any failure resumes through the same clean-tree + durable-trail mechanism as everything else. A debug run over the engines themselves found and fixed the five engines that violated it (gate and numeric-arg validation, plus dead-agent visibility guards in review, resolve, enhance and migrate).
• Plan mode is now the agent's judgment call (feature + migrate guides). Default INTO plan mode when the task is complex, needs the user's answers, or touches something important. Skip it when simple, obvious, or already planned. The user always has the final say. A plan authored without plan mode lives at plans/<runId>/ under root (the plugin data dir when installed), same rules as snapshots.
• The repo is now a Claude Code plugin (aipg) and its own marketplace (aipromptguide). /plugin marketplace add Blakeem/aipromptguide-workflows → /plugin install aipg@aipromptguide. The copy-me command templates in commands/ became plugin skills (skills/<x>/SKILL.md), so the triggers are now namespaced: /aipg-feature → /aipg:feature, and likewise for all eight. A bare checkout still works as before (root CLAUDE.md router, root = the checkout). The old copied /aipg-* commands keep working against a checkout but no longer ship.
• Run-state moved out of reach of plugin updates. Installed, the engines live in the version-swapped plugin cache. The skills therefore point root at the plugin's persistent data dir (~/.claude/plugins/data/…), where runs/<runId>/ and plans/<runId>/ survive updates. Those folders also stay outside every target repo, where the blind reviewer cannot reach them.
• feature and migrate take blockTool (optional): the absolute path to plan-block.mjs for the roadmap/section block command, defaulting to <root>/tools/plan-block.mjs as before. Required in practice when root is not a checkout (the plugin data dir has no tools/). The skills pass it automatically.
• feature and migrate document an autonomous path for when the user hands a finished plan (or says to run unattended). The path is to skip plan mode, snapshot the plan to plans/<runId>/ if a reviewer could reach it (inside target.repo or runs/), refine as usual, resolve refine's questions conservatively when unattended, then build. Approval comes from the user's own plan. The blind reviewer still never sees one.
• The official Claude Code plugin docs are captured under docs/claude-code-plugins/ (verbatim, via docs-cycle) for building against.

2026-07-29

• investigate knows when to stop looking, and says so without claiming it finished. Two new terminal states, never folded into "exhaustive". stopped on saturation: from round 2 the investigator watches its own yield collapse, writes a determination with a new WHERE NEXT section (the unswept avenues, and the premise change that would open new space) and the critic verifies the collapse before the run ends. The search is reported open, not closed. stalled: a round that adds nothing at all (no option, ledger line or claim) stops the run immediately instead of buying another empty round. A round that rules candidates out is still progress and keeps going.
• investigate remembers which ground it swept, not just which candidates died. A second append-only file, SEARCHED.md, records every avenue each round covered, with the search terms it used and what they yielded. It also records the most promising avenue still untried. Until now that survived only in the terminating round's determination, so every other round was free to re-run the last one's searches with the same terms and call the same candidates new.
• A coverage contest now costs the critic a citation. Contesting "the search is finished" used to be free: name any avenue, buy a whole round. It must now carry a source and locator connecting that avenue to the criterion or search-space bound it puts back in play.
• decide says why it could not converge instead of guessing. The reviewer now slugs every gap it raises, so a run that spends its round budget can tell two opposite failures apart. One is the same gaps coming back (the decider is not resolving them, and the hand-back names them and the reviews that first raised them). The other is new gaps every round (the question is under-specified). The per-round split is on the return as gapRounds. The last non-agreeing review ends with a WHERE NEXT section, which names the requirement axis the rubric does not settle and the change that would let a decision converge.

2026-07-28

• investigate produces a real determination. DETERMINATION.md now has a fixed shape of the qualifying options, a comparison over the axes they differ on, which to pick when, the near misses, and the coverage evidence. It is written even when the search runs out of rounds (labelled a partial result) instead of leaving you a folder of option files with no comparison. Options stay unranked on purpose: qualification is pass/fail, and ranking is decide's job.
• investigate keeps near misses. A candidate that failed exactly one criterion is marked in the ledger with the shortfall in numbers and gets its own section in the determination. When nothing qualifies, that is usually the most useful thing the run found, since it is what relaxing a criterion would put back on the table.
• Fixed: investigate could report an option the critic had disqualified. A later round knocking out an option an earlier round upheld left it in the answer set, contradicting the run's own ledger.
• Fixed: a malformed maxRounds silently did nothing. A non-number coerced to NaN and the round loop exited before its first pass. In investigate, decide and docs the run finished having spawned no agents at all and reported it as an ordinary "ran out of rounds". In feature, migrate and debug/resolve the unit parked without a developer ever running. All six throw now, as do values that merely coerce to a legal number ("", false and [] are each 0) and used to switch off a budget floor or docs' verbatim spot-check.
• enhance reports what its impact floor cut. Candidates below minImpact are removed before verification and appear in no proposal file, so a floor set too high used to look identical to a clean system. summary.belowFloor tells you which one you are looking at.
• A feature roadmap is ONE approved plan file of ## Plan: <id> blocks, with no more hand-splitting into per-feature files. Each agent in feature and migrate is handed a command that prints only its own block, so the other units never enter its context.
• Flow maps render reliably. Self-loop conditions moved into a Loops table below the diagram, so a long label can no longer land on a neighbouring box. All nine render clean on both the current Mermaid and the version GitHub serves.

2026-07-27

• New workflow: investigate (/aipg-investigate) finds an answer that already exists and qualifies it against pass/fail criteria, stopping when the search can be evidenced as complete rather than when the first answer works. "Nothing qualifies" is a verified result, not a failure. Use decide when the work is weighing trade-offs instead.
• Every workflow ships a flow map. A FLOW.md beside each engine (linked in the table above) diagrams every agent, gate, loop and terminal state, rendered inline by GitHub. They are generated by watching each engine run, so a diagram can only show a path that really executes. Worth reading before a run you haven't done before: the terminal states are where two very different outcomes read alike.
• Fixed: dead agents reported success. In feature and migrate a refine plan critic that died returned a verdict indistinguishable from "your plan is sound". In migrate a died final sweep read as zero coverage gaps. Both now fail loudly instead.
• Fixed: migrate told you to resume into a red build. A parked section that cleared the tree but left the build broken now halts as unsafe, matching feature and debug.

2026-07-26

• New workflow: enhance (/aipg-enhance) audits a working system for enhancements worth writing up, and stops for you to triage. Defects still belong in debug.
• Work is never discarded. A feature, section, or fix batch that can't pass is now parked: saved to runs/<runId>/parked-<id>.patch, cleared from the tree, with the git apply restore command written into NEEDS-USER.md. It used to be rolled back and lost. A parked feature no longer stops a feature roadmap either. feature parks that plan and builds the next one. migrate still stops, because its sections depend on each other.
• The build engines check your working tree first. A dirty tree halts before any agent does work, naming the two commands that fix it, rather than reviewing your uncommitted changes as its own.
• target.repo is now required on every engine that writes code, instead of quietly defaulting to the checkout's own folder, so a typo can't retarget the wrong project (see One checkout, many projects).
• debug's review pass takes a lens array to sweep the same code from several angles in one pass, merged into one issue file per unit. It also returns the issue index, so there's no hand-grepping to build the fix loop's input.
• decide gains selection: "ranked", which returns a ranked shortlist instead of one winner when the answer is legitimately a portfolio.
• docs spot-checks captured files against their source, so the verbatim promise is tested rather than asserted.

Earlier

• 2026-07-07. The research workflow became docs, which captures docs verbatim, then curates and indexes them.
• 2026-07-04. Renamed upgrade → migrate and review → debug. feature gained the plans roadmap, so several approved features can be built in one run.
• 2026-07-01. decide gained a testbed so claims get measured instead of asserted.

Requirements

• Claude Code with the background Workflow capability.
• The target is a git repository (staging is how regressions are caught, and you do the commit).
• Build and test commands for your project. You provide them, and the engines run them and read pass/fail.
• For frontend work: optionally a browser/MCP driver (Chrome DevTools MCP, Playwright, MCP inspector), else a curl/manual fallback.

Support

If these workflows save you time, you can sponsor their development via GitHub Sponsors.

License

MIT © Blakeem