---
satisfies: [R20, R21, R22, R23]
---

## Description

Rollup. Docs (CHANGELOG, plugin README, CLAUDE.md), website (mickel.tech feature card + count + FAQ), Codex mirror regen, version bump 0.37.0 → 0.38.0.

**Size:** M
**Files:**
- `CHANGELOG.md` (new `[flow-next 0.38.0]` block above 0.37.0 — line ~5)
- `plugins/flow-next/README.md` (commands count, commands table row, flags table, interview subsection, workflow ladder, mermaid lifecycle diagram)
- `CLAUDE.md` (commands list line ~27; "Creating a spec" section lines ~431-466)
- `~/work/mickel.tech/app/apps/flow-next/page.tsx` (commands array line ~566; lede count line ~1034; FAQ lines ~128-130)
- `.claude-plugin/marketplace.json`, `plugins/flow-next/.claude-plugin/plugin.json`, `plugins/flow-next/.codex-plugin/plugin.json` (handled by `bump.sh`)
- `plugins/flow-next/codex/skills/flow-next-capture/`, `plugins/flow-next/codex/skills/flow-next-interview/` (regenerated by `sync-codex.sh`)

## Approach

### CHANGELOG.md

Insert at line ~5 (above existing `## [flow-next 0.37.0] - 2026-04-25` block):

```markdown
## [flow-next 0.38.0] - 2026-04-XX

### Added
- `/flow-next:capture` — agent-native skill that synthesizes conversation context into a flow-next epic spec. Sits between free-form discussion (or `/flow-next:prospect` artifact promotion) and the formal `/flow-next:plan` task breakout. Writes via existing `flowctl epic create + epic set-plan`; no new flowctl subcommands. Hard guardrails: source-tagged acceptance criteria (`[user]` / `[paraphrase]` / `[inferred]`), mandatory read-back loop, duplicate-epic detection, compaction detection, idempotency-via-`--rewrite`, must-ask cases for ambiguous title / untestable acceptance / scope-conflict, "consider splitting?" suggestion at 8+ acceptance criteria (never auto-splits). Adapted from upstream `to-prd` skill; flow-next-shaped (output to `.flow/specs/`, not GitHub issue). <!-- Updated by plan-sync: fn-36.1 implemented 8+ trigger not "~7" -->

### Changed
- `/flow-next:interview` enhanced with three patterns from upstream `grill-me`: (a) every `AskUserQuestion` includes recommendation + confidence tier (`[high]` / `[judgment-call]` / `[your-call]`); (b) pre-question taxonomy — codebase-answerable questions are investigated via Read/Grep/Glob and logged to a new optional `## Resolved via Codebase` spec section, user-judgment-required questions go to AskUserQuestion; (c) dependency-ordered branch walk with cap at 4 turns, discover-as-you-go, abandoned-branch surfacing.

### Notes
- Capture is **Ralph-blocked** by default (requires conversation context + user confirmation; both unavailable in autonomous loops).
- Capture is the **automated alternative** to the manual `flowctl epic create + epic set-plan` heredoc documented in `CLAUDE.md`. Both paths supported.
- Workflow ladder is now: free-form discussion (or `/flow-next:prospect`) → `/flow-next:capture` → `/flow-next:interview` (refine) AND/OR `/flow-next:plan` (break out tasks) → `/flow-next:work` (execute).
```

### Root README.md (top-level)

The root `README.md` (~148 lines) is the project's GitHub landing page. It includes a commands table at lines ~95-105 and brief workflow descriptions throughout.

1. **Commands table** — insert `/flow-next:capture` row near the upstream-of-implementation cluster (after prospect, before interview/plan):
   ```
   | `/flow-next:capture` | Synthesize conversation context into a flow-next epic spec |
   ```
2. **Anywhere a workflow sequence is mentioned** in prose — update to reflect capture as a path. The expected sequences (mirror the spec's ASCII diagram on `## Workflow ladder positioning`):
   - `prospect → plan` (direct, via promote)
   - `prospect → capture → plan` (synthesize a richer spec from prospect-output discussion before planning)
   - `free-form discussion → capture → plan` (no prospect)
   - `free-form discussion → capture → interview → plan` (capture, then refine)
   - All paths terminate at `work`
3. If the README has any **pithy workflow tagline / lifecycle description** in the lede or "How it works" section, update it so users find capture as a first-class option (not a deep-link in the docs).

### plugins/flow-next/README.md

Per docs-gap-scout findings + explicit pathway coverage:

