project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/standards/coding-standards.md

@@ -0,0 +1,217 @@
+# Coding Standards
+
+Code style and quality standards for irismd.
+
+---
+
+## Formatting
+
+### Style: No Formatter Enforced
+
+**Rationale**: Project is primarily markdown and simple JavaScript. Consistent style maintained manually.
+
+### Indentation
+
+- JavaScript: 4 spaces
+- Markdown: 2 spaces for lists
+- YAML: 2 spaces
+
+---
+
+## Naming Conventions
+
+### Files
+
+- **JavaScript**: `camelCase.js` (e.g., `cli-utils.js`, `installer.js`)
+- **Classes**: `PascalCase.js` (e.g., `ClaudeInstaller.js`, `InstallerFactory.js`)
+- **Markdown**: `kebab-case.md` (e.g., `tech-stack.md`, `bolt-plan.md`)
+- **Agents**: `{name}-agent.md` (e.g., `master-agent.md`)
+- **Skills**: `{skill-name}.md` (e.g., `analyze-context.md`)
+
+### Variables & Functions
+
+- **Variables**: `camelCase`
+- **Constants**: `UPPER_SNAKE_CASE`
+- **Functions**: `camelCase`
+- **Classes**: `PascalCase`
+
+### Directories
+
+- Lowercase with hyphens (e.g., `bolt-types/`, `skills/`)
+
+---
+
+## File Organization
+
+### Source Structure
+
+```text
+src/
+├── bin/          # CLI entry points
+├── lib/          # Core library modules
+│   └── installers/   # Tool-specific installers
+└── flows/        # SDLC flow implementations
+    └── aidlc/    # AI-DLC flow
+        ├── agents/   # Agent definitions
+        ├── commands/ # Slash commands
+        └── .irismd/ # Runtime assets
+            ├── skills/
+            └── templates/
+```text
+
+### Agent File Structure
+
+```markdown
+# Agent Name
+
+## Persona
+- Role
+- Identity
+- Communication Style
+- Principles
+
+## Critical Actions
+
+## Skills
+
+## Workflow
+
+## Begin
+```text
+
+### Skill File Structure
+
+```markdown
+# Skill: {Name}
+
+## Mandatory Output Rules (READ FIRST)
+{Formatting rules - embedded in every skill}
+
+## Success Metrics
+{What correct output looks like}
+
+## Failure Modes
+{What to avoid}
+
+---
+
+## Goal
+{Single sentence purpose}
+
+## Input
+{Required and optional inputs}
+
+## Process
+{Step-by-step instructions}
+
+## Output
+{Example output with correct formatting}
+
+## Transition
+{What happens after skill completes}
+```text
+
+See `memory-bank/standards/skill-template.md` for complete specification.
+
+---
+
+## Testing Strategy
+
+### Current: Manual Testing
+
+**Rationale**: Project is primarily configuration and markdown. Automated testing would require complex setup for minimal benefit.
+
+### Future Consideration
+
+- Integration tests for installer flow
+- Validation tests for agent/skill loading
+
+---
+
+## Error Handling
+
+### CLI Errors
+
+- Display user-friendly error messages with chalk colors
+- Exit with appropriate exit codes
+- Never expose stack traces to end users
+
+### File Operations
+
+- Always check file existence before read
+- Create directories recursively with `fs-extra`
+- Handle permission errors gracefully
+
+---
+
+## Logging Standards
+
+### Console Output
+
+- Use `chalk` for colored output
+- Info: Default color
+- Success: Green
+- Warning: Yellow/Amber
+- Error: Red
+
+### No Debug Logging
+
+- Production code should not include console.log for debugging
+- Remove debug statements before commit
+
+---
+
+## Documentation
+
+### Code Comments
+
+- Comment complex logic only
+- No redundant comments that restate the code
+- Use JSDoc for function signatures in complex utilities
+
+### Markdown Documentation
+
+- Every agent has a `-agent.md` file
+- Every skill has a `.md` file
+- Templates define artifact structure
+
+---
+
+## Version Control
+
+### Commit Messages
+
+- Use conventional commits style
+- Format: `type(scope): description`
+- Types: `feat`, `fix`, `docs`, `refactor`, `chore`
+
+### Branch Strategy
+
+- `main` - stable releases
+- Feature branches for development
+
+---
+
+## Summary
+
+- **Indentation**: 4 spaces (JS), 2 spaces (MD/YAML)
+- **File Naming**: camelCase.js, kebab-case.md
+- **Variable Naming**: camelCase
+- **Constants**: UPPER_SNAKE_CASE
+- **Classes**: PascalCase
+- **Error Handling**: User-friendly messages, proper exit codes
+- **Logging**: chalk-colored console output
+- **Commits**: Conventional commits
+
+---
+
+## Output Formatting (AI Agents)
+
+Agent and skill outputs MUST follow these rules:
+
+- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+- ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
+- ✅ **ALWAYS** end with suggested next step pattern
+
+See `memory-bank/standards/output-formatting.md` for complete specification.

