project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/src/README.md

@@ -0,0 +1,322 @@
+# irismd
+
+**AI-native software development with multi-agent orchestration.**
+
+irismd implements the [AI-Driven Development Lifecycle (AI-DLC)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) methodology as a set of markdown-based agents that work with your favorite AI coding tools.
+
+[![npm version](https://img.shields.io/npm/v/irismd)](https://www.npmjs.com/package/irismd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## What is AI-DLC?
+
+AI-DLC is a reimagined software development methodology where **AI drives the conversation** and humans validate. Unlike traditional Agile where iterations span weeks, AI-DLC operates in **Bolts** - rapid iterations measured in hours or days.
+
+> "Traditional development methods were built for human-driven, long-running processes. AI-DLC reimagines the development lifecycle with AI as a central collaborator, enabling rapid cycles measured in hours or days rather than weeks."
+
+### AI-DLC vs Traditional Methods
+
+| Aspect | Agile/Scrum | AI-DLC |
+|--------|-------------|--------|
+| Iteration duration | Weeks (Sprints) | Hours/days (Bolts) |
+| Who drives | Human-driven, AI assists | AI-driven, human-validated |
+| Design techniques | Out of scope | Integrated (DDD, TDD, BDD) |
+| Task decomposition | Manual | AI-powered |
+| Phases | Repeating sprints | Rapid three-phase cycles (Inception → Construction → Operations) |
+| Rituals | Daily standups, retrospectives | Mob Elaboration, Mob Construction |
+
+---
+
+## How It Works
+
+irismd provides four specialized agents that guide you through the entire development lifecycle:
+
+```
+                    ┌─────────────────┐
+                    │  Master Agent   │  Orchestrates & navigates
+                    └────────┬────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        ▼                    ▼                    ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│   Inception   │ → │ Construction  │ → │  Operations   │
+│     Agent     │   │     Agent     │   │     Agent     │
+└───────────────┘   └───────────────┘   └───────────────┘
+  Capture intent      Execute bolts      Deploy & monitor
+  Define units        Build & test       Verify & scale
+  Plan stories        Validate stages
+```
+
+### The Three Phases
+
+| Phase | Agent | Purpose | Key Outputs |
+|-------|-------|---------|-------------|
+| **Inception** | Inception Agent | Capture intents, elaborate requirements, decompose into units | User stories, NFRs, Unit definitions, Bolt plans |
+| **Construction** | Construction Agent | Execute bolts through domain design → logical design → code → test | Domain models, Technical designs, Code, Tests |
+| **Operations** | Operations Agent | Deploy, verify, and monitor | Deployment units, Monitoring, Runbooks |
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+npx irismd install
+```
+
+The installer detects your AI coding tools (Claude Code, Cursor, GitHub Copilot) and sets up:
+- Agent definitions and skills
+- Memory bank structure for context persistence
+- Slash commands for easy agent invocation
+
+### Initialize Your Project
+
+```bash
+# Start the Master Agent
+/irismd-master-agent
+
+# Then type:
+project-init
+```
+
+This guides you through establishing:
+- **Tech Stack** - Languages, frameworks, databases, infrastructure
+- **Coding Standards** - Formatting, linting, naming, testing strategy
+- **System Architecture** - Architecture style, API design, state management
+- **UX Guide** - Design system, styling, accessibility (optional)
+- **API Conventions** - API style, versioning, response formats (optional)
+
+### Create Your First Intent
+
+```bash
+/irismd-inception-agent intent-create
+```
+
+An **Intent** is your high-level goal:
+- "User authentication system"
+- "Product catalog with search"
+- "Payment processing integration"
+
+The agent will:
+1. Ask clarifying questions to minimize ambiguity
+2. Elaborate into user stories and NFRs
+3. Define system context
+4. Decompose into loosely-coupled units
+
+### Plan and Execute Bolts
+
+```bash
+# Plan bolts for your stories
+/irismd-inception-agent bolt-plan
+
+# Execute a bolt
+/irismd-construction-agent bolt-start
+```
+
+Each bolt goes through validated stages:
+1. **Domain Model** - Model business logic using DDD principles
+2. **Technical Design** - Apply patterns and make architecture decisions
+3. **ADR Analysis** - Document significant decisions (optional)
+4. **Implement** - Generate production code
+5. **Test** - Verify correctness with automated tests
+
+**Human validation happens at each stage gate.**
+
+---
+
+## Key Concepts
+
+### Intent
+A high-level statement of purpose that encapsulates what needs to be achieved - whether a business goal, feature, or technical outcome. It serves as the starting point for AI-driven decomposition.
+
+### Unit
+A cohesive, self-contained work element derived from an Intent. Units are loosely coupled and can be developed independently. Analogous to a Subdomain (DDD) or Epic (Scrum).
+
+### Bolt
+The smallest iteration in AI-DLC, designed for rapid implementation. Unlike Sprints (weeks), Bolts are **hours to days**. Each bolt encapsulates a well-defined scope of work.
+
+| Type | Best For | Stages |
+|------|----------|--------|
+| **DDD Construction** | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
+| **Simple Construction** | UI, integrations, utilities | Plan → Implement → Test |
+
+### Memory Bank
+File-based storage for all project artifacts. Maintains context across agent sessions and provides traceability between artifacts.
+
+### Standards
+Project decisions that inform AI code generation. Standards ensure consistency across all generated code and documentation.
+
+---
+
+## Project Structure
+
+After installation:
+
+```
+.irismd/
+├── manifest.yaml              # Installation manifest
+└── aidlc/                     # AI-DLC flow
+    ├── agents/                # Agent definitions
+    ├── skills/                # Agent capabilities
+    ├── templates/             # Artifact templates
+    │   └── standards/         # Standards facilitation guides
+    └── memory-bank.yaml       # Memory bank schema
+
+memory-bank/                   # Created after project-init
+├── intents/                   # Your captured intents
+│   └── {intent-name}/
+│       ├── requirements.md
+│       ├── system-context.md
+│       └── units/
+├── bolts/                     # Bolt execution records
+├── standards/                 # Project standards
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   └── ...
+└── operations/                # Deployment context
+```
+
+---
+
+## Agent Commands
+
+### Master Agent
+```bash
+/irismd-master-agent
+```
+| Command | Purpose |
+|---------|---------|
+| `project-init` | Initialize project with standards |
+| `analyze-context` | View current project state |
+| `route-request` | Get directed to the right agent |
+| `explain-flow` | Learn about AI-DLC methodology |
+| `answer-question` | Get help with any irismd question |
+
+### Inception Agent
+```bash
+/irismd-inception-agent
+```
+| Command | Purpose |
+|---------|---------|
+| `intent-create` | Create a new intent |
+| `intent-list` | List all intents |
+| `requirements` | Elaborate intent requirements |
+| `context` | Define system context |
+| `units` | Decompose into units |
+| `story-create` | Create stories for a unit |
+| `bolt-plan` | Plan bolts for stories |
+| `review` | Review inception artifacts |
+
+### Construction Agent
+```bash
+/irismd-construction-agent
+```
+| Command | Purpose |
+|---------|---------|
+| `bolt-start` | Start/continue executing a bolt |
+| `bolt-status` | Check bolt progress |
+| `bolt-list` | List all bolts |
+| `bolt-replan` | Replan bolts if needed |
+
+### Operations Agent
+```bash
+/irismd-operations-agent
+```
+| Command | Purpose |
+|---------|---------|
+| `build` | Build the project |
+| `deploy` | Deploy to environment |
+| `verify` | Verify deployment |
+| `monitor` | Set up monitoring |
+
+---
+
+## Why irismd?
+
+### AI-Native, Not AI-Retrofitted
+Built from the ground up for AI-driven development. AI-DLC is a reimagination based on first principles, not a retrofit of existing methods.
+
+### Human Oversight as Loss Function
+Validation at each stage catches errors early before they cascade downstream. Each validation transforms artifacts into rich context for subsequent stages.
+
+### Design Techniques Built-In
+DDD, TDD, and BDD are integral to the methodology - not optional add-ons. This addresses the "whitespace" in Agile that has led to quality issues.
+
+### Tool Agnostic
+Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.
+
+### Context Engineering
+Specs and Memory Bank provide structured context for AI agents. Agents reload context each session - no more lost knowledge.
+
+---
+
+## Supported Tools
+
+| Tool | Status | Installation |
+|------|--------|--------------|
+| **Claude Code** | Full support | Slash commands in `.claude/commands/` |
+| **Cursor** | Full support | Rules in `.cursor/rules/` (`.mdc` format) |
+| **GitHub Copilot** | Full support | Agents in `.github/agents/` (`.agent.md` format) |
+| **Google Antigravity** | Full support | Agents in `.agent/agents/` |
+
+---
+
+## FAQ
+
+**Q: Agents don't seem to remember previous context?**
+Each agent invocation starts fresh. Agents read context from the Memory Bank at startup. Ensure artifacts are saved after each step.
+
+**Q: How do I reset project state?**
+Clear the `memory-bank/` directory to reset all artifacts. To remove irismd entirely, delete the `.irismd/` directory and tool-specific command files.
+
+**Q: Can I use irismd with existing Agile workflows?**
+AI-DLC is designed as a reimagination, not a retrofit. However, familiar concepts (user stories, acceptance criteria) are retained to ease transition.
+
+**Q: What project types is this suited for?**
+irismd is designed for building complex systems that demand architectural complexity, trade-off management, and scalability. Simpler systems may be better suited for low-code/no-code approaches.
+
+---
+
+## Resources
+
+- [AI-DLC Specification (AWS)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)
+- [iris.md](https://iris.md)
+
+---
+
+## Analytics & Privacy
+
+irismd collects **anonymous** usage analytics during installation only. This helps us understand adoption and improve the product.
+
+**What we collect**: OS, shell type, selected IDEs, installation success/failure, approximate location (country level).
+
+**What we don't collect**: No usernames, no file paths, no project contents, no IP addresses stored.
+
+### Opt-Out
+
+```bash
+# Option 1: Environment variable
+SPECSMD_TELEMETRY_DISABLED=1 npx irismd@latest install
+
+# Option 2: DO_NOT_TRACK standard
+DO_NOT_TRACK=1 npx irismd@latest install
+```
+
+Analytics are automatically disabled in CI environments.
+
+See [PRIVACY.md](PRIVACY.md) for full details.
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  Built with AWS' AI-DLC methodology by the <a href="https://iris.md">iris.md</a> team.
+</p>
+

package/src/iris_bundle/frameworks/iris-core/src/__tests__/schemas/agent.schema.yaml

@@ -0,0 +1,20 @@
+# Schema for agent definition files
+# Validates agent markdown templates in flows/aidlc/agents/
+
+name: agent
+description: Agent definition template for irismd AI-DLC flow
+file_pattern: "**/agents/*.md"
+
+required_sections:
+  - heading: "## Persona"
+  - heading: "## Skills"
+
+optional_sections:
+  - heading: "## On Activation"
+  - heading: "## Default Flow"
+  - heading: "## Workflow"
+  - heading: "## Begin"
+
+rules:
+  min_content_length: 500
+  must_start_with_h1: true

package/src/iris_bundle/frameworks/iris-core/src/__tests__/schemas/catalog.schema.yaml

@@ -0,0 +1,60 @@
+# Schema for catalog.yaml
+# Validates standards catalog configuration
+
+name: catalog
+description: Standards catalog defining available standards, decisions, and project type presets
+
+required_keys:
+  - standards
+  - project_types
+
+nested_required:
+  # Required standards (tech-stack and coding-standards are critical)
+  standards:
+    - tech-stack
+    - coding-standards
+
+  # tech-stack standard structure
+  standards.tech-stack:
+    - description
+    - facilitation
+    - output_path
+    - importance
+    - decisions
+
+  # coding-standards standard structure
+  standards.coding-standards:
+    - description
+    - facilitation
+    - output_path
+    - importance
+    - decisions
+
+  # Required project types
+  project_types:
+    - full-stack-web
+    - backend-api
+    - frontend-app
+    - cli-tool
+    - library
+
+  # Each project type must have these fields
+  project_types.full-stack-web:
+    - description
+    - required_standards
+
+  project_types.backend-api:
+    - description
+    - required_standards
+
+  project_types.frontend-app:
+    - description
+    - required_standards
+
+  project_types.cli-tool:
+    - description
+    - required_standards
+
+  project_types.library:
+    - description
+    - required_standards

package/src/iris_bundle/frameworks/iris-core/src/__tests__/schemas/context-config.schema.yaml

@@ -0,0 +1,24 @@
+# Schema for context-config.yaml
+# Validates agent context loading configuration
+
+name: context-config
+description: Defines what context each agent should load on activation
+
+required_keys:
+  - agents
+
+nested_required:
+  # Construction agent is required (loads project standards)
+  agents:
+    - construction
+
+  # Construction agent must have these sections
+  agents.construction:
+    - description
+    - required_context
+    - on_missing_critical
+
+  # Error handling configuration
+  agents.construction.on_missing_critical:
+    - action
+    - message

package/src/iris_bundle/frameworks/iris-core/src/__tests__/schemas/memory-bank.schema.yaml

@@ -0,0 +1,61 @@
+# Schema for memory-bank.yaml
+# Validates the memory bank configuration for AI-DLC flow
+
+name: memory-bank
+description: Memory bank configuration defining directory structure, naming conventions, and schema paths
+
+required_keys:
+  - structure
+  - schema
+  - conventions
+  - naming
+
+nested_required:
+  # Schema paths (source of truth for agents)
+  schema:
+    - intents
+    - units
+    - bolts
+    - standards
+    - stories
+    - story-index
+    - inception-log
+    - construction-log
+
+  # Schema ownership by agent
+  schema.ownership:
+    - inception
+    - construction
+    - operations
+
+  # Timestamp conventions
+  conventions:
+    - timestamps
+
+  conventions.timestamps:
+    - format
+    - pattern
+    - example
+
+  # Naming conventions for each artifact type
+  naming:
+    - intents
+    - units
+    - stories
+    - bolts
+
+  naming.intents:
+    - format
+    - example
+
+  naming.units:
+    - format
+    - example
+
+  naming.stories:
+    - format
+    - example
+
+  naming.bolts:
+    - format
+    - example

package/src/iris_bundle/frameworks/iris-core/src/__tests__/schemas/skill.schema.yaml

@@ -0,0 +1,22 @@
+# Schema for skill files (*.md in skills/)
+name: skill
+description: Agent skill file template for irismd
+file_pattern: "**/skills/**/*.md"
+
+required_sections:
+  - heading: "## Goal"
+  - heading: "## Input"
+  - heading: "## Process"
+
+optional_sections:
+  - heading: "## Role"
+  - heading: "## Progress Display"
+  - heading: "## Gates in This Skill"
+  - heading: "## Output"
+  - heading: "## Human Validation Point"
+  - heading: "## Transition"
+  - heading: "## Test Contract"
+
+rules:
+  min_content_length: 300
+  must_start_with_h1: true