project-iris 0.2.3 → 0.3.0

package/flows/aidlc/commands/construction-agent.md

@@ -35,7 +35,7 @@ You are now the **Construction Agent** for iris AI-DLC.
 - **List Bolts**: `.iris/aidlc/skills/construction/bolt-list.md` → View all bolts
 - **Bolt Status**: `.iris/aidlc/skills/construction/bolt-status.md` → Detailed bolt status
 - **Start/Continue Bolt**: `.iris/aidlc/skills/construction/bolt-start.md` → Execute bolt stages
-- **Plan Bolts**: `.iris/aidlc/skills/construction/bolt-plan.md` → Redirects to Inception
+- **Replan Bolts**: `.iris/aidlc/skills/construction/bolt-replan.md` → Modify bolt plan during construction
 - **Menu**: `.iris/aidlc/skills/construction/navigator.md` → Show skills
 
 ---

package/flows/aidlc/commands/operations-agent.md

@@ -36,6 +36,7 @@ You are now the **Operations Agent** for iris AI-DLC.
 - **Deploy**: `.iris/aidlc/skills/operations/deploy.md` → Deploy to environment
 - **Verify**: `.iris/aidlc/skills/operations/verify.md` → Validate deployment
 - **Monitor**: `.iris/aidlc/skills/operations/monitor.md` → Setup observability
+- **Rollback**: `.iris/aidlc/skills/operations/rollback.md` → Rollback deployment
 - **Menu**: `.iris/aidlc/skills/operations/navigator.md` → Show skills
 
 ---

package/flows/aidlc/skills/construction/bolt-start.md

@@ -21,6 +21,9 @@
 - ✅ Checkpoint prompts clear and actionable
 - ✅ Code references stories (comments: `// Story: S-XXX`)
 - ✅ Tests reference acceptance criteria they verify
+- ✅ **Stories processed sequentially in code generation stages**
+- ✅ **Story progress list shown during execution**
+- ✅ **stories_progress updated in bolt file after each story**
 
 ## Failure Modes
 
@@ -30,6 +33,9 @@
 - ❌ Not reading bolt type definition first
 - ❌ Code without story traceability comments
 - ❌ Tests without acceptance criteria references
+- ❌ **Implementing all stories at once without tracking progress**
+- ❌ **Not showing story progress during code generation**
+- ❌ **Stories implemented out of order without justification**
 
 ---
 
@@ -194,19 +200,75 @@ For the current stage, follow the bolt type definition:
    {From bolt type definition}
 
    ### Stories in Scope
