Make PR
/flow-next:make-pr takes a spec with done tasks and a branch ahead of its base (main, or the parent spec’s branch for a dependent spec), closes the spec on that branch, and opens a pull request whose body is a briefing for the person who has to review it. On a GitLab origin it opens a merge request with the same body.
Creates the PR directly: no confirm gate
Section titled “Creates the PR directly: no confirm gate”Invoking the skill is the intent, so make-pr pushes and opens the PR directly - there is no “create / abort” confirm prompt. The PR opens ready for review unless it has open items (open spec questions, a completion review that needs work, incomplete tasks, other unfinished work), which make it a draft. Deferred findings and follow-ups are listed in the body and are not a reason to draft. The only prompts are Phase 0 info prompts to resolve something it cannot derive (no --base and no detection match, or no spec detected) - never “do you want to create it?”. The escape hatch is --dry-run (print the body without creating), and --ready / --draft force the draft state.
The spec closes at the pull request head
Section titled “The spec closes at the pull request head”When every task of the spec is done, make-pr closes the spec and commits the close as the last commit on the branch, before the pull request opens:
chore(flow): close fn-12-export-json-flagThat is the default message. When your project instructions state commit-message rules, such as a subject length limit or a required work-item reference, the agent writes the close message to follow them, for example chore(flow): close fn-4 AB#1234. If the rules need a value the agent cannot find in the conversation, the branch or the spec, it keeps the default.
The commit carries the spec’s done status and every task’s final status. Merging the pull request carries the close to the base, so a protected base that refuses direct pushes is no longer a problem, and land has nothing to write after the merge.
- The close happens before the body is composed, so the body describes the same head the pull request opens at. If the branch moves between the close and the push, make-pr stops and asks for a re-run.
- A failed close, a failed commit, or uncommitted changes in the spec and task files stop make-pr before anything is pushed.
- A spec with open tasks, or with no tasks at all, is not closed. Interactively it opens as a draft; an autonomous run refuses a spec with open tasks.
- A spec whose configured completion review has not passed stays open too. Interactively it opens as a draft that land will not merge; an autonomous run stops before closing or pushing.
- Once a draft’s work is done and any completion review has passed,
/flow-next:make-pr <spec-id> --updatecloses the spec, commits and pushes the close, and refreshes the body. Marking the pull request ready stays with you. - An already closed spec is left untouched.
--dry-runnever closes. - Creating or starting a follow-up task reopens a closed spec. Finishing that task does not close it again; the next make-pr run does.
In the tracker, a closed spec with an open pull request stays in review. Only a confirmed merge moves the issue to its terminal status.
Dependent specs: chains and stacks
Section titled “Dependent specs: chains and stacks”A spec that depends on another spec (depends_on_epics) gets its PR opened against the parent’s branch, so the reviewer sees only that layer’s diff and the dependent spec never waits for the parent’s PR to merge. Make-pr detects the chain from history, never from recorded state: the merge-base with the parent’s branch tip (or, once the parent merged, its PR head) is the boundary of the parent’s work inside this branch. When the parent’s PR is still open, the base is the parent’s branch; on GitHub the PR is also linked into the parent’s stack through the stacks REST API of GitHub’s stacked pull requests public preview, so the merge box shows the stack map and GitHub owns sequential merge and retarget; the gh-stack extension is never required. A failed link leaves a plain chain layer with one line on stderr, and on any other host the PR is a plain chain layer to begin with. When the parent already merged, a create run rewrites the branch onto the chain base from the detected boundary before opening the PR; --dry-run and --update never rewrite.
One bound: chains are linear, one open parent and one child at a time; the build loop parks a second child until the first child’s PR merges. A chained layer with nothing open opens ready like any other PR, which matters because GitHub cannot merge a draft from the stack UI. --base <ref> still overrides detection. The branch itself is forked by work; merging the chain is land’s job; the glossary defines chain, stack, layer, and frontier.
The briefing, section by section
Section titled “The briefing, section by section”The body leads with what a reviewer needs before opening the diff: where to start, where to look hard, what feedback is wanted and what nobody has proven yet. It never repeats what the forge already shows, such as the changed-file list or line totals. Sections come in a fixed order, and a section with nothing to say has no heading and no placeholder. The excerpts below are from the pull request that shipped this design, trimmed.
Why. The intent and the approach, in the author’s words, with its line breaks kept.
## Why
make-pr's body put the reading order, the risk notes and the unproven checks below a longfile tree, and it repeated the changed-file list and line totals that GitHub already shows. […]Review focus. Where to start reading, one to three places to look hard and why, and the feedback the author wants.
## Review focus
Start with `render_pr_cognitive_aid_markdown` in `plugins/flow-next/scripts/flowctl.py`. […]Look hard at two choices. The validator accepts one new optional field, `changeWalkthrough.shape`,so any consumer that rejects unknown fields has to accept it before it reads new artifacts. […]I would like feedback on the guidance in `skills/flow-next-make-pr/pr-cognitive-aid.md`.Needs you. Every check that failed or was never run, then the open work. This is where the reviewer takes over, so it sits on the first screen.
## Needs you
- [ ] unverified: Live make-pr in this repo: the new guidance was measured on four replayed pull requests […]- Open: flow-next.dev, mickel.tech and the vault follow after merge.Shape. When the change adds or changes a public surface (types, signatures, CLI flags, schema, config keys) or a call path, a short fenced sketch of it, so the reviewer sees the contract before the code that uses it. Every name in it comes from the diff or the spec. A change without such a surface has no Shape section.
## Shape
```text## Review focus changeWalkthrough.blastRadius## Needs you proof cells with outcome fail|unverified, then "- Open: " + openItems## Shape changeWalkthrough.shape (new, optional, one fenced block)[…]```What changes for a user or operator. What someone running the software will notice.
Reading order. The review steps in the order to read them. Each step has a bold numbered title with the requirement ids it serves, one or two sentences on what to check there, and the one file to start at. Steps whose files are all mechanical or generated, and any such files inside other steps, are named once in a closing safe-to-skim line. A declared requirement that no step covers gets its own line, so anything the spec promised and the diff did not deliver stays visible.
## Reading order
**1. Renderer and validator**
Check the section order, that Needs you takes only fail and unverified cells, the start-fileand safe-to-skim rules, and that `shape` must be one fenced block.
Start at `plugins/flow-next/scripts/flowctl.py`
[…]
Safe to skim: the Codex mirror, the tracker manifest, the version files.Tradeoffs. The alternatives that were rejected, and why. An unattended run (flow --auto) also writes its Decisions list here: each default it chose, finding it declined and review it skipped on your behalf, with the evidence behind it.
Verified. The checks that passed, ticked, and recorded facts such as measurements as plain items. Proof comes from receipts, task evidence and CI; make-pr does not re-run tests to fill the body, and a gate with no recorded result shows under Needs you as unverified.
A bug fix adds its own cells. When a task ran the defect route, the checklist carries Prior fixes, Cause (the confirmed mechanism and the commit that introduced it), Base (the observation and the surface it ran through, such as the reported command or request), Head and Live cells. A step that did not happen or a live check that did not run renders unverified with its reason; the full record stays with the task. A hill climb adds cells for the metric and target, the baseline and final values with the percent change, the attempt counts (kept, reverted, inconclusive), the kept commits in order, the harness proof, the final gate and the best untried idea; an unmet target renders unverified, never passed.
A human-only call that blocks nothing else lands under Needs you as an open item, which keeps the PR a draft until you settle it.
Measured on 12 real pull requests, a reviewer reaches the intent, the start point, the risks and the unproven checks after a median of about 150 words, against about 720 in the 9.2 body, and make-pr takes no longer to write it.
If your repository requires a fixed line on every pull request description, such as a ticket footer or a sign-off, say so in its instruction file (AGENTS.md, CLAUDE.md). make-pr appends that line after the rendered briefing and adds nothing else to the body (since 9.12.0).
The body ends with one invisible HTML comment carrying the artifact id, the base SHA and the head SHA. There is no size threshold and no line budget: every pull request gets the same form, and the body is as long as its authored content. A body above 65,000 characters stops the run with the file kept, never truncated.
Mentions in authored prose are made inert, so a body never pings @someone by accident. Issue and pull request numbers, URLs and commit SHAs stay live links. That includes closing keywords: fixes #12 in the authored text closes that issue on merge, as it would in a body you wrote by hand.
What the agent writes and what flowctl fills
Section titled “What the agent writes and what flowctl fills”The agent authors one object, the aid artifact, and nothing else. flowctl validates it, stores it and renders the Markdown in one pass. The agent never assembles sections by hand and makes no extra model call.
| The agent authors (judgment) | flowctl fills (mechanics) |
|---|---|
| Why, review focus, user impact, tradeoffs, open items, and the optional shape sketch | Section order and headings; empty sections dropped |
| The review steps: order, title, what to check, requirement and task ids | Step numbering, each step’s start file, the safe-to-skim line |
| The must-read files: path, one-line purpose, requirement ids, the first one per step being where to start | Each file’s added, deleted or renamed state, its line counts and its diff link, kept in the stored artifact |
| Which files are safe to skim, where a pattern does not already say so | Every file the agent did not mention, kept in the artifact; state files, lockfiles and mirrors classed by pattern |
| Verification items and whether each passed, failed or is unverified | The ticks, the split between Needs you and Verified, the uncovered-requirement line |
The agent’s input is sparse: it lists the files a reviewer must read and lets flowctl account for the rest of the diff. The stored artifact is always complete. Everything the agent cites must trace to the export, a receipt, or a commit:
flowctl spec export-cognitive-aid <spec-id> --base <ref> --jsonValidation rejects a claim with no source, a file listed twice, an unsafe path, and a summary that is only whitespace, and it reports every violation at once with its field path. When attribution is unknown the body says so. An invalid or stale artifact renders nothing, and make-pr falls back to a plainly labeled body built from the export’s goal, tasks, verification and open items. A diff over 500 changed files can never validate, so make-pr writes that labeled body directly, in the briefing’s section order, and names a bulk formatter or codemod commit in one Review focus sentence.
Several specs in one pull request
Section titled “Several specs in one pull request”An integration branch that closes several specs gets one body. The artifact lists every spec in specIds, requirement ids are qualified (fn-250:R4), each spec gets at least one review step with its short id in the title, and coverage prints one line per spec. Commits that belong to no spec get a step of their own. The title names the combined change.
When no spec names the current branch, make-pr finds the specs the branch closes and hosts the body on the highest-numbered one. The same read is available to you:
flowctl spec closed-in-range --base origin/main # one spec id per lineflowctl spec closed-in-range --base origin/main --json # {"spec_ids": [...]}It is read-only and never fetches. Land selects the same set from the pull request’s remote head.
A file’s diff link opens the file at the reviewed head in your forge’s own path: /blob/ on GitHub, /-/blob/ on GitLab for a project in a group of any depth, /src/ on Bitbucket Cloud. An origin no forge recognises gets plain paths instead of a guessed link. The briefing describes what the code at the head does: where a task summary says something a later commit changed, the head wins.
House style shortens the body
Section titled “House style shortens the body”The renderer sets no length budget, so the length of a body is the length of what the agent wrote. If your team wants shorter bodies, say so in the project’s instruction file (AGENTS.md, CLAUDE.md, or your host’s equivalent). The agent reads that file in the same context as the prose contract, and a length budget or reading level written there reaches every artifact it drafts, this one included:
## Pull request bodies
- Why: three sentences at most.- One sentence per file row. At most five review steps.- Tradeoffs: only alternatives a reviewer would otherwise ask about.A house rule shortens the authored text. It cannot drop or reshape a section: the section order, the verification checklist and the coverage lines belong to the renderer.
One portable artifact, three render surfaces
Section titled “One portable artifact, three render surfaces”Make-pr stores the artifact as an immutable v1 JSON generation under
.flow/artifacts/<spec-id>/pr-cognitive-aid/<artifactId>.json. Its artifact id
and base/head SHAs decide currentness; a stale or invalid generation remains
evidence but cannot supply current verification claims. The file stays local:
flowctl init keeps new generations and their write lock out of broad staging.
A repository that already tracks them can untrack them once (local files are kept):
flowctl initgit rm --cached --ignore-unmatch -- '.flow/artifacts/*/pr-cognitive-aid/*.json' '.flow/artifacts/*/pr-cognitive-aid/.write.lock'The same validated object drives the stored artifact and the Markdown briefing.
For a visual walkthrough of the diff, run /flow-next:visual
or ask the agent for an HTML page. The artifact accepts four
optional authored strings (userImpact, blastRadius, tradeoffs,
openItems) and an optional outcome (pass, fail, unverified) on each
verification cell. These are additive: the schema version stays 1, and an older
artifact renders without gaining a pass claim.
For downstream integrations, Flow-Next ships a maximum-normal v1 fixture with
metadata pinning its source path, source commit, and exact SHA-256. Consumers
such as Flow Swarm vendor byte-identical fixture and metadata copies, validate
the local digest, and run without cross-repository network access in CI.
The metadata also pins a strict <100 ms p95 validation-plus-Markdown-render
budget over 30 warm runs.
Invocation
Section titled “Invocation”| Flag | Effect |
|---|---|
--draft / --ready | Force draft or ready state. Without either, the PR opens ready unless it has open items. |
--base <ref> | Override base-branch detection, including the parent-branch base of a chained spec. A branch name resolves against origin/<branch>, refreshed first, so a stale local base never widens the diff. |
--update | Refresh the body of the open pull request on this branch against the current diff. Closes the spec once its work is done, as a create does. Never rewrites a branch. |
--memory | Write a knowledge/architecture-patterns/ memory entry alongside the PR. |
--dry-run | Print the body without closing the spec, pushing, or opening a PR. |
The --no-mermaid flag is removed. The briefing has no diagrams to skip, and an unknown flag is refused.
make-pr takes the forge from your origin remote. On GitHub it needs gh installed and logged in. A login to github.com passes the preflight, and so does a login only to a GitHub Enterprise host; every later gh call targets the host your origin remote points at. On GitLab it needs glab, and on Bitbucket Cloud bkt, as the next sections describe. Any other host stops make-pr before it closes or pushes anything.
GitLab merge requests
Section titled “GitLab merge requests”On a GitLab origin, gitlab.com or a self-managed instance, make-pr creates or updates a merge request through glab, with the same briefing body and the same spec close it uses on GitHub. There is no setting to turn on: the forge comes from the origin remote.
- Login. Run
glab auth loginfor the origin host with a token or a browser login that has theapiscope. A login without that scope stops make-pr before it closes or pushes, naming the host. - SSH origin on another web port. An SSH remote names no web port, so with a self-managed instance whose web port differs from the default, set
GITLAB_HOST=<host>:<port>. - Drafts. A draft is a merge request whose title starts with
Draft:.--draftand--readywork as on GitHub.--updatereplaces the description and keeps the draft state;--update --readyalso dropsDraft:,[Draft]or(Draft)from the title. - Chains. A dependent spec’s merge request targets the parent’s branch while the parent’s merge request is open. GitLab gets no stack link; the merge request stands as a plain chain layer.
- No spec, or no
.flow/. A branch without a spec, and a repository without.flow/, still get a merge request, and--dry-runpreviews against the project’s merge requests. - Bot-authored merge requests.
FLOW_PR_CREATE_CMD(below) still replaces the create call, and make-pr reads the…/-/merge_requests/<n>URL from its output.
From here on, resolve-pr works through the merge request’s discussions and land merges it.
Bitbucket Cloud pull requests
Section titled “Bitbucket Cloud pull requests”On a Bitbucket Cloud origin (bitbucket.org, cloned over HTTPS or SSH), make-pr creates or updates a pull request through bkt, with the same briefing body and the same spec close it uses on GitHub. There is no setting to turn on: the forge comes from the origin remote.
-
Login and context. Log
bktin with an Atlassian API token, then give it a Bitbucket Cloud context, whichbktneeds for every call:Terminal window bkt auth login https://bitbucket.org --kind cloud --username <your Atlassian email> --web-tokenbkt context create bitbucket --host https://api.bitbucket.org/2.0 --workspace <workspace>The token must belong to the account whose email you give. make-pr picks a Bitbucket Cloud context itself, so your active
bktcontext may point anywhere. Without a login or a context, make-pr stops before it closes or pushes and prints these two commands. -
Drafts.
--draftand--readywork as on GitHub.--updatereplaces the description and keeps the draft state;--update --readyalso marks the draft ready. -
One open pull request per branch. Bitbucket answers a second create on a branch that already has an open pull request by overwriting that pull request’s title and description. make-pr checks first and refuses, so use
--updatefor an open one. -
Chains. A dependent spec’s pull request targets the parent’s branch while the parent’s pull request is open, and the default branch once it is merged, including when Bitbucket closed the parent’s branch on merge. Bitbucket gets no stack link.
-
Forks. A pull request opened from a fork that shares the branch name is not yours and is left out.
-
Bitbucket Data Center (self-hosted) is not recognised; make-pr stops there as on any other unknown host.
From here on, resolve-pr works through the pull request’s comments and land merges it.
App/bot-authored PRs: FLOW_PR_CREATE_CMD
Section titled “App/bot-authored PRs: FLOW_PR_CREATE_CMD”By default make-pr opens the PR with gh pr create, so the PR is authored by whatever identity gh is logged in as. Repos that require App- or bot-authored PRs - the canonical case is a single-maintainer repo with required_approving_review_count: 1, where GitHub forbids approving your own PR, making a human-authored PR unmergeable - can interpose the create call:
export FLOW_PR_CREATE_CMD=/path/to/wrapperThe wrapper receives make-pr’s stable argument contract - --title <t> --body-file <f> [--draft] --base <branch> --head <branch> - and must exit 0 and print the PR URL on success. Extra logging is tolerated: make-pr extracts the last …/pull/<n> (or Bitbucket’s …/pull-requests/<n>, or GitLab’s …/-/merge_requests/<n>) from the combined output rather than trusting it verbatim. The command runs through sh -c, so it behaves the same whether the agent’s shell is bash or zsh, it may carry its own arguments (FLOW_PR_CREATE_CMD="my-wrapper --org acme"), and a path with spaces needs shell quoting. On failure the wrapper’s combined output is surfaced verbatim, and wrappers that proxy gh inherit make-pr’s eventual-consistency retry for free.
/flow-next:features opens its maintain PRs through the same variable with the same contract, which is how a non-GitHub host ships a maintain pass.
Scope is the create call only - authorship is fixed at creation. On GitHub, gh remains a preflight requirement (gh pr view / gh pr edit, --update mode, and the post-create link repair all use it), and identity work - minting App installation tokens - belongs to the wrapper, not flow-next. Wrapper-free alternative for short runs: export GH_TOKEN with an App installation token; gh prefers it over stored auth. Installation tokens expire after an hour, which is exactly when the wrapper seam earns its keep.
Tracker linkage and Linear Diffs
Section titled “Tracker linkage and Linear Diffs”When the tracker bridge is active, make-pr unconditionally links the new PR to the spec’s tracker issue - no separate opt-in. A spec with no issue yet gets one created and linked first. An unreachable tracker skips the call, and a failed call warns without changing the PR. For Linear that means a non-closing Ref WOR-N in the body (plus a rich attachment on the GraphQL transport), which makes the PR render as a Linear Diff inside the issue; for GitHub it is a native Refs #N cross-link. Non-closing is deliberate: the issue stays in review while the pull request is open, and only a confirmed merge moves it to its terminal status. With tracker.specWins: true, make-pr also writes the rendered spec as the issue’s final body (Let the spec win).
The tracker call runs after the push and writes into the spec’s JSON: the sync state, and for a spec that had no issue yet, the link to the issue the call created. Since 9.11.0 make-pr commits that file alone (chore(flow): tracker sync state for <spec-id>) and pushes it to the pull request branch, so the link reaches the default branch with the merge and the post-merge Done step finds the issue. Before 9.11.0 the file stayed uncommitted, and the next run on the same checkout could carry it into another pull request. A failed push of that commit prints a warning and leaves the pull request as opened.
Unattended runs
Section titled “Unattended runs”Under flow --auto (or mode:autonomous) the Phase 0 prompts never fire: a gap that would need input hard-errors instead, and a spec with open tasks is refused. The PR is created directly, ready unless it has open items, and its URL is printed so the run can move on while a human reviews. In a repository whose commit hooks enforce message rules, the rule-following close message is what lets the run finish without a hand amend.
What gets forbidden
Section titled “What gets forbidden”- No quoting raw diff content. The diff is the diff; the body is the map to it.
- No
gh pr mergefrom the skill. Merging belongs to a human or to an authorized land call. - No inflating scope beyond what the diff supports. If the spec covered more than the diff did, the uncovered criteria appear as gaps, not as accomplishments.
- No tick without a pass. A gate that never ran is written as unverified, with the gap named.
Worked example
Section titled “Worked example”/flow-next:make-pr fn-12-export-json-flagClosed fn-12-export-json-flag on feat/export-json (chore(flow): close fn-12-export-json-flag)Aid artifact written: 2 review steps, 3 must-read files, R1-R3 coveredOpened: https://github.com/acme/api/pull/214 (ready for review)The reviewer opens the pull request and finds the reading order, the files that matter, and a checklist that ticks only what ran green.
Dynamic usage
Section titled “Dynamic usage”Recipes that compose with make-pr in the cookbook:
- Evidence-first - the coverage lines are the spec’s acceptance criteria proving themselves in the PR.
- One-shot chains - “work the spec and open the PR when review ships” ends here without a second prompt.
- Team patterns - the PR briefing is handover object #6; your reviewer starts from the reading order, not from zero.
Next step
Section titled “Next step”/flow-next:resolve-pr