project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/docs.iris.md/index.mdx

@@ -0,0 +1,179 @@
+---
+title: Introduction
+description: A framework for spec-driven AI development with pluggable flows
+---
+
+
+<iframe
+  src="https://asciinema.org/a/763995/iframe?autoplay=1&loop=1&speed=1.5&t=2&rows=30"
+  title="specs.md demo"
+  style={{width: '100%', height: '560px', borderRadius: '12px', border: 'none'}}
+></iframe>
+
+<img
+  className="block dark:hidden"
+  src="/images/hero-light.svg"
+  alt="specs.md Framework Architecture"
+/>
+<img
+  className="hidden dark:block"
+  src="/images/hero-dark.svg"
+  alt="specs.md Framework Architecture"
+/>
+
+## What is specs.md?
+
+**specs.md** is a framework for spec-driven AI development that uses markdown-based agents to orchestrate your software development workflow. It supports pluggable development flows, with **AI-DLC (AI-Driven Development Lifecycle)** as the first implemented flow.
+
+<CardGroup cols={2}>
+  <Card
+    title="Quick Start"
+    icon="rocket"
+    href="/getting-started/quick-start"
+  >
+    Get up and running in minutes with your AI coding tool
+  </Card>
+  <Card
+    title="Architecture"
+    icon="sitemap"
+    href="/architecture/flows"
+  >
+    Understand the pluggable flow architecture
+  </Card>
+  <Card
+    title="Core Concepts"
+    icon="cube"
+    href="/core-concepts/intents"
+  >
+    Learn about Intents, Units, Bolts, and the Memory Bank
+  </Card>
+  <Card
+    title="Agents"
+    icon="robot"
+    href="/agents/overview"
+  >
+    Explore the four specialized agents that guide development
+  </Card>
+</CardGroup>
+
+## Framework Architecture
+
+specs.md is built as a **pluggable framework** where development methodologies are implemented as **flows**:
+
+```
+specs.md (Framework)
+├── Core (Memory Bank, Standards, Agents)
+└── Flows/
+    └── aidlc/          ← AI-DLC (first flow)
+    └── (future flows...)
+```
+
+<Info>
+  **AI-DLC** is the first implemented flow, based on the [AWS AI-Driven Development Lifecycle](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) methodology. More flows can be added to support different development approaches.
+</Info>
+
+## Key Features
+
+<AccordionGroup>
+  <Accordion title="Pluggable Flows">
+    Development methodologies are implemented as flows. AI-DLC is the first flow, but the framework supports multiple approaches.
+  </Accordion>
+  <Accordion title="AI-Native Design">
+    Built from the ground up for AI-driven development. AI proposes plans, humans validate, AI executes.
+  </Accordion>
+  <Accordion title="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.
+  </Accordion>
+  <Accordion title="Design Techniques Built-In">
+    Domain-Driven Design (DDD) is integral to the Construction phase, addressing the "whitespace" in Agile that has led to quality issues.
+  </Accordion>
+  <Accordion title="Tool Agnostic">
+    Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.
+  </Accordion>
+  <Accordion title="VS Code Extension">
+    Track your progress with our [sidebar extension](/getting-started/vscode-extension) for VS Code, Cursor, and Windsurf. Monitor bolts, browse specs, and view project metrics visually.
+  </Accordion>
+</AccordionGroup>
+
+## AI-DLC Flow Overview
+
+The AI-DLC flow implements three sequential phases:
+
+| Phase | Purpose | Key Activities |
+|-------|---------|----------------|
+| **Inception** | What & Why | Requirements, Stories, Unit Decomposition, Bolt Planning |
+| **Construction** | How to Build | Domain Design, Logical Design, Code, Tests |
+| **Operations** | Deploy & Monitor | Build Artifacts, Deploy, Verify, Monitor |
+
+## Supported Tools
+
+specs.md is **IDE and AI-agnostic**—you choose your tools, no vendor lock-in.
+
+<CardGroup cols={3}>
+  <Card title="Claude Code" icon="terminal">
+    Slash commands
+  </Card>
+  <Card title="Cursor" icon="code">
+    Rules integration
+  </Card>
+  <Card title="GitHub Copilot" icon="github">
+    Agents support
+  </Card>
+  <Card title="Windsurf" icon="wind">
+    Rules integration
+  </Card>
+  <Card title="Cline" icon="robot">
+    Rules integration
+  </Card>
+  <Card title="Roo" icon="paw">
+    Rules integration
+  </Card>
+  <Card title="Kiro" icon="aws">
+    Agents support
+  </Card>
+  <Card title="Google Antigravity" icon="google">
+    Agents support
+  </Card>
+  <Card title="Gemini CLI" icon="sparkles">
+    Agents support
+  </Card>
+  <Card title="Codex CLI" icon="microchip">
+    Agents support
+  </Card>
+  <Card title="OpenCode" icon="code-branch">
+    Agents support
+  </Card>
+</CardGroup>
+
+<Info>
+Unlike tools that lock you into a specific paid IDE, specs.md works with **any AI coding tool**. Your specs and agents are portable markdown files that work everywhere.
+</Info>
+
+## Get Started
+
+<Steps>
+  <Step title="Install specs.md">
+    ```bash
+    npx specsmd@latest install
+    ```
+  </Step>
+  <Step title="Initialize your project">
+    Run the Master Agent and type `project-init`
+  </Step>
+  <Step title="Create your first Intent">
+    Use the Inception Agent to capture what you want to build
+  </Step>
+</Steps>
+
+## Why specs.md?
+
+Traditional development methods were built for human-driven, long-running processes. **specs.md reimagines the development lifecycle** with AI as a central collaborator, enabling:
+
+- **Rapid cycles** measured in hours or days rather than weeks
+- **Complete planning upfront** through Mob Elaboration (weeks of work in hours)
+- **Persistent context** that AI can reference across sessions
+- **Structured artifacts** that build on each other progressively
+
+<Info>
+  <strong>Featured on Product Hunt!</strong> Check out our launch and leave a review: <a href="https://www.producthunt.com/products/specs-md" target="_blank" rel="noopener">specs.md on Product Hunt →</a>
+</Info>

