initiative/specs/005-set-initiative/quickstart.md

Quickstart: Set Initiative

What This Feature Does

Adds an optional initiative value to combatants. When set, the encounter automatically sorts combatants from highest to lowest initiative. Combatants without initiative appear at the end. The active turn is preserved through reorders.

Key Files to Modify

1. packages/domain/src/types.ts — Add initiative?: number to Combatant
2. packages/domain/src/events.ts — Add InitiativeSet event to the union
3. packages/domain/src/set-initiative.ts — New domain function (pure, no I/O)
4. packages/domain/src/index.ts — Export new function and types
5. packages/application/src/set-initiative-use-case.ts — New use case
6. packages/application/src/index.ts — Export use case
7. apps/web/src/hooks/use-encounter.ts — Add setInitiative callback
8. apps/web/src/App.tsx — Add initiative input next to each combatant

Implementation Order

1. Domain types + event (foundation)
2. Domain function + tests (core logic)
3. Application use case (orchestration)
4. Web adapter hook + UI (user-facing)

How to Verify

pnpm check    # Must pass: format + lint + typecheck + test

Patterns to Follow

• Domain functions return { encounter, events } | DomainError — never throw
• Use readonly everywhere, create new objects via spread
• Tests live in packages/domain/src/__tests__/
• Use cases follow get → call → check error → save → return events