Dev flow

Use ap-dev-flow when you want a coding agent to build a change in deliberate steps you can inspect: research, a written plan, an independent plan review, your approval, implementation one task at a time with a review of every task, a review of the whole change, and a final verification run.

Every step is a separate skill. ap-dev-flow only sequences them, so you can also run any single step on its own.

When nobody is available to approve the plan, ap-dev-flow-auto runs the same pipeline without questions and ends with an open draft pull request.

Start a run

ap-dev-flow runs only when you name it, because its subagents create commits:

Use ap-dev-flow to add CSV export to the reports page. Use main as the base
branch.

The pipeline needs a coding agent that can start subagents (isolated helper agents). Without them it still researches and plans, then stops before the plan review instead of reviewing its own work.

The stages

Step	Skill	What happens	Saved as
1. Research	`ap-dev-research`	Reads the code and current documentation. Every finding must cite a file or source; unsupported claims are labeled as assumptions.	`01-research.md`
2. Plan	`ap-dev-plan`	Opens with a plain-language summary of what will change and the decisions you are approving, then phases of numbered tasks. Each task lists its intent, test cases, files, and one command that proves it works; each phase ends with a verify command.	`02-plan.md`
3. Plan review	`ap-review-plan`	A fresh subagent reviews the plan. Required changes are applied and a new reviewer checks again, for up to two rounds.	`03-plan-reviews/r01.md`, …
4. Your approval	—	The agent shows the plan’s summary, the task titles, and the review verdict, and waits. Nothing is implemented before you approve.	`meta.yaml`
5. Implement	`ap-dev-implement`	For each task: a fresh implementer writes and commits it, its verify command must pass, and a separate read-only reviewer checks it. Each phase’s verify command must pass before the next phase starts.	`04-implementation-ledger.md`, `tasks/`
6. Integration review	`ap-dev-review-code`	A fresh reviewer examines the whole change for problems that span tasks, using the `ap-code-reviewer` subagent when installed.	`05-code-reviews/r01.md`, …
7. Verify	`ap-dev-verify`	Runs the plan’s acceptance commands and records each result.	`06-verify.md`

At the end the branch is ready. The agent offers to open a pull request and does so only if you agree; the PR description then includes the plan and the verification results. It never pushes, merges, or deploys on its own.

If a stage skill is not installed, ap-dev-flow names the missing component and offers to install it instead of doing that step itself.

Run it unattended

ap-dev-flow-auto is an optional skill that runs the same seven stages with nobody watching:

Use ap-dev-flow-auto to add CSV export to the reports page.

The review bar does not change. Every task still gets an independent review, and the whole change still gets an integration review and acceptance verification. What changes is what happens where a human used to be:

	`ap-dev-flow`	`ap-dev-flow-auto`
Plan approval	You approve it	A machine gate: `ready` with zero blocking findings, or the plan is revised and reviewed again
Questions during the run	It asks you	It never asks; open questions go on the pull request with the assumption taken
Plan review rounds	2	4
Integration review rounds	2	4
Verification repair waves	2	4
Task repair rounds	5	5
Finish	Branch ready, offers a pull request	Branch pushed, draft pull request open

The plan gate is deliberately strict. A plan passes only when a review round comes back ready with no blocking findings. A ready with changes verdict is not a pass: the changes are applied and a new reviewer looks again. If four rounds go by without a clean verdict, the run stops instead of implementing a plan nobody approved.

What it may and may not do

Naming ap-dev-flow-auto authorizes it to push the branch it creates to your default remote and to open one draft pull request from it. That is the whole grant. It does not merge, publish, deploy, force-push, rewrite remote history, or push to your primary branch or any branch it did not create.

A stopped run opens no pull request. If a cap runs out or a defect has no credible fix, the branch and the run folder are left exactly as they are and the agent reports why. You pick the work up from there.
Ask for no pull request and it stops at a ready branch, writing the pull request body to 07-pr-body.md in the run folder instead.
It checks before it starts that subagents are available and that gh is authenticated, and refuses to begin rather than running for an hour and then discovering it cannot finish.

The pull request body carries the plan, the verification table, every carried question with the assumption taken, and every unresolved finding with its ruling — so the work survives even after the worktree is removed.

Reviews and repairs

Two kinds of review are intentional:

Task review checks one task’s diff against that task. If it finds a problem, the task goes through up to five repair rounds, each followed by a new reviewer. Rounds 1–3 go back to the original implementer; rounds 4–5 use a fresh, more capable one. After round five the agent records a decision on each remaining finding and stops only if no credible correction exists.
Integration review checks the accumulated change. Critical findings block; High or Medium findings require a repair; Low findings alone pass. Up to two review rounds are allowed, or four under ap-dev-flow-auto.

Reviewers never edit code, and a reviewer never reviews its own or a previous reviewer’s work. Every decision the agent makes on your behalf is recorded as a ruling with its cost if wrong and listed in the final report.

The run folder

ap-dev-flow works in one dedicated Git worktree, set up through ap-start-dev-session, and saves the run at the root of that worktree:

.agents-pack/runs/2026-09-19-csv-export-a3f2c1/
├── meta.yaml                  # goal, branch, paths, round counters, status
├── STATUS.md                  # short human-readable status
├── 01-research.md
├── 02-plan.md
├── 03-plan-reviews/r01.md
├── 04-implementation-ledger.md
├── 05-code-reviews/r01.md
├── 06-verify.md
└── tasks/                     # per-task briefs, reports, reviews, diffs

A .gitignore inside .agents-pack/runs/ keeps run files out of Git. You do not need to edit your own .gitignore.
To continue in a new session, start it in the same worktree, or give the agent the run path. It resumes from STATUS.md without repeating finished work.
Removing the worktree removes its runs, so keep the worktree until the branch is merged.
Use ap-clean-dev-runs to list old runs and delete the ones you choose. It shows what it would delete first.

Run one stage on its own

Each stage works without the orchestrator. Give it a run folder, or let it answer in the conversation:

Use ap-dev-research to find how authentication is wired before we plan SSO.
Use ap-review-plan to critique docs/plans/csv-export.md.
Use ap-dev-implement to execute docs/plans/csv-export.md.
Use ap-dev-verify to run the acceptance commands in the current run.

Plan review is critique-only on its own. It reports a verdict and a corrected plan but does not edit your plan unless you ask it to apply the changes. Under ap-dev-flow it applies them.
ap-dev-implement runs only when named and needs a dedicated feature worktree. Given a plan outside a run, it creates a run folder and copies the plan into it.

Coming from subagent-driven development

ap-dev-implement replaces ap-subagent-driven-development. It keeps the same authority rules, task loop, and repair limits, and adds task and phase verify commands and the run folder. The whole-branch review moved to ap-dev-review-code. See the release notes for update steps.