package/src/iris_bundle/frameworks/iris-core/docs.iris.md/methodology/ai-dlc-vs-agile.mdx

@@ -0,0 +1,138 @@
+---
+title: AI-DLC vs Agile
+description: How AI-DLC compares to traditional Agile methods
+---
+
+## Side-by-Side Comparison
+
+| 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 in construction bolts) |
+| **Task Decomposition** | Manual | AI-powered |
+| **Phases** | Repeating sprints | Rapid three-phase cycles |
+| **Rituals** | Daily standups, retrospectives | Mob Elaboration, Mob Construction |
+| **Documentation** | Often neglected | Built-in artifacts |
+| **Context Engineering** | Lost between sprints | Specs + Memory Bank |
+
+## Iteration: Sprints vs Bolts
+
+<Tabs>
+  <Tab title="Agile Sprints">
+    - **Duration**: 1-4 weeks
+    - **Planning**: Sprint planning ceremony
+    - **Execution**: Daily standups, continuous work
+    - **Review**: Sprint review, retrospective
+    - **Output**: Potentially shippable increment
+  </Tab>
+  <Tab title="AI-DLC Bolts">
+    - **Duration**: Hours to days
+    - **Planning**: AI-powered decomposition
+    - **Execution**: Stage-gated progression
+    - **Review**: Human validation at each checkpoint
+    - **Output**: Validated, tested feature
+  </Tab>
+</Tabs>
+
+## Role Inversion
+
+### Traditional Agile
+
+```mermaid
+flowchart LR
+    H1[Human] --> P[Plans] --> H2[Human] --> E[Executes] --> AI[AI assists]
+
+    style H1 fill:#60A5FA,stroke:#3B82F6,color:#fff
+    style P fill:#60A5FA,stroke:#3B82F6,color:#fff
+    style H2 fill:#60A5FA,stroke:#3B82F6,color:#fff
+    style E fill:#60A5FA,stroke:#3B82F6,color:#fff
+    style AI fill:#94A3B8,stroke:#64748B,color:#fff
+```
+
+Humans drive the entire process. AI tools (copilots, assistants) help with specific tasks but don't lead.
+
+### AI-DLC
+
+```mermaid
+flowchart LR
+    H1[Human] --> I[Defines Intent] --> AI1[AI Proposes] --> H2[Human Validates] --> AI2[AI Executes]
+
+    style H1 fill:#60A5FA,stroke:#3B82F6,color:#fff
+    style I fill:#60A5FA,stroke:#3B82F6,color:#fff
+    style AI1 fill:#34D399,stroke:#10B981,color:#fff
+    style H2 fill:#F472B6,stroke:#EC4899,color:#fff
+    style AI2 fill:#34D399,stroke:#10B981,color:#fff
+```
+
+AI leads the conversation. Humans provide intent and validation. AI handles decomposition, planning, and execution.
+
+## Design Techniques
+
+<CardGroup cols={2}>
+  <Card title="Agile Approach" icon="question">
+    Design techniques like DDD are optional. Many teams skip them due to time pressure, leading to technical debt.
+  </Card>
+  <Card title="AI-DLC Approach" icon="check">
+    Domain-Driven Design is built into DDD construction bolts. You can't skip Domain Modeling - it's a required gate.
+  </Card>
+</CardGroup>
+
+## Bolt Types with Built-in Design
+
+| Bolt Type | Best For | Stages |
+|-----------|----------|--------|
+| **DDD Construction** | Complex domain logic, business rules | Model → Design → ADR → Implement → Test |
+| **Simple Construction** | UI, integrations, utilities | Plan → Implement → Test |
+
+## Context Engineering
+
+<Warning>
+  One of the biggest challenges in traditional Agile is context loss between sprints. Knowledge leaves with team members, decisions aren't documented, and the codebase becomes a mystery.
+</Warning>
+
+### AI-DLC Solution: Specs + Memory Bank
+
+Specs and Memory Bank provide structured context for AI agents:
+
+- All project artifacts (requirements, designs, decisions)
+- Traceability between artifacts
+- Context that agents can reload in any session
+
+```
+memory-bank/
+├── intents/           # What we're building
+├── bolts/             # How we built it
+├── standards/         # Project decisions
+└── operations/        # Deployment context
+```
+
+## When to Use Each
+
+<Tabs>
+  <Tab title="Use Agile When">
+    - Team is not using AI coding tools
+    - Organization has established Agile processes
+    - Regulatory requirements mandate specific ceremonies
+    - Team prefers human-led planning
+  </Tab>
+  <Tab title="Use AI-DLC When">
+    - Building with AI coding assistants
+    - Need rapid iteration cycles
+    - Want integrated design practices
+    - Building complex systems
+    - Context persistence is critical
+  </Tab>
+</Tabs>
+
+## Migration Path
+
+AI-DLC retains familiar concepts to ease transition:
+
+| Agile Concept | AI-DLC Equivalent |
+|---------------|-------------------|
+| Epic | Intent |
+| User Story | Story (within Unit) |
+| Sprint | Bolt |
+| Backlog | Intent/Unit definitions |
+| Definition of Done | Checkpoint validations |

package/src/iris_bundle/frameworks/iris-core/docs.iris.md/methodology/sdlc-reimagined.mdx

@@ -0,0 +1,270 @@
+---
+title: "The AI-Native SDLC: Reimagined"
+description: "Why the Agentic Age demands a new methodology—and why retrofitting AI into Agile doesn't work."
+---
+
+## The End of "Faster Horse Chariots"
+
+For decades, software development methodologies evolved incrementally. Waterfall gave way to Agile. Sprints replaced long release cycles. Story points replaced time estimates. Each iteration made us marginally faster.
+
+Then AI arrived—and broke the entire model.
+
+<Info>
+**"Retrofitting AI into existing methods not only limits its potential, but also reinforces outdated inefficiencies. To fully leverage AI's transformative power, SDLC methods need to be reimagined."**
+
+— [AWS AI-DLC Whitepaper](https://github.com/fabriqaai/specsmd/blob/main/resources/aidlc.pdf)
+</Info>
+
+We don't need faster horse chariots. We need automobiles.
+
+---
+
+## Three Eras of AI in Development
+
+| Era | Human Role | AI Role | Paradigm |
+|-----|------------|---------|----------|
+| **AI-Assisted** (2020-2023) | Primary creator | Autocomplete, suggestions | Human drives, AI helps |
+| **AI-Driven** (2023-2025) | Validator, decision-maker | Generates code, plans, tests | AI proposes, human approves |
+| **Agentic** (2025+) | Supervisor, architect | Autonomous multi-step execution | AI executes, human oversees |
+
+We're now in the **Agentic Age**—where AI agents don't just assist; they autonomously plan, reason, and execute complex workflows.
+
+This isn't a minor upgrade. It's a paradigm shift that renders traditional methodologies obsolete.
+
+---
+
+## Why Sprints Don't Work Anymore
+
+### Two Weeks Is No Longer Fast
+
+<Warning>
+AI-enabled development produces working prototypes in hours. A two-week sprint is not rapid iteration—it's an artificial delay that queues work behind an arbitrary time boundary.
+</Warning>
+
+When concept-to-working-code happens in an afternoon, waiting twelve more days for a sprint boundary serves no purpose except ceremony compliance.
+
+### The Cost of Code Has Collapsed
+
+Agile assumed producing code was expensive because human effort was expensive. The methodology optimized for producing *less code more carefully*.
+
+AI inverted this assumption. Code generation now costs minutes, not days.
+
+### Estimation Becomes Meaningless
+
+| Traditional Metric | Problem in AI Era |
+|-------------------|-------------------|
+| **Story Points** | AI execution time bears no relation to human effort estimates |
+| **Velocity** | Fluctuates wildly based on AI tool usage, not team capability |
+| **Sprint Planning** | Creates artificial delays for completed work waiting for ceremonies |
+| **Daily Standups** | Consume time sharing information automated systems could surface instantly |
+
+<Info>
+**"Would effort estimation (story points) be as critical if AI diminishes the boundaries between simple, medium, and hard tasks? Would metrics like velocity be relevant, or should we replace it with Business Value?"**
+
+— AWS AI-DLC Whitepaper
+</Info>
+
+---
+
+## The V-Bounce Model: Humans as Validators
+
+The [V-Bounce paper](https://arxiv.org/abs/2408.03416) from Crowdbotics introduced a foundational insight:
+
+<Card title="Core Insight" icon="lightbulb">
+**The role of humans shifts from primary implementers to validators and verifiers.**
+</Card>
+
+### Traditional V-Model vs V-Bounce
+
+| Aspect | Traditional V-Model | V-Bounce |
+|--------|---------------------|----------|
+| **Implementation Phase** | Substantial (weeks/months) | Drastically reduced (hours/days) |
+| **Human Role** | Hands-on coding | Validation and verification |
+| **Emphasis** | Code production | Requirements + Architecture + Continuous validation |
+| **AI Role** | None/minimal | End-to-end: planning → code → tests → maintenance |
+
+### Three Core Assumptions
+
+<Steps>
+  <Step title="Near-Instantaneous Code Generation">
+    LLMs enable rapid generation of high-quality code
+  </Step>
+  <Step title="Natural Language as Primary Interface">
+    Programming is becoming language-driven
+  </Step>
+  <Step title="Humans as Verifiers">
+    Human roles shift from creators to sophisticated validators
+  </Step>
+</Steps>
+
+### Empirical Results
+
+- **55.8%** faster task completion with AI tools (GitHub Copilot study)
+- **70%+** efficiency in generating test suites with AI
+- Enhanced early bug detection and overall software quality
+
+---
+
+## AI-DLC: The Methodology for the Agentic Age
+
+AWS's **AI-Driven Development Lifecycle (AI-DLC)** takes these insights and builds a complete, production-ready methodology.
+
+### Core Principle: Reimagine, Don't Retrofit
+
+<Info>
+**"We need automobiles, not faster horse chariots."**
+</Info>
+
+AI-DLC doesn't bolt AI onto existing processes. It rebuilds from first principles for an AI-native world.
+
+### The Reversed Conversation
+
+In traditional development, humans prompt AI:
+
+```
+Human: "Write a function that calculates tax"
+AI: [generates code]
+Human: "Now add error handling"
+AI: [updates code]
+```
+
+In AI-DLC, **AI drives the conversation**:
+
+```
+AI: "I've analyzed your intent. Here are 3 Units I propose,
+     with 12 user stories. I have 5 clarifying questions
+     before we proceed. Question 1: What's your compliance
+     framework for tax calculations?"
+Human: [validates, approves, or redirects]
+```
+
+This is like Google Maps: *humans set the destination, AI provides step-by-step directions, humans maintain oversight.*
+
+### Three Phases, Not Endless Sprints
+
+| Phase | Ritual | Duration | Output |
+|-------|--------|----------|--------|
+| **Inception** | Mob Elaboration | Hours | Intents → Units → Stories |
+| **Construction** | Mob Construction | Hours/Days (Bolts) | Domain Design → Code → Tests |
+| **Operations** | Continuous | Ongoing | Deployment, monitoring, maintenance |
+
+### Bolts Replace Sprints
+
+| Sprints | Bolts |
+|---------|-------|
+| 2-4 weeks | Hours or days |
+| Fixed timeboxes | Flexible, intent-driven |
+| Velocity measured | Business value measured |
+| Story points estimated | AI executes, humans validate |
+
+### Mob Rituals: Collaborative AI Alignment
+
+<AccordionGroup>
+  <Accordion title="Mob Elaboration (Inception)">
+    - Product managers, developers, QA collaborate with AI from the start
+    - AI proposes breakdown into Units and Stories
+    - Team validates in single room with shared screen
+    - *What took months now takes hours*
+  </Accordion>
+  <Accordion title="Mob Construction (Construction)">
+    - Teams work in parallel after domain modeling
+    - AI generates component models, sequence diagrams, functional flows
+    - Team provides real-time clarification on technical decisions
+    - *Prevents hallucinations and poor design*
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## Why You Don't Need Other Spec-Driven Tools
+
+### The Landscape Today
+
+| Tool | Philosophy | Limitation |
+|------|------------|------------|
+| **Spec Kit** | Lightweight toolkit | No methodology, human-driven |
+| **BMAD** | 19-agent simulation | Complex, no formal methodology |
+| **OpenSpec** | Change-centric | No lifecycle, brownfield-only |
+| **Kiro** | IDE-integrated | Vendor lock-in, no team rituals |
+
+### What They're Missing
+
+These tools focus on **specifications**—they help you write better prompts and structure your requirements.
+
+But specifications alone don't solve the fundamental problem:
+
+<Warning>
+Traditional methods were built for longer iteration durations (months and weeks), which led to rituals like daily standups and retrospectives. With AI, iteration cycles are measured in hours or days. This needs continuous, real-time validation and feedback mechanisms, rendering many traditional rituals less relevant.
+</Warning>
+
+### AI-DLC Is Different
+
+AI-DLC isn't a tool—it's a **methodology** that includes:
+
+- **Formal phases** (Inception → Construction → Operations)
+- **Defined rituals** (Mob Elaboration, Mob Construction)
+- **Design integration** (DDD as core, not optional)
+- **Reversed conversation** (AI proposes, human validates)
+- **New artifacts** (Intents, Units, Bolts)
+
+---
+
+## specs.md: AI-DLC Implementation
+
+**specs.md** is a faithful implementation of AWS's AI-DLC methodology.
+
+<CardGroup cols={2}>
+  <Card title="specs.md" icon="rocket" href="/methodology/what-is-ai-dlc">
+    **Available Now**
+
+    For complex systems requiring architectural trade-offs, multi-team coordination, regulated environments, and enterprise scalability.
+
+    - Phase-based agents
+    - Memory Bank for persistent context
+    - DDD integration as core
+    - Mob ritual support
+  </Card>
+  <Card title="specs.md (Simple Flow)" icon="bolt">
+    **Coming Soon**
+
+    For simpler projects and teams wanting a lighter entry point.
+
+    - Kiro-style workflow: Requirements → Design → Tasks
+    - Graduate to full AI-DLC when complexity demands
+  </Card>
+</CardGroup>
+
+---
+
+## The Bottom Line
+
+| Old World | New World |
+|-----------|-----------|
+| Sprints (weeks) | Bolts (hours/days) |
+| Story points | Business value |
+| Human codes, AI assists | AI proposes, human validates |
+| Retrofit AI into Agile | Reimagine from first principles |
+| Specification tools | Complete methodology (AI-DLC) |
+
+<Info>
+**"AI might be the death of Agile, but it's the beginning of true agility."**
+</Info>
+
+---
+
+## Further Reading
+
+<CardGroup cols={2}>
+  <Card title="AI-DLC Whitepaper (AWS)" icon="file-pdf" href="https://github.com/fabriqaai/specsmd/blob/main/resources/aidlc.pdf">
+    The original AWS whitepaper defining AI-DLC methodology
+  </Card>
+  <Card title="V-Bounce Paper (arXiv)" icon="book" href="https://arxiv.org/abs/2408.03416">
+    The AI-Native Software Development Lifecycle research paper
+  </Card>
+  <Card title="AWS Blog: AI-DLC" icon="aws" href="https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/">
+    AWS DevOps blog post on reimagining software engineering
+  </Card>
+  <Card title="Compare Tools" icon="scale-balanced" href="/compare/overview">
+    See how specs.md compares to Spec Kit, BMAD, Kiro, and OpenSpec
+  </Card>
+</CardGroup>