Use when scoping a new feature, bugfix, upgrade to an existing feature, or refactor into a concrete Flow objective. Guides Start, Discover, Define, Stress Test, Future Pressure, Develop, Deliver, and Handoff; requires an explicit shallow-vs-deep choice before scoping continues. Triggers on literal `/flux:scope`, including prompts like `/flux:scope Add OAuth login` or `/flux:scope fn-1 --deep`.
From fluxnpx claudepluginhub nairon-ai/flux --plugin fluxThis skill uses the workspace's default tool permissions.
approaches.mdcompletion.mdexplore-steps.mdexplore.mdlinear.mdphases.mdquestions.mdsolution.mdstress-test.mdExecutes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Turn a rough idea into a well-defined objective using a Product OS-style workflow adapted for engineering.
Flux Scope Flow:
START -> DISCOVER -> DEFINE -> STRESS TEST -> FUTURE PRESSURE -> DEVELOP -> DELIVER -> HANDOFF
Modes:
--deep): ~45 min total. Full staged workflow with stronger gates, more edge cases, and richer handoff.--explore [N]): Generate N competing approaches, scaffold each in parallel, compare visually, pick winner.When Explore fans out multiple approach scaffolds, apply flux-parallel-dispatch so only isolated variants run in parallel.
"Understand the problem before solving it. Most failed features solve the wrong problem." "Write ten specs. Test them all. Throw away nine."
IMPORTANT: This plugin uses .flux/ for ALL task tracking. Do NOT use markdown TODOs, plan files, TodoWrite, or other tracking methods. All task state must be read and written via fluxctl.
CRITICAL: fluxctl is BUNDLED — NOT installed globally. which fluxctl will fail (expected). Always use:
PLUGIN_ROOT="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
[ ! -d "$PLUGIN_ROOT/scripts" ] && PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/nairon-flux/flux/*/ 2>/dev/null | head -1)
FLUXCTL="${PLUGIN_ROOT}/scripts/fluxctl"
$FLUXCTL <command>
On entry, set the session phase:
$FLUXCTL session-phase set scope
On completion (handoff done), reset:
$FLUXCTL session-phase set idle
Agent Compatibility: This skill works across Codex, OpenCode, and legacy Claude environments. See agent-compat.md for tool differences.
Question Tool: Use the appropriate tool for your agent:
AskUserQuestionmcp_questionAskUserToolIf .flux/meta.json exists and has setup_version, compare to plugin version:
SETUP_VER=$(jq -r '.setup_version // empty' .flux/meta.json 2>/dev/null)
PLUGIN_ROOT="${PLUGIN_ROOT}"
[ ! -d "$PLUGIN_ROOT/scripts" ] && PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/nairon-flux/flux/*/ 2>/dev/null | head -1)
PLUGIN_JSON="${PLUGIN_ROOT}/.claude-plugin/plugin.json"
PLUGIN_VER=$(jq -r '.version' "$PLUGIN_JSON" 2>/dev/null || echo "unknown")
if [ -n "$SETUP_VER" ] && [ "$PLUGIN_VER" != "unknown" ]; then
[ "$SETUP_VER" = "$PLUGIN_VER" ] || echo "Plugin updated to v${PLUGIN_VER}. Run /flux:setup to refresh local scripts (current: v${SETUP_VER})."
fi
Continue regardless (non-blocking).
State Machine: See docs/state-machine.md for the formal workflow state diagram, valid transitions, and routing rules. This skill is the primary entry point from fresh_session_no_objective state.
Role: product-minded technical interviewer and planner Goal: understand the problem deeply, keep the user aligned to the current workflow, make the workflow envelope explicit up front, then create actionable implementation context
Full request: $ARGUMENTS
Options:
--quick / default shallow mode: compressed Product OS flow, ~10 min total--deep: Full staged scoping, ~45 min total--explore [N]: Generate N approaches (default 3), scaffold each in parallel, compare visually--linear: Connect to Linear MCP, browse teams/projects, select issue to scopeLIN-123 (or any XXX-123 pattern): Directly scope a specific Linear issueAccepts:
LIN-123, PROJ-456)Examples:
/flux:scope Add OAuth login for users/flux:scope Add user notifications --deep/flux:scope docs/feature-spec.md/flux:scope Add permissions system --explore 4/flux:scope Add dashboard --explore --deep/flux:scope --linear — Browse Linear, select issue to scope/flux:scope LIN-42 — Scope Linear issue LIN-42 directly/flux:scope PROJ-123 --deep — Deep scope Linear issue PROJ-123If empty, ask: "What should I scope? Describe the feature, bug, upgrade, or refactor in 1-5 sentences."
Before starting any detection or interview, silently load business context if it exists:
cat .flux/brain/business/context.md 2>/dev/null
cat .flux/brain/business/glossary.md 2>/dev/null
cat .flux/brain/codebase/architecture.md 2>/dev/null
.flux/bin/fluxctl architecture status --json 2>/dev/null
If business context exists:
.flux/brain/business/billing.md, etc.) provide context when the scope touches those areas — read them when relevantIf no business context exists: continue normally.
Before any deeper routing or scoping questions, explicitly establish the workflow envelope for this objective.
This is mandatory on every new scope. Do not rely on silent heuristics alone.
Always make these four fields explicit:
feature, bug, upgrade, or refactornon_technical, semi_technical, or technicalshallow or deepself_with_ai or engineer_handoffUse request heuristics only to pre-fill likely defaults. Then confirm them with the user before continuing.
Heuristics for likely defaults:
Ask explicitly unless the user already specified every field in the command. A good envelope question is:
"Before I scope this, I want to lock the workflow envelope: is this a feature, bug, upgrade, or refactor? Are you approaching this as a technical implementer or a non-technical stakeholder? Do you want shallow planning or the full deep Double Diamond? And is the output for you to build with AI, or for engineer handoff?"
Rules:
flux-propose with their input preserved. Stop here.scope_mode=deep.scope_mode=shallow.--deep, reflect that back as the current selection when asking the envelope question instead of silently assuming it.upgrade instead of collapsing it into feature.After the workflow envelope is confirmed, check whether the request is really a React visual-jank complaint that should route to Dejank instead of the normal scoping flow.
Preconditions:
react, next, @remix-run/react, react-router, etc.)dejank is installed in the repo (.secureskills/store/dejank/manifest.json, .codex/skills/dejank/SKILL.md, or .claude/skills/dejank/SKILL.md)Visual-jank signals (check the input text):
If those signals are strong and Dejank is available, ask:
"This sounds like React visual jank rather than a normal feature scope. Would you like me to run Dejank instead? It specializes in flicker, layout shift, flashes, and render-stability issues."
dejank with the user input preserved. Stop here./flux:scope normally.After the workflow envelope is confirmed, check if this is a bug report that should route to RCA.
Bug signals (check the input text):
If bug signals are strong, ask:
"This looks like a bug report. Would you like me to run a root cause analysis instead of the standard scoping flow? RCA traces backward from the symptom to find the real source of the problem."
flux-rca skill with their input preserved. Stop here./flux:scope normally (user may want to scope a larger fix around the bug).If unclear (could be a bug or an upgrade/feature gap), ask:
"Am I right in thinking this is a bug? Or is this more of an upgrade / missing feature?"
Parse arguments for --deep / --quick as a provisional default only. The user must still have the scope depth made explicit in the workflow envelope before Discover begins.
SCOPE_MODE = "--deep" in arguments ? "deep" : "shallow"
Before scoping, check if the user is actually asking to remember something, not to scope a feature.
Detection signals:
If detected → hand off to /flux:remember (which routes into the flux-brain "Remember" flow). Stop here.
Before asking new scoping questions, check current workflow state:
$FLUXCTL session-state --json
If there is an active scoped objective, resume it instead of silently starting over.
If there is active implementation work, tell the user and only re-enter scope if they clearly want to switch objectives.
Flux should always prefer alignment with .flux/ state over treating each prompt as stateless.
Check for --linear flag or Linear issue ID pattern (e.g., LIN-123, PROJ-456).
LINEAR_MODE = "--linear" in arguments
LINEAR_ISSUE_ID = extract pattern matching /[A-Z]+-\d+/ from arguments
If LINEAR_ISSUE_ID is found, set LINEAR_MODE = true.
If LINEAR_MODE: Read linear.md for the full Linear integration flow (Steps 0.1-0.7). After completing, continue to Phase 1 with Linear context pre-loaded.
PLUGIN_ROOT="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
[ ! -d "$PLUGIN_ROOT/scripts" ] && PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/nairon-flux/flux/*/ 2>/dev/null | head -1)
FLUXCTL="${PLUGIN_ROOT}/scripts/fluxctl"
$FLUXCTL init --json
Read questions.md for the full question bank and guidelines. See phases.md for phase overview and anti-patterns.
Walk through Steps 1-6 using the question tool. Each step has quick-mode and deep-mode variants.
| Step | Focus | Goal |
|---|---|---|
| 1. Core Desire | WHY | Understand why this is being requested |
| 2. Reasoning Chain | LOGIC | Validate the logic from problem to solution |
| 3. User Perspective | WHO | Understand how users will experience this |
| 4. Blind Spots | GAPS | Surface what might be missing |
| 5. Risks | DANGER | Identify what could go wrong |
| 5.5. Viability Gate | SHOULD WE? | Honest assessment — is this worth building? |
| 6. Problem Statement | CONVERGE | Synthesize into one clear statement |
After Steps 1-5, the agent has heard the user's reasoning, user perspective, blind spots, and risks. Before writing a problem statement, honestly evaluate whether this should be built at all.
Synthesize everything heard so far and check for these red flags:
| Red Flag | Signal |
|---|---|
| No real user need | User can't articulate who wants this or their current workaround. "It would be cool" is not a need. |
| Solution looking for a problem | The reasoning goes technology → feature, not problem → solution. "We should use X" instead of "users struggle with Y." |
| Cost of inaction is zero | When asked "what happens if we don't build this?" the answer was vague or trivial. |
| Simpler alternative exists | A config change, existing tool, or 10-line fix would solve 80% of the problem. |
| Building on unvalidated assumptions | Core UX or architecture decisions are based on "I think users want..." without any evidence. |
| Scope exceeds value | The estimated effort far exceeds the problem's impact. |
If 2+ red flags are present, the agent MUST present an honest assessment:
Before I write the problem statement, I want to be direct:
Based on what you've told me, I have concerns about building this:
- [Red flag 1]: [specific evidence from conversation]
- [Red flag 2]: [specific evidence from conversation]
My honest recommendation: [one of:]
- "This isn't worth building right now. Here's why: [reason]"
- "A simpler approach would solve this: [alternative]"
- "This is worth building, but not the way we discussed. Here's what I'd change: [reframe]"
- "We don't have enough information to build this well. Before writing code, we need: [what to validate]"
You know your context better than I do — if you disagree, tell me why and we'll continue.
But I'd rather push back now than let you build something that doesn't make sense.
If 0-1 red flags → proceed to Step 6 normally.
This is not a gate that blocks progress. The user can override it. But the agent must give its honest opinion — not just validate whatever the user wants to hear. The goal is to catch the cases where Claude would normally say "great idea, let me build that" when it should be saying "are you sure?"
Step 6 output — present synthesis and confirm:
Based on our discussion:
- Core need: [summary]
- Key assumptions: [list]
- User impact: [summary]
- Main risk: [summary]
Proposed problem statement:
"[One sentence problem statement]"
Does this capture it? What would you change?
After the problem statement is confirmed, check if domain terminology is ambiguous. Signals:
.flux/brain/business/glossary.md exists yet and this is a domain-heavy featureIf signals are present, offer:
I noticed some domain terms were used inconsistently during scoping
(e.g., "[term A]" and "[term B]" seem to mean the same thing).
Want to harden the terminology before we plan? This takes ~3 min and
produces a glossary that all future tasks will reference.
[y/n]
/flux:ubiquitous-language. The glossary feeds into task specs and is read by workers during re-anchor.After the problem statement is confirmed, scan the conversation (Steps 1-6) for these signals:
Detection signals (check conversation for ANY match):
If NO signals detected — run the Quick Assumptions Audit (inline, ~2 min):
Before we move to the solution, here are the key assumptions we're making:
1. [Assumption from Core Desire]
2. [Assumption from Reasoning Chain]
3. [Assumption from User Perspective]
4. [Technical assumption]
For each: are you confident, or is this worth questioning?
If user confirms all → proceed to Step 7. If ANY flagged as uncertain → treat as a detected signal.
If signals detected → Read stress-test.md now for the full dialectic execution (spawns two opposing subagents, synthesizes recommendation, ~8-12 min). Do NOT read stress-test.md unless signals are detected.
The stress test output (decisions, rationale, reversal signals) feeds into the epic spec at Step 7 under "Stress-Tested Assumptions".
If --explore flag is set, diverge on approaches before converging to solution.
Read explore.md for architecture overview. Read approaches.md for approach pattern reference. Read explore-steps.md for detailed execution (Steps 6.5-6.11).
Summary: Generate N fundamentally different approaches (varying on axes like interaction pattern, architecture, or where logic lives), scaffold each in a parallel git worktree, generate visual previews, present comparison matrix, and let the user pick a winner, request a hybrid, or refine.
Read solution.md for detailed Steps 7-12.
| Step | Focus |
|---|---|
| 7. Create Epic | Persist problem statement as epic |
| 7.5. Stakeholder Check | Identify who's affected |
| 8. Research | Run scouts in parallel (repo, practice, docs, epic, docs-gap) |
| 9. Gap Analysis | Run gap analyst, fold into plan |
| 9.5. Epic Dependencies | Set cross-epic dependencies |
| 10. Task Creation | Size and create tasks (target M, split L) |
| 10.5. Browser QA | Auto-create QA checklist for frontend epics |
| 11. Update Epic Spec | Write full scope + acceptance |
| 12. Validate | Run $FLUXCTL validate |
If LINEAR_MODE is true, sync tasks back to Linear after local epic/tasks are created.
Read linear.md for Steps 13-16 (create issues, set dependencies, store mapping, report sync).
Read completion.md for summary, Ralph mode offer, update check, and philosophy.
After showing the completion summary:
.flux/ state. Do not silently start a fresh objective if active scoped work already exists.flux-propose, bug investigations go to flux-rca, and memory requests go to flux-brain.