package/src/iris_bundle/frameworks/iris-core/memory-bank/standards/output-formatting.md

@@ -0,0 +1,202 @@
+# Output Formatting Standards
+
+Standards for consistent AI agent output formatting across irismd.
+
+---
+
+## Overview
+
+All AI agents and skills in irismd MUST follow these output formatting standards. These rules are embedded directly in every skill file to ensure the AI cannot deviate from them.
+
+**Design Principle**: Formatting rules are embedded in each skill file rather than relying on agents reading shared documentation. The AI cannot deviate from rules embedded in the file it must execute.
+
+---
+
+## Core Rules
+
+### 1. No ASCII Tables for Options
+
+**Rule**: 🚫 **NEVER** use ASCII tables for presenting options or choices to users.
+
+**Why**: ASCII tables break at different terminal widths and are harder to read in CLI environments.
+
+**Incorrect**:
+
+```markdown
+| # | Option | Description |
+|---|--------|-------------|
+| 1 | Build | Create artifacts |
+| 2 | Deploy | Deploy to env |
+```
+
+**Correct**:
+
+```markdown
+1 - **Build**: Create artifacts
+2 - **Deploy**: Deploy to env
+```
+
+### 2. Numbered List Format
+
+**Rule**: ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+
+**Format**:
+
+```text
+{number} - **{option-name}**: {description}
+```
+
+**Example**:
+
+```markdown
+1 - **requirements**: Gather functional and non-functional requirements
+2 - **context**: Define system context and integrations
+3 - **units**: Decompose into deployable units
+```
+
+### 3. Status Indicators
+
+**Rule**: ✅ **ALWAYS** use consistent status indicators for progress display.
+
+**Indicators**:
+
+- `✅` - **Completed**: Step/task is done
+- `⏳` - **In progress**: Currently active step (mark with `← current`)
+- `[ ]` - **Not started**: Pending future step
+- `🚫` - **Blocked**: Requires human decision
+- `⚠️` - **Warning**: Needs attention
+
+**Example**:
+
+```markdown
+### Progress
+
+- ✅ Requirements gathered
+- ✅ System context defined
+- ⏳ Units decomposed ← current
+- [ ] Stories created
+- [ ] Bolts planned
+```
+
+### 4. Suggested Next Step Pattern
+
+**Rule**: ✅ **ALWAYS** end skill outputs with a suggested next step.
+
+**Format**:
+
+```markdown
+### Actions
+
+1 - **option1**: Description of first option
+2 - **option2**: Description of second option
+3 - **option3**: Description of third option
+
+### Suggested Next Step
+→ **option1** - Recommended action for `{context}`
+
+**Type a number or press Enter for suggested action.**
+```
+
+**Components**:
+
+- **Actions section**: Numbered list of all available options
+- **Suggested Next Step**: Arrow (`→`) pointing to recommended option
+- **Call-to-action**: Clear instruction for user input
+
+---
+
+## Mandatory Output Rules Section
+
+Every skill file MUST include this section at the top:
+
+```markdown
+## Mandatory Output Rules (READ FIRST)
+
+- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+- ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
+- {skill-specific rules}
+
+## Success Metrics
+
+- ✅ Options presented as numbered list (not table)
+- ✅ Progress shown with status indicators
+- ✅ {skill-specific success criteria}
+
+## Failure Modes
+
+- ❌ Using ASCII tables for options
+- ❌ {skill-specific failure modes}
+```
+
+---
+
+## Emoji Conventions
+
+Use these emoji prefixes consistently in Mandatory Rules:
+
+- `🚫` - **Forbidden**: Actions that must never be done
+- `✅` - **Required**: Actions that must always be done
+- `🛑` - **Stop/Critical**: Critical rules that halt execution
+- `📖` - **Read**: File/document reading requirements
+- `💾` - **Save/Persist**: Data persistence requirements
+- `🎯` - **Goal/Focus**: Primary objectives
+- `⛔` - **Human Gate**: Requires explicit human approval
+
+---
+
+## Human Validation Points
+
+When human input is required, format as:
+
+```markdown
+### ⏸️ Human Validation Required
+
+> "{question or confirmation request}"
+
+**Options:**
+1 - **Continue**: Proceed to next step
+2 - **Request changes**: Modify before continuing
+3 - **Pause**: Save progress for later
+```
+
+For critical decisions (production deployments, etc.):
+
+```markdown
+### ⚠️ APPROVAL REQUIRED
+
+> "This action affects production. Confirm to proceed? (yes/no)"
+```
+
+---
+
+## Tables in Documentation vs Output
+
+**Important Distinction**:
+
+- **Agent OUTPUT to user**: No ASCII tables (use lists)
+- **Documentation/Templates**: Tables are acceptable for reference material
+
+Tables inside ```` ```markdown ```` blocks in skill files are showing *artifact format*, not agent output. These are intentional.
+
+---
+
+## Rationale
+
+1. **CLI Compatibility**: Numbered lists work at any terminal width
+2. **Consistency**: Same format across all agents reduces cognitive load
+3. **Scannability**: Status indicators are instantly recognizable
+4. **Actionability**: Suggested next step guides users forward
+5. **Reliability**: Embedded rules prevent AI deviation
+
+---
+
+## Related Standards
+
+- `memory-bank/standards/skill-template.md` - Complete skill file template
+- `memory-bank/standards/coding-standards.md` - General coding standards
+- `memory-bank/glossary.md` - Term definitions
+
+---
+
+*Last updated: 2025-12-09*

package/src/iris_bundle/frameworks/iris-core/memory-bank/standards/skill-template.md

@@ -0,0 +1,308 @@
+# Skill File Template
+
+This document defines the standard structure for AI-DLC skill files. All skills MUST follow this template to ensure consistent output formatting across agents.
+
+**Design Decision**: Output formatting rules are embedded directly in each skill file rather than relying on agents reading shared documentation. This ensures consistency because the AI cannot deviate from rules embedded in the file it must execute.
+
+---
+
+## Skill File Structure
+
+Every skill file MUST have these sections in order:
+
+```markdown
+# Skill: {Skill Name}
+
+## Mandatory Output Rules (READ FIRST)
+
+{Formatting rules - embedded in every skill}
+
+## Success Metrics
+
+{What correct output looks like}
+
+## Failure Modes
+
+{What to avoid}
+
+---
+
+## Goal
+
+{Single sentence describing what this skill does}
+
+---
+
+## Input
+
+{Required and optional inputs}
+
+---
+
+## Process
+
+{Step-by-step execution instructions}
+
+---
+
+## Output
+
+{Example output showing correct formatting}
+
+---
+
+## Transition
+
+{What happens after skill completes}
+```
+
+---
+
+## Mandatory Output Rules Section
+
+Every skill MUST include these rules at the top:
+
+```markdown
+## Mandatory Output Rules (READ FIRST)
+
+- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+- ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
+- {Additional skill-specific rules}
+
+## Success Metrics
+
+- ✅ Options presented as numbered list (not table)
+- ✅ Progress shown with status indicators
+- ✅ {Skill-specific success criteria}
+
+## Failure Modes
+
+- ❌ Using ASCII table for options
+- ❌ Plain list without status indicators
+- ❌ {Skill-specific failure modes}
+```
+
+---
+
+## Status Indicators
+
+Use these consistently across all skills:
+
+- `✅` - **Completed**: Step/task is done
+- `⏳` - **In progress**: Currently active step
+- `[ ]` - **Not started**: Pending future step
+- `🚫` - **Blocked**: Requires human decision
+- `⚠️` - **Warning**: Needs attention
+
+**Note**: Use `✅` for completed items in output displays. Use standard markdown checkboxes `[ ]` for pending items. Use emoji indicators `⏳` and `🚫` for in-progress and blocked states.
+
+---
+
+## Option Formatting
+
+### Correct Format (Numbered List)
+
+```markdown
+1 - **Option Name**: Description of what this option does
+2 - **Another Option**: Description of this option
+3 - **Third Option**: Description of the third option
+
+**Type a number to continue.**
+```
+
+### Incorrect Format (ASCII Table)
+
+```markdown
+| # | Option | Description |
+|---|--------|-------------|
+| 1 | Option Name | Description |
+| 2 | Another Option | Description |
+```
+
+**Why**: ASCII tables break at different terminal widths and are harder to read in CLI environments.
+
+---
+
+## Progress Display
+
+### Correct Format
+
+```markdown
+### Progress
+
+- ✅ Step 1 complete
+- ✅ Step 2 complete
+- ⏳ Step 3 ← current
+- [ ] Step 4
+- [ ] Step 5
+```
+
+Use `✅` for completed items and `[ ]` for pending items. Use `⏳` only for the currently active step.
+
+### Incorrect Format
+
+```markdown
+### Progress
+
+- Done: Step 1
+- Done: Step 2
+- Current: Step 3
+- Pending: Step 4
+```
+
+**Why**: Checkboxes are universally recognized. The `⏳` indicator clearly marks the active step.
+
+---
+
+## Decision Points
+
+When human input is required:
+
+```markdown
+🚫 {Phase/Stage}: BLOCKED
+
+**Decision Required**: {clear description of what's needed}
+
+1 - **Option name**: Description of this option
+2 - **Option name**: Description of this option
+3 - **Option name**: Description of this option
+
+**Waiting for your input to continue.**
+```
+
+---
+
+## Emoji Conventions
+
+Use these emoji prefixes consistently in Mandatory Rules:
+
+- `🚫` - **Forbidden**: Actions that must never be done
+- `✅` - **Required**: Actions that must always be done
+- `🛑` - **Stop/Critical**: Critical rules that halt execution
+- `📖` - **Read**: File/document reading requirements
+- `💾` - **Save/Persist**: Data persistence requirements
+- `🎯` - **Goal/Focus**: Primary objectives
+
+---
+
+## Example Skill File
+
+```markdown
+# Skill: Example Navigator
+
+## Mandatory Output Rules (READ FIRST)
+
+- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+- ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
+- 📖 **ALWAYS** load context before presenting menu
+- 🚫 **FORBIDDEN** to execute without user selection
+
+## Success Metrics
+
+- ✅ Options presented as numbered list (not table)
+- ✅ Progress shown with status indicators
+- ✅ Context loaded and displayed
+
+## Failure Modes
+
+- ❌ Using ASCII table for options
+- ❌ Plain list without status indicators
+- ❌ Executing without user confirmation
+
+---
+
+## Goal
+
+Present available actions and guide user to next step.
+
+---
+
+## Input
+
+- **Required**: `.irismd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--context` - Additional context parameter
+
+---
+
+## Process
+
+### 1. Load Context
+
+Read project state from memory bank.
+
+### 2. Present Menu
+
+\`\`\`markdown
+## Example Agent
+
+### Current State
+
+- ✅ Step 1 complete
+- ⏳ Step 2 ← current
+- [ ] Step 3
+
+### Actions
+
+1 - **Action One**: Description of first action
+2 - **Action Two**: Description of second action
+3 - **Action Three**: Description of third action
+
+**Type a number to continue.**
+\`\`\`
+
+### 3. Handle Selection
+
+Execute selected action.
+
+---
+
+## Transition
+
+After user selection:
+- Load corresponding skill file
+- Pass context
+- Execute
+```
+
+---
+
+## Rationale
+
+
+1. **Embedded Rules**: Formatting rules are in every skill file, not just a shared doc
+2. **Success/Failure Metrics**: Clear criteria for correct vs incorrect output
+3. **Emoji Conventions**: Visual markers for quick rule identification
+4. **Examples in Every Skill**: Show correct format, not just describe it
+
+The AI cannot deviate from rules embedded in the file it must execute. This ensures consistency across all agents and skills.
+
+---
+
+## Suggested Next Step Pattern
+
+Every skill output MUST end with a suggested next step:
+
+```markdown
+### Actions
+
+1 - **option1**: Description of first option
+2 - **option2**: Description of second option
+3 - **option3**: Description of third option
+
+### Suggested Next Step
+→ **option1** - Recommended action for `{context}`
+
+**Type a number or press Enter for suggested action.**
+```
+
+This pattern:
+
+- Presents all available options as numbered list
+- Highlights the recommended action with `→`
+- Provides clear call-to-action for the user
+
+---
+
+*Last updated: 2025-12-09*