deft-directive-decompose

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.