id3-cli 0.9.1

package/templates/skills/id3-identify-entities/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: id3-identify-entities
+description: >
+  Identify domain entities from existing code (brownfield) or through structured
+  interview (greenfield). This is the IDDD workflow entry point.
+  Trigger: identify entities, information analysis, domain analysis, new project,
+  information design, entity identification
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+user-invocable: true
+---
+
+# Phase 0/1: Entity Identification
+
+You are the lead agent performing IDDD (Information Design-Driven Development) entity identification. This skill is the entry point for the IDDD workflow. It automatically determines whether the project is brownfield (existing code) or greenfield (new project) and routes to the appropriate phase.
+
+IDDD starts from "what information exists?" rather than "what features should we build?" The information model is the generative center from which all development artifacts (requirements, API contracts, screen designs, business rules) are derived.
+
+## Auto-Detection Logic
+
+Before starting, scan the project root for existing database/ORM artifacts.
+
+**Check for these files/directories:**
+- `prisma/schema.prisma` or any `*.prisma` file
+- `drizzle/` directory or `drizzle.config.*`
+- `migrations/` directory
+- `**/models.py` (Django)
+- `**/entities/*.ts` or `**/entities/*.java` (TypeORM, JPA)
+- `schema.sql` or `*.sql` migration files
+- `sequelize/` configuration directory
+- Any other ORM/DB schema files
+
+**If ANY of the above exist --> Phase 0 (Brownfield Reverse-Extraction)**
+**If NONE exist --> Phase 1 (Greenfield Structured Interview)**
+
+Announce the detection result to the user before proceeding: "Detected [brownfield/greenfield] project. Entering Phase [0/1]."
+
+---
+
+## Phase 0: Brownfield Reverse-Extraction (Summary)
+
+Extract the implicit information model from existing code into explicit IDDD artifacts. The goal is to make the invisible visible -- every entity, relationship, and business rule that currently lives only in code becomes a documented, trackable artifact.
+
+### 4-Layer Hierarchical Investigation
+
+Investigate these information layers in order, from highest confidence to lowest:
+
+| Layer | Source | What to Investigate | Confidence |
+|-------|--------|---------------------|------------|
+| L1 | DB Schema | Tables, columns, foreign keys, indexes, constraints | Highest |
+| L2 | ORM/Model definitions | Virtual fields, derived attributes, soft delete, state transitions, lifecycle hooks | High |
+| L3 | API contracts | Endpoints, DTOs, request/response schemas, validation logic, authorization rules | Medium |
+| L4 | Frontend | Routes, pages, components, form fields, data fetching patterns | Reference |
+
+**Investigation order matters.** Start with L1 to establish the ground truth, then augment with each subsequent layer. Each layer may reveal information not present in previous layers.
+
+### L4 UI Inventory Extraction
+
+Layer 4 investigation is not merely a reference check. Systematically capture the current UI structure into `specs/ui-inventory.md`:
+
+- **Route/page structure**: Extract from file-based routing (Next.js `app/`, `pages/`), React Router, Vue Router, etc. Capture full page list with URL patterns.
+- **Screen-entity mapping**: Determine which entities each page displays by examining API calls, data fetching hooks, and component props.
+- **UI pattern classification**: Classify each screen as list view, detail view, create/edit form, dashboard/aggregate view, or relationship navigation.
+- **Component-entity relationships**: Map reusable UI components to the entities/attributes they represent.
+- **Form field-attribute mapping**: Map input form fields to their corresponding entity attributes. Note any fields that don't correspond to known attributes.
+
+### Discovery Classification
+
+After investigating all layers, classify each discovered element:
+
+- **Match** -- Consistently represented across all relevant layers --> Confirmed information model skeleton. Record directly in entity-catalog.md with high confidence.
+- **Mismatch** -- Represented differently across layers (e.g., column in DB but never exposed in API, different naming conventions, validation in API but no DB constraint) --> Record in `docs/info-debt.md` with layers involved, what each layer says, and recommended resolution.
+- **Missing** -- Exists only in code logic (if statements, comments, error messages) but not formalized anywhere --> Extract and make explicit as business rules in `docs/business-rules.md`.
+
+### Verification Interview
+
+After completing reverse-extraction, present the consolidated results to the user:
+1. Entity summary with source layers and confidence levels
+2. Mermaid ERD showing all discovered relationships
+3. Info-debt items requiring resolution guidance
+4. Implicit rules extracted from code logic for confirmation
+
+**Key question:** "Does this information model accurately reflect your current codebase? Are there any entities, relationships, or rules that are missing or incorrect?"
+
+Incorporate user corrections and additions before finalizing artifacts.
+
+**For detailed layer-by-layer investigation procedures, see:** `references/phase0-brownfield.md`
+
+### Phase 0 Artifacts
+
+Generate these files:
+- `specs/entity-catalog.md` -- Each entity annotated with source (L1: DB schema, L2: ORM only, L3: API only, L4: UI only, or Multiple)
+- `specs/data-model.md` -- Mermaid ERD with all relationships, columns, and types
+- `specs/ui-inventory.md` -- Current UI structure inventory (screen list, screen-entity mapping matrix, UI pattern classification, unmapped entities/screens)
+- `docs/business-rules.md` -- Each rule with enforcement location (DB constraint, ORM hook, API validation, etc.) and source layer
+- `docs/info-debt.md` -- Cross-layer mismatches, missing constraints, unused schema elements, each with severity and recommended resolution
+
+---
+
+## Phase 1: Greenfield Structured Interview (Summary)
+
+Discover the domain's core information through conversation with the user. This phase is NOT parallelized -- the lead agent conducts the interview directly. Domain discovery requires nuanced conversation that cannot be split across agents.
+
+### Interview Steps
+
+1. **Check existing artifacts**: Read `specs/entity-catalog.md`, `specs/data-model.md`, and `steering/product.md` if they exist. Build on prior work if present.
+
+2. **Information identification questions**:
+   - "What are the main 'things' (nouns) this system needs to manage?"
+   - "For each thing, what information does it contain?"
+   - "What does the user ultimately want to see? What screens, reports, or dashboards are most important?" (output image -- outputs first, inputs later)
+
+3. **Relationship questions**:
+   - "How are these things related to each other?"
+   - "Can one [A] have multiple [B]s, or is it one-to-one?"
+   - "If [A] is deleted, what should happen to its [B]s?" (CASCADE, SET NULL, RESTRICT)
+   - "Must every [B] belong to an [A], or can it exist independently?" (FK nullability)
+
+4. **Rule questions**:
+   - "Are there rules this information must always follow?" (mandatory constraints)
+   - "Does anything have a lifecycle or status flow?" (state transitions)
+   - "Are any values calculated from other values?" (derived/computed attributes)
+
+5. **Silverston Universal Pattern Checklist** -- Cross-reference discovered entities against these patterns to catch gaps:
+   - [ ] Party (person, organization, role)
+   - [ ] Product/Service (product, service, catalog)
+   - [ ] Order/Transaction (order, transaction, event)
+   - [ ] Classification/Category (classification, tag, category)
+   - [ ] Status/Lifecycle (status, stage, transition)
+   - [ ] Hierarchy (hierarchy, tree, parent-child)
+   - [ ] Contact Mechanism (email, phone, address)
+   - [ ] Document/Content (document, content, attachment)
+
+For any universal pattern that reveals a missing entity, explain the pattern to the user and ask whether to include it. If yes, run through Steps 2-4 for the new entity.
+
+### Interview Best Practices
+
+- Use the user's own language. Record entities and attributes in terms the user actually uses. Build the ubiquitous language naturally and record it in `docs/domain-glossary.md`.
+- Don't over-engineer. Phase 1 captures the conceptual model. Data types, indexes, and storage decisions come in Phase 2.
+- Capture uncertainty. If the user says "maybe" or "I'm not sure," record it with a note rather than forcing premature decisions.
+- Show progress. After every 3-4 entities, show the current ERD. Visual feedback keeps the conversation grounded.
+
+**For detailed interview procedures and artifact format, see:** `references/phase1-greenfield.md`
+
+### Phase 1 Artifacts
+
+Generate these files:
+- `specs/entity-catalog.md` -- Entity definitions with attributes, relationships, state transitions, and business rule references
+- `specs/data-model.md` -- Mermaid ERD with entity columns and relationship annotations
+- `docs/business-rules.md` -- Discovered business rules numbered BR-001 and up
+
+---
+
+## Verification Checklist (Both Phases)
+
+Before completing either phase, verify ALL of the following:
+- [ ] All core entities identified
+- [ ] Each entity has attributes defined (PK + core attributes minimum)
+- [ ] All relationships and cardinalities specified
+- [ ] Delete rules (CASCADE, SET NULL, RESTRICT) defined for each relationship
+- [ ] Business rules recorded in `docs/business-rules.md`
+- [ ] Output image captured (what the user ultimately wants to see)
+- [ ] Domain terms added to `docs/domain-glossary.md`
+
+---
+
+## Preview Integration
+
+After completing either phase:
+1. Generate ERD preview HTML at `.iddd/preview/erd-phase0.html` (brownfield) or `.iddd/preview/erd-phase1.html` (greenfield) using Mermaid rendering
+2. Start the preview server and display the URL so the user can review the ERD in their browser
+3. Walk the user through the visual ERD for final confirmation before marking the phase complete
+
+---
+
+## Version Header Update
+
+Upon completion, update YAML frontmatter in `specs/entity-catalog.md` and `specs/data-model.md`:
+
+```yaml
+---
+version: "0.1"
+last_verified: "YYYY-MM-DD"
+phase: "Phase 0 Complete"   # or "Phase 1 Complete"
+entity_count: N
+rule_count: N
+audit_status: "clean"
+---
+```
+
+Add an initial entry to `docs/model-changelog.md`:
+
+```markdown
+## [0.1] -- YYYY-MM-DD
+### Phase 0/1 Complete
+- N entities identified
+- M relationships mapped
+- K business rules recorded
+```
+
+---
+
+## Entity Catalog Format
+
+Each entity in `specs/entity-catalog.md` follows this structure:
+
+```markdown
+## Entity: [Name]
+- **Description**: [one sentence]
+- **Source**: [L1: DB Schema | L2: ORM only | Multiple] (brownfield only)
+- **Attributes**:
+  | Name | Type | Required | Constraints | Notes |
+  |------|------|----------|-------------|-------|
+  | id | UUID | Yes | PK | Primary key |
+- **Relationships**:
+  | Target | Type | Cardinality | Delete Rule |
+  |--------|------|-------------|-------------|
+- **State Transitions**: [if applicable]
+- **Business Rules**: [BR-xxx references]
+```
+
+## Business Rule Format
+
+Each rule in `docs/business-rules.md` follows this structure:
+
+```markdown
+### BR-001: [Rule Name]
+- **Entity**: [related entity]
+- **Type**: Constraint | Derivation | Transition | Validity
+- **Description**: [rule description]
+- **Enforcement Location**: DB constraint | Application logic | Both
+```
+
+---
+
+## Completion Message
+
+After all artifacts are generated, the verification checklist passes, and version headers are updated, output:
+
+"Information model is ready. N entities identified, M relationships mapped, K business rules recorded. Proceed to Phase 2 (information design) with 'design information', or use /id3-spawn-team to compose a downstream Agent Team."

