scope

name

scope

description

ALWAYS invoke this skill when the user asks to scope, promote, formalize, cluster, or track new work — do not start drafting items inline. Promotes ideas from .work/backlog/ or fresh user requests into the active tier as epics, features, or stories with declared dependencies. Use when scoping new work, formalizing a new direction, clustering backlog, or promoting an idea into tracking. Triggers on "scope this", "scope it", "let's scope", "scope this item", "scope the backlog", "promote this", "let's track this", "this should be a feature/epic/story", or any request to formalize a new direction. For vision/spec/architecture changes, also rolls foundation docs forward in the same stride.

Scope

You promote an idea to active substrate work. You decide the right kind (epic / feature / story), declare dependencies, and — if scope is large enough to change the project's standing context — roll foundation docs forward as part of the same operation.

When to invoke

Trigger phrases:

• "scope this", "promote this to active"
• "let's track this as a feature"
• "this needs to be a feature/epic/story"
• A new direction surfaces and the user wants to formalize it
• "scope the backlog", "scope all of this", "cluster the backlog", "promote the backlog", or scope <NL filter> like "scope the auth stuff" → batch / clustering mode (see Invocation modes below)

If the user wants to fix a bug, use /agile-workflow:fix. If they want to capture an idea without acting on it, use /agile-workflow:park.

Invocation modes

Invocation	Behavior
scope <id>	Single-idea mode — promote one backlog item at .work/backlog/<id>.md.
scope <free-form idea>	Single-idea mode — distill the user's fresh idea, then promote.
scope (no arg)	Default → equivalent to --all: batch / clustering mode over all of .work/backlog/.
scope --all	Explicit batch / clustering mode over all of .work/backlog/.
scope <NL filter> (e.g. scope the auth-related stuff, scope everything tagged perf)	Batch / clustering mode over the filtered subset of .work/backlog/. The filter is interpreted by the agent as a directive against the backlog, not parsed as a flag.

Disambiguation. An arg is treated as a backlog <id> only if .work/backlog/<arg>.md exists. Otherwise: if it reads like a one-paragraph fresh idea, treat as single-idea mode; if it reads like a filter directive over the backlog (mentions tags, areas, themes, or "everything that..."), treat as batch-filter mode. When genuinely ambiguous, prefer batch-filter mode and confirm via structured question tool before writing — a bigger read costs nothing, but a fresh idea misread as a filter wastes user time.

Workflow — batch / clustering mode

Use this path for scope, scope --all, or scope <NL filter>. Goal: read the targeted backlog, find natural clusters, propose a structure (epics / features / stories), confirm with the user once, then promote.

Phase B1: Inventory the backlog

Read every targeted backlog file. Targeting:

