Recursive Planning
Decomposition Process
- Survey -- greenfield or existing? For existing: read README, types, error classes, test setup, conventions. These are constraints.
- Identify domains -- genuinely different kinds of work (parsing vs querying vs aggregating vs formatting)
- Map dependencies -- which domains need outputs from others? Dependencies flow through interfaces only.
- Assign waves -- no dependencies -> Wave 1. Depends on Wave 1 -> Wave 2. Wave 0 is always contracts/setup. Integration is final wave.
- Assign scopes -- each module gets a directory or file set. Zero overlap between parallel modules.
- Specify conventions -- language, test framework, type system, DI pattern, path handling, package manager
- Plan deliverables -- README, CHANGELOG,
--version, runtime version access, coverage config
Module Split Criteria
See recursive-development skill for split principle and examples. Goal: natural, best-practice file structure.
Contract Guidance
Wave 0 agent designs contracts. The plan specifies what they should cover:
- Enumerate capabilities -- list all operations/formats/modes, not just common ones
- Error handling -- "Parsers yield Record | ParseError" not "Parsers raise on bad input"
- Batch interfaces -- "Aggregator takes list[AggregationSpec]" not single-item
- Injectable I/O -- "Formatters accept a write callable"
- Types only -- contracts file has protocols, dataclasses, enums, type aliases, constants. No callable stubs.
- Exception hierarchy -- base exception + subtypes per failure domain
- Logging -- modules use named loggers, CLI configures at entry point
For existing projects: extend existing contracts, match established patterns.
Wave Plan Format
Save to .claude/workspace/wave-plan-<project-name>.md.
## Implementation Plan -- `<name>` <description>
### Issue Summary
### Language & Conventions
### Language-Specific Standards
(Standards shaped to this project's language and domain -- specifics that all agents must follow.
These go beyond generic conventions. Think about what a senior developer in this language would
insist on in a code review.)
### Existing Patterns (existing projects only)
### Chosen Approach
## Wave 0: Contracts & Project Setup
## Wave 1: <name> (N parallel)
### Module A -- Owns: <scope>, Responsibility: <one line>
## Wave 2: <name>
### Module C -- Owns: <scope>, Depends on: <interfaces>, Responsibility: <one line>
## Wave N: Integration + Documentation (README.md, CHANGELOG.md)
## File Ownership Map
### Complexity: Simple | Moderate | Complex
1---2name: recursive-planning3description: How to decompose projects into wave plans -- module identification, dependency mapping, wave assignment, contract guidance, deliverables.4---56# Recursive Planning78## Decomposition Process9101. **Survey** -- greenfield or existing? For existing: read README, types, error classes, test setup, conventions. These are constraints.112. **Identify domains** -- genuinely different kinds of work (parsing vs querying vs aggregating vs formatting)123. **Map dependencies** -- which domains need outputs from others? Dependencies flow through interfaces only.134. **Assign waves** -- no dependencies -> Wave 1. Depends on Wave 1 -> Wave 2. Wave 0 is always contracts/setup. Integration is final wave.145. **Assign scopes** -- each module gets a directory or file set. Zero overlap between parallel modules.156. **Specify conventions** -- language, test framework, type system, DI pattern, path handling, package manager167. **Plan deliverables** -- README, CHANGELOG, `--version`, runtime version access, coverage config1718## Module Split Criteria1920See `recursive-development` skill for split principle and examples. Goal: natural, best-practice file structure.2122## Contract Guidance2324Wave 0 agent designs contracts. The plan specifies what they should cover:2526- **Enumerate capabilities** -- list all operations/formats/modes, not just common ones27- **Error handling** -- "Parsers yield Record | ParseError" not "Parsers raise on bad input"28- **Batch interfaces** -- "Aggregator takes list[AggregationSpec]" not single-item29- **Injectable I/O** -- "Formatters accept a write callable"30- **Types only** -- contracts file has protocols, dataclasses, enums, type aliases, constants. No callable stubs.31- **Exception hierarchy** -- base exception + subtypes per failure domain32- **Logging** -- modules use named loggers, CLI configures at entry point3334For existing projects: extend existing contracts, match established patterns.3536## Wave Plan Format3738Save to `.claude/workspace/wave-plan-<project-name>.md`.3940```text41## Implementation Plan -- `<name>` <description>42### Issue Summary43### Language & Conventions44### Language-Specific Standards45(Standards shaped to this project's language and domain -- specifics that all agents must follow.46These go beyond generic conventions. Think about what a senior developer in this language would47insist on in a code review.)48### Existing Patterns (existing projects only)49### Chosen Approach5051## Wave 0: Contracts & Project Setup52## Wave 1: <name> (N parallel)53### Module A -- Owns: <scope>, Responsibility: <one line>54## Wave 2: <name>55### Module C -- Owns: <scope>, Depends on: <interfaces>, Responsibility: <one line>56## Wave N: Integration + Documentation (README.md, CHANGELOG.md)5758## File Ownership Map59### Complexity: Simple | Moderate | Complex60```
Jartan-LLC