package/templates/skills/id3-identify-entities/references/phase0-brownfield.md

@@ -0,0 +1,377 @@
+# Phase 0: Brownfield Reverse-Extraction -- Detailed Procedures
+
+This document provides the detailed investigation procedures for Phase 0 (brownfield reverse-extraction). The lead agent follows these steps to extract the implicit information model from an existing codebase.
+
+---
+
+## Overview
+
+Phase 0 systematically investigates 4 information layers in order of confidence, from highest (DB schema) to lowest (frontend). Each layer reveals a different facet of the information model. After investigating all layers, discoveries are classified and consolidated into IDDD artifacts.
+
+---
+
+## Layer 1: DB Schema (Highest Confidence)
+
+### What to Investigate
+- Tables, columns, data types
+- Primary keys and foreign keys
+- Indexes (unique, composite, partial)
+- Constraints (NOT NULL, DEFAULT, CHECK, UNIQUE)
+
+### How to Investigate
+
+1. **Locate schema files:**
+   - Prisma: `prisma/schema.prisma`
+   - Drizzle: `drizzle/**/*.ts`
+   - SQL migrations: `migrations/**/*.sql`, `schema.sql`
+   - Django: `**/models.py`
+   - TypeORM: `**/entities/*.ts`
+   - JPA: `**/entities/*.java`
+   - Sequelize: `sequelize/` configuration
+
+2. **For each table/model found, extract:**
+   - Table name and purpose (infer from name and comments)
+   - Column list with data types and constraints
+   - Primary key strategy (UUID, auto-increment, composite)
+   - Foreign key relationships (which table, which column, what rule)
+   - Indexes (what they cover, uniqueness)
+
+3. **Build initial entity list:**
+   - Each table becomes a candidate entity
+   - Junction/pivot tables indicate many-to-many relationships
+   - Identify tables that are purely technical (migrations, sessions) vs. domain entities
+
+### Recording Format
+
+For each entity discovered at L1:
+
+```
+Entity: [TableName]
+Source: L1 (DB Schema)
+Columns: [list with types and constraints]
+PKs: [primary key columns]
+FKs: [foreign key references]
+Indexes: [index definitions]
+```
+
+---
+
+## Layer 2: ORM/Model Definitions (High Confidence)
+
+### What to Investigate
+- Virtual/computed fields not in DB schema
+- Derived attributes (getters, computed properties)
+- Soft delete patterns (`deleted_at`, `is_active`)
+- State machine definitions and transitions
+- Model hooks/lifecycle callbacks (beforeCreate, afterUpdate, etc.)
+- Scopes/query helpers that imply business rules
+
+### How to Investigate
+
+1. **Locate model files:**
+   - Same files as L1, but focus on code-level annotations and logic
+   - Prisma: `@default`, `@updatedAt`, virtual relations
+   - Django: `Meta` class, `@property`, managers, querysets
+   - TypeORM: `@BeforeInsert`, `@AfterUpdate`, subscribers
+   - Sequelize: hooks, scopes, virtual fields
+
+2. **For each model, extract:**
+   - Virtual fields and their computation logic
+   - Lifecycle hooks and what they enforce
+   - Soft delete configuration
+   - State transition definitions (enum fields + transition methods)
+   - Custom validation methods
+
+3. **Compare with L1 findings:**
+   - Note any fields that exist in ORM but not in DB (virtual/computed)
+   - Note any constraints enforced in ORM but not in DB
+   - Record discrepancies as potential info-debt items
+
+### Recording Format
+
+For each entity augmented at L2:
+
+```
+Entity: [ModelName]
+L2 Additions:
+  Virtual fields: [list]
+  Computed properties: [list with formulas]
+  Lifecycle hooks: [hook -> action]
+  Soft delete: [yes/no, pattern]
+  State transitions: [from -> to transitions]
+  L1-L2 discrepancies: [list]
+```
+
+---
+
+## Layer 3: API Contracts (Medium Confidence)
+
+### What to Investigate
+- Endpoints (REST routes, GraphQL resolvers)
+- DTOs (Data Transfer Objects) / request/response schemas
+- Validation logic at API boundaries
+- Authorization rules tied to entities
+- Aggregation/transformation logic
+
+### How to Investigate
+
+1. **Locate API definition files:**
+   - Express/Fastify: route files, controller files
+   - NestJS: `*.controller.ts`, `*.dto.ts`
+   - Django REST: `views.py`, `serializers.py`, `urls.py`
+   - GraphQL: schema definitions, resolvers
+   - OpenAPI/Swagger: `openapi.yaml`, `swagger.json`
+
+2. **For each endpoint, extract:**
+   - HTTP method + path pattern
+   - Which entity/entities it operates on
+   - Request body schema (create/update fields)
+   - Response schema (what attributes are exposed)
+   - Validation rules (required fields, format checks, range limits)
+   - Authorization requirements (who can access)
+
+3. **Compare with L1/L2 findings:**
+   - Fields in API response but not in entity -> possible derived field
+   - Fields in entity but not exposed in API -> intentionally hidden or oversight
+   - Validation in API but not in DB -> missing constraint
+   - Entities with no API endpoints -> potentially unused or internal-only
+
+### Recording Format
+
+For each entity augmented at L3:
+
+```
+Entity: [EntityName]
+L3 API Coverage:
+  Endpoints: [method + path -> operation]
+  Exposed attributes: [list]
+  Hidden attributes: [list]
+  API-only validations: [list]
+  L1/L2-L3 discrepancies: [list]
+```
+
+---
+
+## Layer 4: Frontend (Reference Confidence)
+
+### What to Investigate
+- Route/page structure
+- Screen-entity mapping
+- UI pattern classification
+- Component-entity relationships
+- Form field-attribute mapping
+
+### How to Investigate
+
+1. **Locate frontend structure:**
+   - Next.js: `app/` or `pages/` directory
+   - React Router: route configuration files
+   - Vue Router: `router/index.ts`
+   - Angular: routing modules
+   - Other: scan for route/page patterns
+
+2. **For each page/screen, extract:**
+   - URL pattern
+   - Related entities (infer from API calls, data fetching, imports)
+   - UI pattern classification:
+     - **List view**: table, grid, card list
+     - **Detail view**: single entity display
+     - **Create/Edit form**: entity creation or modification
+     - **Dashboard/Aggregate view**: charts, summaries, KPIs
+     - **Relationship navigation**: parent-to-child drill-down
+
+3. **Build UI inventory:**
+   - Screen inventory table (screen name, URL, related entity, UI pattern, notes)
+   - Screen-entity mapping matrix (entity vs. list/detail/create/edit availability)
+   - Unmapped entities (in DB but no UI)
+   - Unmapped screens (UI exists but no clear entity mapping)
+
+4. **Map form fields to entity attributes:**
+   - For each create/edit form, list input fields
+   - Match each field to entity attributes from L1/L2
+   - Note any fields that don't correspond to known attributes
+
+### Recording Format
+
+```
+Screen: [PageName]
+URL: [pattern]
+Related Entities: [list]
+UI Pattern: [classification]
+Form Fields: [field -> entity.attribute mapping]
+L1-L4 discrepancies: [list]
+```
+
+---
+
+## Discovery Classification
+
+After investigating all 4 layers, classify every discovered element:
+
+### Match (Consistent)
+
+Elements represented consistently across all relevant layers. These form the confirmed information model skeleton.
+
+**Action:** Record directly in `specs/entity-catalog.md` with high confidence.
+
+### Mismatch (Inconsistent)
+
+Elements represented differently across layers. Common examples:
+- Column exists in DB but is never used in API or UI
+- API validates a field that has no DB constraint
+- UI shows a field that doesn't exist in the model
+- Different naming across layers (e.g., `user_id` in DB, `userId` in API, `author` in UI)
+- Soft delete in ORM but not enforced in DB
+
+**Action:** Record each mismatch in `docs/info-debt.md` with:
+- Layers involved
+- What each layer says
+- Recommended resolution
+- Severity (high/medium/low)
+
+### Missing (Implicit)
+
+Rules or constraints that exist only in code logic (if statements, comments, error messages) but are not formalized anywhere.
+
+**Action:** Extract and formalize as explicit business rules in `docs/business-rules.md`.
+
+---
+
+## Verification Interview
+
+After completing the investigation and classification, present the consolidated results to the user:
+
+1. **Entity summary:** List all discovered entities with their source layer and confidence level
+2. **Relationship map:** Show the ERD (Mermaid diagram)
+3. **Info debt items:** Present mismatches and ask for resolution guidance
+4. **Missing rules:** Present extracted implicit rules for confirmation
+5. **Questions:** Ask about anything ambiguous or contradictory
+
+**Key question:** "Does this information model accurately reflect your current codebase? Are there any entities, relationships, or rules that are missing or incorrect?"
+
+Incorporate user corrections and additions before finalizing artifacts.
+
+---
+
+## Artifact Generation
+
+### specs/entity-catalog.md
+
+For each entity:
+
+```markdown
+## Entity: [Name]
+- **Description**: [one sentence]
+- **Source**: [L1: DB Schema | L2: ORM only | L3: API only | L4: UI only | Multiple]
+- **Attributes**:
+  | Name | Type | Required | Constraints | Source | Notes |
+  |------|------|----------|-------------|--------|-------|
+  | id | UUID | Yes | PK | L1 | |
+  | ... | ... | ... | ... | ... | ... |
+- **Relationships**:
+  | Target | Type | Cardinality | Delete Rule | Source |
+  |--------|------|-------------|-------------|--------|
+  | ... | ... | ... | ... | ... |
+- **State Transitions**: [if applicable, from L2]
+- **Business Rules**: [rule numbers, e.g., BR-001, BR-002]
+```
+
+### specs/data-model.md
+
+```markdown
+---
+version: "0.1"
+last_verified: "YYYY-MM-DD"
+phase: "Phase 0 Complete"
+entity_count: N
+rule_count: N
+audit_status: "clean"
+---
+
+# Data Model
+
+## ER Diagram
+
+\`\`\`mermaid
+erDiagram
+  ENTITY_A ||--o{ ENTITY_B : "relationship description"
+  ...
+\`\`\`
+
+## Index Strategy
+
+[Entity-by-entity index design extracted from L1]
+
+## Design Decision Log
+
+| Decision ID | Subject | Choice | Reason | Date |
+|-------------|---------|--------|--------|------|
+| (To be filled in Phase 2) | | | | |
+```
+
+### specs/ui-inventory.md
+
+```markdown
+## Screen Inventory
+
+| Screen | URL Pattern | Related Entities | UI Pattern | Notes |
+|--------|-------------|-----------------|------------|-------|
+| ... | ... | ... | ... | ... |
+
+## Screen-Entity Mapping Matrix
+
+| Entity | List View | Detail View | Create Form | Edit Form | Notes |
+|--------|-----------|-------------|-------------|-----------|-------|
+| ... | ... | ... | ... | ... | ... |
+
+## Unmapped Entities (No UI)
+- [Entities that exist in DB but have no corresponding UI]
+
+## Unmapped Screens (No Entity)
+- [Screens that don't clearly map to any entity in the catalog]
+```
+
+### docs/business-rules.md
+
+```markdown
+### BR-001: [Rule Name]
+- **Entity**: [related entity]
+- **Type**: Constraint | Derivation | Transition | Validity
+- **Description**: [rule description]
+- **Enforcement Location**: DB constraint | Application logic | Both
+- **Implementation**: [specific implementation approach]
+- **Source**: [L1/L2/L3/L4, or implicit from code logic]
+```
+
+### docs/info-debt.md
+
+```markdown
+## Info Debt Item: [ID]
+- **Layers Involved**: [e.g., L1 vs. L3]
+- **Description**: [what the mismatch is]
+- **L1 says**: [...]
+- **L3 says**: [...]
+- **Severity**: High | Medium | Low
+- **Recommended Resolution**: [suggestion]
+- **Status**: Open | Resolved
+```
+
+---
+
+## Preview Integration
+
+After artifact generation:
+
+1. Generate an ERD preview from `specs/data-model.md` Mermaid content
+2. Write it to `.iddd/preview/erd-phase0.html`
+3. Start the preview server and display the URL
+
+---
+
+## Completion
+
+Update version headers in `specs/entity-catalog.md` and `specs/data-model.md` (version: "0.1", phase: "Phase 0 Complete").
+
+Add an entry to `docs/model-changelog.md`.
+
+Output the completion message with entity count, relationship count, and business rule count.