• scope / scope --all → all of .work/backlog/*.md
• scope <NL filter> → interpret the filter against each backlog file's body and tags; keep matches. Log the interpretation for the run summary.

For each item, capture id, brief, tags, and any inline hints (referenced files, areas, related ids).

If the targeted set is empty, halt with a clear message — suggest a narrower filter or /agile-workflow:park for fresh ideas.

If the targeted set is a single item, fall through to single-idea mode with that item.

Phase B2: Light grounding

Read docs/VISION.md, docs/SPEC.md, docs/ARCHITECTURE.md, .work/CONVENTIONS.md, and AGENTS.md / CLAUDE.md. One pass, skim — you're orienting, not absorbing every detail. You'll re-read selectively for large clusters in Phase B5.

Phase B3: Map code areas (read-first, maybe one exploratory sub-agent)

Start locally. Use Glob/rg --files to identify likely modules, packages, and tests, and Grep/rg for terms from the targeted backlog ideas. If the ideas clearly touch a small set of known areas, build the area-map yourself and skip exploratory fanout.

Spawn one read-only exploratory sub-agent only when the batch spans unclear code areas or you cannot confidently name the natural seams from direct reading. Use the host's generic/general-purpose subagent prompted with the explorer capsule from ../principles/references/subagents.md, at medium effort. If no generic subagent adapter is available, keep the area-map in the host session. Give it:

• The list of targeted backlog ideas (id + brief, one per line)
• A one-paragraph summary of the foundation docs from Phase B2
• The question: "Which areas of the codebase do these ideas touch, and what natural seams (modules, packages, bounded contexts) group them?"

Expect back an area-map keyed by code seam, with backlog ids attached to each seam plus a one-line rationale. Don't recurse — one pass.

If the agent's confidence is low for an idea (no clear code touchpoint), note it and fall back to text-only clustering for that idea in Phase B4.

Phase B4: Cluster

Using the area-map plus the backlog text, group ideas into clusters. Each proposed cluster gets a kind, a parent decision, and a one-line rationale.

Sizing heuristics (same as single-idea-mode Phase 2, applied per cluster):

Cluster shape	Proposed kind
1 item, no architectural shift	story (standalone)
2-5 cohesive items in one area, deserves a design pass, no foundation-doc impact	feature; backlog items become child stories or design inputs
Multi-feature scope, OR shifts vision / spec / architecture / audience, OR a clear capability arc that wants epic-design decomposition	epic

Bias rules:

• Lean smaller — prefer multiple features over one giant epic. But forming an epic as a natural grouping is fine even without a foundation-doc shift: if a set of backlog items clearly belongs under one capability arc, hand it to /agile-workflow:epic-design rather than pre-flattening it into features here.
• Don't force-cluster. Ideas that don't naturally belong with anything else are leftovers; handle them in Phase B6.
• [refactor] tag application. Only tag a cluster [refactor] if it passes the black-box test — no observable behavior change for callers of the public surface. Pure structural cleanup (dedupe, split, rename, dead-code removal) qualifies. "Major rework that keeps the surface" or anything that shifts internal semantics does NOT — let those route through feature-design. Same rule for [perf]: pure performance work on an existing capability only.

Phase B5: Strategic decisions (per large cluster)

For each cluster sized large (epic with foundation-doc impact), run the single-idea-mode Phase 1.7 logic — derive 2-5 strategic-level ambiguities for that cluster (vision / spec / architecture / audience layer) and queue them for the Phase B7 confirmation gate.

For small / medium clusters and for "natural grouping" epics with no foundation-doc impact, skip — strategic ambiguities fall to epic-design or feature-design later.

If more than 3 clusters are sized large, defer strategic decisions to the design family entirely — don't try to consolidate them into one round.

Phase B6: Prepare leftovers question

Identify backlog items that didn't fit any cluster. Queue a multi-select question for the Phase B7 gate, offering per leftover:

• promote as standalone story
• promote as standalone feature
• leave in .work/backlog/ (default)

Phase B7: Confirm with the user (single round-trip)

Make one structured question tool call covering all of the below (the tool accepts 1-4 questions per call):

1. Cluster structure — present each cluster (ids included, proposed kind, proposed parent, one-line rationale) and accept adjustments. Common NL feedback: "merge clusters 2 and 3", "split that cluster", "make X an epic instead", "move Y under Z". The "Other" option handles free-form replies.
2. Strategic decisions — one question per large cluster from Phase B5 (skip if more than 3 large clusters per the Phase B5 rule).
3. Leftovers disposition — the multi-select question prepared in Phase B6.

Apply the adjustments and proceed. One gate is enough — do not loop on a second confirmation round.

Phase B8: Promote each confirmed cluster

For each cluster, run the single-idea-mode Phases 3-6 inline:

1. Declare dependencies — within-cluster (child stories under a feature) and cross-cluster (one feature depends on another's output). Use work-view --blocking for cycle detection.
2. Foundation-doc roll-forward (large clusters only) — full Phase 4 of single-idea mode, scoped to that cluster's impact.
3. Write item files — the parent (epic or feature) plus any child files. Use git mv to move backlog files into the new structure where they map 1:1; reference the backlog idea in the parent's brief and git rm the backlog file where it was absorbed without a direct child.
4. Commit per cluster — scope: <cluster-id> (<kind>, <size>) with a foundation-doc roll-forward note where applicable.

Promote leftovers per the Phase B7 decision (one commit per promoted leftover, same message format).

Phase B9: Output

In conversation:

• Filter interpretation (NL-filter mode only): one-line description of how the filter was applied
• Clusters promoted: for each, <id> (<kind>, <size>) with member backlog ids
• Leftovers: list with disposition (promoted as standalone story/feature, or left in backlog)
• Foundation docs rolled forward: list of files touched (or "none")
• Next: design family picks up drafting features/epics (/agile-workflow:feature-design, epic-design, refactor-design, perf-design, prose-author for [prose] features, or agentic-research:research-orchestrator for [research] features when that plugin is installed — without it the tag is inert and the item routes through feature-design — based on kind and tags); implementing stories are ready for an autopilot goal or /agile-workflow:implement-orchestrator ([research] items run end-to-end through the research-orchestrator, not the implement family; prose features implement inline).

Workflow — single-idea mode

Use this path for scope <id> and scope <free-form idea>. The phases below also serve as the per-cluster engine for batch mode Phase B8.

Phase 1: Source the idea

The input is one of:

• A backlog item: .work/backlog/<id>.md exists. Read its body.
• A fresh request: the user is describing the idea directly. Distill it to a clear one-paragraph statement.

Phase 1.5: Explore the idea (large-scope only)

For small or medium scope, skip this phase — go to Phase 1.7.

For large scope (something that may change vision/spec/architecture), have a short freeform conversation before sizing. Cover:

• What — what does this add? What's the user-facing behavior or new capability?
• Why — what problem does it solve? What's the motivation?
• Where — where does it fit in the existing architecture? What does it touch?
• Scale — focused addition or significant new direction?
• Dependencies — external APIs, libraries, or internal features required?
• Constraints — performance, compatibility, security considerations?

Push for specificity. "Handle errors well" becomes "invalid input returns a 400 with a structured error body." When you can articulate the addition clearly, summarize and ask: "Did I get this right?"

Then proceed to Phase 1.7.

Phase 1.7: Surface strategic-level design ambiguities

Before sizing or writing the item, derive specific, concrete strategic questions about this idea — directional choices at the vision / spec / architecture / audience layer. These are the calls that, if locked in now, will set the frame for the whole epic and any foundation-doc roll-forward. The questions must come from the actual idea; examples of the shape only:

• "Is this aimed at our existing users or a new audience segment?"
• "Should this live as a new bounded context, or extend the existing domain model?"
• "Is real-time sync a v1 requirement, or is eventual-consistency acceptable?"
• "Do we expose this externally (public API surface) or keep it internal-only for now?"
• "Does this displace an existing capability, or sit alongside it?"

These sit a layer above epic-design Phase 4.7 and feature-design Phase 4.5 — those resolve epic- and feature-internal direction. Phase 1.7 resolves the framing that determines what the epic even is. Skip anything the foundation docs or the user's prompt already pin. Skip anything that is safely an epic-design or feature-design call (decomposition, boundaries, interfaces).

Aim for 2-5 questions. Zero is fine if the user's brief and foundation docs already pin every strategic choice. For small (story) and medium (feature) scope, the bar is higher — only ask if a strategic ambiguity genuinely affects framing; otherwise skip directly to Phase 2.

Use structured question tool to ask. Capture answers in the item body under a ## Strategic decisions section so the downstream design family inherits the locked-in direction:

## Strategic decisions
- **<question>**: <choice> — <one-line rationale>

For large scope, the answers here directly inform the foundation-doc roll-forward in Phase 4.

Phase 1.8: UI surface alignment (runs when ux-ui-design is installed)

Per the tier rule in ux-ui-principles (mock at the highest tier where it can land), scope-tier locks the design system and any clear cross-feature journey before the item is written.

• Large scope + UI (epic-shaped) →

  1. If .mockups/design-system/tokens.css does NOT exist, invoke /ux-ui-design:palette during the Phase 4 roll-forward.
  2. If the idea spans a multi-screen journey that's already clear (signup, onboarding, checkout, recovery), invoke /ux-ui-design:flows <flow-name>. Reference the path under ## Strategic decisions so epic-design Phase 4.6 inherits it.

  Screen-level mocks belong to epic-design once the decomposition exists.

• Medium scope (feature) + UI surface that's net-new or novel → tag the feature [ui] and note the surface in the body. Mocking happens at whichever tier picks it up next — epic-design if there's an epic parent, feature-design otherwise.

• Small scope or no UI → skip.

Skip this phase if ux-ui-design is not installed.

Then proceed to Phase 2.

Phase 2: Size the scope

Three sizes determine what gets created and whether foundation docs roll forward.

Size	Signals	Outputs
Small (story)	Single-session work, no architectural change, fits in one feature's scope	One story file at .work/active/stories/<id>.md, stage: implementing (often skips drafting)
Medium (feature)	Spans multiple files, deserves a design pass, may have child stories, no foundation-doc impact	One feature file at .work/active/features/<id>.md, stage: drafting
Large (epic + foundation roll)	Changes the project's vision, spec, architecture, or audience; spans multiple features; introduces a new capability area	Epic at .work/active/epics/<id>.md plus updates to docs/VISION.md, docs/SPEC.md, and/or docs/ARCHITECTURE.md per the rolling-foundation principle

Size check — ask yourself:

• Does this contradict or extend a current foundation-doc assertion? → at least medium, possibly large
• Will it introduce a new contract, new boundary, or new architectural component? → large
• Is it one cohesive change in one area? → small or medium

If unclear, lean smaller — easier to upgrade a story to a feature than to unwind a premature epic.

Phase 3: Declare dependencies

Ask the user (or surface from context): what items, if any, must be at stage: done before this can start?

• For a backlog item the user mentions as a prerequisite: add to depends_on
• For a related in-flight feature in the same area: consider adding to depends_on if the new work's design assumes the in-flight feature's output

Cycle check: if <id> is the new item and <dep> is a candidate dependency, verify that <dep> does not transitively depend on <id>. Run:

.work/bin/work-view --blocking <id> --paths

If <dep> is in that output, adding <dep> to <id>'s depends_on would create a cycle. Report it and ask the user to resolve.

Phase 4: Foundation-doc roll-forward (large scope only)

When the scope is large, first do an impact assessment along four axes:

1. Architecture impact — does the current architecture support this, or does it need to evolve? New layers, boundaries, integration points?
2. Spec impact — new technical constraints, interfaces, non-functional requirements?
3. Vision impact — does the project's purpose or audience change, or just capabilities?
4. Principles impact — does this new direction force a new substrate or code-design principle, or fit existing ones?

Run /agile-workflow:research first if the expansion uses unfamiliar technology and you don't yet have research docs for it.

Then identify which foundation docs need updating:

• VISION.md — if scope changes audience, success criteria, or the project's purpose
• SPEC.md — if scope introduces a new technical constraint, interface, or non-functional requirement
• ARCHITECTURE.md — if scope adds a component, changes a boundary, or alters data flow
• PRINCIPLES.md — only when a genuinely new principle emerges (rare)

For each affected doc:

1. Read the current version in full
2. Edit the relevant sections to reflect the current or intended future state — extend, replace, restructure as needed
3. Do NOT add "previously" notes, "in v1.x", or migration prose. Git carries history; the doc carries truth (rolling-foundation principle)

Design-system lock-in (UI-bearing large scope only). If Phase 1.8 flagged palette or a flow, invoke /ux-ui-design:palette and/or /ux-ui-design:flows <flow-name> here. The locked mocks ship in the same roll-forward commit and are inherited by epic-design Phase 4.6.

Phase 5: Write the item file

Per the SPEC.md frontmatter contract. Required fields for an item in active.

Before applying [refactor] as a tag, apply the black-box test: would any observable behavior of the public surface change for a caller? If yes, do NOT tag [refactor] — let the item route to feature-design instead. [refactor] is reserved for pure structural change (extract helpers, split god files, rename for clarity, remove dead code, inline a one-call abstraction). "Major rework that keeps the API shape" still fails the test if internal semantics shift. The same rule applies to [perf] — apply only if the work is purely about throughput / latency / memory of an existing capability, not adding new capability that happens to be fast.

---
id: <slug>
kind: epic|feature|story
stage: drafting    # or implementing for stories
tags: [<tag>, ...]
parent: <slug>|null
depends_on: [<slug>, ...]
release_binding: null
gate_origin: null
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

# <name>

## Brief
<one to three paragraphs describing what this is and why it exists>

<!-- Subsequent sections (Design, Implementation Notes, etc.) accumulate as
work progresses. -->

If sourcing from .work/backlog/<id>.md, use git mv to move it:

git mv .work/backlog/<old-id>.md .work/active/<kind>s/<new-id>.md

Then edit the moved file to add full frontmatter and brief.

If a fresh request, just create the file directly with Write.

Phase 6: Commit

git add .work/active/<kind>s/<id>.md docs/VISION.md docs/SPEC.md docs/ARCHITECTURE.md  # whichever exist + were changed
git commit -m "scope: <id> (<kind>, <size>)"

If foundation docs rolled forward, the commit message should note it:

scope: <id> (epic) + foundation roll-forward

Rolled forward: SPEC.md (added multi-tenancy section), ARCHITECTURE.md (added tenant boundary).

Output (single-idea mode)

(Batch mode has its own output in Phase B9.)

In conversation:

• Scoped: <id> as <kind> at stage: <stage>
• Parent: <parent-id> (or "none — top-level")
• Depends on: [<id>, ...] (or "no dependencies")
• Foundation docs rolled forward: list of files touched (or "none")
• Next: for features at drafting, the design family will pick this up (/agile-workflow:feature-design, refactor-design, perf-design, prose-author for [prose] features, or agentic-research:research-orchestrator for [research] features (when that plugin is installed; otherwise the tag is inert), based on tags); for epics at drafting, /agile-workflow:epic-design decomposes into child features.

Guardrails

• Foundation docs roll forward IN PLACE — never add "previously" or "originally" prose. Git is the audit trail.
• Cycle detection is mandatory for depends_on. Use work-view --blocking before writing.
• Do NOT pre-populate stages beyond what the size mapping specifies. Don't set a feature to implementing at scope time — design does that when it advances.
• Do NOT pre-bind to a release. release_binding stays null until /agile-workflow:release-deploy runs.
• If sizing is genuinely unclear after Phase 2, ask the user via structured question tool rather than guessing.
• Batch mode: one confirmation gate, not many. Phase B7 is a single structured question tool call (up to 4 questions). Apply NL adjustments from the user's reply and proceed — do not loop on a second confirmation round.
• Batch mode: read-first in Phase B3. Use direct mapping when the backlog ideas touch obvious areas. If an agent is needed, use one medium-breadth Explore pass over the backlog list, not three; don't fan out per cluster.
• Batch mode: leftovers default to staying in backlog. Forcing leftovers into a "miscellaneous" feature dilutes the clustering signal.
• Batch mode: lean smaller, but accept natural-grouping epics. Prefer multiple features over one giant epic; form an epic when there's a real capability arc that wants epic-design decomposition, not just to bundle loosely related items.