id3-cli 0.9.1

package/templates/skills/id3-design-information/references/phase2-procedure.md

@@ -0,0 +1,241 @@
+# Phase 2: Detailed Step-by-Step Procedure
+
+This document provides the full procedural detail for Phase 2 (Information Design). The parent `SKILL.md` contains the overview; refer here for implementation-level instructions.
+
+---
+
+## Step 1: Attribute Refinement (Detailed)
+
+### 1.1 Read Current State
+
+1. Read `specs/entity-catalog.md` to load all entities and their current attribute definitions.
+2. Read `steering/data-conventions.md` to load project-specific naming and typing conventions.
+3. Note which attributes already have concrete types (from Phase 0 brownfield extraction) vs. those that are still abstract.
+
+### 1.2 Assign Data Types
+
+For each entity, for each attribute:
+
+| Abstract Type | Concrete Type (default) | Notes |
+|---|---|---|
+| identifier / ID | UUID (v7) | Time-sortable; override with BIGINT if convention says auto-increment |
+| short text | VARCHAR(N) | Determine max length from domain context |
+| long text | TEXT | No length limit |
+| number (integer) | INTEGER or BIGINT | Use BIGINT for counters that may exceed 2^31 |
+| number (decimal) | DECIMAL(p,s) | Use for money, measurements; never FLOAT for money |
+| boolean | BOOLEAN | |
+| date | DATE | Date only, no time |
+| datetime | TIMESTAMP WITH TIME ZONE | Always store in UTC |
+| enumeration | ENUM or reference table | 3 or fewer fixed values -> ENUM; otherwise reference table |
+| JSON / flexible | JSONB | Only for frequently changing metadata; normalize if searchable |
+| binary / file | TEXT (URL/key) | Store reference, not binary data |
+
+### 1.3 Add Constraints
+
+For each attribute, determine:
+
+- **NOT NULL**: Is this field required? If yes, add NOT NULL.
+- **DEFAULT**: Does this field have a sensible default? (e.g., `status` defaults to `'draft'`, `created_at` defaults to `NOW()`)
+- **UNIQUE**: Must values be unique? (e.g., email, slug, code)
+- **CHECK**: Are there value range or format constraints? (e.g., `price >= 0`, `rating BETWEEN 1 AND 5`)
+
+### 1.4 Evaluate Index Needs
+
+Apply these rules:
+
+1. **Primary key**: Automatically indexed (no action needed).
+2. **Foreign keys**: Add index on every FK column.
+3. **UNIQUE constraints**: Automatically create unique index.
+4. **Search targets**: If the attribute is used for search (e.g., `name`, `title`), add a regular index; consider GIN index for full-text search on TEXT columns.
+5. **Frequently filtered**: If the attribute appears in WHERE clauses regularly (e.g., `status`, `type`, `tenant_id`), add an index.
+6. **Composite indexes**: If queries frequently filter on multiple columns together, consider composite indexes.
+
+Document index decisions in `specs/data-model.md` under "Index Strategy".
+
+### 1.5 Apply Timestamp Conventions
+
+Ensure every entity has:
+
+- `created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()`
+- `updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()`
+
+If soft delete applies to this entity (determined in Step 4):
+- `deleted_at TIMESTAMP WITH TIME ZONE` (nullable)
+
+---
+
+## Step 2: Relationship Concretization (Detailed)
+
+### 2.1 FK Placement Rules
+
+| Relationship | FK Location | Rationale |
+|---|---|---|
+| 1:1 mandatory | Either side (prefer the dependent entity) | The entity that cannot exist without the other holds the FK |
+| 1:1 optional | The optional side | Avoids NULL FK on the mandatory side |
+| 1:N | The "many" side | Standard normalization |
+| N:M | Junction table | Both FKs in the junction table |
+
+### 2.2 Delete and Update Rules
+
+For each FK, specify:
+
+| Rule | When to Use |
+|---|---|
+| CASCADE | Child has no meaning without parent (e.g., OrderLineItem when Order is deleted) |
+| SET NULL | Child can exist independently but loses its association (e.g., Task.assignee when User is deleted) |
+| RESTRICT | Deletion should be prevented if children exist (e.g., Category with Products) |
+| SET DEFAULT | Rare; child reverts to a default parent |
+
+### 2.3 Junction Table Design
+
+For each N:M relationship:
+
+1. Name the junction table: `{entity_a}_{entity_b}` (alphabetical order) or a domain-specific name if one exists (e.g., `enrollment` for Student-Course).
+2. Columns:
+   - `{entity_a}_id` FK NOT NULL
+   - `{entity_b}_id` FK NOT NULL
+   - Composite unique index on both FK columns
+   - `created_at` timestamp
+   - Any additional attributes specific to the relationship (e.g., `role`, `quantity`, `start_date`)
+3. Delete rule: Usually CASCADE on both FKs (removing either entity removes the association).
+
+### 2.4 Update the ERD
+
+After all FK decisions are made, update the Mermaid ERD in `specs/data-model.md` to reflect:
+
+- FK columns shown on the correct side
+- Junction tables included
+- Cardinality notation (||--o{, }o--o{, etc.)
+
+---
+
+## Step 3: Business Rule Auto-Derivation (Detailed)
+
+### 3.1 Systematic Scan Process
+
+Process entities in alphabetical order. For each entity:
+
+1. **Scan constraints**: NOT NULL -> required rule, UNIQUE -> uniqueness rule, CHECK -> range/format rule
+2. **Scan FKs**: For each FK, derive a referential integrity rule based on the delete/update rule
+3. **Scan ENUMs**: For each ENUM attribute, derive a validity domain rule
+4. **Scan state transitions**: If the entity has a `status` or `state` attribute with ENUM values, derive allowed transition paths. Ask the user to confirm the state machine if not already defined.
+5. **Scan derived attributes**: If any attribute is computed from others (e.g., `total`, `full_name`, `age`), derive a computation rule.
+
+### 3.2 Rule Numbering
+
+- Use sequential numbering: BR-001, BR-002, BR-003, ...
+- If Phase 0/1 already defined some rules, continue from the last number.
+- Do not renumber existing rules.
+
+### 3.3 Rule Documentation Format
+
+For each rule, write to `docs/business-rules.md`:
+
+```markdown
+### BR-NNN: [Rule Name]
+- **Entity**: [Related entity or entities]
+- **Type**: constraint | derivation | transition | validity
+- **Description**: [Clear, unambiguous rule statement]
+- **Enforcement**: DB constraint | application logic | both
+- **Implementation**: [Specific implementation approach, e.g., "NOT NULL on users.email column" or "Zod schema validation in create-user handler"]
+```
+
+### 3.4 Cross-Entity Rules
+
+Some rules span multiple entities:
+
+- **Cascading constraints**: "Deleting a Project cascades to all its Tasks and Comments"
+- **Aggregate rules**: "Order.total must equal the sum of all LineItem.subtotal values"
+- **Cross-reference rules**: "A User cannot be both the author and reviewer of the same Document"
+
+These require explicit documentation since they cannot be enforced by a single column constraint.
+
+### 3.5 Conflict Resolution
+
+If an auto-derived rule conflicts with an existing rule from Phase 0/1:
+
+1. Flag the conflict to the user.
+2. Present both versions.
+3. Let the user decide which to keep.
+4. Update `docs/info-debt.md` if the conflict reveals a design issue.
+
+---
+
+## Step 4: Design Decision Questions (Detailed)
+
+### 4.1 Question Categories
+
+Present these categories to the user. Skip categories that are clearly not applicable.
+
+**Category A -- Storage Strategy:**
+- Are there attributes that store large binary data (images, files, PDFs)?
+- Should these be stored inline (JSONB/BYTEA) or in external storage (S3, GCS)?
+- What is the expected size range?
+
+**Category B -- Soft Delete:**
+- Which entities should support soft delete (`deleted_at` pattern)?
+- General rule: entities with audit requirements or user-facing data should use soft delete; internal/transient entities can use hard delete.
+- Soft delete implications: all queries must filter `WHERE deleted_at IS NULL`.
+
+**Category C -- Multi-Tenancy:**
+- Does the application serve multiple tenants?
+- If yes: row-level isolation (`tenant_id` column on every table) or schema-level isolation?
+- Which entities are tenant-scoped vs. global?
+
+**Category D -- Audit Trail:**
+- Which entities need change history (who changed what field, when)?
+- Implementation options: audit log table, event sourcing, temporal tables.
+- Minimum: `updated_by` column. Maximum: full audit log with before/after snapshots.
+
+**Category E -- Project-Specific:**
+- Any domain-specific architectural choices not covered above?
+- Examples: versioning strategy, approval workflows, notification triggers.
+
+### 4.2 Recording Decisions
+
+For each decision, add to `specs/data-model.md`:
+
+```markdown
+| D-NN | [Topic] | [Choice] | [Rationale] | YYYY-MM-DD |
+```
+
+Apply decisions immediately: add `deleted_at` columns, `tenant_id` columns, audit columns, etc., to the entity catalog and ERD.
+
+---
+
+## Step 5: Artifact Updates (Detailed)
+
+### 5.1 Update Order
+
+Update artifacts in this specific order to maintain consistency:
+
+1. `specs/entity-catalog.md` -- Add all refined attributes, types, constraints
+2. `specs/data-model.md` -- Update ERD, add junction tables, index strategy, design decisions
+3. `docs/business-rules.md` -- Add all derived rules
+
+### 5.2 Entity Catalog Update Checklist
+
+For each entity, verify:
+
+- [ ] All attributes have concrete data types
+- [ ] NOT NULL / DEFAULT / UNIQUE constraints are specified
+- [ ] Index needs are documented
+- [ ] `created_at` and `updated_at` are present
+- [ ] Soft delete column added (if applicable per D-xx decision)
+- [ ] Tenant column added (if applicable per D-xx decision)
+- [ ] Audit columns added (if applicable per D-xx decision)
+- [ ] All relationships list FK column, cardinality, and delete rule
+
+### 5.3 Data Model Update Checklist
+
+- [ ] Mermaid ERD reflects all entities, attributes, and relationships
+- [ ] Junction tables are included in ERD
+- [ ] Index strategy section is populated
+- [ ] Design decisions table is populated
+
+### 5.4 Business Rules Update Checklist
+
+- [ ] All auto-derived rules are numbered sequentially
+- [ ] Each rule has entity, type, description, enforcement, and implementation fields
+- [ ] Cross-entity rules are documented
+- [ ] No duplicate or conflicting rules exist

package/templates/skills/id3-design-ui/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: id3-design-ui
+description: >
+  Design and implement UI from the information model. Derives screen structure
+  from entities, establishes visual design contracts, generates HTML mockups
+  for review, and implements screens via Agent Teams.
+  Trigger: design ui, ui design, screen design, frontend design, implement ui,
+  Phase 2.5, information representation
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+user-invocable: true
+---
+
+# Phase 2.5: UI Design and Implementation
+
+You are the lead agent performing IDDD Phase 2.5 -- Information Representation. This phase derives UI structure from the information model, establishes a visual design contract, validates through a 7-Pillar quality gate with mockup preview, and implements screens via Agent Teams.
+
+**Core principle:** Every UI element traces back to an Entity, Attribute, or Business Rule. There is no guessing -- screens and widgets are derived from the information model.
+
+## Prerequisites
+
+Before starting, verify all of the following:
+
+1. `specs/entity-catalog.md` exists with version >= `"1.0"` (Phase 2 complete).
+2. `specs/data-model.md` exists with a finalized Mermaid ERD.
+3. `docs/business-rules.md` exists with confirmed BR-xxx rules.
+4. `steering/data-conventions.md` exists with naming/typing conventions.
+
+If prerequisites are **not** met, respond:
+
+> "Please complete Phase 2 (information design) first. Use 'design information' to start."
+
+Do **not** proceed until all prerequisites are confirmed.
+
+---
+
+## 4-Step Pipeline
+
+```
+Step 1: UI Structure Derivation        [Lead, conversational]
+Step 2: Visual Design Contract          [Lead, conversational]
+Step 3: Pre-Implementation Gate         [Automated + user approval]
+Step 4: Implementation + Post-Audit     [Agent Teams]
+```
+
+Execute each step sequentially. Steps 1-3 are performed by the lead agent with user interaction. Step 4 spawns Agent Teams for parallel implementation.
+
+---
+
+## Step 1: UI Structure Derivation
+
+Automatically derive screen structure from the information model, then refine with the user.
+
+### Procedure
+
+1. **Read inputs:** Load `specs/entity-catalog.md`, `specs/data-model.md`, `docs/business-rules.md`, and `specs/ui-inventory.md` (if brownfield).
+2. **Apply 9 Entity-to-Screen derivation rules** to generate the screen inventory. Every entity produces at least a List View. Additional screens (Detail, Create, Edit, Dashboard, Child Tab, Association Manager) are derived from entity characteristics.
+3. **Apply 12 Attribute-to-Widget mapping rules** to determine the widget type for each attribute based on its data type, constraints, and metadata.
+4. **Apply "Output First" principle:** Arrange dashboards and reports before input forms. Design navigation from dashboard to list to detail to form.
+5. **Brownfield change analysis** (if `ui-inventory.md` exists): Compare current UI inventory against derived screens. Classify differences as New, Modified, Deleted, or Restructured.
+6. **Present derivation results to user:** Show the derived screen inventory and ask the user to confirm, remove, or add screens.
+7. **Write `specs/ui-structure.md`** with the finalized screen inventory, entity-screen traceability matrix, navigation structure (Mermaid graph), and brownfield change summary.
+
+**For detailed derivation rules and output format, see:** `references/step1-structure-derivation.md`
+
+---
+
+## Step 2: Visual Design Contract
+
+Detect the existing frontend stack and establish design tokens with the user.
+
+### Procedure
+
+1. **Scan the project** for frontend framework indicators (package.json, config files, file extensions). Detect React, Vue, Svelte, Next.js, Nuxt, Tailwind, shadcn/ui, Radix, MUI, or greenfield.
+2. **Confirm with user:** Present the detected stack and ask for confirmation. If greenfield, present options.
+3. **Establish 5 design token areas:**
+   - Spacing Scale (8-point grid default)
+   - Typography Scale (4 levels: Display, Heading, Body, Caption)
+   - Color System (60/30/10 ratio: Surface, Secondary, Accent + Semantic)
+   - Copywriting Standards (CTA patterns, empty states, error messages, danger actions)
+   - Component Registry (map widgets to actual framework components)
+4. **Connect Entity Attributes to design tokens:** For each attribute, trace the full path from Entity -> Widget -> Component -> Design Tokens -> Validation Message.
+5. **Write `specs/ui-design-contract.md`** with tech stack, all design tokens, component mapping, and per-screen design specifications.
+
+**For detailed token definitions and output format, see:** `references/step2-visual-contract.md`
+
+---
+
+## Step 3: Pre-Implementation Gate + Visual Mockup Review
+
+Validate the design artifacts and generate HTML mockups for user approval before implementation.
+
+### Procedure
+
+1. **Run 7-Pillar verification** against `specs/ui-structure.md` and `specs/ui-design-contract.md`:
+
+   | # | Pillar | PASS condition |
+   |---|--------|----------------|
+   | 1 | Structure Completeness | Every entity has at least 1 screen mapped |
+   | 2 | Spacing | All values are multiples of the spacing scale |
+   | 3 | Typography | 4 or fewer sizes, 2 or fewer weights |
+   | 4 | Color | Accent defined with usage, semantic 4 colors present |
+   | 5 | Copywriting | CTA/empty/error/danger patterns defined, no generic text |
+   | 6 | Component Registry | Every widget mapped to a component with import path |
+   | 7 | Traceability | Every screen has entity source, every widget has attribute source |
+
+   If any pillar is BLOCKED, fix the issue before proceeding.
+
+2. **Generate mockup HTML files** at 3 fidelity levels (Wireframe, Styled, Interactive) with auto-generated sample data. Write to `.iddd/preview/mockup-index.html` and `.iddd/preview/mockup-{entity}.html`.
+3. **Start preview server** and display the URL for the user to review.
+4. **Wait for user approval:**
+   - `approve` -> proceed to Step 4
+   - `reject` + feedback -> incorporate changes, regenerate mockups, request approval again
+
+**For detailed gate rules and mockup generation, see:** `references/step3-gate-and-mockup.md`
+
+---
+
+## Step 4: Implementation + Post-Audit
+
+Spawn Agent Teams for parallel screen implementation, then perform a visual audit.
+
+### Procedure
+
+1. **Divide tasks by entity:** Each team member implements 1-3 entity screen groups. Common layout (header, sidebar, navigation) is assigned to the first team member.
+2. **Spawn Agent Teams:**
+   - `ui-implementer-N` (1 per entity group): Implements screens following ui-structure.md and ui-design-contract.md
+   - `ui-reviewer` (1): Verifies design token consistency and traceability across all screens
+3. **Implementation principles:**
+   - Follow component mapping from ui-design-contract.md exactly
+   - Apply design tokens via Tailwind classes or CSS variables
+   - Add traceability comments linking each UI element to Entity/Attribute/BR-xxx
+   - Reflect BR-xxx rules in validation code
+   - Atomic commits: one commit per entity screen group
+4. **Post-implementation visual audit:** After all screens are implemented, start the dev server and compare actual rendering against mockup HTML. Score each pillar 1-4 and identify the top 3 fixes.
+   - Average >= 3.0 -> "UI implementation complete"
+   - Average < 3.0 -> Apply top 3 fixes, then re-audit
+
+**For detailed team composition and audit criteria, see:** `references/step4-implementation.md`
+
+---
+
+## Artifacts Produced
+
+| File | Status | Content |
+|------|--------|---------|
+| `specs/ui-structure.md` | Created | Screen inventory, traceability matrix, navigation graph |
+| `specs/ui-design-contract.md` | Created | Tech stack, design tokens, component mapping |
+| `.iddd/ui-gate-result.md` | Created | 7-Pillar verification results |
+| `.iddd/preview/mockup-index.html` | Created | Mockup index page with navigation |
+| `.iddd/preview/mockup-{entity}.html` | Created | Per-entity mockups (3 fidelity levels) |
+| `.iddd/preview/ui-audit.html` | Created | Post-implementation visual audit dashboard |
+
+---
+
+## Preview Integration
+
+After completing Steps 1-3 and generating mockup HTML files:
+
+1. **Start preview server** with mockup files in `.iddd/preview/`. The server serves all files from the `.iddd/preview/` directory.
+2. **Display the URL** so the user can review mockups in their browser. The mockup index page provides navigation across all entity mockups with fidelity level tabs.
+3. **Traceability panel** at the bottom of each mockup shows Entity/Attribute/BR-xxx source and design token values applied. This is the IDDD differentiator -- every visual element has a traceable origin.
+
+Use `/id3-preview` to manually start or restart the preview server at any time.
+
+---
+
+## Version Header Update
+
+Upon completion of all 4 steps, update YAML frontmatter in `specs/ui-structure.md`:
+
+```yaml
+---
+version: "1.0"
+derived_from: "entity-catalog.md v1.0"
+screen_count: N
+entity_coverage: "X/X (100%)"
+audit_status: "clean"
+---
+```
+
+Add an entry to `docs/model-changelog.md`:
+
+```markdown
+## [1.1] -- YYYY-MM-DD
+### Phase 2.5 Complete
+- N screens derived from M entities
+- Visual design contract established
+- 7-Pillar gate passed
+- K screens implemented
+```
+
+---
+
+## Completion Message
+
+When all four steps are finished, display:
+
+> "UI design and implementation complete. N screens derived from M entities, 7-Pillar gate passed, K screens implemented with audit score X.X. Proceed to Phase 3-5 (/id3-spawn-team) for backend implementation."
+
+Replace N, M, K, X.X with actual values from the session.

package/templates/skills/id3-design-ui/references/step1-structure-derivation.md

@@ -0,0 +1,177 @@
+# Step 1: UI Structure Derivation
+
+This reference details how to derive screen structure from the information model. The lead agent executes this step conversationally with the user.
+
+---
+
+## Inputs
+
+| File | Purpose |
+|------|---------|
+| `specs/entity-catalog.md` | Entity definitions, attributes, relationships, state transitions |
+| `specs/data-model.md` | ERD with FK relationships and cardinalities |
+| `docs/business-rules.md` | BR-xxx rules for validation and behavior |
+| `specs/ui-inventory.md` | Current UI structure (brownfield only) |
+
+---
+
+## Entity-to-Screen Derivation Rules (9 Rules)
+
+Apply these rules to every entity in entity-catalog.md. Each rule produces a screen when its condition is met.
+
+| # | Entity Characteristic | Derived Screen | URL Pattern | Derivation Rationale |
+|---|----------------------|----------------|-------------|---------------------|
+| 1 | Entity exists | List View | `/{plural}` | Every entity needs a listing |
+| 2 | PK exists | Detail View | `/{plural}/:id` | PK enables individual retrieval |
+| 3 | NOT NULL attributes (non-PK, non-timestamp) | Create Form | `/{plural}/new` | Required fields imply a creation form |
+| 4 | Mutable attributes (non-PK, non-timestamp) | Edit Form | `/{plural}/:id/edit` | Editable fields imply an update form |
+| 5 | State Transitions defined | Status Dashboard | `/{plural}/dashboard` | Status flow needs a status-oriented view |
+| 6 | 1:N FK (parent side) | Child Tab in Detail | `/{plural}/:id/{child-plural}` | Parent detail shows child listing as tab |
+| 7 | N:M relationship | Association Manager | `/{plural}/:id/{related-plural}/manage` | Many-to-many needs a linking UI |
+| 8 | Derived/computed attribute | Dashboard Widget | _(embedded in dashboard)_ | Aggregated values are visualization candidates |
+| 9 | File/Blob attribute | Upload Widget | _(embedded in create/edit form)_ | File-type attributes need upload UI |
+
+### Pluralization
+
+Convert entity name to URL-safe plural form:
+- `User` -> `users`
+- `Category` -> `categories`
+- `Address` -> `addresses`
+
+### Priority Assignment
+
+| Priority | Criteria |
+|----------|----------|
+| P1 | List + Detail + Create (core CRUD) |
+| P2 | Edit + Dashboard + Child Tab |
+| P3 | Association Manager + specialized widgets |
+
+---
+
+## Attribute-to-Widget Mapping (12 Rules)
+
+For each entity attribute, determine the appropriate UI widget based on data type, constraints, and metadata.
+
+| # | Data Type | Widget | Additional Condition |
+|---|-----------|--------|---------------------|
+| 1 | VARCHAR/TEXT (short) | Text Input | max_length <= 200 |
+| 2 | TEXT (long) | Textarea | max_length > 200 or unlimited |
+| 3 | ENUM | Select Dropdown | Options generated from enum values |
+| 4 | BOOLEAN | Toggle/Checkbox | -- |
+| 5 | INTEGER | Number Input | min/max constraints derive validation |
+| 6 | DECIMAL | Number Input | min/max + step from precision |
+| 7 | DATE | Date Picker | -- |
+| 8 | TIMESTAMP | DateTime Picker | -- |
+| 9 | FK (reference) | Autocomplete/Select | Search against referenced entity |
+| 10 | UUID (PK) | Hidden/Read-only | Never shown as editable input |
+| 11 | File Reference | File Upload | -- |
+| 12 | Email/URL/Phone | Specialized Input | Type-specific validation + format mask |
+
+### Constraint-to-Validation Mapping
+
+| Constraint | Validation Rule |
+|------------|----------------|
+| NOT NULL | Required field |
+| UNIQUE | Uniqueness check (async) |
+| CHECK (min/max) | Range validation |
+| DEFAULT | Pre-filled value |
+| FK | Referential integrity (select from valid options) |
+
+---
+
+## "Output First" Principle
+
+Phase 1 captures the "output image" -- what users ultimately want to see. Use this to drive screen ordering:
+
+1. **Dashboards and reports first.** Place summary views, aggregate displays, and status overviews at the top of the navigation hierarchy.
+2. **Reverse-trace inputs.** For each dashboard element, identify which entities and attributes feed it. Ensure the input forms that populate those attributes are accessible.
+3. **Navigation order:** Dashboard -> List -> Detail -> Create/Edit Form. This reflects the user's mental model: overview first, then drill down, then act.
+
+---
+
+## Brownfield Change Analysis
+
+When `specs/ui-inventory.md` exists (brownfield project), compare the derived screen inventory against the current UI:
+
+| Classification | Condition | Action |
+|---------------|-----------|--------|
+| **New** | Entity has screens derived but no matching current UI | Propose new screens |
+| **Modified** | Entity attributes changed since last UI build | Propose screen modifications (added/removed fields, changed widgets) |
+| **Deleted** | Entity removed from entity-catalog.md | Propose screen removal with redirect |
+| **Restructured** | Relationships changed (FK added/removed) | Propose navigation structure changes |
+
+Present the change analysis to the user as a table before finalizing.
+
+---
+
+## User Conversation Procedure
+
+After completing automatic derivation:
+
+1. **Show summary:** "Derived N screens from M entities. Here is the screen inventory:"
+2. **Present the screen inventory table** (Screen, URL, Entity, Pattern, Priority, Source).
+3. **Ask for confirmation:** "Please review and confirm. Should any screens be added, removed, or re-prioritized?"
+4. **Collect additions:** Users may request screens not derivable from entities (e.g., Settings, About, Help pages). Record these with Source = "User-requested".
+5. **Prioritize:** Confirm the final priority ordering with the user.
+6. **Generate preview** of the navigation structure (Mermaid graph) and display via preview server.
+
+---
+
+## Output: `specs/ui-structure.md`
+
+Write the finalized screen inventory to `specs/ui-structure.md` using this format:
+
+```markdown
+---
+version: "1.0"
+derived_from: "entity-catalog.md v1.0"
+screen_count: N
+entity_coverage: "X/X (100%)"
+---
+
+# UI Structure
+
+## Screen Inventory
+
+| Screen | URL | Primary Entity | Pattern | Priority | Source |
+|--------|-----|----------------|---------|----------|--------|
+| User List | /users | User | List | P1 | Auto-derived |
+| User Detail | /users/:id | User | Detail | P1 | Auto-derived |
+| Create User | /users/new | User | Create | P1 | Auto-derived |
+| ...
+
+## Entity-Screen Traceability Matrix
+
+| Entity | List | Detail | Create | Edit | Dashboard | Notes |
+|--------|------|--------|--------|------|-----------|-------|
+| User | /users | /users/:id | /users/new | /users/:id/edit | - | |
+| ...
+
+## Navigation Structure
+
+​```mermaid
+graph TD
+    Dashboard --> UserList["/users"]
+    UserList --> UserDetail["/users/:id"]
+    UserDetail --> UserEdit["/users/:id/edit"]
+    UserDetail --> UserPosts["/users/:id/posts"]
+    Dashboard --> PostList["/posts"]
+​```
+
+## Change Summary (Brownfield)
+
+| Type | Entity | Current | Proposed | Reason |
+|------|--------|---------|----------|--------|
+| New | Payment | - | /payments, /payments/:id | New entity added in Phase 2 |
+| Modified | User | /users (3 cols) | /users (5 cols) | 2 attributes added |
+| ...
+```
+
+### Completeness Check
+
+Before writing the file, verify:
+- [ ] Every entity in entity-catalog.md has at least one screen
+- [ ] Entity coverage is 100%
+- [ ] All relationships are reflected in navigation (child tabs, association managers)
+- [ ] Traceability matrix has no empty rows
+- [ ] Brownfield changes are classified (if applicable)