id3-cli 0.9.1

package/templates/skills/id3-spawn-team/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: id3-spawn-team
+description: >
+  Spawn an Agent Team (Phase 3-5) to parallelize spec generation, implementation,
+  and QA review based on the information model. Reads entity-catalog.md and
+  data-model.md to auto-generate entity-level tasks with FK dependency ordering.
+  Trigger: spawn team, agent team, phase 3, implement entities, parallel implementation,
+  start implementation, build from model
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+user-invocable: true
+---
+
+# Phase 3-5: Spawn Agent Team
+
+You are the lead agent spawning an Agent Team for IDDD Phase 3 through 5. This skill reads the finalized information model and orchestrates parallel spec generation, implementation, and QA review across team members.
+
+**IMPORTANT: Use Agent Teams, NOT subagents.** Each team member operates in an independent context with its own worktree.
+
+## Prerequisites
+
+Before spawning the team, verify ALL of the following:
+
+1. `specs/entity-catalog.md` exists and contains identified entities.
+2. `specs/data-model.md` exists with a finalized Mermaid ERD.
+3. Phase 2 is complete (entity-catalog.md frontmatter shows `phase: "Phase 2 Complete"` and `version: "1.0"` or higher).
+4. `docs/business-rules.md` exists with derived rules (BR-xxx).
+5. `steering/data-conventions.md` exists with project conventions.
+
+If prerequisites are **not** met, respond:
+
+> "Phase 2 must be completed before spawning an Agent Team. Use 'design information' to run Phase 2 first."
+
+Do **not** proceed until all prerequisites are confirmed.
+
+---
+
+## Team Composition
+
+Spawn exactly **3 team members** with the following roles:
+
+### 1. spec-generator
+
+**Role:** Transform the information model into implementation-ready specifications.
+
+**Reference files (must be provided as context when spawning):**
+- `specs/entity-catalog.md`
+- `specs/data-model.md`
+- `specs/ui-structure.md`
+- `specs/ui-design-contract.md`
+- `specs/ui-inventory.md`
+- `docs/business-rules.md`
+- `steering/data-conventions.md`
+
+**Responsibilities:**
+- Generate `requirements.md` per entity or feature group, derived directly from entity-catalog.md attributes, relationships, and business rules.
+- Generate `api-contracts.md` with endpoint definitions, request/response schemas, and validation rules derived from the information model.
+- Ensure every requirement traces back to a specific entity, attribute, or business rule (BR-xxx).
+- Flag any ambiguity or missing information back to the lead agent rather than making assumptions.
+
+**Work principles:**
+- Every spec line must reference an entity-catalog.md entry or a BR-xxx rule.
+- Do not invent requirements that are not grounded in the information model.
+- Use data-conventions.md for naming, typing, and structural decisions.
+
+### 2. implementer
+
+**Role:** Implement code based on specs produced by spec-generator.
+
+**Reference files (must be provided as context when spawning):**
+- `specs/entity-catalog.md`
+- `specs/data-model.md`
+- `specs/ui-structure.md`
+- `specs/ui-design-contract.md`
+- `specs/ui-inventory.md`
+- `docs/business-rules.md`
+- `steering/data-conventions.md`
+- spec-generator output (requirements.md, api-contracts.md)
+
+**Responsibilities:**
+- Implement entity models, migrations, API endpoints, and validation logic.
+- Commit per entity (one entity per commit, with descriptive commit messages referencing the entity name).
+- Follow the project's tech stack and conventions.
+- Ensure every business rule (BR-xxx) is enforced at the specified enforcement location (DB constraint, application logic, or both).
+
+**Work principles:**
+- Never modify `specs/` or `docs/` files. Implementation follows the spec, not the other way around.
+- If implementation reveals a spec gap, message the qa-reviewer and spec-generator rather than improvising.
+- Each commit must be atomic: one entity's model + migration + API + validation + tests.
+
+### 3. qa-reviewer
+
+**Role:** Verify implementation against the information model. Act as the quality gate.
+
+**Reference files (must be provided as context when spawning):**
+- `specs/entity-catalog.md`
+- `specs/ui-structure.md`
+- `specs/ui-design-contract.md`
+- `docs/business-rules.md`
+
+**Responsibilities:**
+- Review each entity implementation against entity-catalog.md: all attributes present, correct types, correct constraints.
+- Verify all business rules (BR-xxx) are enforced at the correct location.
+- Verify relationship implementations match the ERD (FK placement, delete rules, cardinality).
+- Check UI implementations against ui-structure.md and ui-design-contract.md.
+- If a review fails, message the implementer directly with specific findings and the exact spec reference that was violated.
+
+**Work principles:**
+- Every review finding must cite the specific spec entry (entity name, attribute, BR-xxx) that is violated.
+- Approve only when implementation matches the information model exactly.
+- Track review status per entity: PASS, FAIL (with reasons), or BLOCKED (missing dependency).
+
+---
+
+## Task Generation Rules
+
+### Entity-Level Task Decomposition
+
+1. **Read `specs/entity-catalog.md`** to extract the full entity list.
+2. **Create one task per entity.** Each task includes: model definition, migration, API endpoints, validation, and tests for that entity.
+3. **Analyze FK dependencies** from `specs/data-model.md`:
+   - Entities with no FK dependencies on other project entities are **independent** and can be worked on in parallel.
+   - Entities with FK references to other entities are **dependent** and must wait for their parent entities to be completed first.
+4. **Build a dependency graph** and determine the execution order:
+   - Wave 1: All independent entities (no FK to other project entities).
+   - Wave 2: Entities depending only on Wave 1 entities.
+   - Wave N: Entities depending on entities from previous waves.
+5. **Within each wave**, tasks run in parallel across team members.
+
+### Task Assignment Flow
+
+```
+Lead Agent
+  │
+  ├── Parse entity-catalog.md → entity list
+  ├── Parse data-model.md → FK dependency graph
+  ├── Topological sort → execution waves
+  │
+  ├── Wave 1 (independent entities):
+  │   ├── spec-generator: generate specs for wave 1 entities
+  │   ├── implementer: implement (after specs ready)
+  │   └── qa-reviewer: review (after implementation ready)
+  │
+  ├── Wave 2 (depends on wave 1):
+  │   ├── spec-generator: generate specs for wave 2 entities
+  │   ├── implementer: implement (after specs ready)
+  │   └── qa-reviewer: review (after implementation ready)
+  │
+  └── ... repeat for subsequent waves
+```
+
+### Context Files for All Team Members
+
+When spawning each team member, include these 7 files as mandatory context:
+
+1. `specs/entity-catalog.md`
+2. `specs/data-model.md`
+3. `specs/ui-structure.md`
+4. `specs/ui-design-contract.md`
+5. `docs/business-rules.md`
+6. `steering/data-conventions.md`
+7. `CLAUDE.md` (or `AGENTS.md` for Codex)
+
+---
+
+## Lead Agent Responsibilities
+
+As the lead agent, you do **not** write code or specs yourself. Your role is:
+
+1. **Task distribution:** Assign clear, entity-scoped tasks to team members.
+2. **Progress tracking:** Monitor each team member's progress per entity.
+3. **Quality review:** Review qa-reviewer findings and escalate unresolved issues.
+4. **Feedback:** Provide specific, actionable feedback when work does not meet spec.
+5. **Final integration:** Verify that all entities are implemented, reviewed, and passing before marking the phase complete.
+
+---
+
+## Codex Multi-Agent Workflow
+
+When running on Codex (detected by the presence of `AGENTS.md` and `.codex/` directory), the multi-agent workflow uses the Agents SDK handoff pattern instead of Agent Teams:
+
+- **Project Manager agent** reads entity-catalog.md, builds the dependency graph, and coordinates handoffs.
+- **spec-generator agent** receives entity assignments and produces specs.
+- **implementer agent** receives specs and produces code.
+- **qa-reviewer agent** receives implementations and produces review verdicts.
+
+The roles, responsibilities, and task generation rules are identical to the Claude Code Agent Teams workflow above. Only the orchestration mechanism differs.
+
+---
+
+## Completion
+
+When all entities have been implemented and passed QA review:
+
+1. Update `specs/entity-catalog.md` and `specs/data-model.md` frontmatter:
+   ```yaml
+   version: "1.x"  # increment minor version
+   last_verified: "YYYY-MM-DD"
+   phase: "Phase 3-5 Complete"
+   audit_status: "clean"
+   ```
+
+2. Add an entry to `docs/model-changelog.md`:
+   ```markdown
+   ## [1.x] -- YYYY-MM-DD
+   ### Phase 3-5 Complete
+   - N entities implemented
+   - M business rules enforced
+   - All QA reviews passed
+   ```
+
+3. Display completion message:
+
+> "Agent Team completed Phase 3-5. N entities implemented, M business rules enforced, all QA reviews passed. Run /id3-info-audit for a comprehensive information model audit."

