project-iris 0.0.17 → 0.1.0

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

@@ -27,6 +27,22 @@
 
 ---
 
+## Display Convention (CRITICAL)
+
+When referencing bolt files to the user, ALWAYS show the **bolt ID prominently**, not just "bolt.md":
+
+**WRONG**:
+- "Working on bolt.md"
+- "Open bolt.md to see details"
+
+**CORRECT**:
+- "Working on **001-extension-foundation**"
+- "Open **001-extension-foundation/bolt.md** to see details"
+
+The bolt ID (directory name like `001-extension-foundation`) is the identifier. The file `bolt.md` is just the metadata file inside. Users should always see and understand WHICH bolt they're working on.
+
+---
+
 ## Checkpoints
 
 **Checkpoint 1**: Which bolt to work on?

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

@@ -33,6 +33,24 @@
 
 ---
 
+## Display Convention (CRITICAL)
+
+When referencing bolt files to the user, ALWAYS show the **bolt ID prominently**, not just "bolt.md":
+
+**WRONG**:
+- "Working on bolt.md"
+- "Updating bolt.md status"
+- "Approve changes to bolt.md?"
+
+**CORRECT**:
+- "Working on **001-extension-foundation**"
+- "Updating **001-extension-foundation** status"
+- "Approve changes to **001-extension-foundation/bolt.md**?"
+
+The bolt ID (directory name like `001-extension-foundation`) is the identifier. Users should always see and understand WHICH bolt they're working on.
+
+---
+
 ## Bolt Type Execution
 
 Stages, activities, outputs, and checkpoints come from the bolt type definition:
@@ -145,7 +163,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")
 ---
 ```
 
@@ -430,6 +448,24 @@ If construction log doesn't exist, create it using template:
 
 ---
 
+## CRITICAL: Post-Bolt Options (NEVER SKIP)
+
+**After EVERY bolt completion, you MUST present the Actions menu above.**
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  BOLT COMPLETED                                              │
+│  → You MUST show the Actions menu (1-next, 2-list, 3-ops)   │
+│  → Do NOT just ask "approve to continue?"                    │
+│  → Let the user CHOOSE their next action                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Failure Mode**: Asking "Ready to proceed to next bolt?" without showing options
+**Correct Behavior**: Always show numbered Actions list and wait for user choice
+
+---
+
 ## Bolt Completion Checklist
 
 **Use this checklist to verify all completion tasks are done:**

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

@@ -255,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/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/requirements.md

@@ -325,7 +325,74 @@ Do these SLOs align with your expectations?
 
 ---
 
-### Step 5: Document Trade-offs
+### Step 5: Define Measurement Criteria (AI-DLC Requirement)
+
+**Per AI-DLC specification, Measurement Criteria must trace to the business intent.**
+
+Unlike technical SLOs, Measurement Criteria capture business-level success indicators.
+
+```markdown
+## Measurement Criteria
+
+Measurement Criteria trace back to the business intent and help validate whether the feature delivers expected value.
+
+### Business Outcome Metrics
+
+1. **Primary Success Metric**: What single metric best indicates this feature is successful?
+   - Metric: ___
+   - Current baseline (if known): ___
+   - Target: ___
+   - Measurement method: ___
+
+2. **User Adoption Metrics**:
+   - Expected active users: ___
+   - Feature usage frequency: ___
+   - Time to first value: ___
+
+3. **Business Impact Metrics**:
+   - Revenue impact (if applicable): ___
+   - Cost reduction (if applicable): ___
+   - Efficiency gain (if applicable): ___
+
+### Leading Indicators
+What early signals will indicate we're on track?
+- ___
+- ___
+
+### Lagging Indicators
+What will confirm long-term success?
+- ___
+- ___
+
+### Measurement Timeline
+- **Week 1-2**: {Early indicators to monitor}
+- **Month 1**: {Short-term success criteria}
+- **Quarter 1**: {Long-term validation}
+```
+
+**Wait for user input on key metrics.**
+
+**After receiving answers, document in requirements.md:**
+
+```markdown
+## Measurement Criteria
+
+### Primary Success Metric
+- **Metric**: {metric name}
+- **Baseline**: {current state}
+- **Target**: {goal}
+- **Measurement**: {how to measure}
+
+### Business Traceability
+| Metric | Business Goal | FR/NFR Link |
+|--------|---------------|-------------|
+| {Metric 1} | {Which business goal it validates} | FR-1, FR-2 |
+| {Metric 2} | {Which business goal it validates} | NFR-P1 |
+```
+
+---
+
+### Step 6: Document Trade-offs
 
 If requirements conflict, document trade-offs:
 
@@ -347,7 +414,7 @@ I've identified these trade-offs in your requirements:
 
 ---
 
-### Step 6: Document Requirements
+### Step 7: Document Requirements
 
 1. **Read Path**: Check `schema.requirements` from `.iris/aidlc/memory-bank.yaml`
    *(Default: `memory-bank/intents/{intent-name}/requirements.md`)*
@@ -393,6 +460,19 @@ I've identified these trade-offs in your requirements:
    - **Latency (p95)**: < {X}ms
    - **Error Rate**: < {X}%
 
+   ## Measurement Criteria (AI-DLC Required)
+
+   ### Primary Success Metric
+   - **Metric**: {metric name}
+   - **Baseline**: {current state}
+   - **Target**: {goal}
+   - **Measurement**: {how to measure}
+
+   ### Business Traceability
+   | Metric | Business Goal | FR/NFR Link |
+   |--------|---------------|-------------|
+   | {Metric 1} | {Which business goal it validates} | FR-1, FR-2 |
+
    ## Trade-off Decisions
    - {Trade-off 1}: Chose {option} because {reason}
    ```
