project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/009-versioning-strategy/units.md

@@ -0,0 +1,312 @@
+# Units: Versioning Strategy
+
+## Unit Breakdown
+
+| Unit | Description | Priority | Dependencies |
+|------|-------------|----------|--------------|
+| **tag-based-publish** | Modify workflow to publish on tags only | Critical | None |
+| **prerelease-support** | Add npm tag handling for pre-releases | High | tag-based-publish |
+| **release-documentation** | Document release process for contributors | High | tag-based-publish |
+| **changelog-automation** | Auto-generate changelog (Phase 2) | Low | prerelease-support |
+
+---
+
+## Unit 1: tag-based-publish
+
+### Responsibility
+
+Modify GitHub Actions workflow to stop auto-publishing on push to main and instead publish only when version tags are pushed.
+
+### Stories
+
+1. As a maintainer, I need pushes to main to NOT trigger npm publish
+2. As a maintainer, I need tags matching `v*` pattern to trigger npm publish
+3. As a maintainer, I need the version to be extracted from the tag (not package.json)
+4. As a maintainer, I need tests to run before publish
+5. As a maintainer, I need the workflow to fail gracefully if version already exists
+6. As a maintainer, I need workflow_dispatch to remain available for emergencies
+
+### Implementation Changes
+
+**File: `.github/workflows/publish.yml`**
+
+```yaml
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'  # Only trigger on version tags
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (e.g., 1.2.3)'
+        required: true
+        type: string
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    defaults:
+      run:
+        working-directory: src
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        if: github.event_name == 'push'
+        run: |
+          # Remove 'v' prefix from tag
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Use manual version
+        if: github.event_name == 'workflow_dispatch'
+        run: echo "VERSION=${{ inputs.version }}" >> $GITHUB_ENV
+
+      - name: Validate version format
+        run: |
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+            echo "Invalid version format: $VERSION"
+            exit 1
+          fi
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts || npm install
+
+      - name: Run tests
+        run: npm test
+
+      - name: Update package.json version
+        run: npm version $VERSION --no-git-tag-version --allow-same-version
+
+      - name: Copy README
+        run: cp ../README.md ./README.md
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        if: github.event_name == 'push'
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true
+```
+
+### Acceptance Criteria
+
+- Push to main does NOT trigger publish
+- Tag `v1.2.3` triggers publish with version 1.2.3
+- Invalid tag format fails validation
+- Tests run before publish
+- GitHub release created on tag
+
+---
+
+## Unit 2: prerelease-support
+
+### Responsibility
+
+Add support for pre-release versions with appropriate npm tags.
+
+### Stories
+
+1. As a maintainer, I need pre-release tags (`v1.0.0-beta.1`) to publish with npm tag `next`
+2. As a maintainer, I need stable versions to publish with npm tag `latest`
+3. As a user, I need to install pre-releases via `npm install irismd@next`
+4. As a maintainer, I need GitHub releases to be marked as pre-release
+
+### Implementation Changes
+
+Add to publish workflow:
+
+```yaml
+- name: Determine npm tag
+  run: |
+    if [[ "$VERSION" == *"-"* ]]; then
+      echo "NPM_TAG=next" >> $GITHUB_ENV
+      echo "PRERELEASE=true" >> $GITHUB_ENV
+    else
+      echo "NPM_TAG=latest" >> $GITHUB_ENV
+      echo "PRERELEASE=false" >> $GITHUB_ENV
+    fi
+
+- name: Publish to npm
+  run: npm publish --access public --tag $NPM_TAG
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+- name: Create GitHub Release
+  uses: softprops/action-gh-release@v1
+  with:
+    generate_release_notes: true
+    prerelease: ${{ env.PRERELEASE }}
+```
+
+### Acceptance Criteria
+
+- `v1.0.0` publishes with `latest` tag
+- `v1.0.0-beta.1` publishes with `next` tag
+- Pre-releases marked as such on GitHub
+
+---
+
+## Unit 3: release-documentation
+
+### Responsibility
+
+Document the release process for maintainers and contributors.
+
+### Stories
+
+1. As a contributor, I need to understand the branching strategy
+2. As a maintainer, I need step-by-step release instructions
+3. As a maintainer, I need to know how to create pre-releases
+4. As a contributor, I need to understand version number meanings
+
+### Deliverables
+
+**File: `RELEASING.md`**
+
+```markdown
+# Releasing irismd
+
+## Overview
+
+irismd uses tag-based releases. Pushing to `main` does NOT
+automatically publish to npm. Releases happen when version tags
+are pushed.
+
+## Creating a Release
+
+### 1. Ensure main is ready
+- All tests passing
+- PR reviews complete
+- Changes documented
+
+### 2. Update version
+cd src
+npm version patch  # or minor, or major
+cd ..
+
+### 3. Commit and tag
+git add src/package.json src/package-lock.json
+git commit -m "chore: release v$(node -p "require('./src/package.json').version")"
+git tag v$(node -p "require('./src/package.json').version")
+
+### 4. Push
+git push origin main --tags
+
+GitHub Actions will automatically:
+- Run tests
+- Publish to npm
+- Create a GitHub release
+
+## Pre-releases
+
+For beta/alpha releases:
+cd src
+npm version prerelease --preid=beta  # Creates x.y.z-beta.1
+cd ..
+git add src/package.json src/package-lock.json
+git commit -m "chore: release v$(node -p "require('./src/package.json').version")"
+git tag v$(node -p "require('./src/package.json').version")
+git push origin main --tags
+
+Pre-releases publish to npm with the `next` tag:
+npm install @iris.md/irismd@next
+
+## Emergency Releases
+
+If you need to publish without creating a tag:
+1. Go to Actions → Publish to npm
+2. Click "Run workflow"
+3. Enter the version number
+4. Click "Run workflow"
+
+## Version Guidelines
+
+- MAJOR: Breaking changes to CLI or agent behavior
+- MINOR: New features, new agents, new flows
+- PATCH: Bug fixes, documentation updates
+```
+
+### Acceptance Criteria
+
+- RELEASING.md exists in repo root
+- README references RELEASING.md
+- Instructions are accurate and complete
+
+---
+
+## Unit 4: changelog-automation
+
+### Responsibility
+
+Automatically generate changelog from commit history (Phase 2, post-1.0).
+
+### Stories
+
+1. As a maintainer, I need changelog entries generated from commits
+2. As a user, I need to see what changed between versions
+3. As a maintainer, I need commits to follow conventional format
+
+### Options to Evaluate
+
+| Tool | Approach | Effort |
+|------|----------|--------|
+| **Release Please** | Bot creates release PRs, generates changelog | Medium |
+| **semantic-release** | Fully automated releases based on commits | High |
+| **conventional-changelog** | CLI tool, manual trigger | Low |
+| **Manual** | Write changelog by hand | Lowest |
+
+### Recommendation
+
+Start with manual CHANGELOG.md, evaluate Release Please for 1.0 release.
+
+### Acceptance Criteria (Future)
+
+- CHANGELOG.md maintained in repo
+- Changelog entries auto-generated from commits
+- GitHub releases include changelog excerpt
+
+---
+
+## Dependency Graph
+
+```text
+┌────────────────────┐
+│ tag-based-publish  │ ← Must be done first
+└─────────┬──────────┘
+          │
+    ┌─────┴─────┐
+    │           │
+    ▼           ▼
+┌────────────┐  ┌───────────────────────┐
+│ prerelease │  │ release-documentation │
+│  -support  │  │                       │
+└─────┬──────┘  └───────────────────────┘
+      │
+      ▼
+┌─────────────────────┐
+│ changelog-automation│ ← Phase 2
+└─────────────────────┘
+```
+
+---
+
+## Implementation Priority
+
+1. **Phase 1 (Now)**: tag-based-publish + release-documentation
+2. **Phase 2 (Pre-1.0)**: prerelease-support
+3. **Phase 3 (Post-1.0)**: changelog-automation

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/010-smart-unit-decomposition/requirements.md