1. **Line ~1620** — count update: "Fifteen commands" → "Sixteen commands"
2. **Line ~1624** (commands table) — insert `/flow-next:capture` row. Workflow-ordered placement: after `/flow-next:interview` (line 1627) since capture is the same upstream-of-implementation cluster. (Table is not strictly alphabetical; verify before placing.)
3. **Line ~1669** (flags table) — add capture row with `mode:autofix` / `--rewrite <id>` / `--from-compacted-ok` / `--yes` flags
4. **Lines ~1726-1739** (interview subsection) — add the three grill-me enhancements as bullets
5. **Lines ~280-298** ("Choose Your Flow" workflow ladder table) — extend the table to cover capture pathways. The current table has rows like "No target yet — Prospect → Interview/Plan → Work" / "New feature, want solid spec first → Spec → Interview/Plan → Work". Add/update rows so ALL the pathways from the spec's ASCII diagram appear:
   - "No target yet, want ranked candidates" → `Prospect → Capture → Interview/Plan → Work` (or `Prospect → Plan` direct if user accepts a candidate as-is)
   - "Conversation already in flight" → `Capture → Interview/Plan → Work`
   - "Vague idea / rough notes" → `Interview → Plan → Work` (existing)
   - "Detailed spec/PRD" → `Plan → Interview → Work` (existing)
   - "Well-understood, needs task splitting" → `Plan → Work` (existing)
   - "Small single-task, spec complete" → `Work directly` (existing)
6. **"Prospect vs Spec vs Interview vs Plan" explainer** (under the table at line ~298+) — add a "Capture" entry between Prospect and Spec. Frame it as: "Capture (`/flow-next:capture`) synthesizes conversation context into an epic spec — the automated alternative to manual `flowctl epic create + epic set-plan`. Use after prospect-promotion or after a free-form design discussion. Mandatory read-back loop; never silently invents requirements."
7. **Lines ~826-851** (mermaid lifecycle diagram) — add capture as a node between prospect's promote output and the interview/plan branches. The diagram should show all the spec-ASCII-diagram pathways: prospect can branch directly to plan (existing) OR through capture; free-form discussion enters via capture; capture branches to interview AND/OR plan; both terminate at work.

Verify each line ref before editing — README has shifted across recent changes.

### CLAUDE.md

1. **Line ~27** (commands list) — insert `/flow-next:capture` line after `/flow-next:audit` (existing line 27). Format:
   ```
   - `/flow-next:capture [mode:autofix] [--rewrite <id>] [--from-compacted-ok] [--yes]` → agent-native skill that synthesizes conversation context into a flow-next epic spec. Sits between free-form discussion / prospect-promotion and the formal plan/interview phase. Output via `flowctl epic create + epic set-plan`. Hard guardrails: source-tagged criteria, mandatory read-back, duplicate detection, compaction detection. Ralph-blocked. Added in 0.38.0.
   ```

2. **Lines ~431-466** ("Creating a spec" section) — currently shows manual `flowctl epic create + epic set-plan` heredoc. Add a note at the top of the section pointing at capture as the automated alternative:
   ```
   **Two paths:**
   - **Automated** (recommended for any spec emerging from conversation): `/flow-next:capture` — host agent synthesizes the spec from conversation context, with mandatory read-back. Added in 0.38.0.
   - **Manual** (for direct flowctl scripting): the `flowctl epic create + epic set-plan` heredoc shown below.
   ```
   Then keep the existing manual heredoc verbatim.

### .flow/usage.md

No update needed (capture adds no flowctl subcommands; interview enhancements have no flowctl surface). Verify by reading the file — if it has a skills section that lists slash commands, add capture there.

### Website

`/Users/gordon/work/mickel.tech/app/apps/flow-next/page.tsx`:

1. **Line ~566** (commands array) — insert capture entry after interview. Format mirrors existing entries (slug, name, hint, description).
2. **Line ~1034** (lede count) — `Eleven verbs` → `Twelve verbs`. Eyebrow `11 / Commands` → `12 / Commands`.
3. **Lines ~128-130** (FAQ lifecycle answer) — currently mentions prospect → interview → plan → work. Update to: prospect (or free-form discussion) → capture → interview/plan → work. One-sentence addition explaining capture's role.

This is a separate repo. Commit + push independently after main repo PR merges.

### Codex mirror

```bash
./scripts/sync-codex.sh
```

