project-iris 0.0.16 → 0.0.18

package/flows/aidlc/skills/README.md

@@ -0,0 +1,106 @@
+# AI-DLC Skills
+
+Skills are focused capabilities that agents execute to perform specific tasks. Each skill follows a consistent structure with mandatory output rules, success metrics, and failure modes.
+
+## Directory Structure
+
+```text
+skills/
+├── master/                    # Master Agent skills (6)
+│   ├── project-init.md        # Initialize project with standards
+│   ├── code-elevate.md        # Brownfield code elevation
+│   ├── analyze-context.md     # Analyze current project state
+│   ├── route-request.md       # Route to appropriate agent
+│   ├── explain-flow.md        # Explain AI-DLC methodology
+│   └── answer-question.md     # Answer user questions
+│
+├── inception/                 # Inception Agent skills (10)
+│   ├── navigator.md           # Navigate inception workflow
+│   ├── intent-create.md       # Create new intent
+│   ├── intent-list.md         # List all intents
+│   ├── requirements.md        # Gather requirements
+│   ├── risks.md               # Define risks
+│   ├── context.md             # Define system context
+│   ├── units.md               # Decompose into units
+│   ├── story-create.md        # Create user stories
+│   ├── bolt-plan.md           # Plan bolts for stories
+│   └── review.md              # Review inception artifacts
+│
+├── construction/              # Construction Agent skills (5)
+│   ├── navigator.md           # Navigate construction workflow
+│   ├── bolt-list.md           # List all bolts
+│   ├── bolt-start.md          # Start/continue bolt execution
+│   ├── bolt-status.md         # Check bolt progress
+│   └── bolt-replan.md         # Replan bolts if needed
+│
+└── operations/                # Operations Agent skills (6)
+    ├── navigator.md           # Navigate operations workflow
+    ├── build.md               # Build deployment artifacts
+    ├── deploy.md              # Deploy to environment
+    ├── verify.md              # Verify deployment
+    ├── monitor.md             # Setup monitoring
+    └── rollback.md            # Rollback deployment
+```
+
+## Skill Structure
+
+Every skill file follows this structure:
+
+```markdown
+# Skill: {Name}
+
+## Mandatory Output Rules (READ FIRST)
+- Output formatting rules that MUST be followed
+
+## Success Metrics
+- Criteria for successful skill execution
+
+## Failure Modes
+- Common mistakes to avoid
+
+## Goal
+- What this skill accomplishes
+
+## Input
+- Required and optional parameters
+
+## Process
+- Step-by-step execution guide
+
+## Output
+- Expected output format
+
+## Checkpoints
+- Human validation points (if any)
+
+## Transition
+- Next skills/actions after completion
+
+## Test Contract
+- Input/output specification for validation
+```
+
+## Key Principles
+
+### 1. Mandatory Output Rules
+Every skill starts with formatting rules to ensure consistent output:
+- Never use ASCII tables (they break at different terminal widths)
+- Always use numbered list format for options
+- Always use status indicators (✅ ⏳ [ ] 🚫)
+
+### 2. Human Checkpoints
+Skills that make significant decisions include checkpoints where the AI pauses for human validation before proceeding.
+
+### 3. Artifact Creation
+Skills that create artifacts reference templates from `../templates/` and follow the schema defined in `../memory-bank.yaml`.
+
+### 4. Context Loading
+Skills load context as defined in `../context-config.yaml` to ensure consistent information access.
+
+## Adding New Skills
+
+1. Create a new `.md` file in the appropriate agent folder
+2. Follow the standard skill structure
+3. Include Mandatory Output Rules section
+4. Define clear success metrics and failure modes
+5. Register the skill in the agent's skill list (in `../agents/{agent}-agent.md`)

package/flows/aidlc/skills/construction/bolt-start.md

@@ -19,6 +19,8 @@
 - ✅ Activities listed with completion status
 - ✅ Artifacts created listed with paths
 - ✅ Checkpoint prompts clear and actionable
+- ✅ Code references stories (comments: `// Story: S-XXX`)
+- ✅ Tests reference acceptance criteria they verify
 
 ## Failure Modes
 
@@ -26,6 +28,8 @@
 - ❌ Starting stage work without updating bolt file status
 - ❌ Skipping checkpoints defined by bolt type
 - ❌ Not reading bolt type definition first
+- ❌ Code without story traceability comments
+- ❌ Tests without acceptance criteria references
 
 ---
 
@@ -141,7 +145,7 @@ When transitioning from `planned` to `in-progress`:
 ---
 status: in-progress          # was: planned
 started: {ISO-8601-timestamp} # was: null