@@ -0,0 +1,111 @@
+# Intent: Smart Unit Decomposition
+
+## Overview
+
+Enable the Inception Agent to intelligently decompose intents into appropriate units based on project type, creating both backend and frontend units for full-stack applications instead of only backend services.
+
+**Problem Statement**: Currently, the `units` skill only applies DDD decomposition, creating backend service units. For full-stack web apps, this results in no frontend units being created, leading to only backend code being generated during construction.
+
+---
+
+## Functional Requirements
+
+### FR-1: Project Type Awareness
+
+- FR-1.1: Units skill SHALL read `project_type` from `memory-bank/project.yaml`
+- FR-1.2: Units skill SHALL read unit structure configuration from `catalog.yaml`
+- FR-1.3: Project type configuration SHALL define which unit types are enabled (backend, frontend, cli)
+
+### FR-2: Project Type Configuration
+
+- FR-2.1: `catalog.yaml` SHALL define `unit_structure` for each project type
+- FR-2.2: Unit structure SHALL specify: enabled (boolean), decomposition strategy, default bolt type
+- FR-2.3: Supported project types SHALL include: `full-stack-web`, `backend-api`, `frontend-app`, `cli-tool`, `library`
+
+### FR-3: Backend Unit Decomposition
+
+- FR-3.1: When backend is enabled, units skill SHALL apply domain-driven decomposition
+- FR-3.2: Backend units SHALL use `ddd-construction-bolt` as default bolt type
+- FR-3.3: Backend decomposition SHALL identify bounded contexts, aggregates, services
+
+### FR-4: Frontend Unit Decomposition
+
+- FR-4.1: When frontend is enabled, units skill SHALL create a frontend unit
+- FR-4.2: Frontend unit SHALL be named `{intent}-ui` or `{app-name}-ui`
+- FR-4.3: Frontend units SHALL use `simple-construction-bolt` as default bolt type
+- FR-4.4: Frontend unit SHALL depend on all backend service units
+- FR-4.5: Frontend unit SHALL be assigned all user-facing requirements
+
+### FR-5: Simple Construction Bolt
+
+- FR-5.1: System SHALL provide `simple-construction-bolt` for non-DDD work
+- FR-5.2: Simple bolt SHALL have 3 stages: Plan, Implement, Test
+- FR-5.3: Simple bolt SHALL NOT require domain model or technical design artifacts
+- FR-5.4: Simple bolt SHALL be suitable for: UI work, integrations, utilities, scripts
+
+### FR-6: Smart Bolt Type Selection
+
+- FR-6.1: Bolt plan skill SHALL read default bolt type from `catalog.yaml` based on unit type
+- FR-6.2: Bolt plan skill SHALL NOT hardcode bolt type
+- FR-6.3: Bolt type selection SHALL be overridable per unit in unit-brief.md
+
+---
+
+## Non-Functional Requirements
+
+### NFR-1: Single Source of Truth
+
+- Project type definitions SHALL be managed in one place (`catalog.yaml`)
+- Adding a new project type SHALL NOT require modifying skill files
+
+### NFR-2: Backward Compatibility
+
+- Existing projects without `project.yaml` SHALL default to `backend-api` behavior
+- Existing bolt files with `type: ddd-construction-bolt` SHALL continue to work
+
+### NFR-3: Extensibility
+
+- New unit types (e.g., `mobile`, `embedded`) SHALL be addable via catalog
+- New bolt types SHALL be registerable in catalog
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Full-Stack Project Creates Frontend Unit
+
+- GIVEN a project with `project_type: full-stack-web` in project.yaml
+- WHEN Inception Agent executes units skill
+- THEN a frontend unit is created alongside backend service units
+
+### AC-2: Frontend Unit Has Correct Dependencies
+
+- GIVEN a full-stack project with backend units: auth-service, expense-service
+- WHEN frontend unit `expense-tracker-ui` is created
+- THEN it lists auth-service and expense-service as dependencies
+
+### AC-3: Frontend Bolts Use Simple Bolt Type
+
+- GIVEN a frontend unit with stories
+- WHEN bolt-plan skill creates bolts for the unit
+- THEN bolts have `type: simple-construction-bolt`
+
+### AC-4: Backend-Only Project Has No Frontend
+
+- GIVEN a project with `project_type: backend-api`
+- WHEN Inception Agent executes units skill
+- THEN no frontend unit is created
+
+### AC-5: Catalog Defines Project Structure
+
+- GIVEN `catalog.yaml` with `project_types.full-stack-web.unit_structure`
+- WHEN units skill reads the configuration
+- THEN it knows to create both backend and frontend units
+
+---
+
+## Out of Scope
+
+- Mobile app unit type (future intent)
+- Automatic frontend component generation from API specs
+- Design system / UI kit selection during inception

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/010-smart-unit-decomposition/system-context.md

