project-iris 0.0.1

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

@@ -0,0 +1,187 @@
+---
+title: Agents Overview
+description: Four specialized agents that guide the AI-DLC development lifecycle
+---
+
+## The Agent System
+
+specs.md provides four specialized agents that guide you through the entire development lifecycle. Each agent has a focused responsibility and set of commands.
+
+## Agent Architecture
+
+```mermaid
+flowchart TB
+    MA[Master Agent<br/>Orchestrates] --> IA[Inception Agent]
+    MA --> CA[Construction Agent]
+    MA --> OA[Operations Agent]
+
+    IA --> CA
+    CA --> OA
+
+    style MA fill:#8B5CF6,stroke:#7C3AED,color:#fff
+    style IA fill:#818CF8,stroke:#6366F1,color:#fff
+    style CA fill:#34D399,stroke:#10B981,color:#fff
+    style OA fill:#FBBF24,stroke:#F59E0B,color:#fff
+```
+
+## Agent Responsibilities
+
+<CardGroup cols={2}>
+  <Card title="Master Agent" icon="crown" href="/agents/master-agent">
+    Orchestrates the overall flow, routes requests, maintains project awareness
+  </Card>
+  <Card title="Inception Agent" icon="lightbulb" href="/agents/inception-agent">
+    Captures intents, elaborates requirements, decomposes into units
+  </Card>
+  <Card title="Construction Agent" icon="hammer" href="/agents/construction-agent">
+    Executes bolts, builds code, runs tests through validated stages
+  </Card>
+  <Card title="Operations Agent" icon="server" href="/agents/operations-agent">
+    Deploys, verifies, and monitors systems in production
+  </Card>
+</CardGroup>
+
+## Invoking Agents
+
+<Warning>
+  **These are NOT command-line commands.** These are prompts you type in your AI coding tool's chat interface (Claude Code, Cursor, Copilot, etc.).
+</Warning>
+
+### How to Use
+
+1. Open your AI coding tool (Claude Code, Cursor, GitHub Copilot)
+2. Start a chat/conversation
+3. Type the agent prompt to activate it
+
+<Tabs>
+  <Tab title="Claude Code">
+    Type in Claude Code's chat:
+    ```
+    /specsmd-master-agent
+    /specsmd-inception-agent
+    /specsmd-construction-agent
+    /specsmd-operations-agent
+    ```
+  </Tab>
+  <Tab title="Cursor">
+    Type in Cursor's chat (either format works):
+    ```
+    /specsmd-master-agent
+    /specsmd-inception-agent
+    /specsmd-construction-agent
+    /specsmd-operations-agent
+    ```
+    Or use the `@` prefix:
+    ```
+    @specsmd-master-agent
+    @specsmd-inception-agent
+    @specsmd-construction-agent
+    @specsmd-operations-agent
+    ```
+  </Tab>
+  <Tab title="GitHub Copilot">
+    Type in Copilot's chat:
+    ```
+    /specsmd-master-agent
+    /specsmd-inception-agent
+    /specsmd-construction-agent
+    /specsmd-operations-agent
+    ```
+  </Tab>
+</Tabs>
+
+## Agent Session Lifecycle
+
+Each agent session follows a pattern:
+
+<Steps>
+  <Step title="Context Loading">
+    Agent reads relevant artifacts from Memory Bank
+  </Step>
+  <Step title="Command Execution">
+    Agent performs the requested command
+  </Step>
+  <Step title="Human Validation">
+    Agent pauses for approval at checkpoints
+  </Step>
+  <Step title="Artifact Storage">
+    Agent writes results back to Memory Bank
+  </Step>
+</Steps>
+
+<Warning>
+  Each agent invocation starts fresh. Agents read context from the Memory Bank at startup. Ensure artifacts are saved after each step.
+</Warning>
+
+## Command Reference
+
+### 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 specs.md question |
+
+### 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
+
+| 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
+
+| Command | Purpose |
+|---------|---------|
+| `build` | Build the project |
+| `deploy` | Deploy to environment |
+| `verify` | Verify deployment |
+| `monitor` | Set up monitoring |
+
+## Routing Between Agents
+
+The Master Agent can route you to the appropriate agent:
+
+```
+> I want to add a new feature
+
+Master Agent: That sounds like a new Intent. Let me route you 
+to the Inception Agent.
+
+/specsmd-inception-agent intent-create
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Start with Master">
+    When unsure where to begin, start with the Master Agent. It will guide you to the right place.
+  </Accordion>
+  <Accordion title="Complete Artifacts">
+    Finish and save artifacts before switching agents. Context is loaded from Memory Bank.
+  </Accordion>
+  <Accordion title="Follow the Flow">
+    Inception → Construction → Operations. Don't skip phases.
+  </Accordion>
+  <Accordion title="Use Commands">
+    Each agent has specific commands. Use them rather than free-form requests.
+  </Accordion>
+</AccordionGroup>

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

@@ -0,0 +1,136 @@
+---
+title: Pluggable Flows
+description: Understanding the specs.md flow architecture
+---
+
+## Framework Architecture
+
+specs.md is built as a **pluggable framework** where development methodologies are implemented as **flows**. This architecture allows different teams to use different development approaches.
+
+```mermaid
+flowchart TB
+    subgraph Framework[specs.md Framework]
+        subgraph Flows[Flows]
+            subgraph AIDLC[AI-DLC Flow]
+                MB[Memory Bank]
+                ST[Standards]
+                AS[Agents]
+                TM[Templates]
+            end
+            FF[Future Flows...]
+        end
+    end
+
+    style Framework fill:#1E293B,stroke:#334155,color:#fff
+    style Flows fill:#052E16,stroke:#22C55E,color:#fff
+    style AIDLC fill:#22C55E,stroke:#16A34A,color:#fff
+    style FF fill:#475569,stroke:#64748B,color:#fff,stroke-dasharray: 5 5
+```
+
+## What is a Flow?
+
+A **flow** is a complete development methodology implementation that includes:
+
+<CardGroup cols={2}>
+  <Card title="Phases" icon="diagram-project">
+    Sequential stages of development (e.g., Inception, Construction, Operations)
+  </Card>
+  <Card title="Agents" icon="robot">
+    Specialized AI agents for each phase
+  </Card>
+  <Card title="Templates" icon="file-code">
+    Structured artifacts and outputs
+  </Card>
+  <Card title="Bolt Types" icon="bolt">
+    Execution patterns for different work types
+  </Card>
+</CardGroup>
+
+## Available Flows
+
+Each flow implements a specific development approach with its own components:
+
+| Flow | Status | Description |
+|------|--------|-------------|
+| **AI-DLC** | Implemented | AI-Driven Development Lifecycle from AWS |
+| *(Future)* | Planned | Additional methodologies can be added |
+
+## AI-DLC Flow
+
+AI-DLC (AI-Driven Development Lifecycle) is the first flow implemented in specs.md. It implements the methodology developed by AWS.
+
+### Three Phases
+
+```mermaid
+flowchart TB
+    MA[Master Agent<br/>Orchestrates & Navigates] --> IA[Inception]
+    MA --> CA[Construction]
+    MA --> OA[Operations]
+
+    IA --> CA --> OA
+
+    style MA fill:#8B5CF6,stroke:#7C3AED,color:#fff
+    style IA fill:#818CF8,stroke:#6366F1,color:#fff
+    style CA fill:#34D399,stroke:#10B981,color:#fff
+    style OA fill:#FBBF24,stroke:#F59E0B,color:#fff
+```
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| **Inception** | Inception Agent | Capture intents, elaborate requirements, decompose into units |
+| **Construction** | Construction Agent | Execute bolts through validated stages |
+| **Operations** | Operations Agent | Deploy, verify, and monitor |
+
+### Bolt Types
+
+The AI-DLC flow supports two bolt types:
+
+| Type | Best For | Stages |
+|------|----------|--------|
+| **DDD Construction** | Complex domain logic, business rules | Model → Design → ADR → Code → Test |
+| **Simple Construction** | UI, integrations, utilities | Plan → Implement → Test |
+
+## Creating Custom Flows
+
+<Info>
+  Custom flow creation is a planned feature. The architecture is designed to support multiple flows, with AI-DLC as the reference implementation.
+</Info>
+
+A custom flow would include:
+
+1. **Flow Definition** - Metadata, phases, and configuration
+2. **Phase Agents** - Specialized agents for each phase
+3. **Bolt Types** - Custom execution patterns
+4. **Templates** - Artifacts specific to the methodology
+
+## Tool Integration
+
+Flows integrate with AI coding tools through the shared core:
+
+| Tool | Integration Method |
+|------|-------------------|
+| **Claude Code** | Slash commands in `.claude/commands/` |
+| **Cursor** | Rules in `.cursor/rules/` |
+| **GitHub Copilot** | Agents in `.github/agents/` |
+| **Google Antigravity** | Agents in `.agent/agents/` |
+
+All tools share the same Memory Bank and can work with any installed flow.
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card
+    title="AI-DLC Methodology"
+    icon="arrow-right"
+    href="/methodology/what-is-ai-dlc"
+  >
+    Deep dive into the AI-DLC flow
+  </Card>
+  <Card
+    title="Memory Bank"
+    icon="database"
+    href="/core-concepts/memory-bank"
+  >
+    Learn about the shared artifact storage
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,91 @@
+---
+title: Community
+description: Join the specs.md community - Connect with developers building AI-native software
+---
+
+# Community
+
+Join our growing community of developers building AI-native software with specs.md.
+
+<CardGroup cols={3}>
+  <Card
+    title="Discord"
+    icon="discord"
+    href="https://discord.gg/X8pfZpZHnR"
+  >
+    Join our Discord server to chat with the community, get help, and share your experiences.
+  </Card>
+  <Card
+    title="Zulip"
+    icon="comments"
+    href="https://fabriqa.zulipchat.com/"
+  >
+    Connect with the team on Zulip for discussions and collaboration.
+  </Card>
+  <Card
+    title="X (Twitter)"
+    icon="x-twitter"
+    href="https://x.com/specsmd"
+  >
+    Follow us on X for updates, tips, and announcements.
+  </Card>
+  <Card
+    title="Product Hunt"
+    icon="rocket"
+    href="https://www.producthunt.com/products/specs-md"
+  >
+    Check out our Product Hunt page and leave a review.
+  </Card>
+</CardGroup>
+
+## Featured on Product Hunt
+
+<div style={{fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif', border: '1px solid rgb(224, 224, 224)', borderRadius: '12px', padding: '20px', maxWidth: '500px', background: 'rgb(255, 255, 255)', boxShadow: 'rgba(0, 0, 0, 0.05) 0px 2px 8px'}}>
+  <div style={{display: 'flex', alignItems: 'center', gap: '12px', marginBottom: '12px'}}>
+    <img alt="specs.md" src="https://ph-files.imgix.net/c27cd4d3-2430-4666-bb60-dd29a5646afd.png?auto=format&amp;fit=crop&amp;w=80&amp;h=80" style={{width: '64px', height: '64px', borderRadius: '8px', objectFit: 'cover', flexShrink: 0}} />
+    <div style={{flex: '1 1 0%', minWidth: '0px'}}>
+      <h3 style={{margin: '0px', fontSize: '18px', fontWeight: '600', color: 'rgb(26, 26, 26)', lineHeight: '1.3', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap'}}>specs.md</h3>
+      <p style={{margin: '4px 0px 0px', fontSize: '14px', color: 'rgb(102, 102, 102)', lineHeight: '1.4', overflow: 'hidden', textOverflow: 'ellipsis', display: '-webkit-box', WebkitLineClamp: '2', WebkitBoxOrient: 'vertical'}}>framework for spec-driven AI development with pluggable flow</p>
+    </div>
+  </div>
+  <a href="https://www.producthunt.com/products/specs-md?embed=true&amp;utm_source=embed&amp;utm_medium=post_embed" target="_blank" rel="noopener" style={{display: 'inline-flex', alignItems: 'center', gap: '4px', marginTop: '12px', padding: '8px 16px', background: 'rgb(255, 97, 84)', color: 'rgb(255, 255, 255)', textDecoration: 'none', borderRadius: '8px', fontSize: '14px', fontWeight: '600'}}>Check it out on Product Hunt →</a>
+</div>
+
+## Get Involved
+
+<CardGroup cols={2}>
+  <Card
+    title="GitHub"
+    icon="github"
+    href="https://github.com/fabriqaai/specs.md"
+  >
+    Star the repo, report issues, or contribute to the project.
+  </Card>
+  <Card
+    title="Feedback"
+    icon="comment"
+    href="/feedback"
+  >
+    Share your thoughts and help us improve specs.md.
+  </Card>
+</CardGroup>
+
+## Why Join?
+
+- **Get Help**: Ask questions and get answers from the community and maintainers
+- **Share Knowledge**: Help others and share your AI-DLC experiences
+- **Stay Updated**: Be the first to know about new features and releases
+- **Shape the Future**: Your feedback directly influences the roadmap
+
+## Community Guidelines
+
+We're committed to providing a welcoming and inclusive environment. Please:
+
+- Be respectful and constructive
+- Help others when you can
+- Share your learnings and experiences
+- Report any issues or concerns
+
+<Info>
+  We're just getting started! Join early and help shape the community.
+</Info>

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

@@ -0,0 +1,167 @@
+---
+title: "Compare Spec-Driven Tools"
+description: "How specs.md compares to Spec Kit, BMAD, Kiro, and OpenSpec"
+---
+
+## specs.md: Reimagine Your Development Flow
+
+<Warning>
+**The Main Difference**: specs.md (AI-DLC) is for teams ready to rethink and reimagine their development flows—not just use AI as a copilot for traditional Agile processes.
+
+If you want to keep your existing Agile workflow and add AI assistance, other tools may be a better fit. If you're ready to embrace a new methodology built for the agentic age, specs.md is for you.
+</Warning>
+
+specs.md implements AWS's AI-DLC—a methodology specifically designed for complex systems requiring architectural trade-offs, scalability, and multi-team coordination.
+
+<Info>
+**Coming Soon**: specs.md (Simple Flow) will provide Spec Kit and Kiro-like simple flows for developers who want a lighter entry point before adopting full AI-DLC workflows.
+</Info>
+
+---
+
+## Product Offerings
+
+| Offering | Status | Best For |
+|----------|--------|----------|
+| **specs.md (AI-DLC)** | Available | Complex systems with architectural complexity, trade-offs, multiple teams, regulated orgs |
+| **specs.md (Simple Flow)** | Coming Soon | Simpler projects without complex trade-off management |
+
+---
+
+## Comparison Matrix
+
+| Feature | specs.md | Spec Kit | BMAD | OpenSpec | Kiro |
+|---------|-------------------|----------|------|----------|------|
+| **Target Complexity** | Complex systems | Small-medium | Complex/Enterprise | Any (brownfield-first) | Any |
+| **Type** | Methodology + Framework | Toolkit + Agent Prompts | Multi-agent Framework | Lightweight Framework | Full IDE |
+| **Methodology** | AWS AI-DLC (formal) | Spec Kit SDD | Agentic Agile | OpenSpec SDD | Kiro SDD |
+| **Design Integration** | DDD default (extensible via bolt types) | Constitution file | Optional | Design-agnostic | Design-agnostic |
+| **Rituals** | Mob Elaboration, Mob Construction | None | None | None | None |
+| **Phases** | 3 sequential | 6 sequential | 4 phases | Change-centric | Requirements→Design→Tasks |
+| **Agent Model** | 3 phase-based agents | Prompts for 15+ assistants | 19 role-based agents | AGENTS.md compatible | Built-in + Subagents |
+| **Iteration Cycles** | "Hours or days" (Bolts) | Variable | Variable | Variable | Variable |
+| **Brownfield Support** | Yes (with model elevation) | Yes | Yes | Yes (primary focus) | Yes |
+| **IDE Lock-in** | None (any IDE) | None | None | None | Kiro IDE only |
+| **VS Code Extension** | Yes ([visual dashboard](/getting-started/vscode-extension)) | No | No | CLI dashboard | Built into IDE |
+| **Open Source** | Yes | Yes | Yes | Yes | Partial (Code OSS base, proprietary features) |
+| **Pricing** | Free (OSS) | Free (OSS) | Free (OSS) | Free (OSS) | Free preview → $20-200/mo |
+
+---
+
+## Quick Comparisons
+
+<CardGroup cols={2}>
+  <Card title="vs GitHub Spec Kit" icon="github" href="/compare/vs-speckit">
+    Lightweight toolkit vs full methodology. Learn when to choose each.
+  </Card>
+  <Card title="vs BMAD-Method" icon="users" href="/compare/vs-bmad">
+    Both target complex projects. Compare phase-based vs role-based agents.
+  </Card>
+  <Card title="vs Kiro (AWS)" icon="window" href="/compare/vs-kiro">
+    IDE-integrated vs IDE-agnostic. Compare automation approaches.
+  </Card>
+  <Card title="vs OpenSpec" icon="code-branch" href="/compare/vs-openspec">
+    Full lifecycle vs change-centric. Compare brownfield strategies.
+  </Card>
+</CardGroup>
+
+---
+
+## Key Differentiators
+
+### 1. AI-DLC is a Formal AWS Methodology
+
+Unlike generic "spec-driven development," AI-DLC is defined by AWS with specific phases, rituals, and artifacts. specs.md is a faithful implementation—not an interpretation.
+
+### 2. DDD as Default, Extensible via Bolt Types
+
+Agile frameworks leave design techniques optional. AI-DLC integrates Domain-Driven Design as its default—AI applies DDD principles during decomposition, developers validate.
+
+**Extensible**: Use bolt types to add other methodologies like BDD, TDD, or model your own construction flow. DDD is the default, not a limitation.
+
+### 3. Bolts: Batched Stories with Full Traceability
+
+Unlike other tools with variable iteration cycles, specs.md uses **Bolts**—planned batches of related stories executed together by an agent. Each Bolt follows DDD steps during execution, and artifacts created during construction provide full traceability of what was built and how.
+
+```
+Intent → Units → Stories → Bolt (batched stories)
+                              ↓
+                    DDD Construction Steps
+                              ↓
+                    Traceable Artifacts
+```
+
+### 4. Reversed Conversation Direction
+
+In AI-DLC, **AI initiates and directs conversations**. AI proposes breakdown, trade-offs, designs. Humans validate and approve. This is the opposite of most tools where humans prompt AI.
+
+### 5. Mob Rituals for Team Alignment
+
+Mob Elaboration (Inception) and Mob Construction condense weeks of sequential work into hours while achieving deep alignment between team and AI.
+
+### 6. Built for Complex Systems
+
+<Warning>
+AI-DLC explicitly targets systems with "continuous functional adaptability, high architectural complexity, numerous trade-offs management, scalability, integration and customization requirements."
+
+Simpler projects → specs.md (Simple Flow) coming soon.
+</Warning>
+
+---
+
+## Vendor Lock-in
+
+| Tool | Lock-in Risk |
+|------|-------------|
+| specs.md | None - works with any IDE/AI |
+| Spec Kit | None - works with 15+ AI assistants |
+| BMAD | None - works with any IDE/AI |
+| OpenSpec | None - AGENTS.md compatible with any tool |
+| Kiro | **High** - Kiro IDE + Claude Sonnet only |
+
+---
+
+## Cost Comparison
+
+| Tool | Cost |
+|------|------|
+| specs.md | $0 + API tokens |
+| Spec Kit | $0 + API tokens |
+| BMAD | $0 + API tokens |
+| OpenSpec | $0 + API tokens |
+| Kiro Pro | $20/month (225 vibe + 125 spec/mo) |
+| Kiro Pro+ | $39/month (450 vibe + 250 spec/mo) |
+| Kiro Power | $200/month (2,250 vibe + 1,250 spec/mo) |
+
+---
+
+## Roadmap
+
+We're building new capabilities based on your feedback:
+
+| Feature | Status | Description |
+|---------|--------|-------------|
+| **Full AI-DLC** | Available | Complete Inception → Construction → Operations |
+| **Simple Flow** | Coming Soon | Kiro-style Requirements → Design → Tasks workflow |
+| **Brownfield Support** | Coming Soon | Full support for existing codebases with model elevation |
+
+<Info>
+Start simple, graduate to full AI-DLC when your project complexity demands it.
+</Info>
+
+<Card title="Request a Feature" icon="message" href="/feedback">
+Have a feature request or feedback? Let us know what you'd like to see in specs.md.
+</Card>
+
+---
+
+## Further Reading
+
+<CardGroup cols={2}>
+  <Card title="The AI-Native SDLC: Reimagined" icon="bolt" href="/methodology/sdlc-reimagined">
+    Why the Agentic Age demands a new methodology
+  </Card>
+  <Card title="What is AI-DLC?" icon="circle-question" href="/methodology/what-is-ai-dlc">
+    Deep dive into AI-DLC methodology
+  </Card>
+</CardGroup>