decompose

CLIPPY DECOMPOSE Phase

Reads design artifacts from .ai/design/, produces a task graph for autonomous implementation.

Steps

1. Read design artifacts

Read .ai/design/DESIGN.md, .ai/design/STACK.md, and all files in .ai/design/contracts/. Understand components, connections, tech stack, and testing approach.

2. Identify units

Each component/service/module is a candidate unit. A unit should be:

• Implementable and testable independently
• One component or feature
• Completable in one session (~30-50% of context)

3. Map dependencies and parallelism

• depends_on: which units must complete first
• parallel_group: units with same dependencies and no inter-dependency get the same group name

4. Map contracts

For each unit:

• contracts_read: contract files to read before implementing
• contracts_produced: files this unit creates that others need

5. Validate

• Every inter-component interface has a contract in .ai/design/contracts/. If missing: STOP and report the gap. Do not guess.
• Unit size heuristics: >10 files? >2 component boundaries? Multiple independent features? → split.
• No circular dependencies.

6. Produce state files

.ai/task-graph.yaml:

version: 1
units:
  - id: unit-001
    name: "..."
    description: "..."
    depends_on: []
    contracts_read: []
    contracts_produced: []
    parallel_group: null

.ai/state.yaml:

version: 1
status: pending
current_unit: null
units_completed: []
units_failed: []
units_remaining: [unit-001, ...]
consecutive_failures: 0
error: null

.ai/constraints.yaml — preserve if exists (may have design-phase constraints). Create empty if not:

version: 1
constraints: []

.ai/checkpoints/ — create empty directory.

Validate: re-read task-graph.yaml, verify all fields, verify all contracts_read files exist on disk, verify no circular dependencies.

7. Report

Present task graph summary: N units, M parallel groups, dependency chain depth, any concerns about sizing. Recommend proceeding.

Completion signal

🔚 DECOMPOSE PHASE COMPLETE
Units: N
Parallel groups: M
Dependency depth: D
State written to: .ai/