-   {From bolt instance}
+   {From bolt instance - show with status}
+   - [ ] 001-story-one (pending)
+   - [ ] 002-story-two (pending)
    ```
 
 2. **Perform Activities**:
    - Follow bolt type's activity instructions exactly
    - Create artifacts as specified
    - Respect constraints (e.g., "no code in this stage")
+   - **For code generation stages**: Follow story-by-story execution (see 7b)
 
 3. **Generate Outputs**:
    - Create specified output artifacts
    - Use templates if specified by bolt type
    - Place in correct paths per schema
 
+### 7b. Story-by-Story Execution (Code Generation Stages)
+
+**⛔ CRITICAL**: When executing stages that involve code generation (e.g., Stage 4 in DDD bolts), process stories SEQUENTIALLY:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY-BY-STORY EXECUTION                                    │
+│                                                              │
+│  For EACH story in bolt's stories array:                     │
+│  1. Announce: "⏳ Story {n}/{total}: {story-id}"             │
+│  2. Read story file for acceptance criteria                  │
+│  3. Implement code for that story                            │
+│  4. Update stories_progress in bolt file                     │
+│  5. Announce: "✅ Story {story-id}: Implemented"             │
+│                                                              │
+│  DO NOT batch implement - track each story individually!     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story Progress Display (show after each story)**:
+
+```markdown
+### Story Progress ({completed}/{total})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ⏳ **{SSS}-{story-slug}**: In Progress
+4. [ ] **{SSS}-{story-slug}**: Pending
+5. [ ] **{SSS}-{story-slug}**: Pending
+6. [ ] **{SSS}-{story-slug}**: Pending
+```
+
+**Update bolt file after each story:**
+
+```yaml
+stories_progress:
+  - id: 001-database-init
+    status: completed
+    implemented_at: {timestamp}
+  - id: 002-schema-tables
+    status: completed
+    implemented_at: {timestamp}
+  - id: 003-crud-operations
+    status: in-progress
+  - id: 004-query-helpers
+    status: pending
+```
+
+This ensures:
+- Clear visibility into which story is being worked on
+- Ability to resume if interrupted
+- Validation that all stories are addressed
+
 ### 8. Handle Checkpoints (As Defined by Bolt Type)
 
 The bolt type definition specifies:
@@ -400,6 +462,13 @@ If construction log doesn't exist, create it using template:
 **Type**: {bolt-type}
 **Progress**: Stage {n} of {total}
 
+### Story Progress ({completed}/{total})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ⏳ **{SSS}-{story-slug}**: In Progress
+4. [ ] **{SSS}-{story-slug}**: Pending
+
 ### Activities Performed
 1. ✅ {activity 1}
 2. ✅ {activity 2}
@@ -408,10 +477,6 @@ If construction log doesn't exist, create it using template:
 ### Artifacts Created
 - `{path/to/artifact}` - {description}
 
-### Stories Addressed
-- ✅ **{SSS}-{story-slug}**: {criteria} - Complete
-- ⏳ **{SSS}-{story-slug}**: {criteria} - In Progress
-
 ---
 
 ### Checkpoint (if defined by bolt type)

package/flows/aidlc/skills/inception/story-create.md

@@ -17,6 +17,8 @@
 - ✅ Each story has: User Story format, Acceptance Criteria, Priority
 - ✅ story-index.md updated with ✅ GENERATED markers
 - ✅ Unit-brief.md updated with story summary
+- ✅ **All assigned FRs have corresponding stories (validation passed)**
+- ✅ **FR-to-story mapping shown in output**
 
 ## Failure Modes
 
@@ -24,6 +26,8 @@
 - ❌ Missing acceptance criteria in stories
 - ❌ Not updating story-index.md
 - ❌ Stories without INVEST criteria validation
+- ❌ **Assigned FRs without corresponding stories**
+- ❌ **Proceeding without FR-to-story validation**
 
 ---
 
@@ -144,6 +148,54 @@ Organize stories for bolt planning:
 - **Should**: Important but not blocking (Error handling, validation)
 - **Could**: Nice to have (Advanced features, optimizations)
 
+### 4b. Validate FR-to-Story Coverage (CRITICAL - HARD GATE)
+
+**⛔ HARD GATE**: Before creating story files, validate that ALL assigned FRs have stories.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FR-TO-STORY COVERAGE VALIDATION                             │
+│  → Read "Assigned Requirements" from unit-brief.md           │
+│  → Check each FR has at least one story                      │
+│  → If any FR is uncovered: STOP and create stories for it    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Validation output:**
+
+```markdown
+## FR-to-Story Coverage
+
+### Assigned FRs from Unit Brief
+- **FR-1**: {description}
+- **FR-2**: {description}
+- **FR-N**: {description}
+
+### Coverage Check
+
+- ✅ **FR-1**: {description} → `{SSS}-{story-slug}`, `{SSS}-{story-slug}`
+- ✅ **FR-2**: {description} → `{SSS}-{story-slug}`
+- ❌ **FR-3**: {description} → UNCOVERED
+
+### Validation Result
+- ✅ All FRs covered by stories (proceed)
+- ❌ {n} FRs uncovered - MUST create stories before proceeding:
+  - FR-X: {description} - NEEDS STORY
+```
+
+**If any FRs are uncovered:**
+
+1. **DO NOT PROCEED** to creating story files
+2. Create stories for uncovered FRs
+3. Re-run validation until all FRs are covered
+
+**Important Notes:**
+
+- One FR can map to multiple stories (complex features)
+- Multiple FRs can map to one story (closely related features)
+- Every FR MUST have at least one story
+- This validation catches FRs that were "lost" during decomposition
+
 ### 5. Document Stories
 
 1. **Read Path**: Check `schema.stories` from `.iris/aidlc/memory-bank.yaml`
@@ -294,6 +346,14 @@ This ensures each unit-brief shows its story count at a glance.
 ```markdown
 ## Stories Created: {unit-name}
 
+### FR-to-Story Coverage ✅
+
+- ✅ **FR-1**: {description} → `{SSS}-{story-slug}`, `{SSS}-{story-slug}`
+- ✅ **FR-2**: {description} → `{SSS}-{story-slug}`
+- ✅ **FR-3**: {description} → `{SSS}-{story-slug}`
+
+**All {n} assigned FRs have corresponding stories.**
+
 ### Story Summary
 
 - [ ] **S1**: User can register - Must - No dependencies

package/flows/aidlc/skills/inception/units.md

@@ -15,7 +15,8 @@
 
 - ✅ Unit directories created with unit-brief.md files
 - ✅ Dependency graph shown visually
-- ✅ All FRs mapped to exactly one unit
+- ✅ **All FRs mapped to exactly one unit (validation passed)**
+- ✅ FR coverage validation output shown
 - ✅ Frontend unit included if enabled in project type
 
 ## Failure Modes
@@ -23,6 +24,8 @@
 - ❌ Using ASCII table for unit listing
 - ❌ Not reading project type configuration
 - ❌ FRs not mapped to units
+- ❌ **Proceeding without FR coverage validation**
+- ❌ **Unmapped FRs not flagged**
 - ❌ Missing unit-brief.md files
 
 ---
@@ -149,6 +152,54 @@ This mapping ensures:
 - Units have clear scope based on assigned FRs
 - Stories will be created from unit's assigned FRs (not directly from intent)
 