@@ -0,0 +1,154 @@
+# System Context: Smart Unit Decomposition
+
+## System Boundary
+
+This intent modifies the Inception phase to be project-type aware when decomposing intents into units.
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│                        Inception Agent                          │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                     units.md skill                       │   │
+│  │  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐   │   │
+│  │  │   Read      │  │   Read       │  │   Create      │   │   │
+│  │  │ project.yaml│──│ catalog.yaml │──│ Units by Type │   │   │
+│  │  └─────────────┘  └──────────────┘  └───────────────┘   │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                              │                                  │
+│                              ▼                                  │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                  bolt-plan.md skill                      │   │
+│  │  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐   │   │
+│  │  │ Read Unit   │  │ Get Default  │  │ Create Bolts  │   │   │
+│  │  │   Brief     │──│ Bolt Type    │──│ with Type     │   │   │
+│  │  └─────────────┘  └──────────────┘  └───────────────┘   │   │
+│  └─────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Data Flow
+
+```text
+project-init
+     │
+     ▼
+project.yaml ─────────────────────────┐
+(project_type: full-stack-web)        │
+                                      │
+catalog.yaml ─────────────────────────┤
+(project_types.full-stack-web.        │
+ unit_structure)                      │
+                                      ▼
+                              ┌───────────────┐
+                              │  units skill  │
+                              └───────────────┘
+                                      │
+                    ┌─────────────────┼─────────────────┐
+                    ▼                 ▼                 ▼
+            ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+            │ backend     │   │ backend     │   │ frontend    │
+            │ unit 1      │   │ unit 2      │   │ unit        │
+            │ (DDD)       │   │ (DDD)       │   │ (Simple)    │
+            └─────────────┘   └─────────────┘   └─────────────┘
+                    │                 │                 │
+                    ▼                 ▼                 ▼
+            ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+            │ ddd-bolt    │   │ ddd-bolt    │   │ simple-bolt │
+            └─────────────┘   └─────────────┘   └─────────────┘
+```
+
+---
+
+## Components Modified
+
+### 1. catalog.yaml (Extended)
+
+**Location**: `.irismd/aidlc/templates/standards/catalog.yaml`
+
+**Change**: Add `unit_structure` to each project type definition.
+
+**Before**:
+
+```yaml
+project_types:
+  full-stack-web:
+    description: Full-stack web application
+    required_standards: [tech-stack, coding-standards]
+    recommended_standards: [system-architecture, ux-guide]
+```
+
+**After**:
+
+```yaml
+project_types:
+  full-stack-web:
+    description: Full-stack web application
+    required_standards: [tech-stack, coding-standards]
+    recommended_standards: [system-architecture, ux-guide]
+    unit_structure:
+      backend:
+        enabled: true
+        decomposition: domain-driven
+        default_bolt_type: ddd-construction-bolt
+      frontend:
+        enabled: true
+        decomposition: feature-based
+        default_bolt_type: simple-construction-bolt
+        naming: "{intent}-ui"
+```
+
+### 2. units.md (Modified)
+
+**Location**: `.irismd/aidlc/skills/inception/units.md`
+
+**Change**: Add project type awareness, create frontend unit when enabled.
+
+### 3. bolt-plan.md (Modified)
+
+**Location**: `.irismd/aidlc/skills/inception/bolt-plan.md`
+
+**Change**: Read default bolt type from catalog instead of hardcoding DDD.
+
+### 4. simple-construction-bolt.md (New)
+
+**Location**: `.irismd/aidlc/templates/construction/bolt-types/simple-construction-bolt.md`
+
+**Purpose**: Lightweight 3-stage bolt for non-DDD work.
+
+---
+
+## External Dependencies
+
+None. All changes are within the irismd system.
+
+---
+
+## Actors
+
+| Actor | Role | Interaction |
+|-------|------|-------------|
+| Inception Agent | Executes units and bolt-plan skills | Reads catalog, creates units |
+| Construction Agent | Executes bolts | Loads bolt type definition |
+| Human | Reviews artifacts | Approves at Checkpoint 3 |
+
+---
+
+## Integration Points
+
+| Integration | Type | Protocol | Notes |
+|-------------|------|----------|-------|
+| project.yaml | File | YAML | Read-only during inception |
+| catalog.yaml | File | YAML | Read-only, single source of truth |
+| unit-brief.md | File | Markdown | Created by units skill, read by bolt-plan |
+| bolt.md | File | Markdown | Created by bolt-plan, includes type field |
+
+---
+
+## Constraints
+
+1. **Single Source of Truth**: Project types MUST be defined only in catalog.yaml
+2. **Backward Compatibility**: Projects without project.yaml default to backend-only
+3. **No Hardcoding**: Skills MUST NOT hardcode project types or bolt types
+4. **Catalog Extensibility**: Adding new project types requires only catalog.yaml changes

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/010-smart-unit-decomposition/units.md