package/templates/specs/data-model.md

@@ -0,0 +1,26 @@
+---
+version: "0.0"
+last_verified: ""
+phase: "Initialized"
+entity_count: 0
+rule_count: 0
+audit_status: "unverified"
+---
+# Data Model
+
+## ER Diagram
+
+```mermaid
+erDiagram
+  %% Generated in Phase 1
+```
+
+## Index Strategy
+
+_(Populated in Phase 2)_
+
+## Design Decision Log
+
+| Decision ID | Topic | Choice | Rationale | Date |
+|-------------|-------|--------|-----------|------|
+| _(Populated in Phase 2)_ | | | | |

package/templates/specs/entity-catalog.md

@@ -0,0 +1,22 @@
+---
+version: "0.0"
+last_verified: ""
+phase: "Initialized"
+entity_count: 0
+rule_count: 0
+audit_status: "unverified"
+---
+# Entity Catalog
+
+> This file is the project's **Single Source of Truth**.
+> All development artifacts (requirements, APIs, screens, tests) are derived from this document.
+
+## Entity Summary
+
+| Entity | Description | Status |
+|--------|-------------|--------|
+| _(Populated in Phase 1)_ | | |
+
+---
+
+_(Detailed definitions for each entity will be added below)_

package/templates/specs/ui-design-contract.md