+### 4b. Validate FR Coverage (CRITICAL - HARD GATE)
+
+**⛔ HARD GATE**: Before proceeding, validate that ALL FRs are mapped.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FR COVERAGE VALIDATION                                      │
+│  → Count FRs in requirements.md                              │
+│  → Count FRs in mapping                                      │
+│  → If mismatch: STOP and fix before proceeding               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Validation output:**
+
+```markdown
+## FR Coverage Validation
+
+### Requirements Count
+- **Total FRs in requirements.md**: {n}
+- **Must Have**: {n}
+- **Should Have**: {n}
+- **Could Have**: {n}
+
+### Mapping Count
+- **FRs mapped to units**: {n}
+- **FRs unmapped**: {list or "None"}
+
+### Validation Result
+- ✅ All FRs mapped (proceed to next step)
+- ❌ {n} FRs unmapped - MUST fix before proceeding:
+  - FR-X: {description} - NOT MAPPED
+  - FR-Y: {description} - NOT MAPPED
+```
+
+**If any FRs are unmapped:**
+
+1. **DO NOT PROCEED** to creating unit directories
+2. Review unmapped FRs and assign them to appropriate units
+3. Re-run validation until all FRs are mapped
+
+**Common reasons for unmapped FRs:**
+
+- FR was overlooked during domain analysis
+- FR spans multiple bounded contexts (split or create integration unit)
+- FR is an NFR incorrectly labeled as FR (move to NFRs)
+- FR is duplicate (merge with existing)
+
 ### 5. Create Frontend Unit (if enabled)
 
 **Skip this step if `frontend.enabled: false`.**

package/flows/aidlc/skills/master/project-init.md

@@ -15,6 +15,7 @@
 
 - ✅ project.yaml created with project type AND scenario (greenfield/brownfield/hybrid)
 - ✅ Scenario detected automatically with user confirmation
+- ✅ .gitignore updated with AI-DLC tooling entries
 - ✅ Standards created in correct order (dependencies respected)
 - ✅ Each question is single-focus (not combined)
 - ✅ Final summary shows all created/skipped standards
@@ -26,6 +27,7 @@
 - ❌ Creating standard before its dependencies
 - ❌ Not creating project.yaml
 - ❌ Not detecting/asking about greenfield vs brownfield scenario
+- ❌ Not updating .gitignore with AI-DLC tooling entries
 
 ---
 
@@ -125,9 +127,9 @@ This appears to be a **brownfield** project (enhancing existing code).
 2. **Greenfield** - No, ignore existing code, starting fresh
 3. **Hybrid** - Some features will modify existing, some are new
 
-This affects how the Construction Agent works:
-- **Brownfield**: Runs code elevation first to understand existing structure
-- **Greenfield**: Starts fresh with domain modeling
+This affects the development flow:
+- **Brownfield**: Master Agent runs code elevation first to understand existing structure
+- **Greenfield**: Construction Agent starts fresh with domain modeling
 - **Hybrid**: Asks per-intent which flow to use
 ```
 
@@ -185,6 +187,33 @@ existing_codebase:
 
 This file MUST be created before proceeding to standards facilitation, as other agents (e.g., Inception, Construction) read it to provide context-aware behavior.
 
+### 4b. Update .gitignore
+
+**Add AI-DLC tooling entries to `.gitignore`** to keep the product repository clean.
+
+#### If `.gitignore` exists:
+
+Check if entries already exist. If not, append:
+
+```gitignore
+
+# AI-DLC tooling (iris, claude)
+.iris/
+.claude/
+```
+
+#### If `.gitignore` doesn't exist:
+
+Create it with:
+
+```gitignore
+# AI-DLC tooling (iris, claude)
+.iris/
+.claude/
+```
+
+**Note**: `memory-bank/` is NOT gitignored - it contains valuable project specifications (PRFAQ, intents, stories, standards) that should be version controlled.
+
 ### 5. Check Existing Standards
 
 Before creating new standards, check if any exist:
@@ -314,6 +343,7 @@ After completing all standards:
 - **Type**: {project type} (e.g., full-stack-web)
 - **Scenario**: {scenario} (greenfield/brownfield/hybrid)
 - **Config**: `memory-bank/project.yaml`
+- **Gitignore**: `.gitignore` updated with AI-DLC tooling entries
 
 ### Standards Created
 
@@ -337,9 +367,9 @@ Your project is configured as a **{project type}** ({scenario}) using:
 - Use your chosen libraries and patterns
 - Follow your testing strategy
 
-**Scenario** - Construction Agent will:
-- {If greenfield}: Start with domain modeling (fresh design)
-- {If brownfield}: Run code elevation first (analyze existing code)
+**Scenario** - Development flow:
+- {If greenfield}: Construction Agent starts with domain modeling (fresh design)
+- {If brownfield}: Master Agent runs code elevation first (analyze existing code)
 - {If hybrid}: Ask per-intent which flow to use
 
 ### Actions

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt.md

@@ -349,18 +349,45 @@ Implement CQRS pattern with separate read models for task queries.
 - **REQUIRED**: Load all bolt folder artifacts (see Bolt Context Loading section)
 - **OUTPUT**: Source code based on design docs
 
-**Activities**:
+**⛔ CRITICAL: Story-by-Story Execution**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  STORY-BY-STORY EXECUTION MODE                               │
+│                                                              │
+│  Stories MUST be implemented SEQUENTIALLY:                   │
+│  1. Read bolt's stories array                                │
+│  2. For each story in order:                                 │
+│     a. Announce: "Implementing Story: {story-id}"            │
+│     b. Read story file for acceptance criteria               │
+│     c. Implement code for that story                         │
+│     d. Update story status in bolt tracking                  │
+│     e. Show: "Story {story-id}: ✅ Implemented"              │
+│  3. After ALL stories: proceed to checkpoint                 │
+│                                                              │
+│  DO NOT implement all stories at once without tracking!      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Story Execution Order:**
+
+1. Read `stories` array from bolt.md frontmatter
+2. Process stories in the order listed (this order respects dependencies)
+3. For each story, implement the code needed to satisfy its acceptance criteria
+4. Track progress visibly to user
+
+**Activities** (performed FOR EACH STORY):
 
-1 - **Setup project structure**: Create scaffolding
-2 - **Implement domain entities/value objects**: Create domain code
-3 - **Implement domain services**: Build service layer
-4 - **Implement application layer**: Create use cases
-5 - **Implement infrastructure**: Build repository implementations
-6 - **Implement presentation layer**: Create API endpoints
-7 - **Add validation and error handling**: Implement guards and handlers
-8 - **Add logging and instrumentation**: Add observability code
-9 - **Add story traceability**: Add `// Story: S-XXX` comments linking code to stories
-10 - **Run code quality validation**: Execute linting, type checking, build
+1 - **Announce story**: Display "⏳ Implementing Story: {story-id}: {title}"
+2 - **Read story file**: Load `stories/{story-id}.md` for acceptance criteria
+3 - **Implement code**: Create/modify code to satisfy acceptance criteria
+4 - **Add traceability**: Add `// Story: {story-id}` comments to code
+5 - **Mark progress**: Display "✅ Story {story-id}: Implemented"
+
+**After ALL stories are implemented:**
+
+6 - **Setup project structure**: Verify scaffolding exists
+7 - **Run code quality validation**: Execute linting, type checking, build
 
 **Artifact**: Source code in unit directory
 **Location**: `src/{unit}/` or as defined in project structure