Picks up automatically:
- New `plugins/flow-next/codex/skills/flow-next-capture/` directory (with mirrored SKILL.md, workflow.md, phases.md) — generic copy loop at `sync-codex.sh:120-125`
- Updated `plugins/flow-next/codex/skills/flow-next-interview/` (SKILL.md + questions.md mirrors)
- New slash command at `plugins/flow-next/codex/prompts/flow-next-capture.md` (or wherever Codex slots commands — verify by listing existing prompt files)
- Standard path patches (FLOWCTL var fallback, `.codex-plugin/plugin.json` paths) applied via find-walk

**Critical: extend `sync-codex.sh` `generate_openai_yaml` calls (lines ~380-393) with an entry for `flow-next-capture`.** Without it, capture ships to Codex without UI metadata (display name, brand color, default prompt) — same silent-degradation bug that's affected resolve-pr / prospect / audit / memory-migrate since 0.34.0.

Suggested entry (workflow color, explicit invocation):

```bash
generate_openai_yaml "flow-next-capture" "Flow Capture" "Synthesize conversation context into a flow-next epic spec" "#3B82F6" false "Capture this as a spec: "
```

Also bump the validation threshold at line 603 (currently `>= 9`) to match the new total. **Prerequisite**: 0.37.1 hotfix must already have backfilled openai.yaml entries for resolve-pr / prospect / audit / memory-migrate / capture's siblings before fn-36 ships, or the validation check will need to step over multiple skills at once.

Verify post-sync that all skills (capture, interview, audit, prospect, memory-migrate, resolve-pr) have proper `openai.yaml` files in `plugins/flow-next/codex/skills/<skill>/agents/openai.yaml` and that the codex/skills/ directory listing is alphabetical.

### bump.sh

```bash
./scripts/bump.sh minor flow-next
```

Updates 3 manifests: `marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` to 0.38.0. Verify with `jq -r '.version' <each>` after bump.

### Final commit + tag (manual after merge)

Per `CLAUDE.md` release checklist:

```bash
git commit -am "feat(flow-next): /flow-next:capture skill + interview grill-me enhancements — 0.38.0"
git push
git tag flow-next-v0.38.0 && git push origin flow-next-v0.38.0
```

Tag triggers GitHub Actions release + Discord. Don't tag without pushing.

## Investigation targets

**Required:**
- `CHANGELOG.md:1-50` — recent entry shape (`[flow-next 0.37.0]`, `[flow-next 0.36.0]`)
- `plugins/flow-next/README.md` lines 280-298, 1620-1739, 826-851 — exact line refs from docs-gap-scout (verify before editing — line numbers shift)
- `CLAUDE.md:27` (commands list), `CLAUDE.md:431-466` ("Creating a spec" section)
- `~/work/mickel.tech/app/apps/flow-next/page.tsx:128-130, 551-598, 1034` — commands array, lede count, FAQ
- `scripts/bump.sh` — version-bump script (read for confidence; do NOT edit manifests by hand)
- `scripts/sync-codex.sh` — codex mirror regen

