/flow-next-make-pr

name: flow-next-make-pr
description: Render a cognitive-aid PR body from flow-next state and open via gh. Triggers on /flow-next:make-pr with optional spec id and flags (--draft, --ready, --no-mermaid, --base <ref>, --memory, --dry-run). Auto-detects spec from current branch when no id given. NOT Ralph-blocked — autonomous loops can surface a draft PR for human review.
user-invocable: false
allowed-tools: AskUserQuestion, 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](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](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 R-ID coverage and Verification sections; a body composed without executing it is a contract violation, not a style choice. Phase 1.5b additionally loads [html-lens.md](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](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](mermaid-rules.md) before emitting any mermaid codefence — it defines reserved words, escape patterns, shape selection, and the pre-emission validation checklist.**

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="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

**Inline skill (no `context: fork`)** — `AskUserQuestion` 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 blocking question tools (Claude Code issues #12890, #34592). There is **no Phase 4 confirm prompt** — make-pr creates the PR directly. (sync-codex.sh rewrites any remaining `AskUserQuestion` to a plain-text numbered prompt in the Codex mirror.)

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 [[ "${FLOW_AUTONOMOUS:-}" == "1" ]]; then
  AUTONOMOUS=1
fi

| Flag | Effect | |------|--------| | `--draft` | Force draft PR regardless of open-items count or Ralph context. | | `--ready` | Force non-draft PR. Conflicts with `--draft` (last flag wins; surface the conflict). | | `--no-mermaid` | Skip Phase 3 entirely. Mermaid prose summaries are also skipped. | | `--memory` | After PR creation, write a `knowledge/architecture-patterns/` memory entry summarizing what shipped. Idempotent — rerun adds