@@ -405,7 +485,7 @@ I've identified these trade-offs in your requirements:
 
 ---
 
-### Step 7: Requirements Review
+### Step 8: Requirements Review
 
 **Checkpoint 3**: Present FULL requirements for approval.
 
@@ -467,6 +547,10 @@ I've identified these trade-offs in your requirements:
 - **Latency (p95)**: < {X}ms
 - **Error Rate**: < {X}%
 
+### Measurement Criteria (Business Traceability)
+- **Primary Metric**: {metric} - Baseline: {X} → Target: {Y}
+- **Business Goal Link**: {Which intent goal this validates}
+
 ### Trade-off Decisions
 - {Trade-off 1}: Chose {option} because {reason}
 
@@ -490,7 +574,9 @@ Do these requirements capture your intent?
 - **Functional Requirements**: {N} defined
 - **Non-Functional Requirements**: {N} across 5 categories
 - **SLOs**: {N} defined
+- **Measurement Criteria**: {N} business metrics defined
 - **Trade-offs**: {N} documented
+- **Technical Constraints**: {N} intent-specific
 
 ### FR Quality
 - ✅ All FRs have User Story format
@@ -505,6 +591,15 @@ Do these requirements capture your intent?
 - ✅ Reliability: {count} requirements
 - ✅ Compliance: {count} requirements
 
+### Measurement Criteria (AI-DLC Required)
+- ✅ Primary success metric defined with baseline and target
+- ✅ Business traceability documented (metrics → goals → FRs)
+- ✅ Measurement timeline established
+
+### Technical Constraints
+- **Standards**: Loaded by Construction Agent from `memory-bank/standards/`
+- **Intent-Specific**: {constraints from Q7 not covered by standards, or "None"}
+
 ### Artifact Created
 - `{intent-path}/requirements.md`
 
@@ -590,10 +685,14 @@ Requirements ← YOU ARE HERE
 ## Test Contract
 
 ```yaml
-input: User answers to FR questions + NFR category questions (5 categories)
-output: requirements.md with FRs (user stories, acceptance criteria), NFRs (5 categories), SLOs, trade-offs
+input: User answers to FR questions + NFR category questions (5 categories) + Measurement Criteria questions
+output: requirements.md with FRs (user stories, acceptance criteria), NFRs (5 categories), SLOs, Measurement Criteria (business traceability), trade-offs
 checkpoints: 3
   - Checkpoint 1: FR clarifying questions answered
   - Checkpoint 2: All 5 NFR categories addressed
-  - Checkpoint 3: Full requirements approved
+  - Checkpoint 3: Full requirements approved (includes Measurement Criteria)
+ai_dlc_alignment:
+  - Measurement Criteria traces to business intent (spec requirement)
+  - SLOs provide technical targets
+  - Trade-offs documented for complex decisions
 ```

package/flows/aidlc/skills/master/answer-question.md

@@ -56,7 +56,7 @@ Identify what type of information is being requested:
 - **Status of intent/unit/bolt** → Check respective artifact files
 - **Configuration/settings** → `{schema.standards}/`
 - **Requirements** → `{intent}/requirements.md`
-- **Architecture decisions** → `{unit}/ddd-02-technical-design.md` or `standards/system-architecture.md`
+- **Architecture decisions** → `{unit}/ddd-02-logical-design.md` or `standards/system-architecture.md`
 - **Deployment info** → `{unit}/deployment/`
 - **Story details** → `{unit}/stories/`