Design task decomposition

Design engagements without atomic task files force the entire brand or UI phase to restart on REJECT. With atomic tasks, the lead re-dispatches only the broken unit (one logo direction, one component spec, one screen variant).

When to decompose

If the plan skips decomposition on a size: L engagement, the handoff gate fails (handoff-precheck) on missing tasks/ — same gate as a missing ## Validation log.

Inputs

• engagement/criteria.md (locked)
• engagement/plan.md (lead, Phase 2 output)

Output

• engagement/tasks/{NN}-{slug}.md — one file per atomic task
• engagement/tasks/INDEX.md — manifest with wave grouping (mandatory for L)

Integrity rules (read before drafting tasks)

Domain-neutral rules for keeping intent intact across the conversion: decomposition-integrity.md.

Non-negotiable subset: every task names its Source (the crit-N or the plan.md section it comes from) and repeats the Common objective; the source wins on any conflict with task wording; a requirement that exists because of a risk carries that risk into ## Non-goals / must not break — in design that is usually the regression the rework must not reintroduce; small same-shape edits batch into ONE task instead of one specialist seat each; the coverage check in §6 runs before the set goes to the workflow.

Atomic task = one of these shapes

A design task is "atomic" when its rework wouldn't cascade into adjacent tasks in the same wave. Design atoms by track:

Anti-atom (don't do this):

• "task-01-design-the-landing.md" — span; can't re-run partially.
• "task-02-create-design-system.md" — too big; tokens vs components vs screens are different atoms.
• "task-03-make-it-look-good.md" — vibes; not measurable.

If you can't write a measurable acceptance bullet for the task, it's not atomic — split further.

Per-task contract (S2 — when A.contracts is enabled)

On M/L engagements run with A.contracts on, each tasks/{NN}.md ALSO carries a ## Contract (co-signed) section (the per-task acceptance rubric). You do NOT author it — leave it for the engine's contract handshake (owner proposes assertions in-band → reviewer co-signs and writes the section). Schema: engagement-protocol §"tasks/{id}.md → ## Contract (co-signed)". It binds the per-task review only and never waives criteria.md.

Sequence dependency (CRITICAL for design)

Design has hard sequence rules from design-lead skill:

1. Brand (voice, palette, type) → design tokens → components → screens → flows → assets.
2. Token tasks MUST land before component tasks (component depends on token).
3. Component tasks MUST land before screen tasks (screen consumes component).
4. Brand identity tasks (logo, CIP) are independent of token/component chain — separate dependency tree.

Encode this in depends_on. The Workflow runs waves in dependency order, so a screen task with depends_on: [] is a planning error — tokens must precede it.

Task file template

---
task: {NN}-{slug}                     # NN = 2-digit zero-padded order
engagement: {engagement-name}
domain: design
owner: {specialist-agent-name}        # design-brand-strategist, design-visual-designer, design-ui-designer, design-ux-designer, design-presentation-designer
deliverable_type: {voice-axis | logo-direction | cip-surface | palette-role | type-pairing | token-group | component-spec | screen-variant | ux-flow | asset-pack | slide}
depends_on: [{task-NN}, ...]          # honour brand→tokens→components→screens chain
wave: {N}                             # tasks with same wave can run in parallel
status: pending | in_progress | done | blocked
estimated_effort: XS | S | M          # XS = <30 min, S = ≤2h, M = ≤half day; L per task = split further
validators: [{validator-name}, ...]   # accessibility-validator, ux-review, reality-checker, product-context-validator
crit_refs: [crit-{N}, ...]            # criteria.md bullets this task addresses
theme: light | dark | both            # for screen / component tasks
breakpoint: mobile | tablet | desktop | all  # for screen / component tasks
---

# Task {NN}: {one-line title}

## Goal
One sentence: what observable artefact will exist after this task is done.

## Inputs
- criteria.md crit-N: "{verbatim criterion text}"
- plan.md phase: {phase name}
- prerequisite outputs (if depends_on non-empty): {paths to brand/, design-system/, ui/}

## Steps
1. {action}
2. {action}
3. {action}

Keep ≤ 5 steps. If you need more, the task is too big — split.

## Deliverable
- {artefact path} — e.g. `engagement/design-system/tokens/spacing.json`, `engagement/ui/dashboard-dark-desktop.png`, `engagement/brand/logo/direction-A.svg`

## Done when
- [ ] {testable bullet — e.g. "all 8 spacing values in tokens/spacing.json non-empty"}
- [ ] {validator-specific — e.g. "accessibility-validator passes contrast on each colour pair"}
- [ ] specialist signed off in their executor-report
- [ ] (if ux_heavy) screen captured to `screens/{iter}/{theme}/{surface}.png`

Workflow

Phase 1: Draft tasks (lead)

1. Read criteria.md and plan.md.
2. Map each plan.md phase to atom families using the shape table.
3. Apply sequence rules: brand → tokens → components → screens → flows → assets.
4. Assign wave numbers respecting depends_on:
   • Wave 1: brand atoms (voice, palette, type) + independent assets (logo direction A/B/C in parallel)
   • Wave 2: design-token atoms (consume palette + type from wave 1)
   • Wave 3: component atoms (consume tokens)
   • Wave 4: screen atoms (consume components)
   • Wave 5: flow atoms (consume screens)
5. Write one tasks/{NN}-{slug}.md per atom from the template above.
6. Write tasks/INDEX.md with the wave grouping (mandatory for L, recommended for M with ≥6 tasks).

Phase 2: Validate (lead, single pass)

Design tasks don't need a 3-iteration validation cycle. One self-check pass:

For each task file:

• crit_refs actually cites a criteria.md bullet.
• owner is a real agent name (matches design-* agent in ~/.claude/agents/).
• depends_on honours sequence rule (component task depends on a token task; screen depends on component).
• ## Done when has at least one bullet measurable WITHOUT the lead's eye ("token JSON has 8 spacing values", "WCAG contrast ≥ 4.5:1 on every text/bg pair", not "feels right").
• For UI tasks: theme field present (light / dark / both).
• No two tasks deliver to the same path (would overwrite).

If any check fails — fix the file, don't dispatch.

Phase 3: Execution (the engagement-workflow Workflow runs the waves)

The decomposed tasks/*.md feed the Workflow's deliver phase. There is NO mid-lead dispatch tier — each task's owner field names the specialist agentType directly, and the Workflow dispatches it wave-by-wave (same-wave tasks run in parallel on disjoint artefact paths). Typical owners: design-ui-designer (tokens, components, screens), design-ux-designer (flows), design-presentation-designer (slides), design-brand-strategist (voice), design-visual-designer (logo, CIP, assets).

Each specialist opens its assigned task, does the work, writes the artefact to its engagement path, and appends its result to executor-reports/{specialist-agent-name}.md § "Task {NN}: {title}".

Phase 4: Iter-2 retargeting (on REJECT)

On an iter-2 REJECT, the Workflow's rework loop re-runs ONLY the affected tasks — those where:

• crit_refs includes the failing crit-N, OR
• deliverable_type matches the rejected artefact (e.g. the verdict says "screen X has wrong button radius" → re-run the screen task AND the button component task if the token drifted).

Only those tasks re-run; the specialist appends ## Iteration 2 to its executor-report (per engagement-protocol §4-iter).

Token propagation safety

Design's biggest iter-2 trap: a token changes (wave 2), but components (wave 3) and screens (wave 4) don't get re-rendered. The plan's depends_on must guarantee:

• If a wave-2 token task is re-run on iter-2, every wave-3 component task that consumed that token MUST also re-run, and every wave-4 screen using those components MUST re-render.
• This is automatic IF depends_on is wired correctly. Manual audit: trace the dependency graph from the changed token and queue everything downstream.

tasks/INDEX.md should make this graph explicit so it's not lost on iter-2.

Anti-patterns

• Don't decompose retroactively. Either at Phase 2.5 or skip (size: S).
• Don't write tasks/*.md content longer than 50 lines. Spec details belong in executor-reports/{specialist}.md.
• Don't violate sequence. A screen task with no token dependency = REJECT.
• Don't put the same crit-N in crit_refs of >5 tasks. If a criterion needs that many tasks, sharpen criteria.md (lead-authority, no user touch).
• Don't make a task's owner a lead. Owners are specialists (the lead plans; the engagement-workflow dispatches).
• Don't skip theme field on UI tasks. Light-only and both-themes have different acceptance bars; ambiguity here causes iter-2 "we forgot dark mode".
• Don't number tasks before verifying dependencies. A non-monotonic depends_on (task 05 depends on task 12) hides bugs — re-number after dependency lock.

What this is NOT

• Not a task-creator invocation (dev-only).
• Not validated by dev validators (task-validator, reality-checker). Lead's Phase 2 self-check is sufficient. Critique/accessibility/ux-review run on the delivered artefacts, not on the task files.
• Not a Figma file index — task files describe what to produce, not where the live source is. Live source paths go in the executor report after delivery.

Cost estimate

For an L engagement with 18 atomic tasks (rebrand + product UI): ≈30-45 min of lead time to draft + self-validate + INDEX.md. Saves ≥2 hours on a single iter-2 reject of token drift (which would otherwise re-run components + screens + accessibility audit). Net positive at any reject rate above ~0.2 — current design baseline is 0.6.