project-iris 0.0.1

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

@@ -0,0 +1,364 @@
+---
+title: FAQ
+description: Frequently asked questions about specs.md
+---
+
+## General
+
+<AccordionGroup>
+  <Accordion title="What is specs.md?">
+    specs.md is an implementation of the AI-Driven Development Lifecycle (AI-DLC) methodology. It provides markdown-based agents that work with your favorite AI coding tools (Claude Code, Cursor, GitHub Copilot) to guide software development from requirements through deployment.
+
+    We offer two modes:
+    - **specs.md** - Full methodology for complex systems (available now)
+    - **specs.md (Simple Flow)** - Lightweight mode for simpler projects (coming soon)
+  </Accordion>
+
+  <Accordion title="What is AI-DLC?">
+    AI-DLC is a software development methodology developed by AWS where AI drives the conversation and humans validate. Unlike traditional Agile with week-long sprints, AI-DLC operates in "Bolts" - rapid iterations measured in hours or days.
+
+    Key principles:
+    - **Reimagine, don't retrofit** - AI-DLC is built from first principles, not AI bolted onto Agile
+    - **Reversed conversation** - AI proposes, humans validate (not vice versa)
+    - **DDD as core** - Domain-Driven Design is integral, not optional
+
+    [Learn more about AI-DLC →](/methodology/what-is-ai-dlc)
+  </Accordion>
+
+  <Accordion title="What AI coding tools are supported?">
+    specs.md supports:
+    - **Claude Code** - Full support with slash commands
+    - **Cursor** - Full support with rules
+    - **GitHub Copilot** - Full support with agents
+    - **Google Antigravity** - Full support with agents
+    - **Any AI assistant** - Works with any tool that can read markdown prompts
+  </Accordion>
+
+  <Accordion title="Is specs.md free?">
+    Yes, specs.md is open source under the MIT license. You can use it freely in personal and commercial projects. You only pay for your AI API tokens.
+  </Accordion>
+
+  <Accordion title="Who is specs.md for?">
+    AI-DLC is designed for teams building complex systems that demand:
+    - Continuous functional adaptability
+    - High architectural complexity
+    - Numerous trade-offs management
+    - Scalability and integration requirements
+    - Multiple teams working cohesively
+    - Regulated environments
+
+    For simpler projects without complex trade-off management, wait for specs.md (Simple Flow).
+  </Accordion>
+</AccordionGroup>
+
+## Why AI-DLC? (The Agentic Age)
+
+<AccordionGroup>
+  <Accordion title="Why do we need a new methodology? What's wrong with Agile?">
+    Traditional methods were built for longer iteration durations (months and weeks), leading to rituals like daily standups and retrospectives. With AI, iteration cycles are measured in hours or days.
+
+    Retrofitting AI into Agile limits its potential and reinforces outdated inefficiencies. We need automobiles, not faster horse chariots.
+
+    [Read: The AI-Native SDLC: Reimagined →](/methodology/sdlc-reimagined)
+  </Accordion>
+
+  <Accordion title="Why are sprints becoming obsolete?">
+    - **Two weeks is no longer fast** - AI produces working prototypes in hours
+    - **Story points are meaningless** - AI execution time bears no relation to human effort
+    - **Sprint boundaries create artificial delays** - Completed work waits for ceremonies
+    - **Velocity fluctuates wildly** - Based on AI tool usage, not team capability
+
+    AI-DLC replaces sprints with "Bolts" - hours or days, not weeks.
+  </Accordion>
+
+  <Accordion title="What is V-Bounce?">
+    V-Bounce is a model from the [Crowdbotics research paper](https://arxiv.org/abs/2408.03416) that introduced a key insight: humans shift from primary implementers to validators and verifiers.
+
+    AI handles planning, coding, and testing. Humans focus on requirements, architecture, and continuous validation.
+  </Accordion>
+
+  <Accordion title="What does 'AI drives, human validates' mean?">
+    In traditional development, humans prompt AI to complete tasks. In AI-DLC, the conversation is reversed:
+
+    **Traditional**: Human asks → AI responds
+
+    **AI-DLC**: AI proposes breakdown, trade-offs, designs → Human validates, approves, redirects
+
+    Think of it like Google Maps: you set the destination, AI provides step-by-step directions, you maintain oversight.
+  </Accordion>
+
+  <Accordion title="What are Mob Elaboration and Mob Construction?">
+    These are AI-DLC's collaborative rituals:
+
+    - **Mob Elaboration** (Inception): Product managers, developers, QA collaborate with AI to refine requirements into user stories. What took months now takes hours.
+
+    - **Mob Construction** (Construction): Teams work in parallel after domain modeling, with AI generating component models while team provides real-time clarification.
+
+    Both happen in a single room with shared screen for deep alignment.
+  </Accordion>
+</AccordionGroup>
+
+## Comparisons
+
+<AccordionGroup>
+  <Accordion title="How does specs.md compare to GitHub Spec Kit?">
+    **Spec Kit** is a toolkit with agent prompts (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`) for 15+ AI assistants.
+
+    **specs.md** is a full methodology with phase-based agents, Mob rituals, and DDD integration.
+
+    Choose Spec Kit for a 4-phase workflow with minimal learning curve. Choose specs.md for complex systems needing formal methodology structure.
+
+    *Coming Soon*: specs.md (Simple Flow) will provide Kiro-style Requirements → Design → Tasks workflow.
+
+    [Full comparison →](/compare/vs-speckit)
+  </Accordion>
+
+  <Accordion title="How does specs.md compare to BMAD-Method?">
+    Both target complex systems:
+
+    - **BMAD**: 19+ role-based agents (Analyst, PM, Architect, Dev, QA...)
+    - **specs.md**: 3 phase-based agents (Master, Inception, Construction, Operations)
+
+    Choose BMAD for maximum agent customization. Choose specs.md for formal AWS methodology with simpler agent model.
+
+    [Full comparison →](/compare/vs-bmad)
+  </Accordion>
+
+  <Accordion title="How does specs.md compare to Kiro (AWS)?">
+    **Kiro** is a full IDE with built-in spec-driven development and agent hooks.
+
+    **specs.md** is IDE-agnostic—works with any editor and AI model.
+
+    | Aspect | specs.md | Kiro |
+    |--------|----------|------|
+    | IDE | Any | Kiro only |
+    | AI Model | Any | Claude Sonnet only |
+    | Pricing | Free + API tokens | $19-39/month |
+
+    *Coming Soon*: specs.md (Simple Flow) will add Kiro-style agent hooks.
+
+    [Full comparison →](/compare/vs-kiro)
+  </Accordion>
+
+  <Accordion title="How does specs.md compare to OpenSpec?">
+    **OpenSpec** is brownfield-first, focused on change management with excellent token efficiency.
+
+    **specs.md** provides full lifecycle support (Inception → Operations) for both greenfield and brownfield.
+
+    Choose OpenSpec for high-volume small changes. Choose specs.md for full lifecycle complex systems.
+
+    [Full comparison →](/compare/vs-openspec)
+  </Accordion>
+
+  <Accordion title="Do I need other spec-driven tools if I use specs.md?">
+    No. specs.md is a complete methodology that includes everything you need:
+
+    - Formal phases (Inception → Construction → Operations)
+    - Defined rituals (Mob Elaboration, Mob Construction)
+    - Design integration (DDD as core)
+    - Memory Bank for persistent context
+    - Phase-based agents
+
+    Other tools focus on specifications only. AI-DLC is a full methodology.
+  </Accordion>
+</AccordionGroup>
+
+## Installation
+
+<AccordionGroup>
+  <Accordion title="How do I install specs.md?">
+    ```bash
+    npx specsmd@latest install
+    ```
+
+    The installer automatically detects your AI coding tools and sets up the appropriate agents.
+
+    [Full installation guide →](/getting-started/installation)
+  </Accordion>
+
+  <Accordion title="Should I install globally with npm?">
+    No. Always use `npx specsmd@latest install` to ensure you get the latest version. Global installation may result in using an outdated version.
+  </Accordion>
+
+  <Accordion title="What gets installed?">
+    specs.md creates a `.specsmd/` directory with:
+    - Agent definitions
+    - Skills and capabilities
+    - Templates for artifacts
+    - Memory bank schema
+
+    It also creates tool-specific files (e.g., `.claude/commands/` for Claude Code).
+  </Accordion>
+</AccordionGroup>
+
+## Usage
+
+<AccordionGroup>
+  <Accordion title="Agents don't seem to remember previous context?">
+    Each agent invocation starts fresh. Agents read context from the Memory Bank at startup.
+
+    **Solution**: Ensure artifacts are saved after each step. The Memory Bank is how context persists between sessions.
+  </Accordion>
+
+  <Accordion title="How do I reset project state?">
+    To reset all artifacts, clear the `memory-bank/` directory:
+    ```bash
+    rm -rf memory-bank/
+    ```
+
+    To remove specs.md entirely:
+    ```bash
+    rm -rf .specsmd/
+    rm -rf .claude/commands/specsmd-*  # For Claude Code
+    ```
+  </Accordion>
+
+  <Accordion title="Can I use specs.md with existing Agile workflows?">
+    AI-DLC is designed as a reimagination of development methodology, not a retrofit. However, familiar concepts (user stories, acceptance criteria) are retained to ease transition.
+
+    You can use specs.md alongside existing Agile processes, treating Intents as Epics and Bolts as focused work items within sprints.
+  </Accordion>
+
+  <Accordion title="Can I use specs.md on existing codebases (brownfield)?">
+    Yes. AI-DLC supports brownfield development through "model elevation" - AI first converts existing code to semantic models (domain components, responsibilities, relationships) before making changes.
+
+    This ensures AI understands the existing system before proposing modifications.
+  </Accordion>
+</AccordionGroup>
+
+## Methodology
+
+<AccordionGroup>
+  <Accordion title="What's the difference between Intents, Units, and Bolts?">
+    - **Intent**: High-level goal ("Build user authentication")
+    - **Unit**: Cohesive work element derived from Intent ("User Registration")
+    - **Bolt**: Smallest iteration, hours to days ("Registration Domain Model")
+
+    [Learn more about core concepts →](/core-concepts/intents)
+  </Accordion>
+
+  <Accordion title="What are the three phases?">
+    1. **Inception**: Mob Elaboration ritual - capture intents, decompose into units and stories
+    2. **Construction**: Mob Construction ritual - domain modeling, code generation, testing
+    3. **Operations**: Deployment, monitoring, maintenance
+
+    [Learn more about phases →](/methodology/three-phases)
+  </Accordion>
+
+  <Accordion title="What are human checkpoints?">
+    Human checkpoints are validation points within a bolt. You must approve each stage before proceeding to the next:
+
+    1. Domain Model → **CHECKPOINT** → Technical Design → **CHECKPOINT** → etc.
+
+    This catches errors early before they cascade downstream.
+  </Accordion>
+
+  <Accordion title="What bolt types are available?">
+    | Type | Use Case |
+    |------|----------|
+    | **DDD Construction** | Complex business logic, domain modeling |
+    | **Simple Construction** | UI, integrations, utilities |
+  </Accordion>
+
+  <Accordion title="What is the Memory Bank?">
+    The Memory Bank is a file-based storage system for all project artifacts. It maintains context across agent sessions and provides traceability between requirements, designs, code, and tests.
+
+    [Learn more about Memory Bank →](/core-concepts/memory-bank)
+  </Accordion>
+
+  <Accordion title="Why is DDD (Domain-Driven Design) required?">
+    Unlike Agile frameworks that leave design techniques optional, AI-DLC integrates DDD as its core. AI applies domain-driven design principles during decomposition:
+
+    - Bounded contexts
+    - Aggregates and entities
+    - Domain events
+    - Repositories and factories
+
+    This ensures consistent, high-quality domain models regardless of which team member is working.
+  </Accordion>
+</AccordionGroup>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Agent commands not recognized">
+    Ensure specs.md is installed correctly:
+    ```bash
+    ls .specsmd/aidlc/agents/
+    ```
+
+    If the directory is empty or missing, reinstall:
+    ```bash
+    npx specsmd@latest install
+    ```
+  </Accordion>
+
+  <Accordion title="Memory Bank artifacts missing">
+    Check if the memory-bank directory exists:
+    ```bash
+    ls memory-bank/
+    ```
+
+    If missing, run project initialization:
+    ```bash
+    /specsmd-master-agent
+    > project-init
+    ```
+  </Accordion>
+
+  <Accordion title="Standards not being followed in generated code">
+    Ensure standards are defined in `memory-bank/standards/`:
+    - `tech-stack.md`
+    - `coding-standards.md`
+    - `architecture.md`
+
+    If missing or incomplete, use the Master Agent to define them:
+    ```bash
+    /specsmd-master-agent
+    > project-init
+    ```
+  </Accordion>
+
+  <Accordion title="AI not following the spec properly">
+    This is a known limitation of all spec-driven tools. Even with comprehensive specs, AI agents don't always follow every instruction.
+
+    **Solutions**:
+    - Use checkpoints to catch errors early
+    - Break work into smaller, clearer units
+    - Ensure Memory Bank has complete context
+    - Validate each step before proceeding
+  </Accordion>
+</AccordionGroup>
+
+## Resources
+
+<CardGroup cols={2}>
+  <Card
+    title="AI-DLC Whitepaper (AWS)"
+    icon="file-pdf"
+    href="https://github.com/fabriqaai/specsmd/blob/main/resources/aidlc.pdf"
+  >
+    Original AWS whitepaper defining AI-DLC methodology
+  </Card>
+  <Card
+    title="V-Bounce Paper (arXiv)"
+    icon="book"
+    href="https://arxiv.org/abs/2408.03416"
+  >
+    AI-Native Software Development Lifecycle research
+  </Card>
+  <Card
+    title="GitHub Repository"
+    icon="github"
+    href="https://github.com/fabriqaai/specsmd"
+  >
+    Source code, issues, and contributions
+  </Card>
+  <Card
+    title="Compare Tools"
+    icon="scale-balanced"
+    href="/compare/overview"
+  >
+    See how specs.md compares to alternatives
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,55 @@
+---
+title: Provide Feedback
+description: Help us improve specs.md with your valuable feedback
+---
+
+## Your Feedback Matters
+
+specs.md is an open-source project built for the community, and **your feedback is essential** to making it better. Whether you've encountered a bug, have a feature idea, or simply want to share your experience, we want to hear from you.
+
+<Info>
+  As an early-stage project, your input directly shapes the direction of specs.md. Every piece of feedback helps us understand real-world use cases and prioritize what matters most.
+</Info>
+
+## How You Can Help
+
+<CardGroup cols={2}>
+  <Card title="Report Issues" icon="bug" href="https://github.com/fabriqaai/specsmd/issues/new?template=bug_report.md">
+    Found a bug? Let us know so we can fix it quickly.
+  </Card>
+  <Card title="Request Features" icon="lightbulb" href="https://github.com/fabriqaai/specsmd/issues/new?template=feature_request.md">
+    Have an idea that would make specs.md better? We'd love to hear it.
+  </Card>
+  <Card title="Ask Questions" icon="circle-question" href="https://github.com/fabriqaai/specsmd/issues/new">
+    Confused about something? Open an issue and we'll help clarify.
+  </Card>
+  <Card title="Share Experience" icon="comment" href="https://github.com/fabriqaai/specsmd/issues/new">
+    Tell us how you're using specs.md and what's working (or not).
+  </Card>
+</CardGroup>
+
+## What Makes Great Feedback
+
+When sharing feedback, consider including:
+
+- **Context**: What were you trying to accomplish?
+- **Steps**: What did you do? (Be specific)
+- **Expected vs Actual**: What did you expect to happen? What actually happened?
+- **Environment**: Which AI tool are you using? (Claude Code, Cursor, Copilot)
+- **Ideas**: Any thoughts on how it could be improved?
+
+## Submit Feedback
+
+<Card
+  title="Open a GitHub Issue"
+  icon="github"
+  href="https://github.com/fabriqaai/specsmd/issues"
+>
+  Visit our GitHub Issues page to submit feedback, report bugs, or request features. We review every submission and respond as quickly as possible.
+</Card>
+
+---
+
+<Note>
+  We genuinely appreciate every piece of feedback. It takes time to write up issues and suggestions, and we don't take that for granted. Thank you for helping make specs.md better for everyone.
+</Note>

package/src/iris_bundle/frameworks/iris-core/docs.iris.md/getting-started/installation.mdx

@@ -0,0 +1,91 @@
+---
+title: Installation
+description: Install specs.md and set up your development environment
+---
+
+## Prerequisites
+
+- Node.js 18 or higher
+- An AI coding tool (Claude Code, Cursor, GitHub Copilot, or Google Antigravity)
+
+## Install specs.md
+
+<Note>
+  Always use npx to get the latest version. Do not install globally with npm.
+</Note>
+
+```bash
+npx specsmd@latest install
+```
+
+The installer automatically detects your AI coding tools and sets up:
+
+<CardGroup cols={3}>
+  <Card title="Agent Definitions" icon="robot">
+    Specialized agents for each phase of development
+  </Card>
+  <Card title="Memory Bank" icon="database">
+    Persistent context storage structure
+  </Card>
+  <Card title="Slash Commands" icon="terminal">
+    Easy agent invocation commands
+  </Card>
+</CardGroup>
+
+## What Gets Installed
+
+After installation, you'll see the following structure:
+
+```
+.specsmd/
+├── 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
+```
+
+## Tool-Specific Setup
+
+<Tabs>
+  <Tab title="Claude Code">
+    Slash commands are installed in `.claude/commands/`:
+    - `/specsmd-master-agent`
+    - `/specsmd-inception-agent`
+    - `/specsmd-construction-agent`
+    - `/specsmd-operations-agent`
+  </Tab>
+  <Tab title="Cursor">
+    Rules are installed in `.cursor/rules/` using `.mdc` format.
+  </Tab>
+  <Tab title="GitHub Copilot">
+    Agents are installed in `.github/agents/` using `.agent.md` format.
+  </Tab>
+  <Tab title="Google Antigravity">
+    Agents are installed in `.agent/workflows/`.
+  </Tab>
+</Tabs>
+
+## Verify Installation
+
+After installation, verify everything is set up correctly:
+
+```bash
+# Check the manifest
+cat .specsmd/manifest.yaml
+
+# List installed agents
+ls .specsmd/aidlc/agents/
+```
+
+## Next Steps
+
+<Card
+  title="Quick Start"
+  icon="arrow-right"
+  href="/getting-started/quick-start"
+>
+  Initialize your project and create your first Intent
+</Card>

package/src/iris_bundle/frameworks/iris-core/docs.iris.md/getting-started/quick-start.mdx

@@ -0,0 +1,149 @@
+---
+title: Quick Start
+description: Get up and running with specs.md in minutes
+---
+
+<Warning>
+  **Alpha Version**: specs.md does not yet fully support brownfield applications as defined in the AI-DLC process. Currently, it relies on the underlying LLM model's capabilities for existing codebase analysis. Full brownfield support is coming soon.
+</Warning>
+
+## Initialize Your Project
+
+Open your AI coding tool and start the Master Agent:
+
+<Tabs>
+  <Tab title="Claude Code">
+    ```bash
+    /specsmd-master-agent
+    ```
+  </Tab>
+  <Tab title="Cursor">
+    ```
+    /specsmd-master-agent
+    ```
+    Or use the `@` prefix:
+    ```
+    @specsmd-master-agent
+    ```
+  </Tab>
+  <Tab title="GitHub Copilot">
+    ```bash
+    /specsmd-master-agent
+    ```
+  </Tab>
+</Tabs>
+
+Then type:
+
+```
+project-init
+```
+
+This guides you through establishing:
+
+<Steps>
+  <Step title="Tech Stack">
+    Languages, frameworks, databases, infrastructure
+  </Step>
+  <Step title="Coding Standards">
+    Formatting, linting, naming, testing strategy
+  </Step>
+  <Step title="System Architecture">
+    Architecture style, API design, state management
+  </Step>
+  <Step title="UX Guide (Optional)">
+    Design system, styling, accessibility
+  </Step>
+  <Step title="API Conventions (Optional)">
+    API style, versioning, response formats
+  </Step>
+</Steps>
+
+## Create Your First Intent
+
+An **Intent** is your high-level goal:
+
+- "User authentication system"
+- "Product catalog with search"
+- "Payment processing integration"
+
+```bash
+/specsmd-inception-agent intent-create
+```
+
+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
+/specsmd-inception-agent bolt-plan
+
+# Execute a bolt
+/specsmd-construction-agent bolt-start
+```
+
+Each bolt goes through validated stages:
+
+<CardGroup cols={2}>
+  <Card title="1. Domain Model" icon="diagram-project">
+    Model business logic using DDD principles
+  </Card>
+  <Card title="2. Technical Design" icon="compass-drafting">
+    Apply patterns and make architecture decisions
+  </Card>
+  <Card title="3. ADR Analysis" icon="file-lines">
+    Document significant decisions (optional)
+  </Card>
+  <Card title="4. Implement" icon="code">
+    Generate production code
+  </Card>
+  <Card title="5. Test" icon="vial">
+    Verify correctness with automated tests
+  </Card>
+</CardGroup>
+
+<Warning>
+  Human validation happens at each checkpoint. This ensures errors are caught early before cascading downstream.
+</Warning>
+
+## Project Structure After Init
+
+```
+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
+```
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card
+    title="What is AI-DLC?"
+    icon="lightbulb"
+    href="/methodology/what-is-ai-dlc"
+  >
+    Understand the methodology behind specs.md
+  </Card>
+  <Card
+    title="Core Concepts"
+    icon="cube"
+    href="/core-concepts/intents"
+  >
+    Deep dive into Intents, Units, and Bolts
+  </Card>
+</CardGroup>