@eventmodelers/cli 0.0.1

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: eventmodeling-validating-event-models
+description: "Step 9 of Event Modeling - Validate event-sourced models for completeness, consistency, and event sourcing principles. Ensures events are immutable facts, state projections are deterministic, and commands are pure. Identifies gaps and suggests improvements before code generation. Use when reviewing models before code generation. Do not use for: the structured 23-check production checklist (use eventmodeling-validating-event-models-checklist) or field-level completeness verification (use eventmodeling-checking-completeness)."
+allowed-tools:
+  - Write
+  - Bash
+---
+
+# Validating Event Models
+
+> **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Then invoke the `learn-eventmodelers-api` skill to load the full API reference. Do not proceed until both skills have been loaded.
+
+For validation you treat the Event Model as read only. The only thing you are allowed to change is comments.
+For critical questions, add comments to elements.
+
+For every field in the command, it must be clear where it is coming from.
+Either it´s defined in a transitively connected Read Model, or it is marked as "generated" in either a screen or an automation.
+There should not be any fields without a defined source.
+
+The source can be also determined by looking at the defined Scenarios. Are all Scenarios covered?
+
+## Board Context
+
+Before starting, read the current board state to validate what is actually on the board:
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
+```
+
+After validation, use the `handle-comment` skill to post findings on the relevant nodes — `TASK` for critical violations that must be fixed, `QUESTION` for warnings and recommendations.
+
+## Purpose
+Ensures event-sourced models are complete, correct, and follow pure event sourcing principles (minimal per-command state).
+
+## Workflow
+
+When given an event model, perform comprehensive validation:
+
+### 1. Swimlane Completeness Check
+
+Verify each swimlane has:
+- Clear name (identity)
+- At least one event type
+- Initial event (what creates the stream)
+- State transitions documented
+
+**For each event:**
+- Uses past tense (Created, Confirmed, etc.)
+- Contains **only facts** (no computed fields)
+- All data is **immutable**
+- Unique semantics (no duplicates)
+
+**For each state projection:**
+- Can be deterministically rebuilt from events
+- Replay logic is pure (no side effects)
+
+**For each command:**
+- Clear input parameters
+- Validation rules defined in scenarios (against state)
+- Resulting events specified (or rejection reason)
+- Pure logic (no side effects except event appending)
+
+### 2. Consistency Checks
+
+- [ ] **Event-Stream Mapping**: Every event belongs to exactly one lane
+- [ ] **Command Outcomes**: Every command produces events OR documents rejection
+- [ ] **Deterministic Projections**: State can only be derived one way from events
+- [ ] **No Side Effects in Projections**: Pure state reconstruction logic
+- [ ] **Event Immutability**: No event data is ever modified
+- [ ] **Naming Consistency**: Are naming patterns consistent?
+  - Commands: Verb present (CreateOrder, ConfirmPayment)
+  - Events: Verb past tense (OrderCreated, PaymentConfirmed)
+
+### 3. Event Sourcing Principles Compliance
+
+Check against event sourcing fundamentals:
+
+- [ ] **Events are Facts**: Events describe what happened, not potential futures
+  - "OrderMayBeConfirmed" →  "OrderConfirmed"
+  - "PaymentPending" (in events) →  "PaymentInitiated", "PaymentAuthorized"
+
+- [ ] **Events are Immutable**: No modification of event data
+  - "Update OrderCreated event with new total" →  "Append OrderTotalCorrected event"
+
+- [ ] **Complete Event Data**: Events contain all facts needed for state rebuild
+  - Event: "OrderConfirmed" (missing paymentId) →  Event includes paymentId
+
+- [ ] **No Computed Fields in Events**: Only raw captured facts
+  - OrderCreated includes "totalTax" (computed) →  Includes items + amounts, tax computed in projection
+
+- [ ] **Deterministic Projections**: Replaying events always produces same state
+  - Projection uses: for each event, do X
+  - Projection uses: external API call during replay
+
+- [ ] **State is Derived**: Current state always comes from replaying events
+  - "Load state: replay all events for Order:123"
+  - "Load state: query database Orders table"
+
+### 4. Event Flow Validation
+
+- [ ] **Command → Event Mapping**: Clear what each command produces
+- [ ] **No Zombie Commands**: Commands that never produce events (read-only OK)
+
+### 5. Role & Actor Attribution Validation
+
+Verify that every command has explicit actor attribution from the Role Catalog:
+
+- [ ] **Role Catalog exists**: A Role Catalog was defined in Step 1 (eventmodeling-brainstorming-events)
+  - CRITICAL: No Role Catalog found — commands have no actor attribution
+  - PASS: Role Catalog with human roles and system actors defined
+
+- [ ] **Every command has actor attribution**: No command uses generic "User"
+  - CRITICAL: `CreateOrder` attributed to "User" (which user? Customer? Admin? Seller?)
+  - PASS: `CreateOrder` attributed to "Customer" (specific role from catalog)
+
+### 6. Command State Read Models Validation (CRITICAL)
+
+ **This is the PRIMARY validation gate. Violations are CRITICAL and must be fixed before approval.** Validate that **command state read models** are **minimal and command-specific**, not bundled like DDD aggregates.
+
+### 7. Command & State Validation
+
+- [ ] **State-Based Decisions**: Commands decide based on current state only
+- [ ] **Valid State Transitions**: Document what state changes are allowed
+```text
+Draft → Confirmed (ConfirmOrder)
+Draft → Cancelled (CancelOrder)
+Confirmed → Shipped (ShipOrder)
+Confirmed ↛ Draft (invalid)
+```
+- [ ] **Preconditions Clear**: When can each command execute?
+  - "Can only confirm if state is Draft"
+  - "Can sometimes confirm"
+- [ ] **Error Handling**: What happens if validation fails?
+  - "Reject with ValidationError, no events appended"
+  - "Append ErrorEvent and continue"
+
+### 8. Projection Validation
+
+- [ ] **Read Models**: Read models are rich projections
+- [ ] **Read Models Optional**: Are they needed or just convenience?
+- [ ] **Regenerable**: Can be rebuilt from events at any time
+
+### 9. Issues & Recommendations Report
+
+Format findings as comments:
+
+```markdown
+
+## Validation Summary
+
+**Overall Status**:  Ready with recommendations
+
+**Blockers for Implementation**: 0 critical issues
+
+**Recommended Fixes**:
+1. Add missing OrderCancelled event
+2. Move PaymentMethod to its own minimal state projection
+3. Document all implicit invariants explicitly
+
+**Ready for Code Generation**: Yes, after implementing recommendations
+
+## Next Steps
+1. Review recommendations with domain expert
+2. Update model with critical fixes
+3. Proceed to code generation
+```
+
+## Common Issues to Flag
+
+| Issue | Pattern | Fix |
+|-------|---------|-----|
+| Missing cancellation flows | No "Cancelled" events | Add compensation paths |
+| Implicit invariants | "Obviously can't do X" | Make invariants explicit |
+| Command state too broad | Shared state used by 2+ commands | Split into per-command minimal state projections |
+| Orphaned events | Events no one listens to | Link to projections or commands |
+| No read models | Commands reading query/read models for validation | Add separate query read models; keep command state minimal |
+| Circular dependencies | Projection A depends on B, B on A | Redesign stream boundaries |
+
+## Key Principles for Event Sourcing
+
+1. **Events are the source of truth**: Everything else is derived from them
+2. **Immutable event log**: Events never change, only appended
+3. **State is a projection**: Current state is built by replaying events
+4. **Commands are pure decisions**: Validate against state, produce events or reject
+5. **Projections are optional**: Can be rebuilt at any time
+6. **Stream per entity**: Each entity has one append-only event stream
+
+## Success Criteria
+
+Your event model validation is successful when:
+
+- All requirements are captured in events
+- Commands clearly trigger events
+- Stream roots have clear, minimal boundaries
+- Business rules are explicit invariants (not hidden assumptions)
+- Read models serve actual query needs (not used by commands)
+- Command state is minimal and command-specific (not shared across multiple commands)
+- Events are immutable facts (past tense, no computed fields)
+- State can be deterministically rebuilt from events
+- All command-to-event mappings are documented
+- Critical issues are resolved or documented as known limitations
+
+A model is **ready for code generation** if:
+- No critical issues remain
+- All command state follows naming convention (e.g., `[CommandName]State`)
+- No state is shared between different commands
+- All events are immutable facts
+- All business rules are explicit
+- A Role Catalog exists with all human roles and system actors
+- Every command has explicit actor attribution from the Role Catalog
+
+## Quality Checklist
+
+- [ ] All events are immutable facts (past tense)
+- [ ] No computed fields stored in events
+- [ ] State projection is deterministic from events
+- [ ] Commands validate against current state only
+- [ ] Each command either produces events or rejects (no silent failures)
+- [ ] Event causality/command-event mapping is clear
+- [ ] State transitions are documented
+- [ ] No direct references between lanes
+- [ ] Projections serve specific query needs (or are removed)
+- [ ] Everything can be rebuilt from the event stream
+- [ ] No state is shared between different commands
+- [ ] All command state is minimal (only fields needed for validation)
+- [ ] **Role Catalog exists with human roles and system actors**
+- [ ] **Every command attributed to a specific role/actor (no generic "User")**
+- [ ] **Every human role has at least one command and one read model**
+- [ ] **Permission boundaries from Role Catalog are respected**

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models-checklist/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: eventmodeling-validating-event-models-checklist
+description: "Validate event-sourced CQRS models against 16 architectural checks across 7 phases. Identifies anti-patterns and confirms compliance with event sourcing principles. Use when reviewing event models for production readiness or after completing event modeling steps. Do not use for: reviewing incomplete or in-progress models (use eventmodeling-validating-event-models), or for elaborating new scenarios (use eventmodeling-elaborating-scenarios)."
+allowed-tools:
+  - Write
+  - Bash
+---
+
+# Event Model Validation Checklist Skill
+
+> **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Then invoke the `learn-eventmodelers-api` skill to load the full API reference. Do not proceed until both skills have been loaded.
+
+**Purpose**: Validate any event-sourced CQRS event model against 16 architectural checks across 7 phases. Identifies anti-patterns and confirms compliance with event sourcing principles.
+
+**Applies To**: Any domain - e-commerce, banking, SaaS, marketplace, healthcare, etc.
+
+**When to Use**:
+- After completing Step 2 (Event Plot) of 7-step event modeling
+- After completing Step 7 (Scenarios) before declaring model complete
+- When reviewing an existing event model for production readiness
+- When suspicious of architectural issues in event design
+
+**What It Does**:
+1. Reads current board state (EVENT, COMMAND, READMODEL nodes) as input
+2. Systematically applies 16 validation checks across 7 phases
+2. Identifies violations of event sourcing principles (domain-agnostic)
+3. Flags anti-patterns (calculations as events, non-entity streams, etc.)
+4. Verifies read model/event distinction
+5. Confirms stream independence and business rule enforcement
+6. Returns pass/fail verdict with evidence
+
+---
+
+## Board Context
+
+Read the current board state before running the checklist:
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
+```
+
+Use the board nodes as the model input. After the checklist, use `handle-comment` to post `TASK` comments on nodes that fail checks.
+
+## Validation Phases (Domain-Agnostic)
+
+### Phase 1: Event Stream & Command Handler State Validation (3 checks)
+- Check 1.1: Each event belongs to exactly one stream
+- Check 1.2: Each command handler owns its own [CommandHandler]State class
+- Check 1.3: No hard dependencies between command handlers (orchestrated via events only)
+
+**Anti-pattern to catch**: Sharing state across handlers or treating state as persistent aggregate
+
+### Phase 2: Event Quality Validation (3 checks)
+- Check 2.1: Events represent domain facts, not calculations
+- Check 2.2: Event data is immutable after creation
+- Check 2.3: Event names use past tense (what actually happened)
+
+**Anti-pattern to catch**: Storing computed/aggregated data as events
+
+### Phase 3: Read Model vs Event Distinction (2 checks)
+- Check 3.1: Each read model is NOT an event stream
+- Check 3.2: Read model has natural query pattern
+
+**Anti-pattern to catch**: Confusing projections/calculations with domain facts
+
+### Phase 4: Business Rules Validation (2 checks)
+- Check 4.1: Constraints enforced in command handler decision logic (encapsulated in [CommandHandler]State)
+- Check 4.2: Event preconditions are explicit (what state must exist before command is valid)
+
+**Anti-pattern to catch**: Business rules scattered across handlers or encoded in event stream structure
+
+### Phase 5: Data Traceability (1 check)
+- Check 5.1: Input → Event → Read Model traceability is complete
+
+**Anti-pattern to catch**: Command inputs that disappear or read model fields without source
+
+### Phase 6: Event Flow Validation (1 check)
+- Check 6.1: No impossible event sequences (state machine is sound)
+
+**Anti-pattern to catch**: Events that can occur in invalid state combinations
+
+### Phase 7: Stream Independence (1 check)
+- Check 7.1: Each stream can be versioned/restored independently
+
+**Anti-pattern to catch**: Hard dependencies between streams
+
+### Final Questions (3 checks)
+- Question 1: Could an architect unfamiliar with this domain understand the model in 15 minutes?
+- Question 2: Could you change your core algorithm/calculation without changing event history?
+- Question 3: Could this be implemented in your target technology stack (e.g., TypeScript + PostgreSQL)?
+
+---
+
+## Output Format
+
+The skill returns a validation report with:
+
+### For Each Check
+```
+ Check 1.2: Stream Root is Business Entity, Not Calculation
+Status: PASS
+Evidence: [Specific examples from your model]
+```
+
+### Anti-Patterns Identified (if any)
+```
+CRITICAL: [Anti-pattern description]
+Problem: [Why it violates event sourcing]
+Violates: [Which checks fail]
+Fix: [Recommended action]
+```
+
+### Final Verdict
+```
+Status:  PASS (or  PASS WITH WARNINGS or  FAIL)
+Implementation Ready: YES (or NO - fix issues first)
+Confidence: [percentage]
+```
+
+---
+
+## Common Anti-Patterns (Domain-Agnostic)
+
+### 1. Calculation Events
+```
+ ANTI-PATTERN:
+CalculationPerformed {
+  metric: 4.5  ← Mutable/recalculated
+  timestamp: T
+}
+
+ CORRECT:
+- Event: SomeActionOccurred (immutable fact)
+- ReadModel: MetricView (recalculated from events)
+```
+
+**Why**: Calculations change multiple times as source data changes. Events are immutable.
+
+### 2. Shared vs Handler-Owned State
+```
+ ANTI-PATTERN:
+One shared "OrderAggregate" class used by all handlers
+- ConfirmOrderHandler shares OrderAggregate state
+- ShipOrderHandler modifies same OrderAggregate
+- Result: Tight coupling, hard to parallelize
+
+ CORRECT:
+Each handler owns its own [CommandHandler]State class
+- ConfirmOrderState (only ConfirmOrderHandler uses)
+- ShipOrderState (only ShipOrderHandler uses)
+- CancelOrderState (only CancelOrderHandler uses)
+- All reconstruct state from same events, but independently
+```
+
+**Why**: Each handler is a micro-slice. Separate state classes maintain isolation, enable parallel teams, prevent merge conflicts.
+
+### 3. Circular Dependencies
+```
+ ANTI-PATTERN:
+StreamA → EventA → affects
+StreamB → EventB → affects
+StreamA (circular!)
+
+ CORRECT:
+StreamA → EventA → Event Bus
+StreamB → EventB → Event Bus
+ReadModels ← consume (one-way only)
+No feedback loops
+```
+
+**Why**: Circular dependencies make the system hard to reason about and test.
+
+### 4. Persistent State vs Ephemeral State
+```
+ ANTI-PATTERN:
+Treat [CommandHandler]State as persistent entity
+- Save SubmitReviewState to database after command
+- Load it again next time
+- Result: Duplicates event sourcing, loses audit trail
+
+ CORRECT:
+Reconstruct [CommandHandler]State on-demand
+- Load events from stream
+- Replay via evolve() to rebuild state
+- Process command, emit outcome events
+- Discard state (it's ephemeral, not persisted)
+```
+
+**Why**: State is derived from events, never stored. Events are source of truth. This enables consistent replay, audit trails, and time-travel debugging.
+
+---
+
+## Questions to Ask During Validation
+
+**For each event stream**:
+1. "Do all events in this stream share the same identity (streamId)?"
+2. "Could these events occur in any order, or is sequence important?"
+3. "Is every event in this stream an immutable fact that actually happened?"
+
+**For each command handler**:
+1. "Does this handler own its own [CommandHandler]State class?"
+2. "Is the state ephemeral (reconstructed per command, not persisted)?"
+3. "Can I trace the state reconstruction: events → evolve() → decision?"
+
+**For each read model**:
+1. "Is this calculated from events via a projection?"
+2. "Does it answer a specific query need?"
+3. "Could its data change due to new events or state changes?"
+
+**For system architecture**:
+1. "Does each command handler operate independently (communicate via events only)?"
+2. "Could I run two handlers' code in parallel without merge conflicts?"
+3. "Are the only shared artifacts the event definitions?"
+
+---
+
+## Success Criteria
+
+ **Model is validated when**:
+- All 16 checks pass (or have documented workarounds)
+- No critical anti-patterns identified
+- All 3 final questions answer YES
+- Event sourcing principles clearly upheld
+- Ready to proceed to code generation
+
+ **Model needs fixes when**:
+- Any check fails with clear evidence
+- Anti-patterns identified with specific violations
+- Final questions have NO answers
+- Fixes are straightforward and targeted
+
+ **Model should be redesigned when**:
+- Multiple phases fail
+- Architectural assumptions are fundamentally flawed
+- Anti-patterns are systemic and pervasive
+- Would require rewriting core event structure
+
+---
+
+## Example Validation Patterns
+
+### Pattern: Calculation vs Event
+When you see something like "CalculationDone" or "ReviewRatingUpdated":
+- Ask: "Is this immutable and caused by a user/system action?"
+- If NO → It's a read model, not an event
+- Fix: Remove from events, create read model projection instead
+
+### Pattern: Shared vs Isolated State
+When you see "ReviewAggregate" used by multiple handlers:
+- Ask: "Could SubmitReviewHandler and ApproveReviewHandler work on separate files?"
+- If NO → State classes aren't properly isolated
+- Fix: Create SubmitReviewState and ApproveReviewState, each handler owns one
+
+### Pattern: Persistent vs Ephemeral State
+When state is saved to database after a command:
+- Ask: "Is this state only needed during command processing?"
+- If YES → It's ephemeral, reconstruct from events instead
+- Fix: Load events, replay via evolve(), process command, discard state
+
+### Pattern: Data That Doesn't Trace
+When a read model field appears without source:
+- Ask: "Where did this come from?"
+- If no event source → Add event or remove field
+- If sourced from calculation → Verify it's in projection, not event
+
+---
+
+## Integration with Event Modeling Process
+
+**Recommended timing**:
+```
+Step 1: Brainstorm Events
+Step 2: The Plot (Sequence)
+  ↓
+→ RUN eventmodeling-validating-event-models-checklist (catch structural issues early)
+  ↓
+Fix any violations
+  ↓
+Step 3-7: Complete remaining steps
+  ↓
+→ RUN eventmodeling-validating-event-models-checklist again (final validation)
+  ↓
+PASS → Code generation
+FAIL → Fix identified issues
+```
+
+Running the checklist after Step 2 prevents wasting time on later steps if core events are flawed.
+
+---
+
+## Checklist Questions by Domain
+
+The skill applies the same 16 checks regardless of domain. Here's how to think about it in different contexts:
+
+**E-commerce domain**:
+- Events: OrderCreated, OrderConfirmed, PaymentAuthorized, OrderShipped
+- NOT events: OrderTotal, InventoryLevel, ShippingCost (these are read models)
+
+**Banking domain**:
+- Events: AccountOpened, DepositReceived, WithdrawalProcessed, FundsTransferred
+- NOT events: AccountBalance, InterestCalculated (these are read models)
+
+**SaaS domain**:
+- Events: SubscriptionCreated, PaymentProcessed, PlanUpgraded, SubscriptionCancelled
+- NOT events: MonthlyRecurringRevenue, ChurnRate (these are read models)
+
+**Healthcare domain**:
+- Events: PatientRegistered, AppointmentScheduled, ProcedureCompleted, BillGenerated
+- NOT events: PatientAge, AverageCost (these are read models)
+
+The principle is the same across all domains: **immutable facts as events, calculated results as read models**.
+
+---
+
+## Tips for Best Results
+
+1. **Be specific**: List actual event names, command handler names, and state classes from your model
+2. **Reference your documentation**: Link to or quote from your step 1-7 documents and micro-slice plans
+3. **Provide context**: Explain what your domain is and how handlers will be parallelized
+4. **Ask follow-ups**: If a check flags an issue, ask "How do I fix this specifically?" or "Can this handler be isolated?"
+5. **Iterate**: Run again after making fixes to confirm all checks pass and handlers are properly isolated
+
+## Quality Checklist
+
+- [ ] All 16 checks evaluated — no check skipped without documented justification
+- [ ] Every FAIL result includes the specific event, handler, or stream that violated the check
+- [ ] Anti-patterns identified by name with the exact model element that triggered the flag
+- [ ] Final verdict is one of: PASS / PASS WITH WARNINGS / FAIL — no ambiguous outcomes
+- [ ] All 3 final architectural questions answered YES before declaring model ready for implementation
+- [ ] Any FAIL result has a recommended fix, not just a problem statement
+
+---
+
+## Related Skills
+
+- **eventmodeling-orchestrating-event-modeling**: Main skill coordinating the 7-step event modeling process
+- **eventmodeling-brainstorming-events**: Extract events from requirements (Step 1)
+- **eventmodeling-plotting-events**: Sequence events chronologically (Step 2)
+- **eventmodeling-designing-event-models**: Design your complete event model
+- **eventmodeling-validating-event-models**: Detailed validator with deep analysis
+
+---
+
+## Validation Checklist Reference
+
+The 16-point checklist is defined in the **Validation Phases** section above.
+Each check includes the anti-pattern to catch and questions to ask when evaluating your model.
+