| name | wow-development-workflow |
| description | Use when developing, completing, restructuring, or enhancing Wow framework aggregate or saga behavior, including new domain capability, command/event/state design, cross-aggregate orchestration, aggregate tests, saga tests, KDoc, scenario documents, or design reports. |
Wow Development Workflow
Use this skill after ../wow/SKILL.md routes an end-to-end Wow development task here. This workflow covers aggregate behavior and saga orchestration. Projection work is intentionally outside this workflow for now.
Design Philosophy
These principles guide every phase:
- Source first, docs second, memory last: inspect the current checkout before deciding API names, module names, annotations, or test DSL methods. Use docs as supporting context, not as the final authority.
- Domain truth before code shape: model commands as intent, events as committed facts, and state as sourced memory.
- API metadata is part of the contract: commands and domain events should carry
@Summary and @Description so generated REST/API schema has useful title and description metadata.
- Shared fields deserve names: important repeated domain fields should be modeled as
<FieldName>Capable interfaces instead of being copied across commands, events, and state types.
- Aggregate owns invariants: a command aggregate decides whether a command is valid and emits events; it must not rely on sagas to protect its internal rules.
- Saga coordinates, not owns: a saga reacts to events, evaluates process conditions, and emits commands. It should not become a second aggregate or hidden state owner.
- Make the flow explicit: draw or list command, event, state, and saga paths before editing behavior.
- Tests are contracts: use
AggregateSpec for aggregate behavior and SagaSpec for orchestration behavior. Do not substitute one for the other.
- Enhancement is evidence: comments, scenario documents, and design reports should explain decisions and coverage, not decorate code.
- Verification closes the loop: finish with exact commands, results, and remaining risk.
Methodology
Use this sequence as the mental model for all non-trivial Wow work:
- Align: clarify intent, scope, allowed behavior changes, and proof of success.
- Read: inspect source, tests, module names, and nearby working examples.
- Model: express the domain as command intent, event fact, sourced state, reusable field capability, and process policy.
- Split: decide whether the behavior belongs to the aggregate, a saga, or both.
- Prove: lock aggregate behavior with
AggregateSpec and saga orchestration with SagaSpec.
- Preserve: write comments, scenarios, and design notes only where they carry decision knowledge.
- Close: review semantics, run verification, and report evidence plus residual risk.
If a later phase exposes unclear requirements, return to Align or Model instead of guessing in implementation.
Workflow Map
graph TD
A[User Task] --> B[wow Router]
B --> C{Task Type}
C --> D[Development Workflow]
C --> R[wow code review]
C --> G[wow debugging]
C --> K[wow references]
D --> D0[Align]
D0 --> D1[Discover]
D1 --> D2[Model]
D2 --> X{Cross Aggregate Flow}
X --> A1[Aggregate Flow]
X --> S1[Saga Flow]
A1 --> A2[Command Contract]
A2 --> A3[Event Contract]
A3 --> A4[State Sourcing]
A4 --> A5[Command Handler]
A5 --> AT[Aggregate Behavior Test]
AT --> ATS[AggregateSpec]
S1 --> S2[Trigger Event]
S2 --> S3[Process Condition]
S3 --> S4[Target Aggregate]
S4 --> S5[Derived Command]
S5 --> S6[Routing and Idempotency]
S6 --> S7[Retry Policy]
S7 --> ST[Saga Orchestration Test]
ST --> STS[SagaSpec]
ATS --> E[Enhance]
STS --> E
E --> RV[Review]
RV --> Q{Issue Found}
Q --> D2
Q --> G
Q --> V[Verify]
V --> DONE[Completion Output]
Phase 0: Align
Goal: confirm intent before implementation.
Use a full brainstorming flow when the task adds a new capability, changes architecture, or has unclear business semantics. If a Superpowers-style brainstorming skill is available, use it as the richer implementation of this phase. Otherwise do a lightweight alignment directly.
Answer these before editing:
- What business capability or aggregate behavior should change?
- Is behavior change allowed, or is the task limited to tests, comments, or documentation?
- Which bounded context, aggregate, saga, and module are in scope?
- What is the success criterion?
- What verification command should prove the change?
Exit with a short scope statement and any assumptions.
Phase 1: Discover
Goal: learn the current code before designing changes.
Run focused source searches such as:
rg -n "@AggregateRoot|@OnCommand|@OnSourcing|@StatelessSaga|@OnEvent|@Retry" . -g "*.kt"
rg -n "AggregateSpec<|SagaSpec<|aggregateVerifier|sagaVerifier|expectCommand|expectNoCommand" . -g "*.kt"
rg -n "include\\(" . -g "settings.gradle.kts"
Load the smallest references needed:
../wow/references/modeling.md for aggregate, state, lifecycle, and bounded context rules.../wow/references/annotations.md for command, sourcing, saga, retry, and handler annotations.../wow/references/testing.md for AggregateSpec, SagaSpec, verifier APIs, and FluentAssert.../wow/references/command-gateway.md when command routing, wait behavior, or idempotency affects the design.
Exit with a source inventory: modules, files, command handlers, sourcing handlers, saga handlers, existing tests, and missing coverage.
Phase 2: Model
Goal: turn requirements into explicit domain flow.
Decide:
- Aggregate identity and owner or tenant routing.
- Commands as user or system intent.
- Events as durable facts with enough payload to rebuild state.
@Summary and @Description metadata for each command and domain event.- Important repeated fields that should become
<FieldName>Capable interfaces.
- State fields and the sourcing event that owns each mutation.
- Invariants enforced inside aggregate command handlers.
- Whether any event must trigger another aggregate through a saga.
Exit with one of two paths:
- Aggregate Flow for single-aggregate behavior.
- Saga Flow for cross-aggregate orchestration.
Aggregate Flow
Use this when behavior stays inside one aggregate.
| Node | What to Decide | Exit Evidence |
|---|
| Command Contract | command name, @Summary, @Description, aggregate id, owner or tenant, validation, idempotency input | command type, route, and API metadata are explicit |
| Event Contract | fact name, @Summary, @Description, payload, compatibility, event count | emitted event can rebuild state and has schema metadata |
| Field Capability | important repeated fields and validation contracts | reusable <FieldName>Capable interfaces exist where useful |
| State Sourcing | mutable fields, defaults, sourcing handler, lifecycle handling | state changes only in sourcing |
| Command Handler | invariant checks, returned events, error paths | handler emits events and does not mutate state |
| Aggregate Behavior Test | happy path, error path, edge state, lifecycle | AggregateSpec or verifier proves command behavior |
Use AggregateSpec for this path:
Given events or state
When command
Expect event, state, or error
Saga Flow
Use this when an event from one aggregate should coordinate another aggregate.
| Node | What to Decide | Exit Evidence |
|---|
| Trigger Event | event type, aggregate name filter, payload needed by the saga | saga has a precise trigger |
| Process Condition | branch conditions, no-command branch, external lookup if any | each branch has expected output |
| Target Aggregate | target aggregate id, owner, tenant, route source | command route is deterministic |
| Derived Command | command body, headers, correlation, request semantics | generated command is complete |
| Routing and Idempotency | duplicate event handling, command id or natural id, stale input handling | repeated delivery is intentional |
| Retry Policy | @Retry, recoverable errors, unrecoverable errors, timeout | Saga handler failure behavior is explicit |
| Saga Orchestration Test | trigger, no-command, branch, multi-command cases | SagaSpec proves orchestration |
Use SagaSpec for this path:
Given event
When saga reacts
Expect command or no command
Enhance
Goal: preserve design knowledge and coverage evidence.
Run only the artifacts the user requested, but always start from the Discover inventory.
- For comments, use
references/comment-standards.md.
- For scenario documents, use
references/test-case-template.md.
- For design reports, use
references/design-report-template.md.
- For aggregate and saga test notes, use
references/test-patterns.md.
Enhancement may add missing AggregateSpec or SagaSpec coverage when the scenario document exposes gaps. It must not silently change business behavior.
Review
Before verification, review the work against the philosophy:
- Commands represent intent and events represent facts.
- Commands and domain events have
@Summary and @Description metadata where they are part of the API/domain contract.
- Important repeated domain fields are extracted into
<FieldName>Capable interfaces where reuse improves clarity.
- Aggregate invariants are enforced inside aggregate command handlers.
- State changes are deterministic and sourced from events.
- Saga logic only coordinates process flow and generated commands.
- Aggregate and saga tests use the correct DSL for their responsibility.
- Documentation explains why a decision exists and links to tests or scenarios.
If behavior is wrong or a test fails, switch to ../wow-debugging/SKILL.md. If the task is a PR or diff review, switch to ../wow-code-review/SKILL.md.
Verify
Resolve module names from settings.gradle.kts, then run the narrowest commands that prove the change:
./gradlew <module>:test --tests "fully.qualified.SpecName"
./gradlew <module>:check
python3 scripts/skill_lint.py
Final output must include phases completed, files changed, verification commands and results, and remaining risks or uncovered scenarios.