@@ -0,0 +1,54 @@
+---
+version: "0.0"
+framework: ""
+ui_library: ""
+css: ""
+derived_from: ""
+---
+
+# UI Design Contract
+
+> This document defines the visual design contract -- tech stack, design tokens, copywriting standards, and component mappings. Produced during Phase 2.5.
+
+## Tech Stack
+
+- **Framework:** _(Populated in Phase 2.5)_
+- **UI Library:** _(Populated in Phase 2.5)_
+- **Styling:** _(Populated in Phase 2.5)_
+- **Icons:** _(Populated in Phase 2.5)_
+
+## Design Tokens
+
+### Spacing
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| _(Populated in Phase 2.5)_ | | |
+
+### Typography
+
+| Token | Size | Weight | Line Height | Usage |
+|-------|------|--------|-------------|-------|
+| _(Populated in Phase 2.5)_ | | | | |
+
+### Colors
+
+| Token | Light | Dark | Usage |
+|-------|-------|------|-------|
+| _(Populated in Phase 2.5)_ | | | |
+
+### Copywriting
+
+| Pattern | Template | Example |
+|---------|----------|---------|
+| _(Populated in Phase 2.5)_ | | |
+
+## Component Mapping
+
+| Widget | Component | Import |
+|--------|-----------|--------|
+| _(Populated in Phase 2.5)_ | | |
+
+## Per-Screen Design Spec
+
+_(Populated in Phase 2.5)_

package/templates/specs/ui-inventory.md