@@ -0,0 +1,102 @@
+# Units: Smart Unit Decomposition
+
+## Overview
+
+This intent decomposes into 3 units that modify the inception flow to be project-type aware.
+
+## Requirement-to-Unit Mapping
+
+- **FR-1** (Project Type Awareness) → `catalog-extension`
+- **FR-2** (Project Type Configuration) → `catalog-extension`
+- **FR-3** (Backend Unit Decomposition) → `units-skill-enhancement`
+- **FR-4** (Frontend Unit Decomposition) → `units-skill-enhancement`
+- **FR-5** (Simple Construction Bolt) → `simple-bolt-type`
+- **FR-6** (Smart Bolt Type Selection) → `units-skill-enhancement`
+
+---
+
+## Units
+
+### Unit 1: catalog-extension
+
+- **Purpose**: Extend catalog.yaml with unit structure configuration
+- **Responsibility**: Define how each project type should decompose into units
+- **Assigned Requirements**: FR-1, FR-2
+- **Dependencies**: None
+- **Interface**: YAML configuration read by skills
+- **Entities**: Project type definitions with unit_structure
+- **Priority**: Must (foundation for other units)
+
+**Key Changes**:
+
+- Add `unit_structure` to each project type in `catalog.yaml`
+- Define: enabled, decomposition strategy, default_bolt_type, naming pattern
+
+---
+
+### Unit 2: units-skill-enhancement
+
+- **Purpose**: Modify units.md skill to read project type and create appropriate units
+- **Responsibility**: Project-type aware unit decomposition
+- **Assigned Requirements**: FR-3, FR-4, FR-6
+- **Dependencies**: `catalog-extension` (needs unit_structure config)
+- **Interface**: Skill file read by Inception Agent
+- **Priority**: Must (core functionality)
+
+**Key Changes**:
+
+- Add `project.yaml` and `catalog.yaml` to Input requirements
+- Add step to load project type configuration
+- Add logic to create frontend unit when enabled
+- Update bolt-plan.md to read default_bolt_type from catalog
+
+---
+
+### Unit 3: simple-bolt-type
+
+- **Purpose**: Create lightweight bolt type for non-DDD work
+- **Responsibility**: Define 3-stage construction process
+- **Assigned Requirements**: FR-5
+- **Dependencies**: None (standalone template)
+- **Interface**: Bolt type definition read by Construction Agent
+- **Priority**: Must (needed for frontend bolts)
+
+**Key Changes**:
+
+- Create `simple-construction-bolt.md` with 3 stages: Plan, Implement, Test
+- No domain model or technical design artifacts required
+- Suitable for UI, integrations, utilities
+
+---
+
+## Dependency Graph
+
+```text
+catalog-extension (no dependencies)
+        │
+        ▼
+units-skill-enhancement (depends on catalog-extension)
+        │
+        ├──────────────────┐
+        ▼                  ▼
+ [creates bolts]    simple-bolt-type (standalone)
+```
+
+---
+
+## Execution Order
+
+1. **catalog-extension** - Add unit_structure to catalog.yaml
+2. **simple-bolt-type** - Create simple-construction-bolt.md (can be parallel with #1)
+3. **units-skill-enhancement** - Modify units.md and bolt-plan.md skills
+
+---
+
+## Story Summary
+
+| Unit | Estimated Stories | Priority |
+|------|-------------------|----------|
+| catalog-extension | 2 | Must |
+| units-skill-enhancement | 4 | Must |
+| simple-bolt-type | 2 | Must |
+| **Total** | **8** | - |