Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Search & research

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-pr

About 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 ↗