project-iris 0.0.12 → 0.0.14

package/flows/aidlc/skills/master/project-init.md

@@ -0,0 +1,281 @@
+# Skill: Project Init
+
+---
+
+## Role
+
+Setup skill to initialize a new project by facilitating creation of project standards through guided conversation.
+
+**NO Checkpoint** - Project initialization is a setup process. Standards are confirmed individually during the conversation.
+
+---
+
+## Goal
+
+Initialize a new project by facilitating the creation of project standards through guided conversation. Standards ensure AI agents have the context needed to generate consistent, high-quality code.
+
+---
+
+## Input
+
+- **Required**: `.iris/aidlc/templates/standards/catalog.yaml` - defines available standards
+- **Optional**: Project type hint from user (e.g., "full-stack web app", "backend API")
+- **Optional**: Existing standards files to review/update
+
+---
+
+## Process
+
+### 1. Load Standards Catalog
+
+Read `.iris/aidlc/templates/standards/catalog.yaml` to understand:
+
+- Available standards and their importance
+- Decisions within each standard
+- Dependencies between standards
+- Project type presets
+
+### 2. Determine Project Type
+
+Ask the user what kind of project they're building:
+
+```markdown
+## Project Setup
+
+Before we dive into technical choices, what kind of project are you building?
+
+1. **Full-stack web app** - Frontend + backend + database
+2. **Backend API** - API service, no frontend
+3. **Frontend app** - SPA or SSR frontend
+4. **CLI tool** - Command-line application
+5. **Library** - Reusable package/module
+6. **Other** - Tell me more
+
+This helps me know which standards we need to discuss.
+```
+
+Use the project type to determine:
+
+- Required standards (must create)
+- Recommended standards (suggest, but optional)
+- Skippable standards (not relevant)
+
+**IMPORTANT**: After determining project type, immediately save it to `memory-bank/project.yaml`:
+
+```yaml
+# Project Configuration
+# Generated by project-init
+
+project_type: {selected-type}  # e.g., full-stack-web, backend-api, frontend-app, cli-tool, library
+initialized_at: {ISO timestamp}
+```
+
+This file MUST be created before proceeding to standards facilitation, as other agents (e.g., Inception) read it to provide context-aware suggestions.
+
+### 3. Check Existing Standards
+
+Before creating new standards, check if any exist:
+
+- Read `standards/` directory
+- If files exist, ask: "I found existing standards. Do you want to review and update them, or start fresh?"
+
+### 4. Facilitate Each Standard
+
+For each required/recommended standard:
+
+1. **Load the facilitation guide** from `templates/standards/{standard}.guide.md`
+2. **Follow the guide's discovery process** - don't invent your own questions
+3. **Adapt to user expertise** - be concise with experts, explanatory with newcomers
+4. **Confirm before saving** - summarize choices, get approval
+5. **Generate the standard file** - using the output format in the guide
+6. **Save to path** defined in catalog (`output_path`)
+
+### 5. Order of Standards
+
+Follow dependency order from catalog:
+
+1 - **tech-stack**: No dependencies
+2 - **coding-standards**: Depends on tech-stack
+3 - **system-architecture**: Depends on tech-stack (optional)
+4 - **ux-guide**: Depends on tech-stack (optional)
+5 - **api-conventions**: Depends on tech-stack (optional)
+
+Never create a standard before its dependencies are satisfied.
+
+### 6. Handle Optional Standards
+
+For optional/recommended standards:
+
+```markdown
+## Optional: {Standard Name}
+
+Based on your project type, this standard is recommended but not required:
+- **{standard}**: {description from catalog}
+
+Would you like to define this now, or skip for later?
+```
+
+---
+
+## Facilitation Principles
+
+### Adaptive Communication
+
+**Read user signals:**
+
+- Mentions specific tech confidently → treat as experienced
+- Asks "what do you recommend?" → provide guidance
+- Says "I don't know" → explain tradeoffs, suggest defaults
+- Has strong opinions → respect them, validate coherence
+
+**Adjust your style:**
+
+- Expert: "TypeScript with Next.js? Got it. Deployment target?"
+- Beginner: "TypeScript is great for catching bugs early. Since you mentioned React, Next.js would give you server-side rendering and easy deployment..."
+
+### Collaborative Discovery
+
+- **Don't interrogate** - have a conversation
+- **Build context** - previous answers inform later questions
+- **Surface tradeoffs** - help them make informed decisions
+- **Capture rationale** - "why" is as important as "what"
+
+### Question Format (CRITICAL)
+
+**ALWAYS format questions like this:**
+
+```markdown
+## [Topic Name]
+
+[Brief context if needed - 1-2 sentences max]
+
+1. **Option A** - description
+2. **Option B** - description
+3. **Option C** - description
+4. **Other** - let me know
+
+Type a number or describe your choice.
+```
+
+**Example - GOOD:**
+
+```markdown
+## Database
+
+1. **SQLite** - Simple, file-based, great for small apps
+2. **PostgreSQL** - Robust, scalable, widely supported
+3. **MySQL** - Popular, good for web apps
+4. **MongoDB** - Document store, flexible schema
+5. **TBD** - Decide later
+
+Type a number or tell me your preference.
+```
+
+**Example - BAD (never do this):**
+
+```markdown
+What database are you using? And where will you deploy? Also what's your auth strategy?
+```
+
+**If user gives partial answer:**
+> User says "PostgreSQL"
+> You asked about database AND deployment
+> → Acknowledge the database choice, then re-ask ONLY about deployment
+
+### Practical Defaults
+
+When user is unsure, offer sensible defaults:
+> "For a TypeScript web app, most teams start with: Prettier for formatting, ESLint with strict mode, and Vitest for testing. These are well-supported and work great with AI code generation. Sound good as a starting point?"
+
+---
+
+## Output
+
+After completing all standards:
+
+```markdown
+## Project Initialization Complete
+
+### Standards Created
+
+- ✅ **Tech Stack**: Created at `standards/tech-stack.md`
+- ✅ **Coding Standards**: Created at `standards/coding-standards.md`
+- ⏭️ **System Architecture**: Skipped
+- ⏭️ **UX Guide**: Skipped
+- ⏭️ **API Conventions**: Skipped
+
+### Summary
+
+Your project is configured as a **{project type}** using:
+- **Language**: {language}
+- **Framework**: {framework}
+- **Database**: {database or "TBD"}
+
+### What These Standards Enable
+
+AI agents will now:
+- Generate code matching your style preferences
+- Use your chosen libraries and patterns
+- Follow your testing strategy
+- Understand your project structure
+
+### Actions
+
+1 - **inception**: Create your first intent
+2 - **standards**: Add more optional standards
+3 - **menu**: Return to main menu
+
+### Suggested Next Step
+→ **inception** - Create your first intent with `/iris-inception-agent`
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Points
+
+At each standard completion:
+> "I've captured your {standard} preferences. Here's the summary: {brief summary}. Does this look right? Any changes before I save?"
+
+At project init completion:
+> "Your project is initialized with {n} standards. AI agents now have the context they need. Ready to create your first intent?"
+
+---
+
+## Error Handling
+
+### Missing Catalog
+
+If `catalog.yaml` is not found:
+> "I can't find the standards catalog. Please ensure `.iris/aidlc/templates/standards/catalog.yaml` exists."
+
+### Missing Guide
+
+If a facilitation guide is missing:
+> "The facilitation guide for {standard} is missing. I'll skip this standard. You can create it manually at `standards/{standard}.md`."
+
+### Dependency Not Met
+
+If trying to create a standard before its dependency:
+> "We need to define {dependency} before {standard}. Let's do that first."
+
+---
+
+## Transition
+
+After project initialization:
+
+- → **Inception Agent** (`.iris/agents/inception-agent.md`) - to create first intent
+- → **Analyze Context** (`.iris/skills/master/analyze-context.md`) - if user wants to see project state
+- → **Project Init** again - to add optional standards later
+
+---
+
+## Test Contract
+
+```yaml
+input: User responses to standards questions
+output: Created standards files in standards/ directory
+checkpoints: 0 (setup process with inline confirmations)
+```

package/flows/aidlc/skills/master/route-request.md

@@ -0,0 +1,126 @@
+# Skill: Route Request
+
+---
+
+## Role
+
+Routing skill to direct users to the appropriate specialist agent based on context and request.
+
+**NO Checkpoint** - Routing is a navigation function, not a decision point.
+
+---
+
+## Goal
+
+Direct the user to the appropriate specialist agent based on their current context and request.
+
+---
+
+## Input
+
+- **Required**: Completed context analysis (from `analyze-context.md`)
+- **Required**: User's request or intent
+
+---
+
+## Process
+
+### 1. Match State to Agent
+
+Based on project state:
+
+- **No intents / New feature request** → Inception Agent → `/iris-inception-agent`
+- **Intent exists, needs elaboration** → Inception Agent → `/iris-inception-agent --intent="{name}"`
+- **Ready for construction** → Construction Agent → `/iris-construction-agent --unit="{name}"`
+- **Bolt in progress** → Construction Agent → `/iris-construction-agent --unit="{name}" --bolt-id="{id}"`
+- **Ready for deployment** → Operations Agent → `/iris-operations-agent --unit="{name}"`
+- **In production, needs monitoring** → Operations Agent → `/iris-operations-agent --unit="{name}"`
+
+### 2. Handle Special Cases
+
+**User asks about something different than current state**:
+> "I see you're in {current phase}, but you're asking about {different thing}. Let me help you with that instead."
+
+**User is confused about what to do**:
+> "Based on your project state, the logical next step is {action}. Would you like me to route you there, or do you have something else in mind?"
+
+**Multiple options available**:
+> "You have several options at this point:
+>
+> 1. {Option 1} → {command}
+> 2. {Option 2} → {command}
+> Which would you like to pursue?"
+
+### 3. Provide Clear Handoff
+
+Always include:
+
+1. The specific command to run
+2. What parameters to include
+3. What the agent will help them do
+4. What to expect next
+
+---
+
+## Output
+
+````markdown
+## Routing Recommendation
+
+Based on your current state ({phase}) and request ({what user wants}):
+
+### Recommended Action
+→ **{Agent Name}**: {brief description of what it does}
+
+### Command
+```text
+{exact command with parameters}
+```
+
+### What Happens Next
+
+{Description of what the agent will guide them through}
+
+### Actions
+
+1 - **proceed**: Run the recommended command
+2 - **different**: Choose a different option
+3 - **explain**: Learn more about the target agent
+
+### Suggested Next Step
+
+→ **proceed** - Run the command above
+
+**Type a number or press Enter for suggested action.**
+````
+
+---
+
+## Human Validation Point
+
+> "I'm routing you to the {Agent Name}. This agent will help you {specific task}. Does this match what you're trying to accomplish?"
+
+---
+
+## Transition
+
+After routing:
+
+- User runs the provided command
+- Control transfers to the target agent
+- Master Agent is no longer active
+
+If user declines routing:
+
+- → **Answer Question** (`.iris/skills/master/answer-question.md`) - clarify their needs
+- → **Explain Flow** (`.iris/skills/master/explain-flow.md`) - explain the methodology
+
+---
+
+## Test Contract
+
+```yaml
+input: Context analysis + user request
+output: Routing recommendation with exact command
+checkpoints: 0 (routing only)
+```

package/flows/aidlc/skills/operations/build.md

@@ -0,0 +1,237 @@
+# Skill: Build Deployment Artifacts
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Operations Progress
+- [ ] Build approval  ← current
+- [ ] Staging deploy
+- [ ] Production deploy
+- [ ] Monitoring setup
+```
+
+---
+
+## Checkpoints in This Skill
+
+| Checkpoint | Purpose | Wait For |
+|------------|---------|----------|
+| Checkpoint 1 | Build approval | User confirmation |
+
+---
+
+## Goal
+
+Create deployable packages (containers, functions, bundles) for a Unit and document the build metadata.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to build
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--version` - Explicit version tag (default: auto-generate)
+
+---
+
+## Process
+
+### 1. Verify Prerequisites
+
+Check construction completion:
+
+- [ ] **All bolts complete**: Path from `schema.bolts` (Required)
+- [ ] **Tests passing**: Last bolt test stage (Required)
+- [ ] **Code exists**: Unit source directory (Required)
+
+### 2. Detect Build Type
+
+Analyze unit structure to determine build strategy:
+
+- `Dockerfile` → **Container** → `docker build`
+- `serverless.yml` → **Serverless** → Framework deploy
+- `package.json` → **Node.js** → `npm run build`
+- `Cargo.toml` → **Rust** → `cargo build --release`
+- `go.mod` → **Go** → `go build`
+
+### 3. Determine Version
+
+Generate semantic version:
+
+```markdown
+## Version Calculation
+
+Base: {major}.{minor}.{patch}
+Commit: {short-sha}
+Tag: v{version}-{commit}
+
+Example: v1.2.0-abc123
+```
+
+### 4. Execute Build
+
+Run appropriate build commands:
+
+1. **Pre-build**: Install dependencies
+2. **Build**: Compile/bundle
+3. **Test**: Run final verification
+4. **Package**: Create deployable artifact
+5. **Tag**: Apply version tag
+
+### 5. Push to Registry
+
+Upload artifact to configured registry:
+
+- Container → Container registry
+- Package → Package registry
+- Function → Function storage
+
+### 6. Document Build
+
+Create/update `deployment/build.md`:
+
+```markdown
+---
+version: {version}
+commit: {sha}
+built: {timestamp}
+status: success
+---
+
+## Build: {version}
+
+### Artifact
+- **Type**: {container|function|package}
+- **Tag**: `{registry}/{unit}:{version}`
+- **Size**: {size}
+- **SHA**: {artifact-sha}
+
+### Build Environment
+- OS: {os}
+- Runtime: {runtime-version}
+- Builder: {tool-version}
+
+### Dependencies
+
+- **{dep1}**: {ver}
+- **{dep2}**: {ver}
+
+### Build Log Summary
+{key events from build}
+```
+
+---
+
+## Output
+
+````markdown
+## Build Complete: {unit-name}
+
+### Artifact Created
+
+- **Version**: `{version}`
+- **Tag**: `{registry}/{unit}:{version}`
+- **Built**: {timestamp}
+- **Size**: {size}
+
+### Build Summary
+- Dependencies: {count} packages
+- Build time: {duration}
+- Tests: ✅ All passing
+
+### Artifact Location
+```text
+{registry-url}/{unit}:{version}
+```
+
+### Documentation Updated
+
+- `{unit-path}/deployment/build.md`
+
+### Actions
+
+1 - **deploy**: Deploy to dev environment
+2 - **menu**: Return to operations menu
+
+### Suggested Next Step
+
+→ **deploy** - Deploy `{version}` to dev environment
+
+**Type a number or press Enter for suggested action.**
+````
+
+---
+
+## Output (Build Failed)
+
+````markdown
+## Build Failed: {unit-name}
+
+### Error
+```text
+{error message}
+```
+
+### Failure Point
+
+- **Stage**: {compile|test|package}
+- **Exit Code**: {code}
+
+### Logs
+
+{relevant log excerpt}
+
+### Suggested Actions
+
+1. Fix the build error in source code
+2. Re-run build: `build --unit="{unit}"`
+
+### No Artifacts Created
+
+Build must succeed before deployment.
+````
+
+---
+
+## Build Confirmation
+
+**Checkpoint 1**: Ask user to confirm build:
+
+```text
+Ready to build v{version}?
+
+This will:
+1. Verify all tests pass
+2. Create deployable artifact
+3. Tag with version {version}
+4. Push to registry
+
+Proceed with build?
+1 - Yes, build
+2 - Cancel
+```
+
+**Wait for user response.**
+
+---
+
+## Transition
+
+After build approved and completed:
+
+- → **Deploy** - deploy to dev environment
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, version
+output: Deployable artifact, build.md documentation
+checkpoints: 1
+  - Checkpoint 1: Build approved by user
+```