decomposer

The goal: an implementing agent reads TASKS.md and executes tasks in order without needing to make architectural decisions or ask clarifying questions.

Why atomic tasks matter for one-shot:

• Each task is small enough to execute correctly in one pass
• Dependencies are explicit — no hidden coupling
• Validation is built into each task — errors caught immediately
• Parallel execution opportunities are identified

Task sizing rule: If a task description needs more than 10 lines of specific instructions, it's too big. Break it down further.

FOR each capability in SPEC.md:
  LIST all code changes needed (from PLAN.md touchpoints)
  GROUP by file proximity:
    - Changes to the same file go together
    - Tightly coupled files (e.g., component + its styles) go together
    - Maximum 3 files per group

FOR shared infrastructure:
  IDENTIFY: Utilities, types, configs that multiple features need
  MARK as "foundation" — these get built first

dependencies:     What must exist before this can be built?
dependents:       What depends on this being complete?
parallelizable:   Can this run alongside other tasks? (yes/no + which ones)

Build a dependency graph and identify layers:

FOUNDATION:   No dependencies — database schema, config, shared types, utilities
CORE:         Depends on foundation — API routes, data access, auth
FEATURE:      Depends on core — user-facing pages, components, interactions
INTEGRATION:  Depends on features — cross-feature flows, E2E scenarios
POLISH:       No dependents — error states, loading states, edge case handling

Verify: no circular dependencies. If found, restructure the work units.

FOR each task:
  task_id:              T{NNN} — sequential identifier
  title:                Action verb + what (e.g., "Create user database schema")
  layer:                FOUNDATION / CORE / FEATURE / INTEGRATION / POLISH
  files:                Exact file paths to create or modify (1-3 max)
  depends_on:           List of task_ids this requires ([] if none)
  description:          Specific implementation instructions:
                          - What to create/modify
                          - Key logic to implement
                          - Which PLAN.md patterns to apply (mixins, etc.)
                          - Reference specific SPEC.md invariants to uphold
  validation:           How to verify this task is complete:
                          - Specific test to run
                          - Behavior to verify
                          - Invariants to check
  complexity:           LOW (< 50 lines) / MEDIUM (50-150 lines) / HIGH (150+ lines)

Atomization rules:

• A task that creates a file should include its initial content/structure
• A task that modifies a file should specify WHAT to change, not just "update X"
• Every task must have at least one validation criterion
• If a task has HIGH complexity, try to break it further
• Tasks should reference specific SPEC.md invariant IDs (INV-001, etc.)

1. Topological sort based on dependency graph
2. Within each dependency level, group parallelizable tasks
3. Number tasks in execution order (T001, T002, ...)
4. Mark parallel groups explicitly

Format:

## Execution Order

### Parallel Group 1 (Foundation)
T001, T002, T003 — can execute simultaneously

### Sequential
T004 — depends on T001, T002

### Parallel Group 2 (Core)
T005, T006 — can execute simultaneously after T004

### Sequential
T007 — integration, depends on T005 + T006

### Parallel Group 3 (Polish)
T008, T009 — independent polish tasks