Skip to main content
command CX Codex

refine — Claude Code command for refining specs

refine is a Claude Code command that asks one focused round of questions about a spec, task, or file, or researches related documentation.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What refine does

Pass a spec ID, task ID, or file path to refine. It invokes the flow-next-refine skill for a single interview, with an optional --scope lens to focus on business, technical, or another audience’s decisions. Use --scope=research for a separate read-only pass: it gathers findings from documentation and related sources, then adds a Resolved via Research section after read-back approval.

--docs and --no-docs control glossary and decision-record handling; the command can also detect this mode from project materials. Research is skipped when its findings are already present, while --force runs it again. Acceptance criteria with R-IDs stay append-only, and the read-back identifies the sections changed during the session.

In Claude Code, add and install the flow-next marketplace plugin with the commands below. For Codex, the prompt path is ~/.codex/prompts/refine.md.

What it helps with

  • clarify a spec with a single question pass
  • focus decisions on business or technical concerns
  • research documentation for API and library changes
  • record terminology and decisions in project materials
  • rerun the research pass with --force

Example prompts for the agent

  • Refine fn-1-add-oauth around the product decisions that could change the build.
  • Research fn-1-add-oauth without asking questions.
  • Review the technical requirements in specs/auth.md using --tech.

How to install refine

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

2Manually: put the files in place

.claude/commands/refine.md

Call it with /refine. For all projects use ~/.claude/commands/

Questions about refine

How do I install refine in Claude Code?

Run /plugin marketplace add gmickel/flow-next, then /plugin install flow-next@flow-next. The command file path is .claude/commands/refine.md.

What does the refine command do?

It starts one round of questions about a spec, task, or file. With --scope=research, it gathers documentation findings instead of asking questions.

Can I focus refine on a specific area?

Yes. Set --scope=<lens> to the area you want to examine; --biz and --tech are shortcuts for business and technical focus. Use --scope=research to run without questions.

Source text

refine.md · MIT
---
name: refine
description: Refine a spec, task, or spec file - one question pass that asks only what would change the build, optionally focused by a free-text scope lens, or a read-only research pass
argument-hint: "[spec ID, task ID, or file path] [--scope=<lens> | --scope=research | --biz | --tech] [--docs | --no-docs] [--strategy | --no-strategy] [--force]"
disable-model-invocation: true
---

# IMPORTANT: This command MUST invoke the skill `flow-next-refine`

The ONLY purpose of this command is to call the `flow-next-refine` skill. You MUST use that skill now.

**User input:** $ARGUMENTS

Pass the user input to the skill. The skill handles the interview and the research pass.

## Optional flags

### Scope

- `--scope=<lens>` — optional free-text lens: `business`, `technical`, `qa`, `security`, or any other audience. Refine runs one interview either way; the lens focuses the questions on that audience's decisions, and each answer is written to the section it belongs in. No lens means no filter, and refine never asks which scope to run.
- `--biz` — alias for `--scope=business`.
- `--tech` — alias for `--scope=technical`.
- `--scope=research` — runs no questions. Dispatches the read-only docs, practice, docs-gap, and memory scouts (github when `scouts.github` is on) over the spec's or task's surface and writes a `## Resolved via Research` section (one sub-block per scout: library versions, changed APIs, gotchas, docs that must change, memory that applies, each with its source) through the same read-back approval. Observably skipped, with the reason printed and nothing written, when the section already exists or plan's scout findings are already on the spec's tasks; `--force` reruns it; a spec that now names a library the plan never saw reruns it scoped to that delta.

Sections no answer belongs in come back byte-for-byte, and the read-back names every section the session changed. R-IDs in `## Acceptance Criteria` are append-only — never renumbered, never replaced.

### Doc-aware

- `--docs` — force doc-aware mode on. The pass reads the nearest-ancestor `GLOSSARY.md` and `.flow/memory/knowledge/decisions/`, surfaces glossary conflicts, sharpens overloaded terms via `flowctl glossary add`, and writes decision entries via `flowctl memory add --track knowledge --category decisions ...` when the three-criteria gate passes. If no `GLOSSARY.md` exists yet, the first resolved term lazy-creates one at the repo root.
- `--no-docs` — force doc-aware mode off, even when `GLOSSARY.md` or decision entries exist.
- `--strategy` / `--no-strategy` — force the strategy-aware gate independently of `--docs` / `--no-docs`. Without an explicit flag, `--docs` / `--no-docs` cascades to strategy.

Without any doc-aware flag, the mode autodetects: it activates when `GLOSSARY.md` has at least one defined term (`flowctl glossary list --json` reports `total_terms > 0`) OR `.flow/memory/knowledge/decisions/` has at least one entry OR `STRATEGY.md` has populated sections. An empty `# Glossary` husk left behind after the last term is removed does not trip autodetect.

The scope lens is orthogonal to doc-aware — both combine freely (e.g., `--scope=business --docs`).

Examples:

- `/flow-next:refine fn-1-add-oauth` — one interview, no lens, autodetect doc-aware
- `/flow-next:refine fn-1-add-oauth --biz` — the same interview, focused on the product owner's decisions
- `/flow-next:refine fn-1-add-oauth --scope=qa` — focused on what QA decides (what counts as done, which failures matter)
- `/flow-next:refine fn-1-add-oauth --scope=business --docs` — business lens with doc-aware mode forced on
- `/flow-next:refine fn-1-add-oauth --no-docs` — force doc-aware off
- `/flow-next:refine fn-1-add-oauth --scope=research` — external-docs pass; no questions; skipped when the section or plan's findings already exist
- `/flow-next:refine fn-1-add-oauth --scope=research --force` — rerun the external-docs pass and replace the section

© Gordon Mickel · MIT · gmickel/flow-next

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set70

The whole set →
flow-next-worktree-kit flow-next-worktree-kit is a Claude Code skill that creates, switches, and removes git worktrees and copies .env files between them. It supports parallel feature work without switching branches. CX Codex +1 ★ 730repo stars flow-next-land The flow-next-land skill handles feedback and CI checks for a named pull request, then squash-merges it when authorized and ready. Use it when asked to land a specific PR. CX Codex +1 ★ 730repo stars flow-next-make-pr flow-next-make-pr opens a pull request through gh, with the briefing body rendered by flowctl from the flow-next spec state. Fits repos where PRs are expected to follow a spec. CX Codex +1 ★ 730repo stars uninstall uninstall removes flow-next from your repository. It cleans docs markers and generates safe terminal commands for deleting project files. CX Codex +1 ★ 730repo stars workflow-scout workflow-scout scans repository CI/CD configs, PR and issue templates, automated review bots, and release tooling for readiness checks. CX Codex ★ 730repo stars tooling-scout tooling-scout scans projects for linters, formatters, type checkers and hooks. It is invoked by /flow-next:prime and should not be called directly. CX Codex ★ 730repo stars flow-next-resolve-pr flow-next-resolve-pr coordinates resolution of GitHub PR review feedback, dispatches resolver agents across threads, and closes discussions via GraphQL. CX Codex +1 ★ 730repo stars build-scout build-scout scans project build setup, run commands, CI, and output files. It works through /flow-next:prime, not as a standalone command. CX Codex ★ 730repo stars

Project sponsors

Companies that keep this analytics open