AI Prompt Guide — Workflows

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

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. 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. decide and investigate: when no established answer exists and the work is weighing trade-offs, that's decide; when the answer is already out there and the work is finding it and proving it fits, that's investigate. The tell is whether missing a requirement is a trade-off or simply 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 actually does — 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 in particular are the part 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. That makes it a linter as much as a picture: 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 actually 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 — nothing to copy, nothing to 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: /plugin marketplace add ./aipg 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-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 — converging plan review, replacing feature's phase:"refine" (which never converged: 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. Closes a real leak — the AMENDED pointer line in NEEDS-USER.md handed the blind reviewer a route to verbatim plan text — and debug's documented instruction-only-blindness gap. Principle #5 amended to match (blind stage reads the gate-scoped ledger; 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) — the Gauntlet Loop pattern (builder + fresh blind critic vs. an inspectable exemplar) adapted to the house principles. phase:"mvp" builds an approved COMPONENTS.md decomposition to a working, code-sound alpha: per component, builder → blind code gate (defects AND structural debt) → staged; a component that cannot pass parks and STOPS. phase:"refine" — also the entry point for an existing product — climbs the staged product toward BAR.md in waves: one fresh critic per open quality aspect observes the RUNNING product with its own persistent testbed/ tooling, A/Bs it blind against the exemplar, names ONE largest gap with evidence; an improver closes exactly that gap; the wave diff is blind-reviewed and staged. cycles (the wave budget) is required with no default — you are the brake — and 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 — 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 registered in every project a user-level install touched — 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); 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 — the wt.mjs lifecycle's own shakedown. The features: feature + migrate now warn when a plan file resolves inside target.repo (blindness by placement made structural), and the attestation sweep binds each schema's consumer check to its agent() call's receiver variable (closing the shared-field-name mask; 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 — refs/stash is the one stack every worktree shares, and 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); engines unchanged — a worktree is just a different target.repo.
• New principle #15: "A missing result is its own outcome — fail loud, resume clean." 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 (dead-agent visibility guards in review, resolve, enhance, migrate; plus gate and numeric-arg validation).
• 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 exactly 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 — and 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 — the user hands a finished plan (or says to run unattended): 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, no ledger line, no 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 — plus 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: the same gaps coming back (the decider is not resolving them — the hand-back names them and the reviews that first raised them) versus new gaps every round (the question is under-specified). The per-round split is on the return as gapRounds, and the last non-agreeing review ends with a WHERE NEXT section — 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 — the qualifying options, a comparison over the axes they actually differ on, which to pick when, the near misses, and the coverage evidence — and 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 — 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 — 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) diagramming 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 — it parks and builds the next plan; 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 — sweep the same code from several angles in one pass, merged into one issue file per unit — and returns the issue index, so there's no hand-grepping to build the fix loop's input.
• decide gains selection: "ranked" — 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: verbatim capture, curated and indexed.
• 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