project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/004-standards-system/units/facilitation-guides/unit-brief.md

@@ -0,0 +1,250 @@
+# Unit Brief: Facilitation Guides
+
+## Overview
+
+Facilitation Guides are markdown files that instruct the Master Agent on HOW to have a conversation with the user to gather decisions for each standard. They provide question strategies, recommendations, tradeoff explanations, and adaptive communication styles.
+
+---
+
+## Scope
+
+### In Scope
+
+- Conversational prompts for each decision area
+- Recommendations by use case
+- Tradeoff explanations
+- Adaptive communication strategies
+- Validation questions
+- Summary templates
+
+### Out of Scope
+
+- What decisions exist (handled by standards-catalog)
+- Output format (handled by standards-templates)
+
+---
+
+## Technical Context
+
+### File Location
+
+`.irismd/aidlc/templates/standards/{standard-id}.guide.md`
+
+### Available Guides
+
+- `tech-stack.guide.md`
+- `coding-standards.guide.md`
+- `system-architecture.guide.md`
+- `ux-guide.guide.md`
+- `api-conventions.guide.md`
+
+---
+
+## Implementation Details
+
+### Guide Structure
+
+Every facilitation guide follows this structure:
+
+```markdown
+# {Standard Name} Facilitation Guide
+
+## Purpose
+{Why this standard matters to the project}
+
+---
+
+## Facilitation Approach
+
+{How to adapt to user's expertise level}
+
+**Adapt your style:**
+- If they mention specific technologies confidently → be concise
+- If they seem uncertain → provide more context, examples
+- If they have strong preferences → respect them, ask about tradeoffs
+
+**Your role:**
+- Guide discovery, don't dictate choices
+- Surface tradeoffs they may not have considered
+- Ensure choices are coherent (no conflicting technologies)
+- Capture rationale, not just the choice
+
+---
+
+## Discovery Areas
+
+### 1. {Decision Area Name}
+
+**Goal**: {What we're trying to understand}
+
+**Open with context:**
+> "{Contextual statement about why this matters}"
+
+**Explore:**
+- {Question 1}
+- {Question 2}
+- {Question 3}
+
+**If they're unsure, guide by use case:**
+
+| Use Case | Recommendation | Why |
+|----------|----------------|-----|
+| {case 1} | {recommendation} | {rationale} |
+| {case 2} | {recommendation} | {rationale} |
+
+**Common signals to listen for:**
+- "{signal}" → {interpretation}
+
+**Validate before moving on:**
+> "So we're going with {choice}. This means {implication}. Sound right?"
+
+---
+
+### 2. {Next Decision Area}
+{Same structure...}
+
+---
+
+## Completing the Discovery
+
+Once you've explored all relevant areas, summarize:
+
+```markdown
+## {Standard Name} Summary
+
+Based on our conversation, here's what I understand:
+
+**{Decision 1}**: {choice}
+{brief rationale}
+
+**{Decision 2}**: {choice}
+{brief rationale}
+
+...
+
+Does this capture your choices accurately? Any adjustments needed?
+```
+
+---
+
+## Output Generation
+
+After confirmation, create `standards/{output-file}.md`:
+
+{Template for final output}
+
+---
+
+## Notes for Agent
+
+- Don't ask all questions linearly - adapt based on context
+- Skip irrelevant decisions - CLI tools don't need UI discussion
+- Capture rationale - "why" is as important as "what"
+- Respect existing choices - don't second-guess without reason
+- It's okay to leave things TBD - not every decision needed upfront
+
+```markdown
+
+### Example: Tech Stack Guide Excerpt
+
+```markdown
+### 1. Languages
+
+**Goal**: Understand what programming language(s) they'll use.
+
+**Open with context:**
+> "Let's start with languages. This affects everything else -
+> framework options, available libraries, team hiring, and
+> performance characteristics."
+
+**Explore:**
+- What languages is the team already comfortable with?
+- Is type safety important?
+- What's the runtime environment? (Browser, Node.js, Edge, Native)
+- Any organizational standards or constraints?
+
+**If they're unsure, guide by use case:**
+
+| Use Case | Recommendation | Why |
+|----------|----------------|-----|
+| Web app (full-stack) | TypeScript | Type safety, React/Next.js ecosystem |
+| API service | TypeScript or Go | TS for ecosystem, Go for performance |
+| ML/AI/Data | Python | Libraries (PyTorch, pandas) |
+| High-performance | Go or Rust | Go for simplicity, Rust for safety |
+| Scripts/automation | Python or TypeScript | Readability, quick iteration |
+
+**Common signals:**
+- "We're a React shop" → TypeScript
+- "We do ML/AI" → Python, possibly with TypeScript frontend
+- "Performance is critical" → Go, Rust, or optimized Node.js
+
+**Validate:**
+> "So we're going with {language}. This means {implication}. Sound right?"
+```
+
+### Adaptive Communication
+
+The guide instructs the agent to adapt based on signals:
+
+**Expert signals** (be concise):
+
+- Mentions specific versions ("Node 20", "React 18")
+- Uses technical jargon correctly
+- States preferences with confidence
+- Knows about tradeoffs
+
+**Beginner signals** (provide context):
+
+- Asks "what's the difference between..."
+- Says "I've heard of X but..."
+- Uncertain language ("maybe", "I think")
+- No strong preferences
+
+**Opinionated signals** (respect, probe):
+
+- "We always use X"
+- Strong negative reactions to suggestions
+- Mentions past experiences
+
+---
+
+## Key Facilitation Principles
+
+1. **Discovery over forms**: Have a conversation, don't fill out a checklist
+2. **Rationale over choices**: Capture WHY not just WHAT
+3. **Coherence over completeness**: Ensure choices work together
+4. **Adaptability**: Adjust depth based on user expertise
+5. **Respect agency**: User makes final decisions
+6. **Allow TBD**: Not everything needs answering now
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Guide Loading
+
+- GIVEN Master Agent facilitating tech-stack
+- WHEN guide is loaded
+- THEN all decision areas are available
+- AND recommendations are context-appropriate
+
+### AC-2: Adaptive Communication
+
+- GIVEN user says "We're a TypeScript shop"
+- WHEN agent continues facilitation
+- THEN agent skips basic language explanation
+- AND focuses on framework selection
+
+### AC-3: Tradeoff Surfacing
+
+- GIVEN user selects Next.js
+- WHEN agent validates choice
+- THEN agent mentions React lock-in
+- AND confirms user is comfortable with implication
+
+### AC-4: Summary Generation
+
+- GIVEN all decisions made
+- WHEN facilitation completes
+- THEN summary includes all choices with rationale
+- AND user can request adjustments

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/004-standards-system/units/standards-catalog/unit-brief.md

@@ -0,0 +1,355 @@
+# Unit Brief: Standards Catalog
+
+## Overview
+
+The Standards Catalog is a YAML configuration file that defines all available project standards, their decisions, dependencies, and project type presets. It serves as the registry that tells the Master Agent what standards exist and what decisions need to be made.
+
+---
+
+## Scope
+
+### In Scope
+
+- Standard definitions (id, description, importance)
+- Decision definitions within each standard
+- Decision dependencies and ordering
+- Project type presets
+- Standard inter-dependencies
+
+### Out of Scope
+
+- How to facilitate decisions (handled by facilitation-guides)
+- Output format (handled by standards-templates)
+
+---
+
+## Technical Context
+
+### File Location
+
+`.irismd/aidlc/templates/standards/catalog.yaml`
+
+---
+
+## Implementation Details
+
+### Full Catalog Schema
+
+```yaml
+# Standards Catalog
+# Defines what standards exist, their decisions, and relationships
+
+standards:
+  tech-stack:
+    description: Technology choices for the project
+    facilitation: templates/standards/tech-stack.guide.md
+    output_path: standards/tech-stack.md
+    importance: critical
+    sections:
+      - header: Overview
+        type: static
+        content: "Core technology decisions for this project."
+      - type: from_decisions
+    decisions:
+      - id: languages
+        display_name: Languages
+        category: core
+        importance: critical
+        depends_on: []
+
+      - id: framework
+        display_name: Framework
+        category: core
+        importance: critical
+        depends_on: [languages]
+
+      - id: database
+        display_name: Database
+        category: data
+        importance: high
+        optional: true
+        depends_on: [languages]
+
+      - id: orm
+        display_name: ORM / Database Client
+        category: data
+        importance: medium
+        optional: true
+        depends_on: [database, languages]
+
+      - id: authentication
+        display_name: Authentication
+        category: security
+        importance: high
+        optional: true
+        depends_on: [framework]
+
+      - id: infrastructure
+        display_name: Infrastructure & Deployment
+        category: deployment
+        importance: high
+        depends_on: [framework]
+
+      - id: package_manager
+        display_name: Package Manager
+        category: tooling
+        importance: medium
+        depends_on: [languages]
+
+  coding-standards:
+    description: Code style, patterns, and quality standards
+    facilitation: templates/standards/coding-standards.guide.md
+    output_path: standards/coding-standards.md
+    importance: critical
+    depends_on_standards: [tech-stack]
+    decisions:
+      - id: formatting
+        display_name: Code Formatting
+        category: style
+        importance: high
+
+      - id: linting
+        display_name: Linting Rules
+        category: quality
+        importance: high
+
+      - id: naming_conventions
+        display_name: Naming Conventions
+        category: style
+        importance: high
+
+      - id: file_organization
+        display_name: File & Folder Organization
+        category: structure
+        importance: high
+
+      - id: testing_strategy
+        display_name: Testing Strategy
+        category: quality
+        importance: critical
+
+      - id: error_handling
+        display_name: Error Handling Patterns
+        category: patterns
+        importance: high
+
+      - id: logging
+        display_name: Logging Standards
+        category: observability
+        importance: medium
+
+  system-architecture:
+    description: High-level system design and architectural patterns
+    facilitation: templates/standards/system-architecture.guide.md
+    output_path: standards/system-architecture.md
+    importance: high
+    optional: true
+    depends_on_standards: [tech-stack]
+    decisions:
+      - id: architecture_style
+        display_name: Architecture Style
+        category: structure
+        importance: critical
+
+      - id: api_design
+        display_name: API Design
+        category: communication
+        importance: high
+        optional: true
+
+      - id: state_management
+        display_name: State Management
+        category: data
+        importance: high
+        optional: true
+
+      - id: caching_strategy
+        display_name: Caching Strategy
+        category: performance
+        importance: medium
+        optional: true
+
+      - id: security_patterns
+        display_name: Security Patterns
+        category: security
+        importance: high
+
+  ux-guide:
+    description: UI/UX patterns and design system choices
+    facilitation: templates/standards/ux-guide.guide.md
+    output_path: standards/ux-guide.md
+    importance: medium
+    optional: true
+    depends_on_standards: [tech-stack]
+    decisions:
+      - id: design_system
+        display_name: Design System / Component Library
+        category: ui
+        importance: high
+
+      - id: styling_approach
+        display_name: Styling Approach
+        category: ui
+        importance: high
+
+      - id: accessibility
+        display_name: Accessibility Standards
+        category: compliance
+        importance: high
+
+      - id: responsive_strategy
+        display_name: Responsive Design Strategy
+        category: ui
+        importance: medium
+
+  api-conventions:
+    description: API design conventions and standards
+    facilitation: templates/standards/api-conventions.guide.md
+    output_path: standards/api-conventions.md
+    importance: medium
+    optional: true
+    depends_on_standards: [tech-stack]
+    decisions:
+      - id: api_style
+        display_name: API Style
+        category: design
+        importance: critical
+
+      - id: versioning
+        display_name: API Versioning
+        category: design
+        importance: medium
+
+      - id: response_format
+        display_name: Response Format
+        category: format
+        importance: high
+
+      - id: error_format
+        display_name: Error Response Format
+        category: format
+        importance: high
+
+      - id: pagination
+        display_name: Pagination Strategy
+        category: design
+        importance: medium
+        optional: true
+
+# Project type presets
+project_types:
+  full-stack-web:
+    description: Full-stack web application
+    required_standards:
+      - tech-stack
+      - coding-standards
+    recommended_standards:
+      - system-architecture
+      - ux-guide
+      - api-conventions
+
+  backend-api:
+    description: Backend API service
+    required_standards:
+      - tech-stack
+      - coding-standards
+    recommended_standards:
+      - system-architecture
+      - api-conventions
+
+  frontend-app:
+    description: Frontend application (SPA/SSR)
+    required_standards:
+      - tech-stack
+      - coding-standards
+    recommended_standards:
+      - ux-guide
+
+  cli-tool:
+    description: Command-line tool
+    required_standards:
+      - tech-stack
+      - coding-standards
+    recommended_standards: []
+
+  library:
+    description: Reusable library/package
+    required_standards:
+      - tech-stack
+      - coding-standards
+    recommended_standards:
+      - api-conventions
+```
+
+### Standard Definition Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `description` | string | Yes | Human-readable description |
+| `facilitation` | string | Yes | Path to facilitation guide |
+| `output_path` | string | Yes | Where to write generated standard |
+| `importance` | enum | Yes | critical, high, medium |
+| `optional` | boolean | No | If true, can be skipped |
+| `depends_on_standards` | array | No | Standards that must be completed first |
+| `sections` | array | No | Output structure definition |
+| `decisions` | array | Yes | List of decisions in this standard |
+
+### Decision Definition Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Unique identifier (snake_case) |
+| `display_name` | string | Yes | Human-readable name |
+| `category` | string | Yes | Grouping category |
+| `importance` | enum | Yes | critical, high, medium |
+| `optional` | boolean | No | If true, can be skipped |
+| `depends_on` | array | No | Decision IDs that must be answered first |
+
+### Project Type Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `description` | string | Yes | Project type description |
+| `required_standards` | array | Yes | Standards that must be created |
+| `recommended_standards` | array | Yes | Optional but suggested standards |
+
+---
+
+## Decision Ordering
+
+Decisions are processed in dependency order:
+
+```text
+1. Languages (no dependencies)
+2. Framework (depends on: languages)
+3. Package Manager (depends on: languages)
+4. Database (depends on: languages)
+5. ORM (depends on: database, languages)
+6. Authentication (depends on: framework)
+7. Infrastructure (depends on: framework)
+```
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Standard Discovery
+
+- GIVEN Master Agent runs project-init
+- WHEN catalog.yaml is read
+- THEN all standards are available for selection
+- AND importance levels are respected
+
+### AC-2: Decision Dependencies
+
+- GIVEN tech-stack standard being facilitated
+- WHEN framework decision is reached
+- THEN languages decision has already been made
+- AND framework options are filtered by language
+
+### AC-3: Project Type Preset
+
+- GIVEN user selects "backend-api" project type
+- WHEN standards are determined
+- THEN tech-stack and coding-standards are required
+- AND system-architecture and api-conventions are recommended