@@ -0,0 +1,24 @@
+# UI Inventory (Current Screen Structure)
+
+> For brownfield projects, this captures the analysis of existing UI during Phase 0 (reverse extraction).
+> For greenfield projects, it is normal for this file to be empty.
+
+## Screen Inventory
+
+| Screen | URL Pattern | Related Entities | UI Pattern | Notes |
+|--------|-------------|------------------|------------|-------|
+| _(Populated in Phase 0)_ | | | | |
+
+## Screen–Entity Mapping Matrix
+
+| Entity | List View | Detail View | Create Form | Edit Form | Notes |
+|--------|-----------|-------------|-------------|-----------|-------|
+| _(Populated in Phase 0)_ | | | | | |
+
+## Unmapped Entities (No UI)
+
+_(Populated in Phase 0)_
+
+## Unmapped Screens (Entity Unknown)
+
+_(Populated in Phase 0)_

package/templates/specs/ui-structure.md

@@ -0,0 +1,32 @@
+---
+version: "0.0"
+derived_from: ""
+screen_count: 0
+entity_coverage: ""
+---
+
+# UI Structure
+
+> This document defines the screen inventory and navigation structure, automatically derived from the information model (entity-catalog.md) during Phase 2.5.
+
+## Screen Inventory
+
+| Screen | URL | Primary Entity | Pattern | Priority | Source |
+|--------|-----|----------------|---------|----------|--------|
+| _(Populated in Phase 2.5)_ | | | | | |
+
+## Entity-Screen Traceability Matrix
+
+| Entity | List | Detail | Create | Edit | Dashboard | Notes |
+|--------|------|--------|--------|------|-----------|-------|
+| _(Populated in Phase 2.5)_ | | | | | | |
+
+## Navigation Structure
+
+_(Populated in Phase 2.5 -- Mermaid graph)_
+
+## Change Summary (Brownfield)
+
+| Type | Entity | Current | Proposed | Reason |
+|------|--------|---------|----------|--------|
+| _(Populated in Phase 2.5 for brownfield projects)_ | | | | |

package/templates/steering/data-conventions.md

@@ -0,0 +1,42 @@
+# Data Conventions
+
+> Default rules for data modeling. Modify these to match your project's requirements.
+
+## Primary Key Strategy
+
+- **Default**: UUID v7 (time-sortable)
+- Auto-increment integer IDs are allowed as an alternative
+- All PKs use the column name `id`
+
+## Naming Conventions
+
+- **Database columns**: `snake_case`
+- **Code properties**: `camelCase`
+- **Table names**: plural form (e.g., `users`, `order_items`)
+- **Boolean columns**: prefix with `is_` or `has_` (e.g., `is_active`, `has_verified`)
+
+## Timestamps
+
+- All entities automatically include `created_at` and `updated_at`
+- Stored as `TIMESTAMP WITH TIME ZONE` (UTC)
+
+## Soft Delete
+
+- Pattern: `deleted_at` column (nullable timestamp)
+- Which entities use soft delete is determined in Phase 2
+
+## Indexes
+
+- Foreign keys automatically get an index
+- Add additional indexes for frequently searched attributes
+- Composite indexes for common query patterns
+
+## ENUM vs Reference Table
+
+- **3 or fewer fixed values**: use ENUM type
+- **More than 3 values** or values that may change: use a reference table
+
+## JSON Columns
+
+- Allowed only for metadata whose structure changes frequently
+- If a JSON field is a search target, normalize it into proper columns

package/templates/steering/product.md

@@ -0,0 +1,38 @@
+# Product Vision & Scope
+
+> Fill in the sections below to define the product context for IDDD.
+> This information guides entity identification and UI design decisions.
+
+## Product Name
+
+_(Enter your product or project name)_
+
+## Vision Statement
+
+_(One-paragraph description of what this product aims to achieve)_
+
+## Target Users
+
+_(Who are the primary users? List user roles/personas)_
+
+## Scope
+
+### In Scope
+
+_(Key features and capabilities included in this project)_
+
+### Out of Scope
+
+_(What is explicitly excluded from this project)_
+
+## Domain Context
+
+_(Brief description of the business domain - e.g., e-commerce, healthcare, education)_
+
+## Key Constraints
+
+_(Technical, business, or regulatory constraints that affect design decisions)_
+
+## Existing Systems
+
+_(For brownfield projects: list existing systems, databases, or APIs to integrate with)_