**Optional:**
- Recent fn-34/fn-35 PR diffs for shape of website + docs commit pattern (PR #120 merge was the most recent reference)

## Key context

- **Bundling note**: Don't run `bump.sh` if Tasks 1+2 already triggered an interim bump. Verify `.claude-plugin/marketplace.json` shows 0.37.0 before running. (Spec says no interim bumps; this rollup is the only bump.)
- **Amend, don't replace** the CHANGELOG. Don't touch the existing 0.37.0 block.
- **Mickel.tech is a separate repo.** Commit + push independently. Use that repo's commit conventions (terse, conventional commits).
- **`sync-codex.sh` is idempotent.** Re-running is safe.
- **Tag triggers Discord.** Don't tag locally without pushing.
- **Verify CHANGELOG date placeholder** (`<date>`) gets replaced with actual release date before commit.
- **Line refs may have shifted** since docs-gap-scout ran. Use `grep -n` to verify each ref before editing — the structural anchors (e.g., "Fifteen commands", "## Creating a spec") are stable; the line numbers may not be.

## Acceptance

- [ ] `CHANGELOG.md` has new `[flow-next 0.38.0]` block above 0.37.0 with Added/Changed/Notes covering capture skill + interview enhancements + workflow ladder update. (R20)
- [ ] **Root `README.md`** updated: commands table includes `/flow-next:capture`; any workflow-sequence prose mentions reflect the new pathways (prospect → capture, free-form → capture, capture → interview/plan); pithy lifecycle tagline (if present) makes capture discoverable. (R20)
- [ ] `plugins/flow-next/README.md` updated: commands count (Fifteen → Sixteen), commands table row for capture, flags table row, interview subsection extended with grill-me enhancements. (R20)
- [ ] `plugins/flow-next/README.md` "Choose Your Flow" workflow ladder table covers ALL pathways from the spec's ASCII diagram: prospect→plan (direct), prospect→capture→interview/plan, free-form→capture→interview/plan, plus the existing rows. (R20)
- [ ] `plugins/flow-next/README.md` "Prospect vs Spec vs Interview vs Plan" explainer extended with a Capture entry positioning it as the automated alternative to manual `flowctl epic create + set-plan`, with read-back guarantees. (R20)
- [ ] `plugins/flow-next/README.md` mermaid lifecycle diagram extended with capture node showing all three entry points (prospect-promote, free-form, direct) and both downstream branches (interview, plan). Visually matches the spec's ASCII diagram pathways. (R20)
- [ ] `CLAUDE.md` updated: commands list (line ~27) includes capture, "Creating a spec" section adds capture as automated alternative to manual heredoc. (R20)
- [ ] `.flow/usage.md` checked; updated only if it has a skills section listing slash commands. (R20)
- [ ] `~/work/mickel.tech/app/apps/flow-next/page.tsx` updated: commands array entry for capture (after interview), lede count (Eleven → Twelve), FAQ lifecycle updated. (R21)
- [ ] `scripts/sync-codex.sh` regenerated; `plugins/flow-next/codex/skills/flow-next-capture/` materialized; `flow-next-interview/` mirror updated. Codex slash command for capture added if applicable. (R22)
- [ ] `scripts/sync-codex.sh` extended with `generate_openai_yaml "flow-next-capture" "Flow Capture" ...` call; validation threshold (line ~603) raised to match new total openai.yaml count. **Prerequisite**: 0.37.1 hotfix has already backfilled openai.yaml for resolve-pr / prospect / audit / memory-migrate (verify by reading sync-codex.sh head before merging fn-36). Confirm via `find plugins/flow-next/codex/skills -name openai.yaml | wc -l` after sync. (R22)
- [ ] Canonical `flow-next-interview/` files use `AskUserQuestion` (Claude-native) per repo convention. NO inline cross-platform variant table in the skill prose. sync-codex.sh handles the Codex rewrite to `request_user_input`. Verify Codex mirror has zero `AskUserQuestion` refs in skill prose post-sync. (R17/R22 closure)
- [ ] All three manifests (`marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`) show version 0.38.0; `jq` parses cleanly on each. (R23)
- [ ] All existing smoke tests still green: `audit_smoke_test.sh`, `smoke_test.sh`, `prospect_smoke_test.sh`, `ralph_smoke_test.sh`. (R20-R23)
- [ ] Mickel.tech commit lands separately (separate repo); commit message follows that repo's conventions.
- [ ] All checks ready for manual `git tag flow-next-v0.38.0 && git push origin flow-next-v0.38.0` after PR merge.


## Done summary
Rollup ships /flow-next:capture + interview grill-me enhancements as 0.38.0: CHANGELOG block, root + plugin README updated (commands tables, workflow ladder pathways, mermaid diagram extended with capture node, new Capture section, "Prospect vs ..." explainer extended, interview subsection extended), CLAUDE.md updated (commands list + "Creating a spec" two-paths preamble), website (mickel.tech) updated separately (commands array, lede 11→12 verbs, FAQ rewritten, version 0.38.0). sync-codex.sh extended with flow-next-capture openai.yaml entry + REQUIRED list bumped to 14; Codex mirror regenerated cleanly. All 3 manifests at 0.38.0; four smoke suites green.
## Evidence
- Commits: 2a5685a26972a8d6bc0f20f58ae6b4bcd63e698d, 4e8cfa1994c1515c48e74b18a5c9d1921bceb0bb
- Tests: bash plugins/flow-next/scripts/smoke_test.sh (129/0), bash plugins/flow-next/scripts/audit_smoke_test.sh (41/0), bash plugins/flow-next/scripts/prospect_smoke_test.sh (94/0), bash plugins/flow-next/scripts/ralph_smoke_test.sh (15/0), scripts/sync-codex.sh (14 openai.yaml, 21 skills, 21 agents — zero errors), jq -r .version on .claude-plugin/marketplace.json + plugins/flow-next/.claude-plugin/plugin.json + plugins/flow-next/.codex-plugin/plugin.json (all 0.38.0)
- PRs: