project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/003-memory-bank-system/system-context.md

@@ -0,0 +1,181 @@
+# System Context: Memory Bank System
+
+## Overview
+
+This document defines the boundaries and integration points for the Memory Bank System.
+
+---
+
+## System Boundary
+
+```text
+┌────────────────────────────────────────────────────────────────────┐
+│                         Agent Layer                                 │
+│  ┌────────────┐   ┌────────────┐   ┌────────────┐   ┌──────────┐  │
+│  │   Master   │   │ Inception  │   │Construction│   │Operations│  │
+│  │   Agent    │   │   Agent    │   │   Agent    │   │  Agent   │  │
+│  └─────┬──────┘   └─────┬──────┘   └─────┬──────┘   └────┬─────┘  │
+│        │                │                │               │         │
+│        └────────────────┴───────┬────────┴───────────────┘         │
+│                                 │                                   │
+│                     Read config │ on activation                     │
+└─────────────────────────────────┼───────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Memory Bank System                              │
+│  ┌─────────────────────────────────────────────────────────────┐   │
+│  │               .irismd/memory-bank.yaml                      │   │
+│  │                    (Configuration)                           │   │
+│  │  ┌─────────────┐  ┌───────────┐  ┌───────────────────────┐  │   │
+│  │  │  structure  │  │  schema   │  │      ownership        │  │   │
+│  │  │   section   │  │  section  │  │       section         │  │   │
+│  │  └─────────────┘  └───────────┘  └───────────────────────┘  │   │
+│  └─────────────────────────────────────────────────────────────┘   │
+│                                 │                                   │
+│                    Defines paths│for                                │
+│                                 ▼                                   │
+│  ┌─────────────────────────────────────────────────────────────┐   │
+│  │                   memory-bank/ Directory                     │   │
+│  │  ┌──────────┐  ┌────────┐  ┌─────────┐  ┌───────────────┐   │   │
+│  │  │ intents/ │  │ bolts/ │  │standards│  │  operations/  │   │   │
+│  │  │          │  │        │  │         │  │               │   │   │
+│  │  │  units/  │  │        │  │         │  │               │   │   │
+│  │  └──────────┘  └────────┘  └─────────┘  └───────────────┘   │   │
+│  └─────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  │ Stored in
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                        File System (Git Repo)                       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## External Systems
+
+### File System
+
+- **Type**: Local filesystem
+- **Interface**: Node.js fs/fs-extra operations
+- **Constraint**: Must be git-friendly (no binary files, no large files)
+
+### Git
+
+- **Type**: Version control system
+- **Interface**: User's git workflow
+- **Constraint**: All Memory Bank files must be safe to commit
+
+---
+
+## Internal Components
+
+### Configuration File (memory-bank.yaml)
+
+- **Location**: `.irismd/memory-bank.yaml`
+- **Purpose**: Single source of truth for artifact paths and agent ownership
+- **Consumers**: All agents read this on activation
+
+### Structure Section
+
+Defines the conceptual organization:
+
+```yaml
+structure:
+  - path: intents/
+    description: "Intents (Features/Capabilities)"
+  - path: bolts/
+    description: "Execution Instances (Bolt Sessions)"
+```
+
+### Schema Section
+
+Provides path templates:
+
+```yaml
+schema:
+  intents: "memory-bank/intents/{intent-name}/"
+  units: "memory-bank/intents/{intent-name}/units/{unit-name}/"
+  bolts: "memory-bank/bolts/{bolt-id}.md"
+```
+
+### Ownership Section
+
+Maps agents to artifact types:
+
+```yaml
+ownership:
+  inception: [intents, units, stories]
+  construction: [units, bolts]
+  operations: [operations]
+```
+
+---
+
+## Data Flow
+
+### Agent Activation
+
+```text
+Agent starts
+    │
+    ▼
+Read .irismd/memory-bank.yaml
+    │
+    ▼
+Parse structure, schema, ownership
+    │
+    ▼
+Resolve path templates to actual paths
+    │
+    ▼
+Load relevant artifacts based on phase
+    │
+    ▼
+Execute skills with context
+```
+
+### Artifact Creation
+
+```text
+Skill needs to create artifact
+    │
+    ▼
+Read schema template from memory-bank.yaml
+    │
+    ▼
+Resolve path with actual values
+    │
+    ▼
+Create directories if needed
+    │
+    ▼
+Write markdown file from template
+```
+
+---
+
+## Integration Contracts
+
+### Configuration Format
+
+- YAML format with structure, schema, and ownership sections
+- All paths relative to project root
+- Path templates use `{variable-name}` syntax
+
+### Artifact Format
+
+- All artifacts are markdown files
+- Artifacts may have YAML frontmatter for metadata
+- Human-readable and editable
+
+---
+
+## Constraints
+
+- No database (file-based only)
+- No caching between sessions (agents are stateless)
+- All artifacts must be human-readable
+- All artifacts must be git-safe (no secrets)

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/003-memory-bank-system/units/artifact-storage/unit-brief.md

@@ -0,0 +1,192 @@
+# Unit Brief: Artifact Storage
+
+## Overview
+
+The Artifact Storage unit handles the actual reading and writing of markdown artifacts to the filesystem following the schema defined in memory-bank.yaml.
+
+---
+
+## Scope
+
+### In Scope
+
+- Creating directories on-demand
+- Writing markdown artifacts following templates
+- Reading artifacts from resolved paths
+- Maintaining git-friendly file structure
+
+### Out of Scope
+
+- Schema definition (handled by configuration-schema)
+- Agent context loading (handled by context-loader)
+
+---
+
+## Technical Context
+
+### Storage Location
+
+`memory-bank/` directory in project root
+
+### File Format
+
+All artifacts are stored as markdown files (.md) with optional YAML frontmatter.
+
+---
+
+## Implementation Details
+
+### Directory Structure
+
+After full usage, the memory bank looks like:
+
+```text
+memory-bank/
+├── intents/
+│   ├── 001-user-auth/
+│   │   ├── requirements.md
+│   │   ├── system-context.md
+│   │   ├── inception-summary.md
+│   │   └── units/
+│   │       ├── auth-service/
+│   │       │   ├── unit-brief.md
+│   │       │   └── stories/
+│   │       │       ├── US-001.md
+│   │       │       └── US-002.md
+│   │       └── user-service/
+│   │           └── unit-brief.md
+│   └── 002-payment/
+│       └── requirements.md
+├── bolts/
+│   ├── BOLT-2024-001-auth-registration.md
+│   └── BOLT-2024-002-auth-login.md
+├── standards/
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   └── system-architecture.md
+└── operations/
+    └── deployment-context.md
+```
+
+### Artifact Types and Templates
+
+Each artifact type has a corresponding template in `.irismd/aidlc/templates/`.
+
+| Artifact | Template Location | Created By |
+|----------|-------------------|------------|
+| Intent requirements | `templates/inception/requirements-template.md` | Inception Agent |
+| Intent inception summary | `templates/inception/inception-summary-template.md` | Inception Agent |
+| System context | `templates/inception/context-template.md` | Inception Agent |
+| Unit brief | `templates/inception/unit-brief-template.md` | Inception Agent |
+| Story | `templates/inception/story-template.md` | Inception Agent |
+| Bolt | `templates/construction/bolt-template.md` | Construction Agent |
+| Standards | `templates/standards/{standard}-template.md` | Master Agent |
+
+### Artifact File Format
+
+Standard artifact format with optional frontmatter:
+
+```markdown
+---
+# Optional YAML frontmatter for metadata
+status: draft
+created: 2024-01-15
+updated: 2024-01-16
+---
+
+# Artifact Title
+
+## Section 1
+
+Content...
+
+## Section 2
+
+Content...
+```
+
+### Write Operation
+
+```text
+function writeArtifact(templateKey, variables, content):
+    1. Resolve path using schema template + variables
+    2. Ensure parent directories exist (fs.ensureDir)
+    3. If template exists:
+       - Read template from templates/
+       - Merge content into template
+    4. Write content to resolved path
+    5. Return success/failure
+```
+
+### Read Operation
+
+```text
+function readArtifact(templateKey, variables):
+    1. Resolve path using schema template + variables
+    2. Check if file exists
+    3. If exists: read and return content
+    4. If not exists: return null or throw
+```
+
+### List Operation
+
+```text
+function listArtifacts(templateKey):
+    1. Get base path from schema (without variables)
+    2. List all directories/files under path
+    3. Return list of artifact identifiers
+```
+
+---
+
+## Git-Friendliness Requirements
+
+1. **No binary files** - All artifacts are text/markdown
+2. **No large files** - Artifacts should be concise
+3. **No secrets** - Sensitive data never stored in memory bank
+4. **Line-based diffs** - Markdown format enables clean diffs
+5. **UTF-8 encoding** - Consistent encoding for all files
+
+---
+
+## Error Handling
+
+| Error Case | Handling |
+|------------|----------|
+| Directory doesn't exist | Create on-demand |
+| File doesn't exist (read) | Return null, let agent handle |
+| Permission error | Surface error to agent |
+| Template not found | Use default content structure |
+| Invalid path characters | Reject, suggest correction |
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Directory Creation
+
+- GIVEN path `memory-bank/intents/001-new-feature/`
+- WHEN artifact is written and directory doesn't exist
+- THEN directory is created automatically
+- AND parent directories are created if needed
+
+### AC-2: Artifact Write
+
+- GIVEN Inception Agent creates requirements.md
+- WHEN write operation completes
+- THEN file exists at `memory-bank/intents/{intent}/requirements.md`
+- AND content matches template + provided data
+
+### AC-3: Artifact Read
+
+- GIVEN existing artifact at path
+- WHEN read operation is performed
+- THEN content is returned correctly
+- AND frontmatter is parsed if present
+
+### AC-4: Git Safety
+
+- GIVEN any artifact in memory bank
+- WHEN committed to git
+- THEN no merge conflicts from encoding
+- AND diffs are readable

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/003-memory-bank-system/units/configuration-schema/unit-brief.md

@@ -0,0 +1,204 @@
+# Unit Brief: Configuration Schema
+
+## Overview
+
+The Configuration Schema unit defines the `memory-bank.yaml` file structure that serves as the single source of truth for all agents. Every agent reads this file on activation to understand where artifacts are stored.
+
+---
+
+## Scope
+
+### In Scope
+
+- YAML schema definition for memory bank structure
+- Path template syntax and resolution
+- Agent ownership boundaries
+- Default configuration values
+
+### Out of Scope
+
+- Actual artifact storage (handled by artifact-storage unit)
+- Agent reading logic (handled by context-loader unit)
+
+---
+
+## Technical Context
+
+### File Location
+
+`.irismd/memory-bank.yaml`
+
+---
+
+## Implementation Details
+
+### Full Configuration Schema
+
+```yaml
+# Memory Bank Configuration for AI-DLC Flow
+# Defines the directory structure and required folders for project context
+
+# Structure Section
+# Describes the conceptual organization of artifacts
+structure:
+  - path: intents/
+    description: "Intents (Features/Capabilities)"
+  - path: intents/units/
+    description: "Units of Work (Services/Components)"
+  - path: intents/units/stories/
+    description: "Individual User Stories"
+  - path: bolts/
+    description: "Execution Instances (Bolt Sessions)"
+  - path: standards/
+    description: "Project Standards (Architecture, Tech Stack)"
+  - path: operations/
+    description: "Operations Context (Deployment, Monitoring)"
+
+# Schema Section
+# Path templates for each artifact type
+# Variables in {} are resolved at runtime
+schema:
+  intents: "memory-bank/intents/{intent-name}/"
+  units: "memory-bank/intents/{intent-name}/units/{unit-name}/"
+  stories: "memory-bank/intents/{intent-name}/units/{unit-name}/stories/{story-id}.md"
+  bolts: "memory-bank/bolts/{bolt-id}.md"
+  story-index: "memory-bank/story-index.md"
+  standards: "memory-bank/standards/"
+  operations: "memory-bank/operations/"
+
+  # Agent Ownership
+  # Defines which agent can create/modify which artifact types
+  ownership:
+    inception: [intents, units, stories, story-index]
+    construction: [units, bolts]
+    operations: [operations]
+
+# Global Story Index Configuration
+story-index:
+  enabled: true
+  # Options:
+  #   1. single-file: One story-index.md at memory-bank root (recommended for small projects)
+  #   2. per-intent: One story-index.md per intent folder (recommended for large projects)
+  #   3. aggregate: Auto-generated from unit-level stories (computed, not stored)
+  mode: "single-file"
+  path: "memory-bank/story-index.md"
+```
+
+### Configuration Sections
+
+#### 1. `structure` Section
+
+Describes the conceptual hierarchy of the memory bank. Used by installer to create initial directory structure.
+
+| Path | Description | Created By |
+|------|-------------|------------|
+| `intents/` | High-level features | Inception Agent |
+| `intents/units/` | Decomposed work elements | Inception Agent |
+| `intents/units/stories/` | Implementation tasks | Inception Agent |
+| `bolts/` | Execution sessions | Construction Agent |
+| `standards/` | Project standards | Master Agent (project-init) |
+| `operations/` | Deployment context | Operations Agent |
+
+#### 2. `schema` Section
+
+Path templates with variable placeholders. Agents resolve these to actual paths.
+
+**Variable Syntax**: `{variable-name}`
+
+**Resolution Example**:
+
+```text
+Template: memory-bank/intents/{intent-name}/
+Variables: { intent-name: "001-user-auth" }
+Resolved:  memory-bank/intents/001-user-auth/
+```
+
+**Schema Keys**:
+
+| Key | Template | Example Resolved Path |
+|-----|----------|----------------------|
+| `intents` | `memory-bank/intents/{intent-name}/` | `memory-bank/intents/001-user-auth/` |
+| `units` | `memory-bank/intents/{intent-name}/units/{unit-name}/` | `memory-bank/intents/001-user-auth/units/auth-service/` |
+| `stories` | `.../stories/{story-id}.md` | `.../stories/001-user-auth-AUTH-001.md` |
+| `bolts` | `memory-bank/bolts/{bolt-id}.md` | `memory-bank/bolts/bolt-auth-service-1.md` |
+| `standards` | `memory-bank/standards/` | `memory-bank/standards/` |
+| `operations` | `memory-bank/operations/` | `memory-bank/operations/` |
+
+#### 3. `ownership` Section
+
+Maps agents to artifact types they can create/modify.
+
+| Agent | Owned Artifacts | Permissions |
+|-------|-----------------|-------------|
+| `inception` | intents, units, stories | Create, Update |
+| `construction` | units (update only), bolts | Update, Create |
+| `operations` | operations | Create, Update |
+
+**Note**: Master Agent reads everything but doesn't own artifacts (except standards via project-init).
+
+---
+
+## Path Resolution Algorithm
+
+```text
+function resolvePath(templateKey, variables):
+    1. Get template from schema[templateKey]
+    2. For each variable in template:
+       - Find {variable-name} pattern
+       - Replace with variables[variable-name]
+    3. Return resolved path
+```
+
+**Example**:
+
+```javascript
+// Input
+templateKey = "units"
+variables = { "intent-name": "001-user-auth", "unit-name": "auth-service" }
+
+// Processing
+template = "memory-bank/intents/{intent-name}/units/{unit-name}/"
+// Replace {intent-name} → "001-user-auth"
+// Replace {unit-name} → "auth-service"
+
+// Output
+"memory-bank/intents/001-user-auth/units/auth-service/"
+```
+
+---
+
+## Default Values
+
+When memory-bank.yaml is installed, these are the defaults:
+
+| Setting | Default |
+|---------|---------|
+| Root directory | `memory-bank/` |
+| Config location | `.irismd/memory-bank.yaml` |
+| Intent folder | `{NNN}-{intent-name}` (e.g., `001-user-authentication`) |
+| Unit folder | `{unit-name}` (e.g., `auth-service`) |
+| Story file | `{SSS}-{unit-name}.md` (e.g., `001-auth-service.md`) |
+| Bolt file | `bolt-{unit-name}-{N}.md` (e.g., `bolt-auth-service-1.md`) |
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Schema Completeness
+
+- GIVEN a freshly installed irismd
+- WHEN agent reads memory-bank.yaml
+- THEN all artifact types have defined paths in schema section
+- AND all paths use consistent variable syntax
+
+### AC-2: Path Resolution
+
+- GIVEN schema template `memory-bank/intents/{intent-name}/`
+- WHEN resolved with `{ "intent-name": "001-test" }`
+- THEN result is `memory-bank/intents/001-test/`
+
+### AC-3: Ownership Validation
+
+- GIVEN Construction Agent
+- WHEN attempting to create an intent
+- THEN operation is blocked (intents owned by inception)