@@ -405,6 +432,7 @@ src/{unit}/
 
 **Completion Criteria**:
 
+- [ ] **All stories implemented in order** (see Story Progress below)
 - [ ] All domain models implemented
 - [ ] All use cases implemented
 - [ ] All API endpoints implemented
@@ -422,6 +450,15 @@ src/{unit}/
 ```text
 ## Stage 4 Complete: Code Generation
 
+### Story Progress ({n}/{n})
+
+1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+3. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+4. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+5. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+6. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
+
 ### Code Generated
 - {n} domain entities
 - {n} use cases
@@ -433,9 +470,8 @@ src/{unit}/
 - ✅ Build: Passed
 - ✅ Traceability: All files linked to stories
 
-### Story Coverage
-- S-001: {files implementing}
-- S-002: {files implementing}
+### Acceptance Criteria Preview
+Each story's ACs will be validated in Stage 5 (Testing).
 
 Ready to proceed to testing?
 1 - Yes, continue to Stage 5
@@ -560,19 +596,42 @@ Story S-002: Password Reset
 
 ## State Tracking
 
-Bolt instance tracks progress:
+Bolt instance tracks progress at both stage and story level:
 
 ```yaml
 ---
-current_stage: design
+current_stage: code
 stages_completed:
-  - name: model
+  - name: domain-design
     completed: 2024-12-05T10:00:00Z
     artifact: ddd-01-domain-design.md
+  - name: logical-design
+    completed: 2024-12-05T12:00:00Z
+    artifact: ddd-02-logical-design.md
 status: in-progress
+
+# Story-level tracking (updated during Stage 4)
+stories_progress:
+  - id: 001-database-init
+    status: completed
+    implemented_at: 2024-12-05T14:00:00Z
+  - id: 002-schema-tables
+    status: completed
+    implemented_at: 2024-12-05T14:30:00Z
+  - id: 003-crud-operations
+    status: in-progress
+  - id: 004-query-helpers
+    status: pending
 ---
 ```
 
+**Story status values:**
+
+- `pending` - Not yet started
+- `in-progress` - Currently being implemented
+- `completed` - Implementation done (not yet tested)
+- `verified` - Tests passing (after Stage 5)
+
 ---
 
 ## Bolt Context Loading

package/flows/aidlc/templates/standards/api-conventions.guide.md

@@ -0,0 +1,305 @@
+# API Conventions Facilitation Guide
+
+## Purpose
+
+Define the API design conventions, response formats, and standards that will guide how APIs are built, ensuring consistency and predictability for API consumers.
+
+---
+
+## Facilitation Approach
+
+You are collaborating with a peer to discover their API design preferences. This is relevant for projects with backend APIs.
+
+**Adapt your style:**
+
+- If they have existing APIs → focus on consistency with what exists
+- If they're building public APIs → emphasize documentation and stability
+- If they're building internal APIs → focus on developer experience
+
+**Your role:**
+
+- Guide discovery, don't dictate choices
+- Surface tradeoffs between simplicity and flexibility
+- Ensure choices work with their tech stack
+- Capture rationale, not just the choice
+
+---
+
+## Discovery Areas
+
+### 1. API Style
+
+**Goal**: Understand the fundamental API approach.
+
+**Open with context:**
+> "Let's talk about how your API will be structured. This affects how clients interact with it, how it's documented, and how it evolves over time."
+
+**Explore:**
+
+- Who will consume this API? (Internal frontend, mobile apps, third parties)
+- What kind of operations? (CRUD, complex queries, real-time)
+- Is this public or internal?
+- Do they have existing API patterns to follow?
+
+**Guide by use case:**
+
+| Use Case | Recommendation | Why |
+|----------|----------------|-----|
+| Simple CRUD | REST | Well understood, great tooling |
+| Complex queries | GraphQL | Flexible queries, single endpoint |
+| Internal services | REST or tRPC | tRPC for TypeScript full-stack |
+| Public API | REST with OpenAPI | Documentation, client generation |
+| Mobile + Web | REST or GraphQL | GraphQL avoids over-fetching |
+| Microservices (internal) | gRPC | Performance, type safety |
+
+**REST vs GraphQL vs tRPC:**
+
+| Aspect | REST | GraphQL | tRPC |
+|--------|------|---------|------|
+| Learning curve | Low | Medium | Low (TypeScript) |
+| Flexibility | Endpoints per resource | Single endpoint, flexible queries | Full type safety |
+| Caching | HTTP caching | Requires custom | N/A (internal) |
+| Best for | Public APIs, simple apps | Complex UIs, mobile | TypeScript monorepos |
+
+---
+
+### 2. API Versioning
+
+**Goal**: Understand how they'll handle API evolution.
+
+**Explore:**
+
+- Is this a public API that needs stability?
+- How often do they expect breaking changes?
+- Who are the consumers? (Internal team vs. external developers)
+
+**Options:**
+
+| Strategy | Example | Best For |
+|----------|---------|----------|
+| URL versioning | `/api/v1/users` | Public APIs, clear separation |
+| Header versioning | `Accept: application/vnd.api.v1+json` | Cleaner URLs |
+| No versioning | Just `/api/users` | Internal APIs, rapid iteration |
+| Query param | `/api/users?version=1` | Less common, avoid |
+
+**Recommendations:**
+
+- **Public API**: URL versioning (`/api/v1/`) - clear and obvious
+- **Internal API**: No versioning initially, add when needed
+- **Evolving API**: Use backward-compatible changes when possible
+
+---
+
+### 3. Response Format
+
+**Goal**: Understand the structure of API responses.
+
+**Explore:**
+
+- Do they need pagination? (Lists of items)
+- How should errors be returned?
+- Is there metadata needed? (Request IDs, timing)
+
+**Standard patterns:**
+
+**Single resource:**
+```json
+{
+  "data": {
+    "id": "123",
+    "name": "Example"
+  }
+}
+```
+
+**Collection with pagination:**
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "per_page": 20,
+    "total": 100,
+    "total_pages": 5
+  }
+}
+```
+
+**Or cursor-based:**
+```json
+{
+  "data": [...],
+  "pagination": {
+    "cursor": "abc123",
+    "has_more": true
+  }
+}
+```
+
+**Recommendations:**
+
+- Wrap responses in `data` for consistency
+- Use cursor pagination for large/real-time datasets
+- Use page pagination for smaller, static datasets
+
+---
+
+### 4. Error Response Format
+
+**Goal**: Understand how errors will be communicated.
+
+**Explore:**
+
+- Do they need error codes for client handling?
+- How detailed should errors be? (Security vs. debugging)
+- Is this for developers or end users?
+
+**Standard pattern:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ]
+  }
+}
+```
+
+**HTTP status codes to use:**
+
+| Status | Use For |
+|--------|---------|
+| 200 | Success |
+| 201 | Created |
+| 204 | No content (delete) |
+| 400 | Bad request (validation) |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+| 409 | Conflict |
+| 422 | Unprocessable entity |
+| 500 | Server error |
+
+**Recommendations:**
+
+- Always include an error `code` for programmatic handling
+- Include `message` for human-readable description
+- Include `details` for validation errors
+- Don't expose stack traces in production
+
+---
+
+### 5. Pagination Strategy
+
+**Goal**: Understand how lists will be paginated.
+
+**Explore:**
+
+- How large are the datasets?
+- Do items change frequently? (Insertions/deletions)
+- Do they need to jump to specific pages?
+
+**Options:**
+
+| Strategy | Best For | Tradeoffs |
+|----------|----------|-----------|
+| Offset/Page | Small datasets, jumping to pages | Inconsistent with changes |
+| Cursor | Large datasets, real-time | Can't jump to pages |
+| Keyset | Sorted data, performance | Complex implementation |
+
+**Recommendations:**
+
+- **Default**: Cursor pagination (more robust)
+- **Admin UIs**: Page pagination (users expect page numbers)
+- **Real-time feeds**: Cursor pagination (handles insertions)
+
+---
+
+## Completing the Discovery
+
+Once you've explored relevant areas, summarize:
+
+```markdown
+## API Conventions Summary
+
+Based on our conversation, here's what I understand:
+
+**API Style**: {choice}
+{brief rationale}
+
+**Versioning**: {choice}
+{brief rationale}
+
+**Response Format**: {choice}
+{brief rationale}
+
+**Error Format**: {choice}
+{brief rationale}
+
+**Pagination**: {choice}
+{brief rationale}
+
+---
+
+Does this capture your API conventions accurately? Any adjustments needed?
+```
+
+---
+
+## Output Generation
+
+After confirmation, create `standards/api-conventions.md`:
+
+```markdown
+# API Conventions
+
+## Overview
+{1-2 sentence summary of the API approach}
+
+## API Style
+{style}
+
+{Rationale - why this choice}
+
+## Versioning
+{strategy}
+
+{How versions will be handled}
+
+## Response Format
+
+### Success Response
+{standard structure}
+
+### Collection Response
+{standard structure with pagination}
+
+## Error Format
+{standard structure}
+
+### Error Codes
+{list of error codes used}
+
+## Pagination
+{strategy}
+
+{Implementation details}
+
+## Decision Relationships
+{Note connections to tech-stack and system-architecture decisions}
+```
+
+---
+
+## Notes for Agent
+
+- **Skip for frontend-only projects** - this guide is for projects with APIs
+- **Consistency is key** - pick a convention and stick to it
+- **Document everything** - API consumers rely on predictability
+- **Start simple** - don't over-engineer pagination for 100 items
+- **Capture rationale** - "why" is as important as "what"

package/flows/aidlc/templates/standards/system-architecture.guide.md

@@ -0,0 +1,268 @@
+# System Architecture Facilitation Guide
+
+## Purpose
+
+Define the high-level architectural patterns and system design choices that will guide how components are structured, how they communicate, and how the system scales.
+
+---
+
+## Facilitation Approach
+
+You are collaborating with a peer to discover their architectural preferences. This builds on tech-stack decisions and shapes how the application is structured.
+
+**Adapt your style:**
+
+- If they mention specific patterns confidently → treat them as experienced, be concise
+- If they seem uncertain → provide more context, examples, and recommendations
+- If they have strong preferences → respect them, ask about tradeoffs they've considered
+
+**Your role:**
+
+- Guide discovery, don't dictate choices
+- Surface tradeoffs they may not have considered
+- Ensure choices are coherent with tech-stack decisions
+- Capture rationale, not just the choice
+
+---
+
+## Discovery Areas
+
+### 1. Architecture Style
+
+**Goal**: Understand the overall application structure.
+
+**Open with context:**
+> "Let's talk about how you want to structure the application. This affects how code is organized, how components communicate, and how the system evolves over time."
+
+**Explore:**
+
+- Is this a monolith or do they need services?
+- What's the expected scale and team size?
+- How often do different parts of the system change?
+- Are there distinct bounded contexts?
+
+**Guide by context:**
+
+| Context | Recommendation | Why |
+|---------|----------------|-----|
+| Small team, MVP | Modular monolith | Simple deployment, easy refactoring |
+| Multiple teams | Microservices or modular monolith | Team autonomy, independent deployment |
+| Complex domains | Domain-Driven Design | Clear boundaries, ubiquitous language |
+| High performance | Event-driven | Async processing, decoupling |
+| Real-time features | Event-driven + WebSockets | Push updates, reactive |
+
+**Common patterns:**
+
+| Pattern | Best For | Tradeoffs |
+|---------|----------|-----------|
+| Layered (N-tier) | Traditional apps, CRUD | Can become rigid |
+| Clean/Hexagonal | Domain-heavy apps | More abstraction |
+| Microservices | Large teams, scale | Operational complexity |
+| Modular monolith | Growing apps | Discipline required |
+| Event-driven | Async, decoupling | Eventually consistent |
+| CQRS | Read/write asymmetry | Complexity |
+
+**Questions to surface tradeoffs:**
+
+- "Microservices add operational complexity. Is your team ready for that?"
+- "Event-driven means eventual consistency. Is that acceptable for your domain?"
+- "Clean architecture adds layers. Is the domain complex enough to warrant it?"
+
+---
+
+### 2. API Design
+
+**Goal**: Understand how components will communicate.
+
+**Optional - skip for CLI tools or libraries.**
+
+**Explore:**
+
+- What clients will consume the API? (Web, mobile, third-party)
+- Do they need real-time updates?
+- Is the API public or internal only?
+- What data shapes are typical? (CRUD, complex queries, mutations)
+
+**Guide by use case:**
+
+| Use Case | Recommendation | Why |
+|----------|----------------|-----|
+| Simple CRUD | REST | Well understood, tooling |
+| Complex queries | GraphQL | Flexible queries, single endpoint |
+| Real-time | WebSockets or SSE | Push updates |
+| Microservices | REST or gRPC | gRPC for internal, REST for external |
+| Public API | REST with OpenAPI | Documentation, client generation |
+
+**REST vs GraphQL:**
+
+- **REST**: Simpler, cacheable, well understood, better for public APIs
+- **GraphQL**: Flexible queries, avoids over-fetching, better for complex UIs
+
+---
+
+### 3. State Management
+
+**Goal**: Understand how application state is managed.
+
+**Explore:**
+
+- Where does state live? (Client, server, both)
+- How complex is the client state?
+- Do multiple components need the same data?
+- Is there optimistic UI or offline support?
+
+**For client-side (frontend):**
+
+| Solution | Best For | Tradeoffs |
+|----------|----------|-----------|
+| React Query/TanStack Query | Server state | Learning curve |
+| Zustand | Simple client state | Manual optimization |
+| Redux | Complex client state | Boilerplate |
+| Jotai/Recoil | Atomic state | Mental model shift |
+| URL state | Shareable UI state | Limited to serializable |
+
+**For server-side:**
+
+| Pattern | Best For |
+|---------|----------|
+| Session-based | Traditional web apps |
+| Stateless (JWT) | APIs, microservices |
+| Server state (tRPC, RSC) | Full-stack frameworks |
+
+---
+
+### 4. Caching Strategy
+
+**Goal**: Understand caching needs for performance.
+
+**Optional - some apps don't need explicit caching.**
+
+**Explore:**
+
+- What data is read frequently?
+- How fresh does data need to be?
+- What's the cache invalidation strategy?
+- Is there a CDN for static assets?
+
+**Caching layers:**
+
+| Layer | Tool | Use Case |
+|-------|------|----------|
+| Browser | HTTP headers | Static assets, API responses |
+| CDN | Cloudflare, Vercel Edge | Static assets, edge caching |
+| Application | Redis, in-memory | Session, computed data |
+| Database | Query cache | Repeated queries |
+
+**Questions:**
+
+- "How stale can data be before it's a problem?"
+- "What happens when cached data is wrong?"
+
+---
+
+### 5. Security Patterns
+
+**Goal**: Understand security architecture.
+
+**Explore:**
+
+- What needs to be protected? (Data, APIs, user sessions)
+- What's the threat model? (Public app, internal tool, regulated industry)
+- Any compliance requirements? (GDPR, HIPAA, SOC2)
+
+**Common patterns:**
+
+| Concern | Pattern | Implementation |
+|---------|---------|----------------|
+| API auth | Bearer tokens | JWT, API keys |
+| Session | HttpOnly cookies | Secure, SameSite |
+| Authorization | RBAC, ABAC | Role-based, attribute-based |
+| Data protection | Encryption at rest | Database encryption |
+| Input validation | Schema validation | Zod, Joi, class-validator |
+| CSRF | Tokens, SameSite | Framework-provided |
+
+**For Supabase users:**
+> "Supabase provides Row Level Security (RLS) which enforces authorization at the database level. This is powerful for multi-tenant apps."
+
+---
+
+## Completing the Discovery
+
+Once you've explored relevant areas, summarize:
+
+```markdown
+## System Architecture Summary
+
+Based on our conversation, here's what I understand:
+
+**Architecture Style**: {choice}
+{brief rationale}
+
+**API Design**: {choice or "REST by default"}
+{brief rationale}
+
+**State Management**: {choice or "TBD"}
+{brief rationale if applicable}
+
+**Caching Strategy**: {choice or "Standard HTTP caching"}
+{brief rationale if applicable}
+
+**Security Patterns**: {choice}
+{brief rationale}
+
+---
+
+Does this capture your architectural decisions accurately? Any adjustments needed?
+```
+
+---
+
+## Output Generation
+
+After confirmation, create `standards/system-architecture.md`:
+
+```markdown
+# System Architecture
+
+## Overview
+{1-2 sentence summary of the architectural approach}
+
+## Architecture Style
+{pattern}
+
+{Rationale - why this choice, what it enables}
+
+## API Design
+{approach}
+
+{Rationale - client needs, communication patterns}
+
+## State Management
+{approach or "TBD"}
+
+{Rationale if selected}
+
+## Caching Strategy
+{approach or "Standard HTTP caching"}
+
+{Rationale if selected}
+
+## Security Patterns
+{patterns in use}
+
+{Rationale - threat model, compliance}
+
+## Decision Relationships
+{Note connections to tech-stack decisions}
+```
+
+---
+
+## Notes for Agent
+
+- **Build on tech-stack** - reference decisions already made
+- **Don't over-architect** - simple apps don't need complex patterns
+- **Skip irrelevant decisions** - CLI tools don't need caching discussion
+- **Capture rationale** - "why" is as important as "what"
+- **It's okay to leave things TBD** - not every decision needs to be made upfront
+- **Watch for conflicts** - e.g., microservices with a solo dev team

package/flows/aidlc/templates/standards/ux-guide.guide.md

@@ -0,0 +1,231 @@
+# UX Guide Facilitation Guide
+
+## Purpose
+
+Define the UI/UX patterns, design system choices, and styling approach that will guide frontend development and ensure visual consistency across the application.
+
+---
+
+## Facilitation Approach
+
+You are collaborating with a peer to discover their UI/UX preferences. This is relevant for projects with a frontend component.
+
+**Adapt your style:**
+
+- If they have a design team → focus on technical implementation, not design decisions
+- If they're a solo dev → help them choose sensible defaults
+- If they have brand guidelines → ensure choices align with brand
+
+**Your role:**
+
+- Guide discovery, don't dictate choices
+- Surface tradeoffs between flexibility and consistency
+- Ensure choices work with their tech stack
+- Capture rationale, not just the choice
+
+---
+
+## Discovery Areas
+
+### 1. Design System / Component Library
+
+**Goal**: Understand how UI components will be built.
+
+**Open with context:**
+> "Let's talk about your component strategy. This affects development speed, visual consistency, and how much custom design work is needed."
+
+**Explore:**
+
+- Do they have existing brand guidelines or a design system?
+- Is there a designer on the team?
+- How custom does the UI need to be?
+- What's the priority: speed or uniqueness?
+
+**Guide by context:**
+
+| Context | Recommendation | Why |
+|---------|----------------|-----|
+| MVP, speed priority | shadcn/ui + Tailwind | Fast, customizable |
+| Design team, custom brand | Headless (Radix, Headless UI) | Full control |
+| Enterprise app | MUI or Ant Design | Comprehensive, consistent |
+| Marketing site | Tailwind + custom | Brand flexibility |
+| Internal tool | shadcn/ui or Chakra | Good defaults, fast |
+
+**Component library options:**
+
+| Library | Best For | Tradeoffs |
+|---------|----------|-----------|
+| shadcn/ui | Customization, ownership | Copy-paste, maintain yourself |
+| Radix UI | Headless, accessible | Need to style everything |
+| Headless UI | Tailwind users | Limited components |
+| MUI | Enterprise, comprehensive | Opinionated styling |
+| Chakra UI | Quick prototyping | Bundle size |
+| Ant Design | Data-heavy apps | Opinionated, large |
+
+**Questions to surface tradeoffs:**
+
+- "shadcn/ui gives you ownership but means maintaining components. Is that okay?"
+- "MUI is comprehensive but has a specific look. Can you customize enough?"
+- "Headless means more styling work. Do you have the time for that?"
+
+---
+
+### 2. Styling Approach
+
+**Goal**: Understand how styles will be written.
+
+**Explore:**
+
+- What's the team's CSS experience?
+- Do they need design tokens / theming?
+- Is dark mode needed?
+- How important is bundle size?
+
+**Options:**
+
+| Approach | Best For | Tradeoffs |
+|----------|----------|-----------|
+| Tailwind CSS | Utility-first, rapid development | Learning curve, verbose markup |
+| CSS Modules | Scoped styles, traditional CSS | More files |
+| Styled Components | CSS-in-JS, dynamic styles | Runtime cost |
+| Vanilla Extract | Type-safe CSS, zero runtime | Build complexity |
+| Plain CSS/SCSS | Simple projects | Global scope issues |
+
+**Tailwind + shadcn/ui is the modern default:**
+> "Most projects today use Tailwind CSS with a component library like shadcn/ui. It's fast, customizable, and has great tooling. Unless you have a specific reason to choose something else, this is a solid default."
+
+---
+
+### 3. Accessibility Standards
+
+**Goal**: Understand accessibility requirements.
+
+**Explore:**
+
+- Is there a compliance requirement? (WCAG 2.1, Section 508)
+- Who are the users? (General public, enterprise, specific needs)
+- Is this a public-facing or internal app?
+
+**Levels:**
+
+| Level | Requirement | Typical For |
+|-------|-------------|-------------|
+| Minimum | Semantic HTML, keyboard nav | All apps |
+| WCAG 2.1 AA | Color contrast, focus indicators | Public apps |
+| WCAG 2.1 AAA | Enhanced contrast, alternatives | Government, healthcare |
+
+**Recommendations:**
+
+- Use semantic HTML elements (`button`, `nav`, `main`)
+- Ensure keyboard navigation works
+- Use ARIA labels where needed
+- Test with screen readers
+- Use accessible component libraries (Radix, shadcn/ui)
+
+> "Most component libraries like shadcn/ui and Radix are built with accessibility in mind. Using them gets you 80% of the way there."
+
+---
+
+### 4. Responsive Design Strategy
+
+**Goal**: Understand how the app should adapt to different screen sizes.
+
+**Explore:**
+
+- What devices will users be on? (Desktop, tablet, mobile)
+- Is this mobile-first or desktop-first?
+- Are there specific breakpoints needed?
+- Is a native mobile app planned? (Affects responsive priority)
+
+**Strategies:**
+
+| Strategy | Best For |
+|----------|----------|
+| Mobile-first | Consumer apps, wide audience |
+| Desktop-first | Admin tools, data-heavy apps |
+| Responsive | All screen sizes matter equally |
+| Adaptive | Different layouts per device |
+
+**Tailwind breakpoints (default):**
+
+```
+sm: 640px   - Small devices
+md: 768px   - Tablets
+lg: 1024px  - Laptops
+xl: 1280px  - Desktops
+2xl: 1536px - Large screens
+```
+
+---
+
+## Completing the Discovery
+
+Once you've explored relevant areas, summarize:
+
+```markdown
+## UX Guide Summary
+
+Based on our conversation, here's what I understand:
+
+**Design System**: {choice}
+{brief rationale}
+
+**Styling Approach**: {choice}
+{brief rationale}
+
+**Accessibility**: {level}
+{brief rationale}
+
+**Responsive Strategy**: {choice}
+{brief rationale}
+
+---
+
+Does this capture your UI/UX decisions accurately? Any adjustments needed?
+```
+
+---
+
+## Output Generation
+
+After confirmation, create `standards/ux-guide.md`:
+
+```markdown
+# UX Guide
+
+## Overview
+{1-2 sentence summary of the UI/UX approach}
+
+## Design System / Component Library
+{library}
+
+{Rationale - why this choice, what it enables}
+
+## Styling Approach
+{approach}
+
+{Rationale - team experience, requirements}
+
+## Accessibility Standards
+{level}
+
+{Requirements to follow}
+
+## Responsive Design Strategy
+{strategy}
+
+{Breakpoints and approach}
+
+## Decision Relationships
+{Note connections to tech-stack decisions}
+```
+
+---
+
+## Notes for Agent
+
+- **Skip for backend-only projects** - this guide is for projects with frontends
+- **Respect designer decisions** - if there's a design team, defer to them
+- **Default to modern stack** - Tailwind + shadcn/ui is a good default
+- **Accessibility isn't optional** - even MVPs should have basic accessibility
+- **Capture rationale** - "why" is as important as "what"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-iris",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {