project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/standards/system-architecture.md

@@ -0,0 +1,177 @@
+# System Architecture
+
+High-level architectural patterns and design decisions for irismd.
+
+---
+
+## Architecture Style
+
+### Multi-Agent Orchestration
+
+irismd implements a multi-agent architecture where specialized AI agents collaborate through a shared Memory Bank.
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│                    User (AI-Native Engineer)            │
+└───────────────────────────┬─────────────────────────────┘
+                            │ Slash Commands
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│              Agentic Coding Tool Layer                  │
+│         (Claude Code / Cursor / GitHub Copilot)         │
+└───────────────────────────┬─────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                   Agent Layer                           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
+│  │  Master  │  │Inception │  │Construct.│  │   Ops   │ │
+│  │  Agent   │  │  Agent   │  │  Agent   │  │  Agent  │ │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
+│       │             │             │             │       │
+│       └─────────────┴──────┬──────┴─────────────┘       │
+│                            │ Skills                     │
+└────────────────────────────┼────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────┐
+│                   Memory Bank (File System)             │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌───────────┐  │
+│  │ Intents │  │  Units  │  │  Bolts  │  │ Standards │  │
+│  └─────────┘  └─────────┘  └─────────┘  └───────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Component Architecture
+
+### Agents
+
+- **Stateless**: Each invocation starts fresh
+- **Context-Aware**: Read Memory Bank on activation
+- **Skill-Based**: Execute focused skills for specific tasks
+- **Human-Validated**: Request approval at decision points
+
+### Skills
+
+- **Single Responsibility**: One skill = one capability
+- **Template-Driven**: Use templates for artifact generation
+- **Composable**: Skills can reference other skills
+
+### Memory Bank
+
+- **File-Based**: No database, pure filesystem
+- **Markdown-First**: All artifacts are markdown
+- **Schema-Defined**: Structure defined in `memory-bank.yaml`
+- **Git-Friendly**: Version controllable
+
+### Installers
+
+- **Factory Pattern**: `InstallerFactory` creates tool-specific installers
+- **Interface-Based**: All installers extend `ToolInstaller` base class
+- **Pluggable**: New tools can be added via new installer class
+
+---
+
+## State Management
+
+### No Global State
+
+- Agents are stateless
+- All state persisted in Memory Bank
+- Fresh context loaded on each invocation
+
+### Artifact-Based State
+
+```text
+Project State = f(Memory Bank Artifacts)
+
+Current Phase = determined by:
+  - Existence of intents → Inception started
+  - Existence of units with stories → Inception progressing
+  - Existence of bolts → Construction started
+  - Bolt completion status → Operations ready
+```
+
+---
+
+## Security Patterns
+
+### No Secrets in Memory Bank
+
+- Memory Bank contains only project artifacts
+- No credentials, tokens, or sensitive data
+- All files safe to commit to git
+
+### Human Oversight
+
+- All significant actions require human approval
+- Validation points at phase boundaries
+- No autonomous code deployment
+
+---
+
+## API Design
+
+### Slash Command Interface
+
+- Entry point for all agent interactions
+- Parameters via `--param="value"` format
+- Optional parameters have defaults
+
+### Skill Interface
+
+- Input: Context from Memory Bank + user request
+- Process: Defined workflow steps
+- Output: Artifacts written to Memory Bank
+
+---
+
+## Deployment Architecture
+
+### Distribution: npm Package
+
+```bash
+npx irismd install
+```
+
+### Installation Targets
+
+```text
+Project Root/
+├── .irismd/           # irismd runtime
+│   ├── skills/
+│   ├── templates/
+│   └── memory-bank.yaml
+├── .claude/commands/   # Claude Code commands
+├── .cursor/commands/   # Cursor commands
+├── .github/copilot/commands/  # Copilot commands
+└── memory-bank/        # Project artifacts
+```
+
+---
+
+## Caching Strategy
+
+### No Caching Required
+
+- File-based storage eliminates caching needs
+- Each agent invocation reads fresh state
+- Filesystem provides inherent caching
+
+---
+
+## Error Handling Patterns
+
+### Graceful Degradation
+
+- Missing directories created automatically
+- Missing templates produce helpful errors
+- Partial artifacts saved on interruption
+
+### User-Friendly Errors
+
+- Technical errors translated to actionable messages
+- Clear next steps provided
+- No stack traces in production output

package/src/iris_bundle/frameworks/iris-core/memory-bank/standards/tech-stack.md

@@ -0,0 +1,88 @@
+# Tech Stack
+
+Technology choices for irismd.
+
+---
+
+## Languages
+
+### Primary Language: JavaScript (Node.js)
+
+**Rationale**: Node.js provides cross-platform compatibility, excellent CLI tooling support via Commander.js, and seamless npm distribution.
+
+**Version**: Node.js 18+
+
+---
+
+## Framework
+
+### CLI Framework: Commander.js
+
+**Rationale**: Industry-standard CLI framework for Node.js with excellent argument parsing, help generation, and subcommand support.
+
+---
+
+## UI Libraries
+
+### Terminal UI
+
+- **chalk** - Terminal string styling
+- **figlet** - ASCII art text generation
+- **gradient-string** - Color gradients for terminal
+- **inquirer** - Interactive command line prompts
+
+**Rationale**: These libraries provide rich, colorful CLI experiences that make installation feel polished.
+
+---
+
+## File System
+
+### fs-extra
+
+**Rationale**: Extended file system methods (copy, move, mkdirp) that simplify installer operations.
+
+---
+
+## Configuration
+
+### YAML (js-yaml)
+
+**Rationale**: Human-readable configuration format for memory-bank schema, standards catalog, and manifests. Widely adopted in DevOps tooling.
+
+---
+
+## Package Management
+
+### npm
+
+**Rationale**: Standard Node.js package manager. Supports `npx` for zero-install execution.
+
+---
+
+## Distribution
+
+### npm Registry
+
+**Rationale**: Primary distribution channel for Node.js tools. Enables `npx irismd install` pattern.
+
+---
+
+## Build & Tooling
+
+### None Required
+
+**Rationale**: Pure JavaScript with no transpilation needed. Keeps the project simple and reduces dependencies.
+
+---
+
+## Summary
+
+| Category | Choice | Version |
+|----------|--------|---------|
+| Runtime | Node.js | 18+ |
+| CLI Framework | Commander.js | Latest |
+| Terminal UI | chalk, figlet, gradient-string, inquirer | Latest |
+| File System | fs-extra | Latest |
+| Configuration | js-yaml | Latest |
+| Package Manager | npm | Latest |
+| Distribution | npm Registry | - |

package/src/iris_bundle/frameworks/iris-core/memory-bank/story-index.md

@@ -0,0 +1,154 @@
+# Story Index
+
+Global index of all stories across intents and units.
+
+---
+
+## 001-multi-agent-orchestration
+
+> **Pre-irismd**: Implemented before dogfooding. Stories not tracked in AI-DLC.
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| master-agent | — | ✅ Complete (pre-irismd) |
+| inception-agent | — | ✅ Complete (pre-irismd) |
+| construction-agent | — | ✅ Complete (pre-irismd) |
+| operations-agent | — | ✅ Complete (pre-irismd) |
+
+---
+
+## 002-agentic-coding-tool-integration
+
+> **Pre-irismd**: Implemented before dogfooding. Stories not tracked in AI-DLC.
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| installer-core | — | ✅ Complete (pre-irismd) |
+| cursor-installer | — | ✅ Complete (pre-irismd) |
+| claude-code-installer | — | ✅ Complete (pre-irismd) |
+| copilot-installer | — | ✅ Complete (pre-irismd) |
+| windsurf-installer | — | ✅ Complete (pre-irismd) |
+| cline-installer | — | ✅ Complete (pre-irismd) |
+| roo-installer | — | ✅ Complete (pre-irismd) |
+| kilo-installer | — | ✅ Complete (pre-irismd) |
+| kiro-installer | — | ✅ Complete (pre-irismd) |
+| gemini-installer | — | ✅ Complete (pre-irismd) |
+| codex-installer | — | ✅ Complete (pre-irismd) |
+| antigravity-installer | — | ✅ Complete (pre-irismd) |
+| opencode-installer | — | ✅ Complete (pre-irismd) |
+
+---
+
+## 003-memory-bank-system
+
+> **Pre-irismd**: Implemented before dogfooding. Stories not tracked in AI-DLC.
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| configuration-schema | — | ✅ Complete (pre-irismd) |
+| context-loader | — | ✅ Complete (pre-irismd) |
+| artifact-storage | — | ✅ Complete (pre-irismd) |
+
+---
+
+## 004-standards-system
+
+> **Pre-irismd**: Implemented before dogfooding. Stories not tracked in AI-DLC.
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| standards-catalog | — | ✅ Complete (pre-irismd) |
+| facilitation-guides | — | ✅ Complete (pre-irismd) |
+| standards-templates | — | ✅ Complete (pre-irismd) |
+
+---
+
+## 005-testing-strategy
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| 01-specification-contract-testing | TBD | Pending |
+| 02-cli-installer-testing | TBD | Pending |
+| 03-golden-dataset-management | TBD | Pending |
+| 04-agent-behavior-evaluation | TBD | Pending |
+| 05-cicd-integration | TBD | Pending |
+
+---
+
+## 006-brownfield-support
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| (units not yet defined) | TBD | Pending |
+
+---
+
+## 007-installer-analytics
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| 001-analytics-tracker | 6 stories | Ready for Construction |
+| 002-privacy-documentation | 2 stories | 1 Complete, 1 Ready |
+
+### 001-analytics-tracker
+
+| Story | Title | Priority | Status |
+|-------|-------|----------|--------|
+| 001-initialize-mixpanel.md | Initialize Mixpanel with machine and session IDs | Must | Ready |
+| 002-detect-shell.md | Detect shell environment | Must | Ready |
+| 003-check-telemetry-disabled.md | Check if telemetry is disabled | Must | Ready |
+| 004-track-installer-events.md | Track installer lifecycle events | Must | Ready |
+| 005-track-selection-events.md | Track IDE and flow selection events | Must | Ready |
+| 006-cli-no-telemetry-flag.md | Support --no-telemetry CLI flag | Should | Ready |
+
+### 002-privacy-documentation
+
+| Story | Title | Priority | Status |
+|-------|-------|----------|--------|
+| 001-create-privacy-md.md | Create PRIVACY.md with data disclosure | Must | ✅ Complete |
+| 002-add-readme-section.md | Add analytics section to README | Must | Ready |
+
+---
+
+## 008-terminal-dashboard
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| (units not yet defined) | TBD | Pending |
+
+---
+
+## 009-versioning-strategy
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| (units not yet defined) | TBD | Pending |
+
+---
+
+## 010-smart-unit-decomposition
+
+| Unit | Stories | Status |
+|------|---------|--------|
+| (see units.md for planned units) | TBD | Pending |
+
+---
+
+## Summary
+
+| Intent | Units | Stories | Status |
+|--------|-------|---------|--------|
+| 001-multi-agent-orchestration | 4 | — | ✅ Complete (pre-irismd) |
+| 002-agentic-coding-tool-integration | 13 | — | ✅ Complete (pre-irismd) |
+| 003-memory-bank-system | 3 | — | ✅ Complete (pre-irismd) |
+| 004-standards-system | 3 | — | ✅ Complete (pre-irismd) |
+| 005-testing-strategy | 5 | 0 | Pending |
+| 006-brownfield-support | 0 | 0 | Pending |
+| 007-installer-analytics | 2 | 8 | Ready for Construction |
+| 008-terminal-dashboard | 0 | 0 | Pending |
+| 009-versioning-strategy | 0 | 0 | Pending |
+| 010-smart-unit-decomposition | 0 | 0 | Pending |
+
+---
+
+*Note: Intents 001-004 were implemented before irismd dogfooding began. Stories for remaining intents will be defined during Inception phase.*

package/src/iris_bundle/frameworks/iris-core/memory-bank/term-mappings.md

@@ -0,0 +1,121 @@
+# Term Mappings
+
+Mapping between AI-DLC terminology and traditional Agile/Scrum terminology.
+
+---
+
+## AI-DLC ↔ Agile/Scrum
+
+| AI-DLC Term | Agile/Scrum Equivalent | Key Difference |
+|-------------|------------------------|----------------|
+| **Intent** | Epic / Initiative | Intent is AI's starting point for decomposition |
+| **Unit** | Epic / Subdomain | Units are loosely coupled for independent deployment |
+| **Bolt** | Sprint | Bolts are hours/days, not weeks |
+| **User Story** | User Story | Same concept, retained for familiarity |
+| **Acceptance Criteria** | Acceptance Criteria | Same concept |
+| **Mob Elaboration** | Sprint Planning / Backlog Refinement | Single room, AI-led, condenses weeks into hours |
+| **Mob Construction** | Pair Programming / Mob Programming | Teams collocated, AI assists |
+| **Domain Design** | (DDD) Domain Modeling | Integrated into methodology, not optional |
+| **Logical Design** | Architecture / Technical Design | AI recommends patterns, humans validate |
+| **Deployment Unit** | Release / Deployable | Packaged, tested artifacts |
+| **Memory Bank** | (None) | File-based artifact storage for AI context |
+
+---
+
+## AI-DLC ↔ DDD (Domain-Driven Design)
+
+| AI-DLC Term | DDD Equivalent | Notes |
+|-------------|----------------|-------|
+| **Intent** | Business Capability | High-level goal |
+| **Unit** | Subdomain / Bounded Context | Cohesive, loosely coupled |
+| **Domain Design** | Strategic + Tactical Design | Aggregates, entities, value objects |
+| **Logical Design** | Application/Infrastructure Layer | Patterns, services, repositories |
+
+---
+
+## Phases Comparison
+
+| AI-DLC Phase | Agile Equivalent | Notes |
+|--------------|------------------|-------|
+| **Inception** | Discovery / Sprint 0 / Planning | AI elaborates, humans validate |
+| **Construction** | Sprint Execution | Rapid bolts, DDD stages |
+| **Operations** | Release / Support | Deployment, monitoring |
+
+---
+
+## Rituals Comparison
+
+| AI-DLC Ritual | Agile Ritual | Notes |
+|---------------|--------------|-------|
+| **Mob Elaboration** | Sprint Planning + Refinement | AI proposes, mob refines |
+| **Mob Construction** | Sprint Execution + Standups | Continuous, not daily |
+| **(None)** | Daily Standup | Not needed with rapid cycles |
+| **(None)** | Retrospective | Not needed with rapid cycles |
+
+---
+
+## Roles Comparison
+
+| AI-DLC Role | Agile Role | Notes |
+|-------------|------------|-------|
+| **Developer** | Developer | Validates AI output, makes decisions |
+| **Product Owner** | Product Owner | Same concept |
+| **AI Agent** | (None) | New role - drives workflow |
+| **(None)** | Scrum Master | Not needed - AI orchestrates |
+
+---
+
+## Artifacts Comparison
+
+| AI-DLC Artifact | Agile Equivalent | Notes |
+|-----------------|------------------|-------|
+| **Intent** | Epic | Starting point |
+| **Requirements (FR/NFR)** | Product Backlog Items | Structured capture |
+| **System Context** | Architecture Overview | Boundaries, actors |
+| **Unit** | Epic breakdown | Deployment-focused |
+| **User Story** | User Story | Same format |
+| **Bolt Plan** | Sprint Backlog | Hours/days scope |
+| **Domain Design** | (None standard) | DDD integrated |
+| **Logical Design** | Technical Spec | Patterns, ADRs |
+| **PRFAQ** | Product Vision | Press release format |
+| **Risk Register** | Risk Log | Mapped to org framework |
+
+---
+
+## Key Conceptual Differences
+
+### Iteration Duration
+
+- **Agile**: Weeks (2-4 week sprints)
+- **AI-DLC**: Hours or days (bolts)
+
+### Driver
+
+- **Agile**: Human-driven (developers lead)
+- **AI-DLC**: AI-driven (AI proposes, humans validate)
+
+### Design Integration
+
+- **Agile**: Design techniques out of scope
+- **AI-DLC**: DDD, TDD, BDD integrated into core
+
+### Phase Structure
+
+- **Agile**: Iterative sprints with fixed duration
+- **AI-DLC**: Inherently iterative with three phases (Inception, Construction, Operations) allowing continuous refinement and adaptation
+
+### Estimation
+
+- **Agile**: Story points, velocity, day-based estimates
+- **AI-DLC**: Dual estimates (AI implements, human validates)
+  - **AI Implementation Time**: Time for AI agent to generate code/artifacts
+  - **Human Validation Time**: Time for human to review, test, approve
+  - Simple bolt (1-3 stories): ~45 min AI + ~45 min human = ~1.5 hours total
+  - Medium bolt (3-5 stories): ~1.5 hours AI + ~1.5 hours human = ~3 hours total
+  - Complex bolt (5-8 stories): ~2.5 hours AI + ~3 hours human = ~5.5 hours total
+  - Only use day estimates for genuinely complex work (unknown tech, heavy integration)
+
+### Workflow
+
+- **Agile**: Human-initiated conversations with AI (AI-Assisted)
+- **AI-DLC**: AI-initiated conversations with humans (AI-Driven)

package/src/iris_bundle/frameworks/iris-core/pack.yaml

@@ -0,0 +1,2 @@
+include: ["package.json", "tsconfig.json", "README.md", "src/**", "docs/**"]
+exclude: ["node_modules/**", "dist/**", ".iris/runs/**", ".iris/bridge/**"]

package/src/iris_bundle/frameworks/iris-core/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "irismd",
+  "private": true,
+  "description": "Root workspace for irismd development",
+  "scripts": {
+    "validate:all": "cd src && npm run validate:all",
+    "lint:md:fix": "cd src && npm run lint:md:fix",
+    "deps:check": "echo '\\n=== NPM Package (src/) ===' && npx npm-check-updates --cwd src && echo '\\n=== VS Code Extension ===' && npx npm-check-updates --cwd vs-code-extension",
+    "deps:check:minor": "echo '\\n=== NPM Package (src/) ===' && npx npm-check-updates --cwd src --target minor && echo '\\n=== VS Code Extension ===' && npx npm-check-updates --cwd vs-code-extension --target minor"
+  }
+}

package/src/iris_bundle/frameworks/iris-core/policy.yaml

@@ -0,0 +1,73 @@
+version: 1
+phases:
+  inception:
+    requires:
+      - path: memory-bank/intents/
+        type: directory
+      - path: memory-bank/intents/{intentId}/requirements.md
+        type: file
+      - path: memory-bank/intents/{intentId}/system-context.md
+        type: file
+    gates:
+      - id: requirements-approved
+        kind: frontmatter
+        file: memory-bank/intents/{intentId}/requirements.md
+        field: status
+        equals: approved
+      - id: system-context-approved
+        kind: frontmatter
+        file: memory-bank/intents/{intentId}/system-context.md
+        field: status
+        equals: approved
+
+  planning:
+    requires:
+      - path: memory-bank/intents/{intentId}/unit-list.md
+        type: file
+      - path: memory-bank/intents/{intentId}/units/*/unit-brief.md
+        type: file
+    gates:
+      - id: unit-list-approved
+        kind: frontmatter
+        file: memory-bank/intents/{intentId}/unit-list.md
+        field: status
+        equals: approved
+
+  construction:
+    requires:
+      - path: memory-bank/intents/{intentId}/units/*/unit-brief.md
+        type: file
+      - path: memory-bank/intents/{intentId}/units/*/bolts/*/bolt.md
+        type: file
+    gates:
+      - id: unit-briefs-approved
+        kind: frontmatter
+        file: memory-bank/intents/{intentId}/units/*/unit-brief.md
+        field: status
+        equals: approved
+      - id: bolts-testable
+        kind: frontmatter
+        file: memory-bank/intents/{intentId}/units/*/bolts/*/bolt.md
+        field: commands.test
+        # We enforce existence by checking equality to something?
+        # Or just existence? If equals is missing, does it enforce only existence?
+        # Validator logic: `if (gate.equals !== undefined && check)`
+        # If `gate.equals` is undefined, `if (val === undefined)` check above still runs.
+        # So providing NO equals means "check existence".
+
+
+  operations:
+    requires: []
+    gates: []
+
+transitions:
+  - from: inception
+    to: planning
+    requires_gates: [requirements-approved, system-context-approved]
+  - from: planning
+    to: construction
+    requires_gates: [unit-list-approved]
+  - from: construction
+    to: operations
+  - from: operations
+    to: inception