Break multi-file changes into atomic commits ordered by dependency. Use when the user says "split this into commits", "commit strategy", "break this up", or when making refactors, breaking API changes, or features touching 3+ files that need clean git history.
When a feature touches multiple files, implement in waves. Each wave is one logical concern, one commit. This creates a clean git history that tells a story.
Related Skills: See
gitfor commit message conventions and PR guidelines.
Wave 1: Foundation (types, interfaces)
↓
Wave 2: Factories/Builders (functions that create instances)
↓
Wave 3: Contracts/APIs (public interfaces that use types)
↓
Wave 4: Infrastructure (utilities, converters, dependencies)
↓
Wave 5: Consumers (apps, UI, integrations)
Not every change needs all waves. A simple bugfix might be one wave. A cross-cutting refactor might need five.
Each wave must be:
| Property | Description |
|---|
| Atomic | One logical concern per wave |
| Buildable | Code compiles after this wave (run type-check) |
| Focused | Changes relate to ONE layer/concern |
| Complete | No half-done work within a wave |
This feature moved metadata from workspace to tables. Five waves:
feat(schema): add IconDefinition, CoverDefinition, and FieldMetadata types
- Add IconDefinition discriminated union (emoji | external)
- Add CoverDefinition discriminated union (external)
- Add FieldMetadata with optional name/description to all field types
- Update TableDefinition to use icon/cover instead of emoji/order
Files: types.ts only. Foundation for everything else.
feat(schema): add optional name/description to field factory functions
All factory functions (id, text, richtext, integer, real, boolean, date,
select, tags, json) now accept optional name and description parameters.
Files: factories.ts only. Uses types from Wave 1.
feat(schema): remove emoji and description from WorkspaceSchema
Workspace is now just a container with guid, id, name, tables, and kv.
Visual metadata (icon, cover, description) now lives on TableDefinition.
Files: contract.ts only. API change using new types.
feat(schema): use slugify for human-readable SQL column names
- Add @sindresorhus/slugify dependency
- Add toSqlIdentifier() helper using slugify with '_' separator
- SQLite columns now use field.name (or derived from key) instead of key
Files: to-drizzle.ts, package.json. Utility that uses field metadata.
feat(schema): update epicenter app to use TablesWithMetadata
- WorkspaceSchema now accepts TablesSchema | TablesWithMetadata
- Export new types from package index
- Update app to create proper TableDefinition with metadata
Files: App files that consume the new types.
Plan waves before coding
Implement one wave
Verify the wave
bun run tsc --noEmitCommit the wave
Repeat for next wave
| Scenario | Waves? | Why |
|---|---|---|
| Single file bugfix | No | One change, one commit |
| Add new type + factory | Maybe | Could be 1-2 waves |
| Refactor across 5+ files | Yes | Need logical grouping |
| Breaking API change | Yes | Types → API → Consumers |
| Add dependency + use it | Yes | Infra wave then usage wave |