flow-next-make-pr
Open a PR with a cognitive-aid body rendered from flow-next spec state via gh. Use whenever asked to make or open a PR in a flow-next repo.
gmickel · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add gmickel/flow-next --skill flow-next-make-prAbout this skill
name: flow-next-make-pr description: Open a PR with a cognitive-aid body rendered from flow-next spec state via gh. Use whenever asked to make or open a PR in a flow-next repo. user-invocable: false allowed-tools: Read, Bash, Grep, Glob, Write, Edit, Task
/flow-next:make-pr — PR-as-cognitive-aid
A reviewable PR body is itself an artefact: it lets a human decide where to focus before skimming the diff. flow-next already collects every input that body needs — the spec with R-IDs, per-task done summaries and evidence commits, decisions / bug / architecture-patterns memory entries, glossary changes, strategy alignment, deferred review findings, the git diff itself. This skill stitches those into a structured body, optionally adds mermaid diagrams for module-boundary changes, and pushes via gh pr create.
The host agent (Claude Code / Codex / Droid) reads the structured payload from flowctl spec export-cognitive-aid and synthesizes the body directly. Every claim in the body must trace to a structured field in the export payload — never fabricate file paths, SHAs, R-ID attributions, or "why" reasoning. Unknown attribution is honest ("uncovered" / "unclear") rather than invented. The host is competent at "what looks important here?" given the rich input; no second-model review pass is needed (the structured payload does the heavy lifting).
flowctl provides only thin plumbing: flowctl spec export-cognitive-aid <spec-id> --base <ref> --json aggregates the inputs into a single JSON payload (Task 1 of this spec). The skill renders the body, then pushes and creates the PR directly — no confirm prompt (invoking make-pr is the intent; the body is deterministic; the default is a reversible draft). --dry-run prints the body without creating; --ready/--draft set draft state.
Read workflow.md for Phases 0–3 (pre-flight → gather → render body → mermaid) + the §4.0 --dry-run short-circuit — each phase ends with its inline ### Done when checklist. You MUST also read pr-cognitive-aid.md before composing any body — it IS Phase 1.5 (compose → flowctl pr-cognitive-aid validate/write → deterministic render), runs on EVERY invocation including --dry-run, and its rendered walkthrough supersedes the legacy Verification section, and the legacy R-ID coverage section when coverage is fully evidenced (with any unevidenced or undeclared criterion that table renders beside the walkthrough - pr-cognitive-aid.md §4 owns the rule); a body composed without executing it is a contract violation, not a style choice. Phase 1.5b additionally loads html-lens.md only when HTML artifacts are enabled and the run is not --dry-run. The post-render create + finalize machinery (§4.1 title → §4.6 gh pr create/--update → Phase 5 receipt/footer) lives in create-and-finalize.md, read ONLY on a real create (after §4.0 does not short-circuit) — a --dry-run preview never loads it. Read mermaid-rules.md before emitting any mermaid codefence — it defines reserved words, escape patterns, shape selection, the hard caps + allocation rule, the prose-summary rule, the pre-emission validation checklist, the Phase-3 hallucination guardrails, and the diff-fenced structural sketch alternate emission (§8); the --no-mermaid / no-trigger / skip-rule paths never load it. Phase 2's §2.11b Live QA section is likewise gated: references/live-qa-section.md is read only when the spec's qa_verdict receipt is present (the uncommon case).
Preamble
CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks (here and in workflow.md) use $FLOWCTL:
FLOWCTL="${CODEX_HOME:-$HOME/.codex}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl" # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
Inline skill (no context: fork) — plain-text numbered prompt must stay reachable for the Phase 0 info prompts (resolve a missing base ref / undetected spec id — never a confirm gate). Subagents can't call plain-text numbered prompts (Claude Code issues #12890, #34592). There is no Phase 4 confirm prompt — make-pr creates the PR directly.
Mode Detection
Parse $ARGUMENTS as a flag list. Recognized flags: --draft, --ready, --no-mermaid, --memory, --dry-run, --base <ref> (consumes the next token), and the literal token mode:autonomous. Strip recognized tokens; the remainder (if any) is the optional spec id.
RAW_ARGS="$ARGUMENTS"
DRAFT_FORCE="auto" # auto | draft | ready
NO_MERMAID=0
WRITE_MEMORY=0
DRY_RUN=0
BASE_REF=""
SPEC_ID=""
AUTONOMOUS=0
# Tokenize and walk the argument list. The loop handles both `--base=<ref>`
# and space-separated `--base <ref>` via a PREV token holder. Deliberately NO
# bash positional parameters here — the host's argument interpolation rewrites
# positional tokens inside skill code blocks (pilot dogfood finding, 1.13.0).
PREV=""
for ARG in $RAW_ARGS; do
case "$PREV" in
--base) BASE_REF="$ARG"; PREV=""; continue ;;
esac
case "$ARG" in
--draft) DRAFT_FORCE="draft" ;;
--ready) DRAFT_FORCE="ready" ;;
--no-mermaid) NO_MERMAID=1 ;;
--memory) WRITE_MEMORY=1 ;;
--dry-run) DRY_RUN=1 ;;
--base) PREV="$ARG" ;;
--base=*) BASE_REF="${ARG#--base=}" ;;
mode:autonomous) AUTONOMOUS=1 ;;
-*) echo "Unknown flag: $ARG" >&2; exit 2 ;;
*) SPEC_ID="$ARG" ;;
esac
done
[[ -n "$PREV" ]] && { echo "Flag $PREV given without a value" >&2; exit 2; }
# Secondary signal: process-level autonomous driver (env survives only
# within one process tree; the token is the primary, prose-safe carrier).
if
Read the complete source ↗