PM - Entity Registry

Agent mode (--agent)

Supports --agent: runs autonomously in a subagent, drafts the artifact from existing inputs, and returns a short summary + coverage note.

• No flag → interactive (default); if inputs are heavy, offer agent mode.
• --agent → obey. First check inputs are complete. Anything missing: do NOT invent it - mark [ASSUMED - what/why] in the output and summary. Never hallucinate to fill a gap.

Standalone run

Needs the artifacts listed under Dependencies - it synthesizes them, so without them there is nothing to synthesize.

• No workspace, or inputs missing: name which are missing and what each one unlocks, then offer the PREREQ paths - proceed on stated assumptions marked [ASSUMED - what/why], or route to the skill that produces the missing input. Never hard-block, and never invent the input.
• Writing never depends on /pureinn having run: with no workspace, create just the folder this skill writes into, or write to a path the user names, and say where the file went.
• Read pureinn-variables.md / state.json where a value is actually used, not at the top of the run. Missing value: continue and name the capability it costs.

What this skill does

Builds Live Register 1 of 4: the Entity & State Registry (/domain/entities.md).

This register is the architectural foundation of the FDD+SDD framework. It defines:

• What business objects exist in the system
• What states each object can be in
• What transitions are allowed between states (including triggers and emitted events)
• Guard conditions are added JIT in Phase 6 (pm-feature-design) - not here

Position in the 4-register architecture:

Source: PRD Business Capabilities section - or product/scope_brief.md Business Capabilities section on commissioned builds (same table contract; the Scope Brief's [CANDIDATE-BR] edge cases additionally seed the rules register). AI extracts nouns from capabilities → entities. State machines reflect the business lifecycle of each entity.

Domain overview diagram: Generated in Excalidraw (high-level visual for the team). State machines per entity: Mermaid.js (embedded in entities.md - readable by Claude Code).

Reconciled mode (when run by pm-reconcile)

If reconcile/reconciliation_report.md exists, it is the authoritative input - use it instead of a naive extraction. Code is truth for structure and naming; the old docs' business meaning is already reconciled into the report. Carry the report's resolved entities, attributes, and state machines plus any flagged divergences; do not re-derive or re-question what the report already settled.

Dependencies

Required before running:

• pm-prd - PRD must include a Business Capabilities section (or pm-scope-brief on commissioned builds - product/scope_brief.md carries the same Business Capabilities contract)

Produces artifacts used by:

• pm-business-rules-library - entities define the scope of rules
• pm-features-list - entities inform what operations and actions are needed
• pm-feature-design (JIT Phase 6) - adds guard conditions to transitions
• Build phase - Claude Code reads entities.md as architectural guardrail

Step 0: Current state check + mode detection

Check for existing artifacts:

• domain/entities.md in current project workspace

Mode detection:

If append mode detected, inform user with state table (N existing entities), then use AskUserQuestion:

• Question 1: "Which domain/initiative is being added?" (free text answer - user describes it)
• Question 2: "Input source for Business Capabilities?" with options:
  • Option A: "Initiative PRD at initiatives/[slug]/prd.md - Business Capabilities section (Recommended)"
  • Option B: "Paste capabilities directly"

Also check: does a PRD, Initiative PRD, or Scope Brief (product/scope_brief.md, commissioned builds) with a Business Capabilities section exist? Without one, entity extraction is guesswork.

Look for: entities defined as technical components (not business objects), states that are technical statuses (not business lifecycle states), missing state machines for entities with complex lifecycles, transitions without triggers.

Interaction: Group related questions (2-4 per round) and confirm before moving on. For any A/B/C/D choice, use the AskUserQuestion tool with one option marked (Recommended) - never print options as plain text. Keep open-ended questions free-text (don't fake options). If the user is unsure, propose 3-4 concrete options plus "Other". Surface an assumption the moment you make one; never fabricate to fill a gap. (Full standard: CLAUDE.md.)

Step 1: Gather inputs

Ask as plain text:

I need inputs for the Entity & State Registry.

1. PRD BUSINESS CAPABILITIES
   Paste the Business Capabilities section from the PRD, Initiative PRD,
   or Scope Brief (product/scope_brief.md - commissioned builds),
   or confirm it is in context.
   This is the primary source for entity extraction.
   (For append mode: paste only the capabilities for the new domain/initiative)
   [paste or "in context"]

3. EXISTING CONTEXT (optional)
   Is there an existing domain model, ERD, or tech spec that defines some entities?
   [paste or "none"]

Then use AskUserQuestion tool with two questions together:

• Question 1: "Team mode for entity generation?"
  • Option A: "Solo Builder - AI generates entities autonomously, you verify (Recommended)"
  • Option B: "Delivery Team - we refine the entity list together (Domain Walkthrough mode)"
• Question 2: "Do you want a high-level domain overview diagram in Excalidraw after entities are complete?"
  • Option A: "Yes - generate domain overview diagram (Recommended)"
  • Option B: "No - entities.md only"

Step 2: Extract entities

Before generating:

1. Read PRD Business Capabilities
2. Extract all nouns that represent business objects with lifecycle (e.g., Order, Customer, Booking, Payment - NOT: service, module, component)
3. For each entity: identify what states it can be in (business lifecycle states, not technical)
4. Identify state transitions: what triggers the move from state A to state B
5. Identify what event each transition emits (events are named in past tense: order.confirmed, payment.failed)
6. Mark complex entities (3+ states) for full state machine; simple entities (1-2 states) as flat list

Entity extraction rules:

• Entities are nouns with lifecycle (they change state over time)
• States are business-meaningful, not technical: Confirmed not is_confirmed=true
• Transitions have: trigger (what causes the change) + emits (what event is produced)
• Guard conditions are NOT added here - they come JIT in pm-feature-design
• Phase 1 states only: clean states. Example: Draft | Confirmed | Cancelled - not conditions like "if payment > 0"

State-quality heuristics (apply to every state machine before finalizing):

• Behavior test: a state earns its existence only if the system behaves differently in it (different allowed actions, different visibility, different rules). If nothing behaves differently, it is an attribute, not a state - drop it.
• Not a wizard: UI steps ("step 2 of onboarding") and process checkpoints are not lifecycle states. Model the business object's life, not the screen flow.
• Merge twins: two states with identical allowed transitions and identical rules are one state wearing two names.
• Adversarial pass (do this last, per entity): walk the unhappy paths explicitly - what happens on payment failure, timeout, user abandonment, admin override, external-system error, reversal/refund? Most production bugs live in missing unhappy transitions, not in the happy path. Every terminal-looking situation needs either a transition or an entry in Illegal transitions - never silence.

Generate in English.

Step 3: Generate artifact

ARTIFACT: Entity & State Registry

Save to: pureinn-workspace/[project-slug]/domain/entities.md

# Entity & State Registry
# Live Register 1 of 4 - FDD+SDD Framework

> **Product:** [Product Name]
> **Version:** 1.0
> **Last updated:** [date]
> **Maintained by:** pm-entity-registry skill + pm-feature-design (JIT guard conditions)

---

> **How to read this register:**
> - States: business lifecycle states (not technical flags)
> - Transitions: trigger (what causes it) + emits (event produced) + guard (added JIT in Phase 6)
> - This register is an architectural guardrail - Claude Code reads it before implementing any feature

---

## [Entity Name 1] (e.g., Order)

**Business role:** [What this entity represents in the business domain]
**Owned by Feature Set:** [FS-NN: name - filled after pm-features-list]

**States:**

| State | Meaning | Terminal? |
|---|---|---|
| Draft | Created but not confirmed | No |
| Confirmed | Accepted and paid | No |
| Cancelled | Terminated before fulfillment | Yes |
| Fulfilled | Completed successfully | Yes |

**State machine:**

```mermaid
stateDiagram-v2
    [*] --> Draft : created
    Draft --> Confirmed : payment.success [guard: TBD - added JIT]
    Draft --> Cancelled : user.cancel OR timeout.48h
    Confirmed --> Fulfilled : delivery.completed
    Confirmed --> Cancelled : user.cancel [guard: TBD - added JIT]
    Cancelled --> [*]
    Fulfilled --> [*]

Transitions:

Illegal transitions:

• Fulfilled → any state (terminal)
• Cancelled → any state (terminal)

[Entity Name 2] (e.g., Payment)

[same structure]

[Simple Entity] (e.g., Address)

Business role: [Description] States: No lifecycle states - value object. Mutable by owner entity.

Entity Relationship Overview

Changelog

---

## Step 4: Domain overview diagram (if requested)

If user selected option A in Step 1:

Generate a high-level domain overview using Excalidraw MCP (`mcp__claude_ai_Excalidraw__export_to_excalidraw`).

The diagram shows:
- All entities as boxes
- Relationships between entities as labeled arrows
- No states - this is the macro view

[Entity A] --owns--> [Entity B] [Entity B] --triggers--> [Entity C]

After Excalidraw generation, save the checkpoint for future updates.

---

## Internal completeness checklist

<!-- Claude reference only - not shown to user -->

**Entity extraction:**
- [ ] All nouns with business lifecycle are captured (not technical components)
- [ ] Pure value objects (no lifecycle) are marked as such
- [ ] Entity count is realistic (3-15 for typical product - more suggests over-granularity)

**States per entity:**
- [ ] States are business-meaningful (not technical flags)
- [ ] Terminal states are identified
- [ ] No state is unreachable from initial state
- [ ] No missing transitions (what puts entity back / forward)

**Transitions:**
- [ ] Every transition has a trigger (event or action that causes it)
- [ ] Every transition has an emitted event (past tense, dot notation: `entity.state`)
- [ ] Guard conditions are marked TBD (NOT filled here - JIT only)
- [ ] Illegal transitions explicitly listed

**Mermaid.js:**
- [ ] stateDiagram-v2 syntax used
- [ ] Diagram compiles without errors
- [ ] [*] initial and terminal states marked

**Register format:**
- [ ] Header with version + last updated
- [ ] Changelog section maintained

---

## Save to

**Create mode (first run):**

pureinn-workspace/[project-slug]/domain/entities.md

State update → `state.json`: set `registers.entities_initialized` to `true`.

**Append mode (new domain/initiative):**
- Open existing `domain/entities.md`
- Add new domain section(s) after last existing entity
- Update the Changelog section with the new entry:
  `| 1.X | [date] | Added [Domain] entities for [initiative-slug] initiative | Initiative PRD |`
- Update `> Last updated:` in the file header
- Do NOT modify any existing entity sections

---

## Notion push

After saving `entities.md`, push entity data to the Internal Entity Catalogue DB in Notion.

**Step 1 - Get data source ID and template ID:**
1. Read `pureinn-variables.md` key `"Internal Entity Catalogue"` → get DB URL
2. If blank: skip Notion push entirely, continue
3. Call `mcp__claude_ai_Notion__notion-fetch` with the URL
4. Extract `data_source_id` from `<data-source url="collection://...">` → cache in `state.json notion_ids.internal_entity_catalogue`
5. Extract template ID from `<templates>` section - look for `"Internal Entity Template"` → required for Step 2

**Step 2 - Create entries:**

For each **internal entity** in `entities.md`, call `mcp__claude_ai_Notion__notion-create-pages` with both `properties` AND `content`. Do NOT use `template_id` - provide content directly.

properties: Entity: [Entity name] Domain/Source: [[Domain name]] Description: [1-sentence description] Lifecycle States: [states comma-separated, e.g. "Draft, Active, Archived"] Register Status: Active Väzby (R/W/Event): [key relationships]

content: (inline markdown - fill from entities.md)

[Entity Name]

[Description from entities.md]

Lifecycle States

[Paste the stateDiagram-v2 block from entities.md for this entity]

Key Business Rules

[List any BR-IDs that reference this entity, or "See business_rules.md"]

Relationships

[Relationships from entities.md Väzby section]

For **external entities**: use `"External Entity Catalogue"` URL. Use `Source System/Provider` field instead of `Domain/Source`. Include system description and integration type in content.

**Append mode:** For new entities added in append mode, create new entries. Do NOT update existing entries.

**Append checklist:**
- [ ] Existing entities preserved exactly as-is
- [ ] New domain entities added as new sections
- [ ] Entity Relationship Overview table updated with new cross-domain relationships (if any)
- [ ] Changelog updated
- [ ] File header `Last updated` updated

---

## Handoff

**Čo si teraz má:** `entities.md` (Live Register 1) - entity, stavy a Mermaid state machines. Architektonický základ frameworku.

**Ďalší krok:** `/pm-business-rules-library` — Registre 2+3 (pravidlá + decision tables), ktoré strážia prechody entít.

**Môžeš preskočiť ak:** Registre 2+3 už existujú a táto doména k nim nepridáva žiadne pravidlá.