project-iris 0.0.1

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

@@ -0,0 +1,268 @@
+---
+title: Bolts
+description: Time-boxed execution sessions for rapid implementation
+---
+
+## What is a Bolt?
+
+A **Bolt** is a time-boxed execution session in AI-DLC, designed for rapid implementation. Unlike Sprints (weeks), Bolts are completed in **hours to days**. Each bolt encapsulates a well-defined scope of work scoped to a Unit.
+
+<Info>
+  The term "Bolt" emphasizes speed and precision - like a bolt of lightning, work happens fast but with focused energy. Bolts are analogous to Sprints in Scrum, but optimized for AI-driven development.
+</Info>
+
+## Bolt Characteristics
+
+<CardGroup cols={2}>
+  <Card title="Rapid" icon="bolt">
+    Hours to days, not weeks
+  </Card>
+  <Card title="Focused" icon="bullseye">
+    One story or small set of related stories
+  </Card>
+  <Card title="Stage-Gated" icon="door-open">
+    Validated checkpoints prevent errors
+  </Card>
+  <Card title="Complete" icon="check-double">
+    Produces working, tested code
+  </Card>
+</CardGroup>
+
+## Bolt Types
+
+specs.md currently supports two bolt types:
+
+| Type | Best For | Stages |
+|------|----------|--------|
+| **DDD Construction** | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
+| **Simple Construction** | UI, integrations, utilities | Plan → Implement → Test |
+
+### Choosing a Bolt Type
+
+<AccordionGroup>
+  <Accordion title="Use DDD Construction Bolt when...">
+    - Building complex domain logic with business rules
+    - Creating bounded contexts with rich domain models
+    - Implementing services that require domain expertise
+    - Working on core business functionality
+  </Accordion>
+  <Accordion title="Use Simple Construction Bolt when...">
+    - Building frontend pages and components
+    - Creating simple CRUD endpoints
+    - Integrating with external APIs
+    - Writing utilities and helper modules
+    - Building CLI commands or scripts
+  </Accordion>
+  </AccordionGroup>
+
+## DDD Construction Bolt
+
+The most comprehensive bolt type, used for complex domain logic:
+
+<Steps>
+  <Step title="Domain Model">
+    Model business logic using DDD principles:
+    - Identify aggregates, entities, value objects
+    - Define domain events and commands
+    - Establish ubiquitous language
+  </Step>
+  <Step title="Technical Design">
+    Apply patterns and make architecture decisions:
+    - Choose implementation patterns
+    - Define interfaces and contracts
+    - Plan data structures and APIs
+  </Step>
+  <Step title="ADR Analysis">
+    Document significant decisions:
+    - Context and problem
+    - Options considered
+    - Decision and rationale
+  </Step>
+  <Step title="Implement">
+    Generate production code:
+    - Follow coding standards
+    - Apply design patterns
+    - Write clean, documented code
+  </Step>
+  <Step title="Test">
+    Verify correctness:
+    - Unit tests
+    - Integration tests
+    - Acceptance tests
+  </Step>
+</Steps>
+
+## Simple Construction Bolt
+
+A lightweight bolt for UI, integrations, and utilities:
+
+<Steps>
+  <Step title="Plan">
+    Define what to build:
+    - Review stories and requirements
+    - List specific deliverables
+    - Identify dependencies
+    - Define acceptance criteria
+  </Step>
+  <Step title="Implement">
+    Write the code:
+    - Setup file structure
+    - Implement core functionality
+    - Handle edge cases
+    - Add documentation
+  </Step>
+  <Step title="Test">
+    Verify the implementation:
+    - Write unit tests
+    - Run test suite
+    - Verify acceptance criteria
+    - Document results
+  </Step>
+</Steps>
+
+## Human Checkpoints
+
+<Warning>
+  Human validation happens at each checkpoint. You cannot proceed to the next stage without approval. This is the "Human Oversight as Loss Function" principle - catching errors early before they cascade.
+</Warning>
+
+### DDD Construction Checkpoints
+
+```mermaid
+flowchart LR
+    subgraph Stages
+        M[Model] --> D[Design] --> A[ADR] --> I[Implement] --> T[Test]
+    end
+
+    subgraph Gates
+        M -.-> G1[Human Review]
+        D -.-> G2[Human Review]
+        A -.-> G3[Human Review]
+        I -.-> G4[Human Review]
+        T -.-> G5[Human Review]
+    end
+
+    style M fill:#818CF8,stroke:#6366F1,color:#fff
+    style D fill:#818CF8,stroke:#6366F1,color:#fff
+    style A fill:#818CF8,stroke:#6366F1,color:#fff
+    style I fill:#34D399,stroke:#10B981,color:#fff
+    style T fill:#FBBF24,stroke:#F59E0B,color:#fff
+    style G1 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G2 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G3 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G4 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G5 fill:#F472B6,stroke:#EC4899,color:#fff
+```
+
+### Simple Construction Checkpoints
+
+```mermaid
+flowchart LR
+    subgraph Stages
+        P[Plan] --> I[Implement] --> T[Test]
+    end
+
+    subgraph Gates
+        P -.-> G1[Human Review]
+        I -.-> G2[Human Review]
+        T -.-> G3[Human Review]
+    end
+
+    style P fill:#818CF8,stroke:#6366F1,color:#fff
+    style I fill:#34D399,stroke:#10B981,color:#fff
+    style T fill:#FBBF24,stroke:#F59E0B,color:#fff
+    style G1 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G2 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G3 fill:#F472B6,stroke:#EC4899,color:#fff
+```
+
+## Executing Bolts
+
+Start a bolt with the Construction Agent:
+
+```bash
+/specsmd-construction-agent --unit="my-unit"
+```
+
+The agent will:
+
+1. Show available bolts for the unit
+2. Ask which bolt to work on
+3. Guide you through each stage
+4. Generate artifacts at each step
+5. Wait for your approval at gates
+6. Record progress in the Memory Bank
+
+## Bolt Artifacts
+
+Each bolt produces artifacts stored in the Memory Bank:
+
+<Tabs>
+  <Tab title="DDD Construction">
+    ```
+    memory-bank/bolts/{bolt-id}/
+    ├── bolt.md                    # Bolt metadata and state
+    ├── ddd-01-domain-model.md     # Domain model
+    ├── ddd-02-technical-design.md # Technical design
+    ├── adr-*.md                   # Architecture Decision Records (optional)
+    └── ddd-03-test-report.md      # Test results
+    ```
+  </Tab>
+  <Tab title="Simple Construction">
+    ```
+    memory-bank/bolts/{bolt-id}/
+    ├── bolt.md                    # Bolt metadata and state
+    ├── implementation-plan.md     # Plan from Stage 1
+    ├── implementation-walkthrough.md # Developer notes from Stage 2
+    └── test-walkthrough.md        # Test results from Stage 3
+    ```
+  </Tab>
+</Tabs>
+
+## Bolt Commands
+
+| Command | Purpose |
+|---------|---------|
+| `bolt-list` | List all bolts in unit |
+| `bolt-start` | Start or continue a bolt |
+| `bolt-status` | Check current progress |
+| `bolt-replan` | Replan if scope changed |
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Keep Bolts Small">
+    A bolt should complete in hours to a few days. If it's taking longer, the scope is too big - split it into multiple bolts.
+  </Accordion>
+  <Accordion title="Choose the Right Bolt Type">
+    Use DDD for complex domain logic, Simple for UI/utilities. Don't over-engineer simple tasks.
+  </Accordion>
+  <Accordion title="Don't Skip Stages">
+    Each stage builds on the previous. Skipping creates technical debt and increases risk.
+  </Accordion>
+  <Accordion title="Validate Thoroughly">
+    Use gate reviews to catch issues early. It's cheaper to fix problems in design than in code.
+  </Accordion>
+  <Accordion title="Document Decisions">
+    ADRs capture the "why" behind decisions. Future you will thank present you.
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card
+    title="Memory Bank"
+    icon="arrow-right"
+    href="/core-concepts/memory-bank"
+  >
+    Learn how artifacts are persisted and connected
+  </Card>
+  <Card
+    title="Bolt Types Guide"
+    icon="book"
+    href="/guides/bolt-types"
+  >
+    Detailed guide on choosing and using bolt types
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,164 @@
+---
+title: Intents
+description: High-level statements of purpose that drive development
+---
+
+## What is an Intent?
+
+An **Intent** is 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.
+
+<Info>
+  Think of an Intent as the answer to "What do we want to build?" without getting into the details of "How do we build it?"
+</Info>
+
+## Examples of Intents
+
+Good intents are clear, outcome-focused, and appropriately scoped:
+
+<CardGroup cols={2}>
+  <Card title="User Authentication System" icon="lock">
+    Enable users to securely register, login, and manage their accounts
+  </Card>
+  <Card title="Product Catalog with Search" icon="magnifying-glass">
+    Allow customers to browse and search products with filters
+  </Card>
+  <Card title="Payment Processing" icon="credit-card">
+    Integrate payment gateway for secure transactions
+  </Card>
+  <Card title="Real-time Notifications" icon="bell">
+    Push notifications to users for important events
+  </Card>
+</CardGroup>
+
+## Intent Structure
+
+When captured, an Intent becomes a directory in your Memory Bank:
+
+```
+memory-bank/intents/{intent-name}/
+├── requirements.md      # User stories, acceptance criteria, NFRs
+├── system-context.md    # Boundaries, interfaces, constraints
+└── units/               # Decomposed units
+    ├── {unit-1}/
+    └── {unit-2}/
+```
+
+## Creating an Intent
+
+Use the Inception Agent to create intents:
+
+```bash
+/specsmd-inception-agent intent-create
+```
+
+The agent will guide you through:
+
+<Steps>
+  <Step title="Describe Your Goal">
+    Explain what you want to achieve in plain language
+  </Step>
+  <Step title="Answer Clarifying Questions">
+    The AI asks questions to minimize ambiguity
+  </Step>
+  <Step title="Review Requirements">
+    Validate the generated user stories and NFRs
+  </Step>
+  <Step title="Define Context">
+    Establish system boundaries and constraints
+  </Step>
+</Steps>
+
+## Intent vs Epic
+
+| Aspect | Agile Epic | AI-DLC Intent |
+|--------|------------|---------------|
+| **Definition** | Large body of work | Statement of purpose |
+| **Decomposition** | Manual by team | AI-powered |
+| **Output** | User stories | Units with stories |
+| **Context** | Lost over time | Persisted in Memory Bank |
+
+## Requirements Document
+
+The `requirements.md` file contains:
+
+```markdown
+# Intent: User Authentication System
+
+## User Stories
+
+### US-001: User Registration
+As a new user, I want to register with email and password
+so that I can create an account.
+
+**Acceptance Criteria:**
+- [ ] Email validation
+- [ ] Password strength requirements
+- [ ] Confirmation email sent
+
+### US-002: User Login
+...
+
+## Non-Functional Requirements
+
+### NFR-001: Security
+- Passwords must be hashed with bcrypt
+- Sessions expire after 24 hours
+- Rate limiting on login attempts
+
+### NFR-002: Performance
+- Login response time < 500ms
+- Support 1000 concurrent users
+```
+
+## System Context
+
+The `system-context.md` defines boundaries:
+
+```markdown
+# System Context: User Authentication
+
+## In Scope
+- User registration and login
+- Password reset flow
+- Session management
+
+## Out of Scope
+- Social login (OAuth) - future intent
+- Multi-factor authentication - future intent
+
+## Interfaces
+- REST API for frontend
+- Database for user storage
+- Email service for notifications
+
+## Constraints
+- Must use existing PostgreSQL database
+- Must integrate with current session store
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Keep Intents Focused">
+    One intent should represent one cohesive goal. If you find yourself saying "and also...", consider splitting into multiple intents.
+  </Accordion>
+  <Accordion title="Be Outcome-Oriented">
+    Focus on what users will be able to do, not on technical implementation details.
+  </Accordion>
+  <Accordion title="Include Context">
+    Provide relevant business context, constraints, and dependencies upfront.
+  </Accordion>
+  <Accordion title="Iterate on Requirements">
+    Requirements will evolve. Use the agent to refine and clarify as you learn more.
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+<Card
+  title="Units"
+  icon="arrow-right"
+  href="/core-concepts/units"
+>
+  Learn how Intents are decomposed into Units
+</Card>

package/src/iris_bundle/frameworks/iris-core/docs.iris.md/core-concepts/memory-bank.mdx

@@ -0,0 +1,209 @@
+---
+title: Memory Bank
+description: File-based storage for all project artifacts with full traceability
+---
+
+## 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 artifacts.
+
+<Info>
+  Unlike traditional documentation that gets stale, the Memory Bank is actively used by agents. It's the source of truth that agents read and write.
+</Info>
+
+## Why Memory Bank?
+
+<CardGroup cols={2}>
+  <Card title="Context Engineering" icon="database">
+    Agents reload context from Memory Bank each session. No more lost knowledge.
+  </Card>
+  <Card title="Traceability" icon="link">
+    Every artifact links to its source. Inception and construction logs provide full traceability after completion.
+  </Card>
+  <Card title="Human Readable" icon="file-lines">
+    All files are Markdown. Review, edit, and version control with Git.
+  </Card>
+  <Card title="AI Accessible" icon="robot">
+    Structured format that agents can parse and update.
+  </Card>
+</CardGroup>
+
+## Structure
+
+After project initialization:
+
+```
+memory-bank/
+├── intents/                   # Your captured intents
+│   └── {intent-name}/
+│       ├── requirements.md
+│       ├── system-context.md
+│       └── units/
+│           └── {unit-name}/
+│               ├── unit-brief.md
+│               ├── stories/
+│               └── bolts/
+├── bolts/                     # Bolt execution records
+│   └── {bolt-id}/
+│       ├── domain-model.md
+│       ├── technical-design.md
+│       └── implementation/
+├── standards/                 # Project standards
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   ├── architecture.md
+│   └── ux-guide.md
+└── operations/                # Deployment context
+    ├── environments.md
+    └── runbooks/
+```
+
+## Artifact Types
+
+### Standards
+
+Project-wide decisions that inform AI code generation:
+
+| File | Purpose |
+|------|---------|
+| `tech-stack.md` | Languages, frameworks, databases |
+| `coding-standards.md` | Formatting, naming, patterns |
+| `architecture.md` | System architecture decisions |
+| `ux-guide.md` | Design system, styling |
+| `api-conventions.md` | API style, versioning |
+
+### Intent Artifacts
+
+Captured requirements and context:
+
+| File | Purpose |
+|------|---------|
+| `requirements.md` | User stories, acceptance criteria, NFRs |
+| `system-context.md` | Boundaries, interfaces, constraints |
+| `units.md` | Unit decomposition overview |
+
+### Unit Artifacts
+
+Work breakdown within an intent:
+
+| File | Purpose |
+|------|---------|
+| `unit-brief.md` | Scope, interfaces, dependencies |
+| `stories/*.md` | Individual user stories |
+| `bolts/*/` | Bolt execution records |
+
+### Bolt Artifacts
+
+Implementation records:
+
+| File | Purpose |
+|------|---------|
+| `domain-model.md` | DDD artifacts |
+| `technical-design.md` | Architecture decisions |
+| `adr-*.md` | Architectural Decision Records |
+| `implementation/` | Generated code |
+| `tests/` | Test files |
+
+## Traceability
+
+Artifacts link to each other using references:
+
+```markdown
+# Technical Design: User Registration
+
+## Source
+- Intent: user-authentication
+- Unit: user-registration  
+- Story: US-001
+
+## Related ADRs
+- [ADR-001: Password Hashing Algorithm](./adr-001.md)
+
+## Implementation
+- [src/auth/registration.ts](../../src/auth/registration.ts)
+```
+
+## Agent Interaction
+
+Agents read and write to the Memory Bank:
+
+<Steps>
+  <Step title="Context Loading">
+    Agent reads relevant artifacts at session start
+  </Step>
+  <Step title="Work Execution">
+    Agent generates new artifacts during work
+  </Step>
+  <Step title="Artifact Storage">
+    Agent writes artifacts to Memory Bank
+  </Step>
+  <Step title="Reference Linking">
+    Agent updates cross-references
+  </Step>
+</Steps>
+
+## Version Control
+
+The Memory Bank is designed for Git:
+
+```bash
+# Track all artifacts
+git add memory-bank/
+
+# Meaningful commit messages
+git commit -m "feat(auth): Complete user registration bolt"
+
+# Review changes in PRs
+git diff memory-bank/intents/auth/
+```
+
+<Warning>
+  Commit Memory Bank changes along with code changes. This maintains the connection between decisions and implementation.
+</Warning>
+
+## Schema
+
+The Memory Bank follows a schema defined in `.specsmd/aidlc/memory-bank.yaml`:
+
+```yaml
+version: "1.0"
+structure:
+  intents:
+    pattern: "{intent-name}/"
+    required:
+      - requirements.md
+      - system-context.md
+    optional:
+      - units/
+  standards:
+    required:
+      - tech-stack.md
+      - coding-standards.md
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Keep Artifacts Current">
+    Update artifacts when decisions change. Stale documentation is worse than no documentation.
+  </Accordion>
+  <Accordion title="Use Consistent Formatting">
+    Follow the templates. Consistent structure helps agents parse content.
+  </Accordion>
+  <Accordion title="Link Generously">
+    Cross-reference related artifacts. Traceability prevents knowledge silos.
+  </Accordion>
+  <Accordion title="Version with Code">
+    Commit Memory Bank changes with related code. They belong together.
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+<Card
+  title="Standards"
+  icon="arrow-right"
+  href="/core-concepts/standards"
+>
+  Learn about project standards that guide AI generation
+</Card>