| name | claude-tweaks:flow |
| description | Use when you want to run an automated build → test → review → polish → wrap-up pipeline on a work record or spec without stopping between steps. Accepts record references (#N) and specs only — design docs must be decomposed via /claude-tweaks:specify first. |
Interaction style: Present single decisions via the AskUserQuestion tool (options with one marked Recommended) instead of a plain-text numbered list. For multi-item decisions, render a batch table with recommended actions pre-filled, then capture the apply-all/override decision via one AskUserQuestion call. Never make more than one AskUserQuestion call per logical decision — resolve each before showing the next. End skills with a ## Next Actions block rendered via AskUserQuestion (context-specific options, one recommended), not a navigation menu.
Flow — Automated Pipeline
Run multiple lifecycle steps in sequence without stopping between them. Each step has a gate — if a gate fails, the pipeline stops and presents the failure.
/claude-tweaks:capture → /claude-tweaks:challenge → /superpowers:brainstorming → /claude-tweaks:specify → /claude-tweaks:build → /claude-tweaks:test → /claude-tweaks:review → /claude-tweaks:design polish → /claude-tweaks:wrap-up
╰────────────────────────────────────── [ /claude-tweaks:flow ] automates this stretch ──────────────────────────────╯
^^^^ YOU ARE HERE ^^^^ (polish + re-verify run only when frontend)
When to Use
- A spec is ready to build and you want to go from code to clean-slate in one command
- A brainstorming session produced a design doc,
/specify decomposed it into specs, and you want to run those specs through the pipeline
- You trust the pipeline to catch issues at gates rather than stopping for manual checkpoints
- You want to batch a build + test + review + wrap-up session
When NOT to Use
- The input is a design doc, not a spec — run
/claude-tweaks:specify {doc} first
- The plan has tangled cross-task dependencies — flow's shape gate (Step 2.6) will hard-fail anyway; tighten via
/claude-tweaks:specify first
- When you expect significant review findings that need discussion
Syntax
/claude-tweaks:flow <#n>[,#m,#o] [worktree | current-branch] [no-stories] [no-polish] [no-deepen] [auto | interactive | hybrid | confirm] [keep-going] [step1,step2,step3]
All bracketed tokens are optional and order-independent. worktree is the default git strategy when neither worktree nor current-branch is set. keep-going applies to multi-spec runs only. Design doc paths are rejected at Step 2.7 — run /claude-tweaks:specify first. The legacy numeric spec-number form (/claude-tweaks:flow 42, /claude-tweaks:flow 42,45,48) still works — see Input resolution below.
Flow defaults to auto mode (its purpose is hands-off automation). In auto the Pipeline Config Manifesto runs as a read-only FYI — it computes and displays the policy levers, then proceeds without an approval stop. Pass confirm to re-enable the Manifesto approval gate, interactive for per-skill in-flow prompts, or hybrid for floor-gated prompts. See the mode arguments below.
Arguments
| Argument | Required | Description |
|---|
#<n>[,#<m>...] | Yes* | Primary input. One or more work record references (e.g. #123 or #123,#456) — a GitHub issue number under work-backend: github-issues, or (drop the #) a local record id under work-backend: local-files. Resolved, shape-gated, and materialized into {run-dir}/work/{n}-spec.md per materialize.md in this skill's directory — an unshaped record hard-stops the run with a pointer to /claude-tweaks:specify #{n}. /flow never selects, filters, or claims records itself: /claude-tweaks:dispatch claims before handing off (CLAIM_RUN_ID="{run-id}" /claude-tweaks:flow #{n}[,#{m}...]), or a human runs /flow #{n} directly against any record carrying no live claim. When the caller set the CLAIM_RUN_ID env var (dispatch always does — see dispatch/SKILL.md Step 5), thread it through unchanged to /wrap-up's Section E / multispec-review-console.md release step as the ownership-check comparison value, instead of /flow's own PIPELINE_RUN_DIR — dispatch claimed the record under its own (earlier, differently-named) run id. *Not required when the legacy <spec> form below is passed instead. |
<spec> | No | Legacy alias. A spec number (e.g., 42) or comma-separated spec numbers (e.g., 42,45,48) reads specs/{n}-*.md directly — the pre-materialization path, unchanged, for projects that still carry plain numbered spec files. Design docs are not accepted — run /claude-tweaks:specify {design-doc} first to decompose into specs. See Step 2.7. |
worktree | No | Use worktree git strategy — isolated workspace on a feature branch (this is the default for flow). See "Parallel Development with Worktrees" below. |
current-branch | No | Override the default and commit directly on the current branch instead of creating a worktree. |
no-stories | No | Skip automatic story generation even if UI files changed. By default, flow auto-generates stories when the build produces UI file changes. |
no-polish | No | Skip the polish phase (and its re-verify gate) entirely. Overrides any explicit polish in the step list. Use when iterating fast on backend specs, when polish is not desired (one-off scripts, infrastructure-only changes), or when the user has already manually invoked Impeccable polish. The wrapper would skip polish anyway on non-frontend specs (detection layer 2); no-polish is the explicit user-facing escape hatch. |
no-deepen | No | Skip the end-of-run Depth Opportunities survey. By default flow runs /claude-tweaks:deepen's read-only analysis at the Pipeline Summary and surfaces shallow-module candidates as recommendations (it never refactors automatically — see Step 5). no-deepen skips the analysis entirely. Can also be defaulted off project-wide with depth-survey: off in CLAUDE.md under ## Auto-mode policy. |
auto | No | Flow's default mode — pipeline runs hands-off. The Config Manifesto (Step 3) renders as a read-only FYI and proceeds without an approval stop. Silences merge-check (Step 2.5), shape-check (Step 2.6), all path-selection prompts mid-pipeline, and explicitly forbids the model from inserting its own reality-checks or context-window concerns. Failures surface via the ledger and the failure card, never via mid-pipeline questions. Full contract: see _shared/auto-mode-contract.md — that file is the single source of truth for what auto silences AND what it does NOT silence (resolve gate, work-record creation, hard validation failures all remain mandatory). Passing auto explicitly is redundant (it is already the default) but harmless. Passed through to /build. |
confirm | No | Stay in auto but re-enable the Manifesto approval gate at Step 3 (the Approve all / Override / Cancel block). Use when you want to inspect and tweak the policy levers before the pipeline runs hands-off. Everything after the Manifesto still runs as auto. |
interactive | No | Opt out of auto entirely — skills present each decision in-flow as the standalone skills do. The Manifesto is skipped. Highest friction; use when you want a checkpoint at every decision. |
hybrid | No | Manifesto approval gate runs, and downstream skills still prompt when a decision fails the reversibility/confidence/severity floors (see _shared/auto-mode-contract.md). Between full auto and interactive. |
keep-going | No | Multi-spec only. Continue the run after a HARD-GATE failure in one spec — remaining specs still run, committing into the same shared worktree. Failed specs surface in the consolidated Review Console's "Not run / Failed" footer. Use when specs are genuinely independent (no depends-on: edges). The default is to stop on first failure because spec N+1 may build on spec N's correctness — keep-going inverts that safety, so it's opt-in. See multi-spec.md. |
[steps] | No | Step argument(s). Single step = resume from that step onward. Comma-separated steps = run exactly those steps. Default (no steps): build,test,review,polish,wrap-up (re-verify is bundled with polish). |
Flow always uses subagent execution strategy — its purpose is hands-off automation. The batched option (which pauses for human review) is not available in flow; use /claude-tweaks:build batched directly instead.
Input resolution
- Record reference(s) (e.g.,
#123 or #123,#456; under work-backend: local-files, drop the #) → Record mode — resolved, shape-gated, and materialized via materialize.md in this skill's directory before the pipeline proper starts; an unshaped record stops the run with a pointer to /claude-tweaks:specify #{n}. Checked first, since a leading # (or, under work-backend: local-files, a bare id that resolves to an existing record) unambiguously means record mode. /claude-tweaks:dispatch is the primary caller of this form (CLAIM_RUN_ID="{run-id}" /claude-tweaks:flow #{n}[,#{m}...]) — a human can also run it directly against any record carrying no live claim. A single record runs the standard single-spec pipeline below, built from the materialized file. Multiple records (#A,#B) run Multi-spec mode (below), each materializing to its own file under the shared run's spec-{id}/work/ subdirectory (see materialize.md's Multi-record layout and multi-spec.md) — CLAIM_RUN_ID threads through to every record's /wrap-up the same way the legacy multi-spec case does (row below).
- Single spec number (e.g.,
42) → Spec mode, legacy alias — reads specs/42-*.md directly; build uses spec tracking, review checks spec compliance. No materialization and no record-level shape gate — the legacy pre-flight checks (Step 2.4/2.7) cover this path instead.
- Multiple spec numbers (e.g.,
42,45,48) → Multi-spec mode, legacy alias — runs each spec sequentially in one terminal (see Multi-Spec Sequential Flow below). For true parallel execution, use separate terminals with worktree mode. When /claude-tweaks:dispatch is the caller (a bundle group — see dispatch/SKILL.md Step 5), it sets CLAIM_RUN_ID; thread it through to each spec's /wrap-up the same way record mode does (row above) — the release ownership check needs dispatch's run id, not any per-spec one.
- Topic name (e.g.,
meal planning) → search specs/ for a matching spec. If found, use spec mode. If only a design doc exists at docs/superpowers/specs/*-design.md, stop and route to /claude-tweaks:specify (see Step 2.7) — design docs are no longer executable directly by /flow.
- Design doc path → rejected at Step 2.7 with a routing message to
/claude-tweaks:specify. Design-mode flow was removed because it bypassed the granularity contract — design docs describe multi-phase programs, not agent-sized work units.
Automatic story generation
After build completes, flow checks the build output for UI file changes (.tsx, .jsx, .vue, .svelte, .html, .css, or files in component/page directories). If UI files changed and no-stories was not specified:
- Auto-detect the dev server URL using
dev-url-detection.md in skills/_shared/
- Run
/claude-tweaks:stories with the detected URL. When journey files exist in docs/journeys/ (created by /build Common Step 6), the stories step ingests them before browsing — the journey: field is set on derived stories, source files are inherited from the journey's files: frontmatter, and browsing is enrichment rather than fresh discovery for journey-documented pages.
- Generated stories feed into
/claude-tweaks:test (which validates them as part of the test step)
If no UI files changed, or no-stories is set, the stories step is skipped.
Examples
/claude-tweaks:flow 42 → full pipeline in worktree (default = auto): build, test, review, polish, wrap-up; Manifesto shown as FYI, no approval stop
/claude-tweaks:flow 42 confirm → same, but stop at the Manifesto approval gate first (inspect/override levers), then run auto
/claude-tweaks:flow 42 interactive → opt out of auto — per-skill in-flow prompts, no Manifesto
/claude-tweaks:flow 42 current-branch → full pipeline on current branch (no isolation)
/claude-tweaks:flow 42 no-stories → full pipeline in worktree (skip stories even if UI changed)
/claude-tweaks:flow 42 no-polish → full pipeline without polish phase
/claude-tweaks:flow 42 no-deepen → full pipeline, skip the end-of-run depth-opportunities survey
/claude-tweaks:flow 42,45,48 → multi-spec sequential, all specs in one shared worktree
/claude-tweaks:flow 42,45,48 keep-going → multi-spec, continue past HARD-GATE failures (independent specs only)
/claude-tweaks:flow meal planning → resolve to spec by name (rejected if only design doc exists)
/claude-tweaks:flow docs/superpowers/specs/migration-design.md → REJECTED — run /specify first; flow only accepts record references and specs (auto does not silence this)
For resume-from-step and explicit-subset variants (/flow 42 review, /flow 42 review,wrap-up, etc.), see steps-and-gates.md ("Step Arguments" section) for the full enumeration.
Allowed Steps, Step Arguments, and Gate Behavior
For the full Allowed Steps reference (which skills are pipeline-eligible), Step Arguments rules (resume vs explicit subset, auto-inserts, no-polish semantics), Gate Behavior table, and the canonical polish-phase decision tree, read steps-and-gates.md in this skill's directory.
On Gate Failure
When a gate fails, the pipeline stops immediately and renders a failure card. Two card shapes exist (generic vs. "polish broke verification"); both templates and the picker live in failure-cards.md in this skill's directory. Load failure-cards.md only when a gate has actually failed — the success path uses Step 5's Pipeline Summary instead.
Execution
Step 1: Validate Input
-
Parse $ARGUMENTS — extract record reference(s) (#N / #A,#B), spec number(s), or topic name, detect worktree, current-branch, no-stories, no-polish, no-deepen, the mode keywords (auto / interactive / hybrid / confirm), plus optional step list. Resolve the mode in this order (first match wins):
- Explicit mode keyword in
$ARGUMENTS — interactive / hybrid / confirm / auto. (confirm means "auto mode, but gate the Manifesto"; see Step 3.)
- CLAUDE.md
auto-mode: setting — default-off → interactive; default-on → auto.
- Intrinsic default →
auto. Flow's purpose is hands-off automation, so it runs auto unless a param or auto-mode: default-off lowers it.
-
Determine record mode (#N / #A,#B, or a bare id under work-backend: local-files), spec mode (number, legacy alias), or topic-resolution mode (name) — per Input resolution above. A path argument is held until Step 2.7 (pre-flight) where it's checked against the design-doc rejection rule.
-
Git strategy defaults to worktree — same default as /build; flow never prompts. Resolution order:
- Explicit argument:
worktree or current-branch in $ARGUMENTS — always wins
- CLAUDE.md
git-strategy setting — project-level default (see /claude-tweaks:build default resolution)
- Fallback:
worktree
Do NOT prompt the user for git strategy — resolve it silently from the above. This is passed through to /claude-tweaks:build and controls isolation. Flow always uses subagent execution — no prompt needed for execution strategy. Pass subagent as an explicit argument in the /claude-tweaks:build invocation (Step 4) rather than relying on /build's own default-resolution chain — this keeps flow's execution-strategy guarantee independent of whatever CLAUDE.md or .claude-tweaks/policy.yml might otherwise resolve to for a standalone /build call.
-
Validate step list is in lifecycle order and apply the auto-inserts and override rules from steps-and-gates.md ("Step Arguments" section): auto-insert test before review, treat literal re-verify as a no-op, and drop polish when no-polish is set.
-
If record mode: resolve and shape-gate every target record now, via materialize.md's Resolution + Materialization hard gate in this skill's directory — this is the record-level replacement for the legacy pre-flight's spec-committed check (2.4) and design-doc rejection (2.7); an unshaped record stops the run here with a pointer to /claude-tweaks:specify #{n}, before Step 2's other checks or the Config Manifesto run. If spec mode: check prerequisites are met (same as /claude-tweaks:build Spec Step 1)
-
If a path was given in the argument: confirm it's a spec, not a design doc (Step 2.7 enforces). If a topic name was given: resolve to a spec; if only a design doc exists for that topic, stop and present the routing message.
-
If validation fails → stop before starting
-
Create the open items ledger using /claude-tweaks:ledger's create operation. The {feature} name matches the execution plan that build will create. This file tracks findings and operational tasks across all pipeline phases. See /claude-tweaks:ledger for status lifecycle and phase taxonomy.
Step 2: Pre-flight Checks
Four checks before pipeline starts. Each can return OK / WARNING / BLOCKED.
- 2.4 — Spec-committed check (target spec tracked + clean; hard-fail — a worktree from base won't contain an uncommitted spec). Worktree strategy only. Legacy spec-file alias only — record mode's equivalent guarantee already ran at Step 1 (
materialize.md's hard gate on the fetched record body, before any worktree exists).
- 2.5 — Merge check (uncommitted changes, branch ahead/behind)
- 2.6 — Shape check (structural coupling, hard-fail on cross-task deps)
- 2.7 — Design-doc rejection (granularity contract — specs only, not design docs). Legacy spec-file / topic alias only — a record reference is never a file path, so this ambiguity doesn't arise in record mode;
materialize.md's Step 1 hard gate is record mode's equivalent granularity check.
Any hard fail or rejection stops the pipeline before the Config Manifesto runs. Read validation.md in this skill's directory for the detailed procedure for each substep.
Step 3: Pipeline Config Manifesto (front-loaded policy)
This is the bookend "begin stop" that locks in policy for the rest of the pipeline. Runs after pre-flight passes so policy levers are not collected if the pipeline would not have started. In every mode except interactive, it computes the levers (scope-creep, overlap, design-intent, leftover-default, auto-fix-threshold, review-severity-floor, tidy-aggressiveness, unattended-tier, ceremony-profile) from the precedence chain and writes config.yml + initializes decisions.md in .claude-tweaks/pipelines/{ISO-timestamp}-{spec-slug}/. What differs by mode is whether it stops:
| Mode | Manifesto behavior |
|---|
auto (default) | Read-only FYI. Render the computed levers as a ### Pipeline Config (auto) table (value + source per lever), print → proceeding (no approval needed), and continue. No stop. |
confirm | Approval gate. Present the Approve all / Override / Cancel block and wait. After approval, the rest of the pipeline runs as auto. |
hybrid | Approval gate (same as confirm); downstream skills still prompt on floor failures. |
interactive | Skipped — no Manifesto and no run directory; skills prompt each decision in-flow rather than reading config.yml. |
This is the first bookend of the pipeline (see _shared/auto-mode-contract.md). In default auto the begin-stop is informational only; the single user-facing stop is the Wrap-Up Review Console at the end. Regardless of mode, after this step no downstream skill re-asks the user about these levers — they read config.yml and apply.
For the complete Manifesto content (presentation template, recommendation defaults, source values, FYI vs approval-gate flow, path conventions), read manifesto.md in this skill's directory.
Step 4: Run Pipeline
For each step in order:
- Announce the step:
## Flow: Running {step} ({N}/{total})
- Execute the full skill as documented in its own SKILL.md. For the
build step in record mode: compose, write, and commit the materialized file now (materialize.md's Composing the file + When this runs) — {run-dir}/work/{n}-spec.md per record, committed on the current branch before any worktree exists — then invoke /claude-tweaks:build #{n}[,#{m}...], which reads that file exactly as it reads a legacy spec file (and, when /build is invoked standalone with no /flow parent, performs this same materialize step itself instead of relying on it being pre-done).
- Check the gate — if the step fails its gate, stop the pipeline
- Pass context forward — each step's output feeds into the next:
build → check output for UI file changes (.tsx, .jsx, .vue, .svelte, .html, .css, component/page directories). If UI changed and no-stories not set → auto-detect dev URL via dev-url-detection.md in skills/_shared/ and run stories step.stories → test receives the stories directorybuild → test receives VERIFICATION_PASSED=true (so test skips redundant types/lint/tests — see verification.md in the /claude-tweaks:test skill). Test still runs QA if stories exist.test → review receives TEST_PASSED=true and QA results. Flow invokes /claude-tweaks:review in full mode (code + visual review) by default. The review skill delegates visual review to /claude-tweaks:visual-review, which handles its own browser and dev-server resolution:
- Browser + reachable app:
/visual-review runs the full visual review. Dev URL resolution (dev-url-detection.md) applies worktree awareness (a port serving the main checkout is rejected) and, in auto + worktree (flow's default), auto-starts an ephemeral dev server on a free port so the browser reviews this worktree's code. QA data is consumed when available.
- No browser backend (
agent-browser not installed): /visual-review reports the detection failure with install instructions. Review falls back to code mode. Flow notes: "Visual review skipped — no browser backend available."
- No reachable app and no dev command to start one:
/visual-review logs the gap and falls back to code mode. Flow notes: "Visual review skipped — no dev server and no start command."
- The ephemeral server (if started) stays up for the rest of the run and is torn down by
/wrap-up cleanup (Section D) — or, in multi-spec runs, once at the end by /flow.
review → polish (when no-polish not set) — invoke /claude-tweaks:design polish <spec> via the Skill tool. See "Polish phase execution" below for the dispatch logic.polish → re-verify (only when polish modified code) — invoke /claude-tweaks:test skip-qa. See "Re-verify execution" below.polish (or re-verify) → wrap-up receives the review summary, polish results, and verdict. Skill observations (build/skill and review/skill ledger entries) carry forward via the ledger file for wrap-up's skill update analysis (Step 7).
- Ledger carries forward — each step reads and appends to the open items ledger (see
/claude-tweaks:ledger for all operations). Unlike conversation context (which may be compressed), the ledger is a file — it survives context window limits.
Polish + re-verify execution
Follow the polish-phase decision tree in steps-and-gates.md. Mechanics specific to /flow:
Step 5: Present Pipeline Summary
Nothing-left-behind gate: Run the resolve gate from /claude-tweaks:ledger. If any item has status open, present it for resolution -- no item may remain open. The pipeline cannot complete with unresolved items.
Creative Opportunities survey (v4.5.0). Before rendering the summary, run decline detection (compares prior recommendations cache against the new diff to suppress repeatedly-declined items), then invoke /claude-tweaks:design survey <changed-files>. Returned recommendations render as a Creative Opportunities block (template below) before Next Actions; empty or {skipped} returns omit the block.
Depth Opportunities survey. Also before rendering the summary, run the depth survey — the responsible way a hands-off /flow captures /claude-tweaks:deepen's value. After the pre-check passes (source modules changed, no-deepen not set), invoke /claude-tweaks:deepen <changed-source-files> with $PIPELINE_RUN_DIR set, which runs /deepen's analysis-only path (module mapping + deletion test + leverage ranking — read-only). It returns ranked candidates without applying or staging-to-apply any refactor. Render the top candidates as a Depth Opportunities block (template below) before Next Actions; no candidates or a skipped pre-check omit the block. /flow never runs the interactive interface-design step or modifies code for a depth candidate — the block is a recommendation to run /claude-tweaks:deepen manually.
For both surveys' full procedures (wrapper/skill return handling, the depth pre-check and responsibility boundary) and the Creative Opportunities decline-detection algorithm, read survey.md in this skill's directory.
On successful completion of all steps:
## Flow: Pipeline Complete
### Spec {number}: {title}
| Step | Outcome |
|------|---------|
| build | Verification passed |
| stories | {Generated N stories | Skipped — no UI changes | Skipped — no-stories} |
| test | {Passed (types + lint + tests) | Passed (QA: N stories) | Passed (verification skipped — passed in build, QA: N stories)} |
| review | Verdict: PASS {(code + visual) | (code only — no browser)} |
| polish | {Invoked N commands ({list}); re-verify passed | Skipped — non-frontend | Skipped — no-polish | Skipped — Impeccable not installed | No changes to apply | re-verify failed (see failure card)} |
| wrap-up | Learnings captured, artifacts cleaned, ledger resolved |
### Key Outputs
- {summary of what was built}
- {summary of review findings, if any}
- {summary of wrap-up actions taken}
### Manual Steps Required
| # | What | Where |
|---|------|-------|
| 1 | {description} | {source} |
(or: No manual steps — nothing to do outside the codebase.)
> Complete these after merging. The pipeline detected them but cannot execute them.
### Actions Performed
{Rolled-up table from all phases. When >15 rows, collapse to per-phase summaries.}
| Action | Detail | Ref |
|--------|--------|-----|
| {rows from build, stories, review, polish, wrap-up phases} | ... | ... |
### Creative Opportunities
The polish phase ran the auto-fit + issue-driven + intent-driven commands. These could enhance the result further:
| Command | Why it might help |
|---------|------------------|
| `/impeccable:impeccable colorize dashboard` | Heavy monochrome — strategic accent color recommended |
| `/impeccable:impeccable animate settings` | Toggle interactions are static |
Each is a one-shot manual command; flow does not run these automatically.
> Render this block only when `survey` returned `recommendations` non-empty. When the wrapper reports `suppressed > 0`, append: `> N suggestion(s) hidden — previously declined for this spec. Reset with /claude-tweaks:design reset-recommendations <spec>.` Omit the entire section when the wrapper returned `recommendations: []` or `{skipped}`.
### Depth Opportunities
The depth survey analyzed the changed modules. These are shallow abstractions worth restructuring — `/flow` did **not** refactor them (architecture is low-reversibility; the depth refactor is a deliberate, interactive pass):
| Module | Kind | Why it's shallow | Leverage |
|--------|------|------------------|----------|
| `src/services/user.ts` | collapse | Pass-through wrapper — every method forwards one call to the DB | 4 callers simpler |
| `src/jobs/runner.ts` | deepen | Callers must call `init()`→`configure()`→`run()` in order; the module could own the sequence | smaller surface, 3 callers |
Run `/claude-tweaks:deepen <changed-paths>` to act on these — it presents candidates, then walks the interface design for the ones you pick. Flow never runs this automatically.
> Render this block only when the depth survey returned candidates. Cap at the top 3 by leverage; if more exist append `> N more lower-leverage candidates — run /claude-tweaks:deepen for the full list.` Omit the entire section when the survey found no shallow modules, the pre-check skipped it (no source modules changed), or `no-deepen` was set.
Next Actions
Close the template's fence above, then assemble the applicable options (the base 2 always; the two conditional options only when their trigger condition holds) and present them via one AskUserQuestion call as unfenced prose:
question: "What's next?", header: "Next step", multiSelect: false- Option 1 —
label: short name of the next spec's run suffixed (Recommended), description: "/claude-tweaks:flow {next spec} — full pipeline on spec {N}: \"{title}\""
- Option 2 —
label: "Pipeline status", description: "/claude-tweaks:help — full pipeline status"
- Option 3 (if unblocked specs) —
label: "Build {N}", description: "/claude-tweaks:build {N} — spec {N} \"{title}\" now unblocked"
- Option 4 (if the depth survey surfaced candidates) —
label: "Depth opportunities", description: "/claude-tweaks:deepen {changed-paths} — act on the {N} depth opportunit{y/ies} surfaced above"
Multi-Spec Sequential Flow
When multiple spec numbers or record references are provided (e.g., 42,45,48 or #42,#45,#48), flow runs each spec's (or record's) pipeline sequentially in one terminal. Each completes its full pipeline (build → test → review → polish → wrap-up) before the next begins.
Pre-flight enrichments (v4.6.4+):
- Dependency-aware ordering — reads each target's dependency declaration (
depends-on: frontmatter on a legacy spec-file target, blocked-by: on a record-reference target — see materialize.md's Populating the header), builds a DAG, hard-fails on cycles, and offers (or auto-applies in auto mode) topological re-ordering when the user's order violates the graph.
- Cross-spec conflict detection — pre-flight scans each spec's
Files: declarations; surfaces overlapping pairs as a footer line in the Pipeline Preview. Warning, not hard-fail.
Failure handling:
- Default: a HARD-GATE failure in one spec stops the remaining specs (compounding-risk safety).
keep-going: opt-in flag that continues the run past HARD-GATE failures. Failed specs surface in the consolidated Review Console's "Not run / Failed" footer.- Shared worktree: in
worktree mode a sequential multi-spec run uses one shared worktree for the whole run, not one per spec. /flow creates it once up front (from the current local HEAD), runs every spec inside it (per-spec builds skip creation via MULTISPEC_SHARED_WORKTREE=1), and finishes the single branch once at the end. Per-spec worktrees apply only to separate-terminal parallel runs.
Bookend architecture for multi-spec (v4.6.3+): in auto or hybrid mode, per-spec Wrap-Up Review Consoles are deferred — /flow sets MULTISPEC_REVIEW_DEFER=1 when invoking each spec's /wrap-up. After all specs complete (or keep-going finishes the run), /flow runs one consolidated Review Console that reads every per-spec decisions.md + staged/ and surfaces all approvals in one batch. This preserves the bookend promise (Manifesto at start, one Review Console at end) regardless of N. See multispec-review-console.md.
For the full validation rules, dependency-ordering procedure, conflict-detection logic, keep-going semantics, run directory layout (per-spec sub-namespacing under one parent dir), environment variables passed to each per-spec invocation, and consolidated Multi-Spec Summary template, read multi-spec.md in this skill's directory.
Parallel Development with Worktrees
For true parallel execution, run separate terminals with worktree mode — each terminal gets an isolated copy of the repository:
# Terminal 1 # Terminal 2 # Terminal 3
/claude-tweaks:flow 42 worktree /claude-tweaks:flow 45 worktree /claude-tweaks:flow 48 worktree
Each terminal creates its own worktree and feature branch. There is no file overlap risk because each worktree is a full, isolated copy.
For mode-selection guidance (worktree vs current-branch), the merge reconciliation procedure (merge order, conflict handling, conflict resolution prompt), and the post-merge summary template, read worktree-merge.md in this skill's directory.
Next Actions
Next Actions in /flow are outcome-conditional and rendered as part of the Pipeline Summary (Step 5 success template) or Failure Card (see failure-cards.md). See ## Pipeline Summary template above for the canonical AskUserQuestion call on success; see failure-cards.md for the per-failure-shape Next Actions blocks. There is no standalone Next Actions block here — the rendered block fires inside the success or failure template that matches the pipeline outcome.
Anti-Patterns
| Pattern | Why It Fails |
|---|
| Stopping the pipeline because the spec is "big" | Size is not a coupling signal. A clean 50-task spec runs through fine. The shape gate (Step 2.6) blocks on structural signals (cross-task deps, scope leak), not size. Under auto, the model is forbidden from inserting size-driven reality-checks beyond Step 2.6 — see _shared/auto-mode-contract.md. |
Inserting model-side reality-checks under auto | The user said auto. Concerns belong in the ledger or the failure card, not as blocking prompts. See _shared/auto-mode-contract.md for the full anti-list. |
| Ignoring gate failures and restarting | Gates exist to catch real problems — investigate before retrying |
| Running flow on specs with unmet prerequisites | The pipeline will fail at build — check dependencies first |
| Using flow for interactive skills | Capture, challenge, and specify need human decisions — they can't be automated |
Using batched execution in flow | Flow's purpose is hands-off automation — batched pauses for human review, contradicting flow's no-stopping design. Use /claude-tweaks:build batched directly. |
| Ignoring open ledger items at pipeline end | The nothing-left-behind gate prevents dropped work — every item must be explicitly resolved |
Treating auto as authorization to bulk-resolve the ledger | auto silences per the contract in _shared/auto-mode-contract.md. The resolve gate's Phase 2 is on the "What auto does NOT silence" list — every item requires explicit per-item user input |
| Creating a work record from inside flow without explicit per-item user approval | Both backlog and parked are valid destinations, but each record requires the user's explicit choice on that specific item. Pipeline phases never file a record autonomously, even when an item looks like an obvious candidate |
| Skipping test in the pipeline | Test is the mechanical gate — review depends on TEST_PASSED. Omitting test means review runs on potentially broken code. |
| Retrying polish after re-verify failure within the same flow run | The one-cycle cap exists to prevent oscillation (polish → fail → fix → polish → fail → ...). Surface the failure, let the user inspect, and require a fresh /flow {spec} polish to retry. |
| Treating polish skip as a flow failure | Polish skips are normal — non-frontend specs, no Impeccable, no-polish flag, no audit findings + no auto-fit changes needed all skip cleanly. The pipeline continues to wrap-up. |
Running re-verify without skip-qa | Browser QA is irrelevant after stylistic-only polish — re-verify uses /test skip-qa to keep the cycle fast. The Design CLI gate still runs (it is not QA). |
Using no-polish on a frontend spec by reflex | Polish is the value-add for frontend specs — only set no-polish when iterating fast or when the user has manually run Impeccable polish before flow. |
| Auto-running creative commands surfaced in the Creative Opportunities block | The block is recommendations only. Flow never executes Impeccable creative commands from survey output — the user invokes them manually if a suggestion resonates. |
| Applying (or staging-to-apply) a depth refactor inside flow | The depth survey is analysis-only. Architecture is low-reversibility and the depth refactor is interactive by design — flow surfaces candidates as recommendations and the user runs /claude-tweaks:deepen deliberately. Auto-refactoring module interfaces in a hands-off run is exactly the irresponsible move the survey boundary prevents. |
| Running the depth survey on a config-only or docs-only diff | The pre-check exists to keep cost proportionate — skip the survey when no source modules changed. Burning tokens reading call sites on a trivial diff is waste. |
| Rendering the Depth Opportunities block when the survey found nothing | An empty result means the abstractions are earning their keep, not that analysis was skipped — omit the block rather than implying there was nothing to analyze. |
| Rendering the Creative Opportunities block when survey returned empty or skipped | Survey is heuristic. An empty result means "nothing matched the criteria," not "design is complete." Rendering an empty block falsely implies completeness. Omit the block entirely. |
| Skipping decline detection on re-runs of the same spec | The declined-recommendations cache is what keeps the Creative Opportunities block from becoming noise across iterations. Read the prior recommendations cache, compare against the new diff, increment declines for un-invoked recommendations before invoking survey. |
Relationship to Other Skills
| Skill | Relationship |
|---|
/claude-tweaks:build | First step in the default pipeline — invoked against the record materialized via materialize.md (record mode, primary); spec-file mode is the legacy alias (design-mode bypass was removed). Sets VERIFICATION_PASSED=true. |
/claude-tweaks:stories | Auto-triggered between build and test when UI files change (unless no-stories). Ingests journey files from /build for journey-aware story generation. Both skills consume dev-url-detection.md from skills/_shared/ for URL resolution. |
/claude-tweaks:test | Mechanical gate between build/stories and review — types, lint, tests, QA. Receives VERIFICATION_PASSED from build (skips redundant checks). Sets TEST_PASSED=true. |
/claude-tweaks:review | Analytical gate — receives TEST_PASSED=true from test, produces verdict. Runs in full mode (code + visual) by default; delegates visual review to /visual-review which handles its own browser detection. Code mode fallback when no browser available. Never runs verification or QA itself. |
/claude-tweaks:visual-review | Invoked transitively by /review in full mode. Handles browser detection, dev URL resolution, and the full visual review procedure. |
/claude-tweaks:wrap-up | Final step — receives review output, produces clean slate |
/claude-tweaks:deepen | Invoked BY /flow at the Pipeline Summary (Step 5) in analysis-only mode — runs the read-only depth analysis and surfaces shallow-module candidates as a Depth Opportunities recommendation block. /flow never applies a depth refactor (low-reversibility + interactive); the user runs /deepen manually. Skipped by no-deepen or when no source modules changed. |
/claude-tweaks:help | Shows pipeline status and recommends flow-ready specs |
/claude-tweaks:specify | Produces the ready leaf records /flow accepts as #N/#A,#B, materialized via materialize.md — flow never calls /specify internally; an unshaped record's materialization hard gate points back here instead. Also creates the legacy numbered specs the alias path still reads. |
/claude-tweaks:browse | Used transitively — /stories and /review visual modes use /browse for browser interaction |
/superpowers:brainstorming | Produces design docs that /claude-tweaks:specify decomposes into the specs flow consumes. Flow no longer accepts design docs directly — the granularity contract requires /specify between brainstorming and execution. |
/superpowers:using-git-worktrees | Invoked BY flow (when worktree specified) to create the isolated workspace — once per single-spec run, or once per sequential multi-spec run (one shared worktree for all specs) |
/superpowers:finishing-a-development-branch | Invoked BY flow (when worktree specified) at handoff to merge, PR, or discard the feature branch — once at the end of the run (a sequential multi-spec run finishes its single shared branch once, not per spec) |
/claude-tweaks:ledger | Manages the open items ledger. /flow creates the ledger (Step 1), carries it across phases, and runs the resolve gate (Step 5). |
/claude-tweaks:design | /flow invokes /claude-tweaks:design polish <spec> after review verdict PASS (auto-fit + issue-driven + intent-driven dispatch — v4.5.0). The wrapper handles its own detection (non-frontend skips); when polish modifies code, /flow follows up with /test skip-qa (re-verify gate, one-cycle cap). The no-polish argument removes the polish phase entirely. /flow's pipeline summary also invokes /claude-tweaks:design survey <full-diff> to render the Creative Opportunities block (anchor 3 of v4.5.0's creative surfacing system); /flow handles decline detection by comparing the prior recommendations cache against the new diff before each survey call. |
/claude-tweaks:journeys | /journeys produces journey files that /flow's auto-stories step (post-build) ingests so derived stories carry journey: field and inherited source files. |
/claude-tweaks:triage | The human gate upstream of /claude-tweaks:dispatch — grants auto:build/auto:merge on records /flow may later build. Triage itself never invokes /flow, and never selects, filters, sorts, or claims records. |
/claude-tweaks:dispatch | The actual caller of record-mode /flow — claims an authorized record's whole file-overlap group, then invokes CLAIM_RUN_ID="{run-id}" /claude-tweaks:flow #{n}[,#{m}...]. /flow never selects, filters, sorts, or claims records itself; that logic lives entirely in /claude-tweaks:dispatch (selection) and /claude-tweaks:triage (authorization). /flow is opaque to dispatch — materialization (record resolution, multi-record bundling) is /flow's own concern. |
_shared/auto-mode-contract.md | Single source of truth for auto-mode behavior — read before adding any auto-mode handling in /flow. Governs the bookend architecture (Step 3 Manifesto = begin stop, /wrap-up Review Console = end stop), what auto silences, and what it never silences. |
_shared/pipeline-run-dir.md | /flow creates the pipeline run directory at Step 3 (Manifesto) and exports PIPELINE_RUN_DIR to every downstream skill per this shared procedure. Multi-spec runs use the per-spec subdirectory layout documented in multi-spec.md, also rooted in this contract. |
_shared/issue-claims.md | /flow no longer claims records itself — /claude-tweaks:dispatch claims before handing off. Release on a record-mode run happens via /wrap-up's generic Section E abandoned: path (user doesn't merge) or a failure-card-offered release (gate failure) — the same mechanisms any single-spec run already uses, not a flow-specific "console decline" step. |
/claude-tweaks:routine | /flow no longer ships its own routine template — /routine create dispatch instantiates the scheduled headless dispatcher instead (see /claude-tweaks:dispatch). |
