| name | deft-directive-decompose |
| description | Convert approved specification/phase/epic scope xBRIEFs into swarm-ready story xBRIEFs before concurrent agent allocation. |
Deft Directive Decompose
Use this skill when a specification, Phase 4 implementation scope, or epic xBRIEF is too broad for direct concurrent swarm work and must be decomposed into story-level xBRIEFs.
Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
See also: strategies/speckit.md Phase 4.5 | vbrief/vbrief.md Swarm-Ready Story Contract | deft-directive-swarm
Purpose
Convert approved specification/phase/epic scope xBRIEFs into swarm-ready child story xBRIEFs. Story xBRIEFs are the only valid input for concurrent swarm worker allocation.
Phase 0: Inspect
- ! Read
xbrief/specification.xbrief.json and relevant scope xBRIEFs from xbrief/proposed/, xbrief/pending/, and xbrief/active/.
- ! Identify broad scopes with
plan.metadata.kind = "phase" or "epic" or scopes with broad plan.narratives.Acceptance and empty plan.items.
- ! Preserve parent acceptance as context; do not treat it as executable story acceptance.
- ! Treat parent
plan.items as input signals only; they are not automatically child stories.
- ! Inspect relevant codebase paths before drafting file scope so stories reflect real product/code boundaries, not only parent scope prose.
- ! Identify requirement traces, likely file scope, verification commands, outputs/evidence, dependencies, and conflict groups.
- ⊗ Allocate a broad phase/epic scope to concurrent workers during this skill.
Phase 1: Draft
- ! Draft a decomposition JSON proposal with child stories only; do not write child xBRIEFs yet.
- ! Treat the draft JSON as a temporary proposal artifact, not a xBRIEF.
- ! Write draft proposals under
xbrief/.triage-cache/decompositions/, using a parent-derived slug such as xbrief/.triage-cache/decompositions/ip001-auth.json.
- ! Derive
<parent-slug> from the parent xBRIEF filename by removing .xbrief.json and any leading YYYY-MM-DD- date prefix; for example, xbrief/pending/2026-05-12-ip001-auth.xbrief.json uses ip001-auth, while xbrief/pending/feature-xyz.xbrief.json uses feature-xyz.
- ⊗ Agents MUST NOT leave decomposition draft JSON files at the workspace root.
- ! Each story MUST include
id, title, Description, ImplementationPlan, UserStory, executable items or acceptance, traces or explicit trace justification, swarm.file_scope, swarm.verify_commands, swarm.expected_outputs, swarm.depends_on, swarm.conflict_group, swarm.size, swarm.file_scope_confidence, and swarm.model_tier.
- !
Description MUST provide at least two concrete sentences explaining the user/product behavior, boundaries, and why this story is independently buildable.
- !
ImplementationPlan MUST provide at least two concrete implementation steps that identify the expected code path, state/data changes, and test/evidence approach.
- !
UserStory MUST use the exact product-story shape As a <role>, I want <capability>, so that <outcome>..
- ! Each ready story MUST have 2-5 concrete acceptance criteria unless
swarm.acceptance_criteria_justification explains the exception.
- ! Acceptance criteria MUST be observable behavior, preferably Given/When/Then or equivalent testable product behavior.
- ⊗ Mark a story ready when acceptance says only "to refine from parent scope", duplicates the title/description, is placeholder text, or is vague docs-only acceptance.
- ⊗ Mark a story ready with broad write scope such as
backend/**, frontend/**, docs/**, xbrief/**, or any other directory glob.
- ⊗ Mark a story ready when verification is only generic validation such as
task check.
- ⊗ Mark a story ready with
parallel_safe: false or file_scope_confidence: low; use readiness: sequential or readiness: needs_refinement instead.
- ! Model dependencies as story IDs and ensure they form a DAG.
- ~ Draft sequential-safe or low-confidence work as
readiness: sequential or readiness: needs_refinement; it is not eligible for concurrent allocation.
- ⊗ Use deprecated
subItems in newly drafted story items; use items.
Phase 2: Approval
- ! Present the decomposition draft to the user before writing files.
- ! Ask for explicit approval to apply the draft.
- ! If the user requests changes, revise the draft and re-present it.
- ! After explicit approval, run
task scope:decompose ... --check, then apply without --check.
- ? Run
task scope:decompose ... --check before explicit approval only to validate a draft without writing files.
- ⊗ Apply
task scope:decompose without --check before explicit approval.
Phase 3: Apply
- ! Validate the approved draft first:
task scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.triage-cache/decompositions/ip001-auth.json --check
- ! Apply the approved draft:
task scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.triage-cache/decompositions/ip001-auth.json
The command creates generated child story xBRIEFs as lifecycle artifacts, defaulting to xbrief/pending/. It preserves origin/provenance references, sets each child planRef to the parent, updates parent references to include the children, rejects dependency cycles, and rejects ready stories missing executable acceptance, user-story shape, concrete acceptance, narrow file scope, focused verify commands, or traces.
Phase 4: Pending Readiness
- ! Run readiness against the generated pending child story paths after decomposition:
task swarm:readiness -- xbrief/pending/<child-story-1>.xbrief.json xbrief/pending/<child-story-2>.xbrief.json
- ! Treat this as a dry readiness review before activation; do not allocate workers from pending paths.
- ! Route blocked or overlapping stories back to Phase 1 for draft refinement.
- ! Leave lifecycle promotion/activation to the existing approved flow (
task scope:promote, task scope:activate, and the swarm skill lifecycle bridge).
- ⊗ Promote or activate child stories solely because decomposition succeeded.
Exit
deft-directive-decompose complete -- exiting skill. Next, activate the approved child story xBRIEFs through the existing lifecycle flow, then run skills/deft-directive-swarm/SKILL.md for concurrent allocation.