-current_stage: {first-stage}  # was: null (e.g., "domain-model")
+current_stage: {first-stage}  # was: null (e.g., "domain-design")
 ---
 ```
 

package/flows/aidlc/skills/construction/navigator.md

@@ -8,7 +8,7 @@
 - ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
 - ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
 - ✅ **ALWAYS** show active bolt context prominently at top
-- ✅ **ALWAYS** display stage progress (e.g., "Stage 2/4: Technical Design")
+- ✅ **ALWAYS** display stage progress (e.g., "Stage 2/4: Logical Design")
 - ✅ **ALWAYS** end with suggested next step and call-to-action
 
 ## Success Metrics

package/flows/aidlc/skills/inception/bolt-plan.md

@@ -36,12 +36,13 @@ Show at start of this skill:
 ### Inception Progress
 - [x] Intent created
 - [x] Requirements gathered
+- [x] Risks defined
 - [ ] Generating artifacts...  ← current
     - [x] System Context
     - [x] Units
     - [x] Stories
     - [ ] Bolt Plan  ← this skill
-- [ ] Artifacts reviewed (Checkpoint 3)
+- [ ] Artifacts reviewed (Checkpoint 4)
 - [ ] Ready for Construction
 ```
 
@@ -254,7 +255,7 @@ Establish execution order based on dependencies:
    └── {stage-artifacts}            ← Created during construction (varies by bolt type)
    ```
 
-   *Note: Artifact names depend on bolt type (e.g., DDD bolts create `ddd-01-domain-model.md`, simple bolts create `implementation-plan.md`).*
+   *Note: Artifact names depend on bolt type (e.g., DDD bolts create `ddd-01-domain-design.md`, simple bolts create `implementation-plan.md`).*
 
 4. **Bolt File Structure** (CRITICAL: Include all dependencies in frontmatter):
 

package/flows/aidlc/skills/inception/context.md

@@ -35,12 +35,13 @@ Show at start of this skill:
 ### Inception Progress
 - [x] Intent created
 - [x] Requirements gathered
+- [x] Risks defined
 - [ ] Generating artifacts...  ← current
     - [ ] System Context  ← this skill
     - [ ] Units
     - [ ] Stories
     - [ ] Bolt Plan
-- [ ] Artifacts reviewed (Checkpoint 3)
+- [ ] Artifacts reviewed (Checkpoint 4)
 - [ ] Ready for Construction
 ```
 

package/flows/aidlc/skills/inception/intent-create.md

@@ -10,11 +10,13 @@
 - ✅ **ALWAYS** show files created with paths
 - ✅ **ALWAYS** end with numbered actions and suggested next step
 - 📖 **ALWAYS** read project.yaml for context-aware suggestions
+- ✅ **ALWAYS** offer PRFAQ generation after intent creation
 
 ## Success Metrics
 
 - ✅ Intent directory created with correct naming ({NNN}-{name})
 - ✅ requirements.md and inception-log.md initialized
+- ✅ PRFAQ offered (optional but recommended per AI-DLC spec)
 - ✅ Confirmation shows created files with paths
 - ✅ Clear next step suggestion
 
@@ -24,6 +26,7 @@
 - ❌ Missing numeric prefix on intent name
 - ❌ Not reading existing intents for context
 - ❌ Multiple action lists in output
+- ❌ Skipping PRFAQ offer without user choice
 
 ---
 
@@ -195,9 +198,64 @@ Once confirmed, perform these file operations:
    - Initialize with intent metadata and empty sections
    - Track progress, decisions, and scope changes
 
+### 4. Offer PRFAQ Generation (AI-DLC Spec Requirement)
+
+**Per AI-DLC specification, PRFAQ is an optional but recommended Inception output.**
+
+After initializing the intent, offer PRFAQ generation:
+
+```markdown
+## PRFAQ Document (Optional but Recommended)
+
+A PRFAQ (Press Release / FAQ) helps clarify the business value before diving into requirements.
+
+**Benefits:**
+- Forces customer-centric thinking
+- Surfaces scope questions early
+- Aligns stakeholders on the "why"
+- Defines success metrics upfront
+
+Would you like to generate a PRFAQ for this intent?
+
+1 - **Yes**: Generate PRFAQ now (takes ~2 minutes of Q&A)
+2 - **Skip**: Proceed directly to requirements
+```
+
+**If user chooses "Yes":**
+
+Ask these questions to generate the PRFAQ:
+
+```markdown
+## PRFAQ Quick Questions
+
+1. **Headline**: In one sentence, what would the announcement say?
+   (e.g., "Company X launches feature Y, enabling users to Z")
+
+2. **Problem**: What user pain point does this solve?
+
+3. **Key Benefits**: What are the top 3 outcomes users will experience?
+
+4. **Success Metric**: How will you know this feature is successful?
+   (e.g., "50% reduction in time to complete X" or "10K daily active users")
+```
+
+**After receiving answers:**
+
+1. Generate PRFAQ using template: `.iris/aidlc/templates/inception/prfaq-template.md`
+2. Save to: `{intent-path}/prfaq.md`
+3. Update inception-log.md with PRFAQ status
+
+**If user chooses "Skip":**
+
+Note in inception-log.md: "PRFAQ: Skipped by user"
+
+Proceed to confirmation step.
+
 ### 5. Confirm Creation
 
-Show confirmation with **exactly ONE action list** - no workflow overview, no extra lists:
+Show confirmation with **exactly ONE action list** - no workflow overview, no extra lists.
+
+**If PRFAQ was generated:**
 
 ```markdown
 ## Intent Created: `{intent-name}`
@@ -209,6 +267,7 @@ Show confirmation with **exactly ONE action list** - no workflow overview, no ex
 Files created:
 - `requirements.md` (draft)
 - `inception-log.md` (progress tracker)
+- `prfaq.md` (business value summary)
 
 1 - **requirements**: [Recommended] Gather detailed requirements
 2 - **context**: Define system context and boundaries
@@ -217,6 +276,29 @@ Files created:
 **Type a number to continue.**
 ```
 
+**If PRFAQ was skipped:**
+
+```markdown
+## Intent Created: `{intent-name}`
+
+**Goal**: {user's stated goal}
+**Type**: {intent type}
+**Location**: `{intent-path}/`
+
+Files created:
+- `requirements.md` (draft)
+- `inception-log.md` (progress tracker)
+
+> Note: PRFAQ skipped. You can generate it later with the `prfaq` action.
+
+1 - **requirements**: [Recommended] Gather detailed requirements
+2 - **prfaq**: Generate PRFAQ document
+3 - **context**: Define system context and boundaries
+4 - **menu**: Return to inception menu
+
+**Type a number to continue.**
+```
+
 ---
 
 ## Transition
@@ -224,6 +306,7 @@ Files created:
 After intent created:
 
 - → **requirements** - begin checkpoint workflow at Checkpoint 1
+- → **prfaq** (optional) - generate PRFAQ if skipped earlier
 
 ---
 
@@ -231,6 +314,12 @@ After intent created:
 
 ```yaml
 input: User's feature idea
-output: Intent directory with requirements.md and inception-log.md
+output: Intent directory with requirements.md, inception-log.md, and optionally prfaq.md
 checkpoints: 0 (prerequisite to workflow)
+artifacts:
+  required:
+    - requirements.md
+    - inception-log.md
+  optional:
+    - prfaq.md (AI-DLC recommended, user choice)
 ```

package/flows/aidlc/skills/inception/navigator.md

@@ -68,11 +68,12 @@ Scan artifacts **in order** - first missing item is the suggested next step:
 
 1. No intent folder exists → **Create Intent**
 2. `requirements.md` missing → **Gather Requirements**
-3. `system-context.md` missing → **Define Context**
-4. `units.md` missing → **Decompose Units**
-5. `story-index.md` missing → **Create Stories**
-6. `bolt-plan.md` missing → **Plan Bolts**
-7. All complete → **Review & Complete**
+3. `risks.md` missing → **Define Risks**
+4. `system-context.md` missing → **Define Context**
+5. `units.md` missing → **Decompose Units**
+6. `story-index.md` missing → **Create Stories**
+7. `bolt-plan.md` missing → **Plan Bolts**
+8. All complete → **Review & Complete**
 
 **CRITICAL**: The suggested step becomes **Option 1** in the menu.
 
@@ -121,6 +122,7 @@ When user selects an option:
 
 ### Progress
 - {✅ or [ ]} Requirements gathered {← current if next step}
+- {✅ or [ ]} Risks defined {← current if next step}
 - {✅ or [ ]} System context defined {← current if next step}
 - {✅ or [ ]} Units decomposed {← current if next step}
 - {✅ or [ ]} Stories created {← current if next step}
@@ -145,7 +147,7 @@ When user selects an option:
 **Type 1 to continue, or a number for other actions.**
 ```
 
-**Example: Requirements done, context missing**
+**Example: Requirements done, risks missing**
 
 ```markdown
 ## Inception Agent
@@ -155,7 +157,8 @@ When user selects an option:
 
 ### Progress
 - ✅ Requirements gathered
-- [ ] System context defined ← current
+- [ ] Risks defined ← current
+- [ ] System context defined
 - [ ] Units decomposed
 - [ ] Stories created
 - [ ] Bolts planned
@@ -165,7 +168,7 @@ When user selects an option:
 
 ### Continue This Intent
 
-1 - **Define Context** ← Next step
+1 - **Define Risks** ← Next step
 2 - Revisit Requirements
 
 ### Other Actions
@@ -191,6 +194,7 @@ When user selects an option:
 All inception artifacts have been created:
 
 - ✅ Requirements gathered
+- ✅ Risks defined
 - ✅ System context defined
 - ✅ Units decomposed
 - ✅ Stories created
@@ -198,6 +202,7 @@ All inception artifacts have been created:
 - ✅ Review complete
 
 ### Summary
+- Risks identified: {n}
 - Units defined: {n}
 - Stories created: {n}
 - Bolts planned: {n}