olympus-ai 4.5.13 → 4.5.14

package/resources/rules/common/pathway-behaviors.json

@@ -1,60 +1,60 @@
-{
-  "bugfix": {
-    "rules": [
-      {
-        "id": "BF-001",
-        "name": "autonomous-diagnosis",
-        "description": "Before writing any code change, reproduce the defect with a failing test or a documented reproduction recipe, identify the root cause (the specific code path, assumption, or edge case that causes the failure), and document the root cause in the '## Root Cause' section of the unit's test-report.md. Do not write a fix before completing the diagnosis.",
-        "enforcement": "mandatory"
-      },
-      {
-        "id": "BF-002",
-        "name": "root-cause-analysis",
-        "description": "The test-report.md for a bugfix unit must contain a '## Root Cause' section with: file path and line number(s) of the defect, a one-paragraph explanation of why the failure occurs, and confirmation that the fix targets the root cause, not a workaround.",
-        "enforcement": "mandatory"
-      },
-      {
-        "id": "BF-003",
-        "name": "missing-test-rule",
-        "description": "Every bugfix unit MUST produce at least one new test that reproduces the original defect (fails before the fix, passes after), is placed in the appropriate test file for the affected module, and is named to clearly identify the defect it guards against. This rule cannot be overridden via allowFailures. The engine blocks unit completion if tests_total === 0 for any bugfix unit.",
-        "enforcement": "mandatory"
-      }
-    ],
-    "quality_gate_checklist": [
-      "Root cause identified and documented in test-report.md",
-      "Fix addresses the root cause (not just the symptom)",
-      "All existing tests still pass (zero regressions)",
-      "At least one new test reproduces the original defect",
-      "New test passes with the fix applied"
-    ]
-  },
-  "optimization": {
-    "rules": [
-      {
-        "id": "OPT-001",
-        "name": "baseline-measurement",
-        "description": "Before making any code changes, run the relevant benchmark or performance test, record the baseline metric (e.g., execution time, memory usage, throughput) in the '## Baseline' section of the unit's test-report.md, and note the test command used and any environment conditions that could affect the result. Do not proceed with changes until the baseline is captured.",
-        "enforcement": "mandatory"
-      },
-      {
-        "id": "OPT-002",
-        "name": "before-after-comparison",
-        "description": "After applying changes, run the same benchmark or performance test under the same conditions and record the result in the '## Performance Comparison' section of test-report.md, including: baseline metric, post-change metric, and delta (absolute and percentage). Confirm the improvement meets the acceptance criteria defined in the unit spec. If performance has not improved, investigate before marking the unit complete.",
-        "enforcement": "mandatory"
-      },
-      {
-        "id": "OPT-003",
-        "name": "rollback-plan",
-        "description": "Document in test-report.md how to revert the optimization if it causes a regression in production: which files were changed, the prior behavior that would need to be restored, and any feature flags or config knobs that could disable the optimization without a deploy.",
-        "enforcement": "mandatory"
-      }
-    ],
-    "quality_gate_checklist": [
-      "Baseline metric recorded in test-report.md before changes",
-      "Post-change metric recorded with delta (absolute and percentage)",
-      "Improvement meets the acceptance criteria defined in the unit spec",
-      "Rollback plan documented in test-report.md",
-      "All existing tests still pass (zero regressions)"
-    ]
-  }
-}
+{
+  "bugfix": {
+    "rules": [
+      {
+        "id": "BF-001",
+        "name": "autonomous-diagnosis",
+        "description": "Before writing any code change, reproduce the defect with a failing test or a documented reproduction recipe, identify the root cause (the specific code path, assumption, or edge case that causes the failure), and document the root cause in the '## Root Cause' section of the unit's test-report.md. Do not write a fix before completing the diagnosis.",
+        "enforcement": "mandatory"
+      },
+      {
+        "id": "BF-002",
+        "name": "root-cause-analysis",
+        "description": "The test-report.md for a bugfix unit must contain a '## Root Cause' section with: file path and line number(s) of the defect, a one-paragraph explanation of why the failure occurs, and confirmation that the fix targets the root cause, not a workaround.",
+        "enforcement": "mandatory"
+      },
+      {
+        "id": "BF-003",
+        "name": "missing-test-rule",
+        "description": "Every bugfix unit MUST produce at least one new test that reproduces the original defect (fails before the fix, passes after), is placed in the appropriate test file for the affected module, and is named to clearly identify the defect it guards against. This rule cannot be overridden via allowFailures. The engine blocks unit completion if tests_total === 0 for any bugfix unit.",
+        "enforcement": "mandatory"
+      }
+    ],
+    "quality_gate_checklist": [
+      "Root cause identified and documented in test-report.md",
+      "Fix addresses the root cause (not just the symptom)",
+      "All existing tests still pass (zero regressions)",
+      "At least one new test reproduces the original defect",
+      "New test passes with the fix applied"
+    ]
+  },
+  "optimization": {
+    "rules": [
+      {
+        "id": "OPT-001",
+        "name": "baseline-measurement",
+        "description": "Before making any code changes, run the relevant benchmark or performance test, record the baseline metric (e.g., execution time, memory usage, throughput) in the '## Baseline' section of the unit's test-report.md, and note the test command used and any environment conditions that could affect the result. Do not proceed with changes until the baseline is captured.",
+        "enforcement": "mandatory"
+      },
+      {
+        "id": "OPT-002",
+        "name": "before-after-comparison",
+        "description": "After applying changes, run the same benchmark or performance test under the same conditions and record the result in the '## Performance Comparison' section of test-report.md, including: baseline metric, post-change metric, and delta (absolute and percentage). Confirm the improvement meets the acceptance criteria defined in the unit spec. If performance has not improved, investigate before marking the unit complete.",
+        "enforcement": "mandatory"
+      },
+      {
+        "id": "OPT-003",
+        "name": "rollback-plan",
+        "description": "Document in test-report.md how to revert the optimization if it causes a regression in production: which files were changed, the prior behavior that would need to be restored, and any feature flags or config knobs that could disable the optimization without a deploy.",
+        "enforcement": "mandatory"
+      }
+    ],
+    "quality_gate_checklist": [
+      "Baseline metric recorded in test-report.md before changes",
+      "Post-change metric recorded with delta (absolute and percentage)",
+      "Improvement meets the acceptance criteria defined in the unit spec",
+      "Rollback plan documented in test-report.md",
+      "All existing tests still pass (zero regressions)"
+    ]
+  }
+}

package/resources/rules/common/pathway-behaviors.md

@@ -1,100 +1,100 @@
-# Pathway Behaviors
-
-**Loading note**: The orchestrator loads this file at the start of each Construction unit and
-injects the section matching `checkpoint.pathway_type` into the agent context. Only the
-relevant section is injected — the agent sees its pathway section, not the full file.
-
----
-
-## Bugfix Pathway
-
-These rules are non-negotiable. Every bugfix unit must satisfy all items in the quality gate
-before the unit is marked complete.
-
-### Autonomous Diagnosis
-
-Before writing any code change, the agent must:
-
-1. Reproduce the defect with a failing test or a documented reproduction recipe
-2. Identify the root cause — the specific code path, assumption, or edge case that causes
-   the failure
-3. Document the root cause in the `## Root Cause` section of the unit's `test-report.md`
-
-Do not write a fix before completing the diagnosis. A fix that addresses only the symptom
-will likely fail the quality gate.
-
-### Root Cause Analysis Requirement
-
-The `test-report.md` for a bugfix unit must contain a `## Root Cause` section with:
-- File path and line number(s) of the defect
-- A one-paragraph explanation of why the failure occurs
-- Confirmation that the fix targets the root cause, not a workaround
-
-### Missing Test Rule (Non-Negotiable)
-
-Every bugfix unit MUST produce at least one new test that:
-- Reproduces the original defect (fails before the fix, passes after)
-- Is placed in the appropriate test file for the affected module
-- Is named to clearly identify the defect it guards against
-
-This rule cannot be overridden via `allowFailures`. The engine blocks unit completion if
-`tests_total === 0` for any bugfix unit, regardless of options passed.
-
-### Quality Gate Checklist
-
-All items must be satisfied before the bugfix unit is marked complete:
-
-- [ ] Root cause identified and documented in `test-report.md`
-- [ ] Fix addresses the root cause (not just the symptom)
-- [ ] All existing tests still pass (zero regressions)
-- [ ] At least one new test reproduces the original defect
-- [ ] New test passes with the fix applied
-
----
-
-## Optimization Pathway
-
-### Baseline Measurement
-
-Before making any code changes:
-
-1. Run the relevant benchmark or performance test
-2. Record the baseline metric (e.g., execution time, memory usage, throughput) in the
-   `## Baseline` section of the unit's `test-report.md`
-3. Note the test command used and any environment conditions that could affect the result
-
-Do not proceed with changes until the baseline is captured. A comparison without a baseline
-is not a valid optimization result.
-
-### Performance Comparison
-
-After applying changes:
-
-1. Run the same benchmark or performance test under the same conditions
-2. Record the result in the `## Performance Comparison` section of `test-report.md`:
-   - Baseline metric
-   - Post-change metric
-   - Delta (absolute and percentage)
-3. Confirm the improvement meets the acceptance criteria defined in the unit spec
-
-If performance has not improved, investigate before marking the unit complete.
-
-### Rollback Plan
-
-Document in `test-report.md` how to revert the optimization if it causes a regression in
-production:
-- Which files were changed
-- The prior behavior that would need to be restored
-- Any feature flags or config knobs that could disable the optimization without a deploy
-
----
-
-## Standard / Enhancement / Greenfield Pathways
-
-No additional behavioral constraints apply beyond the standard rules defined in:
-
-- `resources/rules/construction/code-generation.md`
-- `resources/rules/construction/test-generation.md`
-
-Follow those rules as written. The orchestrator does not inject any additional context for
-these pathways.
+# Pathway Behaviors
+
+**Loading note**: The orchestrator loads this file at the start of each Construction unit and
+injects the section matching `checkpoint.pathway_type` into the agent context. Only the
+relevant section is injected — the agent sees its pathway section, not the full file.
+
+---
+
+## Bugfix Pathway
+
+These rules are non-negotiable. Every bugfix unit must satisfy all items in the quality gate
+before the unit is marked complete.
+
+### Autonomous Diagnosis
+
+Before writing any code change, the agent must:
+
+1. Reproduce the defect with a failing test or a documented reproduction recipe
+2. Identify the root cause — the specific code path, assumption, or edge case that causes
+   the failure
+3. Document the root cause in the `## Root Cause` section of the unit's `test-report.md`
+
+Do not write a fix before completing the diagnosis. A fix that addresses only the symptom
+will likely fail the quality gate.
+
+### Root Cause Analysis Requirement
+
+The `test-report.md` for a bugfix unit must contain a `## Root Cause` section with:
+- File path and line number(s) of the defect
+- A one-paragraph explanation of why the failure occurs
+- Confirmation that the fix targets the root cause, not a workaround
+
+### Missing Test Rule (Non-Negotiable)
+
+Every bugfix unit MUST produce at least one new test that:
+- Reproduces the original defect (fails before the fix, passes after)
+- Is placed in the appropriate test file for the affected module
+- Is named to clearly identify the defect it guards against
+
+This rule cannot be overridden via `allowFailures`. The engine blocks unit completion if
+`tests_total === 0` for any bugfix unit, regardless of options passed.
+
+### Quality Gate Checklist
+
+All items must be satisfied before the bugfix unit is marked complete:
+
+- [ ] Root cause identified and documented in `test-report.md`
+- [ ] Fix addresses the root cause (not just the symptom)
+- [ ] All existing tests still pass (zero regressions)
+- [ ] At least one new test reproduces the original defect
+- [ ] New test passes with the fix applied
+
+---
+
+## Optimization Pathway
+
+### Baseline Measurement
+
+Before making any code changes:
+
+1. Run the relevant benchmark or performance test
+2. Record the baseline metric (e.g., execution time, memory usage, throughput) in the
+   `## Baseline` section of the unit's `test-report.md`
+3. Note the test command used and any environment conditions that could affect the result
+
+Do not proceed with changes until the baseline is captured. A comparison without a baseline
+is not a valid optimization result.
+
+### Performance Comparison
+
+After applying changes:
+
+1. Run the same benchmark or performance test under the same conditions
+2. Record the result in the `## Performance Comparison` section of `test-report.md`:
+   - Baseline metric
+   - Post-change metric
+   - Delta (absolute and percentage)
+3. Confirm the improvement meets the acceptance criteria defined in the unit spec
+
+If performance has not improved, investigate before marking the unit complete.
+
+### Rollback Plan
+
+Document in `test-report.md` how to revert the optimization if it causes a regression in
+production:
+- Which files were changed
+- The prior behavior that would need to be restored
+- Any feature flags or config knobs that could disable the optimization without a deploy
+
+---
+
+## Standard / Enhancement / Greenfield Pathways
+
+No additional behavioral constraints apply beyond the standard rules defined in:
+
+- `resources/rules/construction/code-generation.md`
+- `resources/rules/construction/test-generation.md`
+
+Follow those rules as written. The orchestrator does not inject any additional context for
+these pathways.

package/resources/rules/common/process-overview.md

@@ -1,157 +1,157 @@
-# AI-DLC Adaptive Workflow Overview
-
-**Purpose**: Technical reference for AI model and developers to understand complete workflow structure.
-
-**Note**: Similar content exists in core-workflow.md (user welcome message) and README.md (documentation). This duplication is INTENTIONAL - each file serves a different purpose:
-- **This file**: Detailed technical reference with Mermaid diagram for AI model context loading
-- **core-workflow.md**: User-facing welcome message with ASCII diagram
-- **README.md**: Human-readable documentation for repository
-
-## The Three-Phase Lifecycle:
-• **INCEPTION PHASE**: Planning and architecture (Workspace Detection + conditional phases + Workflow Planning)
-• **CONSTRUCTION PHASE**: Design, implementation, build and test (per-unit design + Code Generation (two-part: plan then generate) + Build & Test)
-• **OPERATIONS PHASE**: Placeholder for future deployment and monitoring workflows
-
-## The Adaptive Workflow:
-• **Workspace Detection** (always) → **Reverse Engineering** (brownfield only) → **Requirements Analysis** (always, adaptive depth) → **Conditional Phases** (as needed) → **Workflow Planning** (always) → **Code Generation** (always, per-unit) → **Build and Test** (always) → **Documentation** (always)
-
-## How It Works:
-• **AI analyzes** your request, workspace, and complexity to determine which stages are needed
-• **These stages always execute**: Workspace Detection, Requirements Analysis (adaptive depth), Workflow Planning, Code Generation (per-unit), Build and Test, Documentation
-• **All other stages are conditional**: Reverse Engineering, User Stories, Units Generation, per-unit design stages (Functional Design, NFR Requirements, NFR Design, Infrastructure Design)
-• **No fixed sequences**: Stages execute in the order that makes sense for your specific task
-
-## Your Team's Role:
-• **Answer questions** in dedicated question files using [Answer]: tags with letter choices (A, B, C, D, E)
-• **Option E available**: Choose "Other" and describe your custom response if provided options don't match
-• **Work as a team** to review and approve each phase before proceeding
-• **Collectively decide** on architectural approach when needed
-• **Important**: This is a team effort - involve relevant stakeholders for each phase
-
-## AI-DLC Three-Phase Workflow:
-
-```mermaid
-flowchart TD
-    Start(["User Request"])
-    
-    subgraph INCEPTION["🔵 INCEPTION PHASE"]
-        WD["Workspace Detection<br/><b>ALWAYS</b>"]
-        RE["Reverse Engineering<br/><b>CONDITIONAL</b>"]
-        RA["Requirements Analysis<br/><b>ALWAYS</b>"]
-        Stories["User Stories<br/><b>CONDITIONAL</b>"]
-        WP["Workflow Planning<br/><b>ALWAYS</b>"]
-        UnitsG["Units Generation<br/><b>CONDITIONAL</b>"]
-    end
-    
-    subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
-        FD["Functional Design<br/><b>CONDITIONAL</b>"]
-        NFRA["NFR Requirements<br/><b>CONDITIONAL</b>"]
-        NFRD["NFR Design<br/><b>CONDITIONAL</b>"]
-        ID["Infrastructure Design<br/><b>CONDITIONAL</b>"]
-        CG["Code Generation<br/><b>ALWAYS</b>"]
-        BT["Build and Test<br/><b>ALWAYS</b>"]
-        DOC["Documentation<br/><b>ALWAYS</b>"]
-    end
-    
-    subgraph OPERATIONS["🟡 OPERATIONS PHASE"]
-        OPS["Operations<br/><b>PLACEHOLDER</b>"]
-    end
-    
-    Start --> WD
-    WD -.-> RE
-    WD --> RA
-    RE --> RA
-    
-    RA -.-> Stories
-    RA --> WP
-    Stories --> WP
-    
-    WP -.-> UnitsG
-    UnitsG --> FD
-    FD -.-> NFRA
-    NFRA -.-> NFRD
-    NFRD -.-> ID
-    
-    WP --> CG
-    FD --> CG
-    NFRA --> CG
-    NFRD --> CG
-    ID --> CG
-    CG -.->|Next Unit| FD
-    CG --> BT
-    BT --> DOC
-    DOC -.-> OPS
-    DOC --> End(["Complete"])
-    
-    style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
-    style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
-    style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
-
-    style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
-    style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
-    style DOC fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
-    style OPS fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
-    style RE fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
-    style Stories fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
-
-    style UnitsG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
-    style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
-    style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
-    style NFRD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
-    style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
-    style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px, color:#000
-    style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px, color:#000
-    style OPERATIONS fill:#FFF59D,stroke:#F57F17,stroke-width:3px, color:#000
-    style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
-    style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
-    
-    linkStyle default stroke:#333,stroke-width:2px
-```
-
-**Stage Descriptions:**
-
-**🔵 INCEPTION PHASE** - Planning and Architecture
-- Workspace Detection: Analyze workspace state and project type (ALWAYS)
-- Reverse Engineering: Analyze existing codebase (CONDITIONAL - Brownfield only)
-- Requirements Analysis: Gather and validate requirements (ALWAYS - Adaptive depth)
-- User Stories: Create user stories and personas (CONDITIONAL)
-- Workflow Planning: Create execution plan (ALWAYS)
-- Units Generation: Decompose into units of work (CONDITIONAL)
-
-**🟢 CONSTRUCTION PHASE** - Design, Implementation, Build and Test
-- Functional Design: Detailed business logic design per unit (CONDITIONAL, per-unit)
-- NFR Requirements: Determine NFRs and select tech stack (CONDITIONAL, per-unit)
-- NFR Design: Incorporate NFR patterns and logical components (CONDITIONAL, per-unit)
-- Infrastructure Design: Map to actual infrastructure services (CONDITIONAL, per-unit)
-- Code Generation: Generate code with Part 1 - Planning, Part 2 - Generation (ALWAYS, per-unit)
-- Build and Test: Build all units and execute comprehensive testing (ALWAYS)
-- Documentation: Generate documentation drafts from workflow artifacts (ALWAYS)
-
-**🟡 OPERATIONS PHASE** - Placeholder
-- Operations: Placeholder for future deployment and monitoring workflows (PLACEHOLDER)
-
-**Key Principles:**
-- Phases execute only when they add value
-- Each phase independently evaluated
-- INCEPTION focuses on "what" and "why"
-- CONSTRUCTION focuses on "how" plus "build and test"
-- OPERATIONS is placeholder for future expansion
-- Simple changes may skip conditional INCEPTION stages
-- Complex changes get full INCEPTION and CONSTRUCTION treatment
-
-## Approval Gate Safety Rule
-
-**CRITICAL**: NEVER present an approval gate while background agents are still running.
-
-All background agents and parallel tasks MUST complete — and their results MUST be fully incorporated — BEFORE presenting any approval prompt to the user.
-
-**Why**: When a background agent completes, it triggers a new processing turn for the orchestrator. If an approval gate has already been presented, the orchestrator will resume processing from the agent completion notification instead of waiting for the user's response. This bypasses the approval gate entirely.
-
-**Rule**: Before displaying any "You may: Request Changes / Continue" prompt:
-1. Confirm zero pending background agents or tasks
-2. Incorporate all returned results into the current artifact
-3. Only then present the approval prompt
-
-If exploration or file reading is needed during planning, either:
-- Run it in the **foreground** (blocking) so it completes before the approval gate, OR
-- Run it in the background but **wait for completion** before presenting the approval prompt — do NOT present the prompt while agents are still running
+# AI-DLC Adaptive Workflow Overview
+
+**Purpose**: Technical reference for AI model and developers to understand complete workflow structure.
+
+**Note**: Similar content exists in core-workflow.md (user welcome message) and README.md (documentation). This duplication is INTENTIONAL - each file serves a different purpose:
+- **This file**: Detailed technical reference with Mermaid diagram for AI model context loading
+- **core-workflow.md**: User-facing welcome message with ASCII diagram
+- **README.md**: Human-readable documentation for repository
+
+## The Three-Phase Lifecycle:
+• **INCEPTION PHASE**: Planning and architecture (Workspace Detection + conditional phases + Workflow Planning)
+• **CONSTRUCTION PHASE**: Design, implementation, build and test (per-unit design + Code Generation (two-part: plan then generate) + Build & Test)
+• **OPERATIONS PHASE**: Placeholder for future deployment and monitoring workflows
+
+## The Adaptive Workflow:
+• **Workspace Detection** (always) → **Reverse Engineering** (brownfield only) → **Requirements Analysis** (always, adaptive depth) → **Conditional Phases** (as needed) → **Workflow Planning** (always) → **Code Generation** (always, per-unit) → **Build and Test** (always) → **Documentation** (always)
+
+## How It Works:
+• **AI analyzes** your request, workspace, and complexity to determine which stages are needed
+• **These stages always execute**: Workspace Detection, Requirements Analysis (adaptive depth), Workflow Planning, Code Generation (per-unit), Build and Test, Documentation
+• **All other stages are conditional**: Reverse Engineering, User Stories, Units Generation, per-unit design stages (Functional Design, NFR Requirements, NFR Design, Infrastructure Design)
+• **No fixed sequences**: Stages execute in the order that makes sense for your specific task
+
+## Your Team's Role:
+• **Answer questions** in dedicated question files using [Answer]: tags with letter choices (A, B, C, D, E)
+• **Option E available**: Choose "Other" and describe your custom response if provided options don't match
+• **Work as a team** to review and approve each phase before proceeding
+• **Collectively decide** on architectural approach when needed
+• **Important**: This is a team effort - involve relevant stakeholders for each phase
+
+## AI-DLC Three-Phase Workflow:
+
+```mermaid
+flowchart TD
+    Start(["User Request"])
+    
+    subgraph INCEPTION["🔵 INCEPTION PHASE"]
+        WD["Workspace Detection<br/><b>ALWAYS</b>"]
+        RE["Reverse Engineering<br/><b>CONDITIONAL</b>"]
+        RA["Requirements Analysis<br/><b>ALWAYS</b>"]
+        Stories["User Stories<br/><b>CONDITIONAL</b>"]
+        WP["Workflow Planning<br/><b>ALWAYS</b>"]
+        UnitsG["Units Generation<br/><b>CONDITIONAL</b>"]
+    end
+    
+    subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
+        FD["Functional Design<br/><b>CONDITIONAL</b>"]
+        NFRA["NFR Requirements<br/><b>CONDITIONAL</b>"]
+        NFRD["NFR Design<br/><b>CONDITIONAL</b>"]
+        ID["Infrastructure Design<br/><b>CONDITIONAL</b>"]
+        CG["Code Generation<br/><b>ALWAYS</b>"]
+        BT["Build and Test<br/><b>ALWAYS</b>"]
+        DOC["Documentation<br/><b>ALWAYS</b>"]
+    end
+    
+    subgraph OPERATIONS["🟡 OPERATIONS PHASE"]
+        OPS["Operations<br/><b>PLACEHOLDER</b>"]
+    end
+    
+    Start --> WD
+    WD -.-> RE
+    WD --> RA
+    RE --> RA
+    
+    RA -.-> Stories
+    RA --> WP
+    Stories --> WP
+    
+    WP -.-> UnitsG
+    UnitsG --> FD
+    FD -.-> NFRA
+    NFRA -.-> NFRD
+    NFRD -.-> ID
+    
+    WP --> CG
+    FD --> CG
+    NFRA --> CG
+    NFRD --> CG
+    ID --> CG
+    CG -.->|Next Unit| FD
+    CG --> BT
+    BT --> DOC
+    DOC -.-> OPS
+    DOC --> End(["Complete"])
+    
+    style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
+    style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
+    style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
+
+    style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
+    style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
+    style DOC fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
+    style OPS fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
+    style RE fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
+    style Stories fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
+
+    style UnitsG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
+    style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
+    style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
+    style NFRD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
+    style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
+    style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px, color:#000
+    style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px, color:#000
+    style OPERATIONS fill:#FFF59D,stroke:#F57F17,stroke-width:3px, color:#000
+    style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
+    style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
+    
+    linkStyle default stroke:#333,stroke-width:2px
+```
+
+**Stage Descriptions:**
+
+**🔵 INCEPTION PHASE** - Planning and Architecture
+- Workspace Detection: Analyze workspace state and project type (ALWAYS)
+- Reverse Engineering: Analyze existing codebase (CONDITIONAL - Brownfield only)
+- Requirements Analysis: Gather and validate requirements (ALWAYS - Adaptive depth)
+- User Stories: Create user stories and personas (CONDITIONAL)
+- Workflow Planning: Create execution plan (ALWAYS)
+- Units Generation: Decompose into units of work (CONDITIONAL)
+
+**🟢 CONSTRUCTION PHASE** - Design, Implementation, Build and Test
+- Functional Design: Detailed business logic design per unit (CONDITIONAL, per-unit)
+- NFR Requirements: Determine NFRs and select tech stack (CONDITIONAL, per-unit)
+- NFR Design: Incorporate NFR patterns and logical components (CONDITIONAL, per-unit)
+- Infrastructure Design: Map to actual infrastructure services (CONDITIONAL, per-unit)
+- Code Generation: Generate code with Part 1 - Planning, Part 2 - Generation (ALWAYS, per-unit)
+- Build and Test: Build all units and execute comprehensive testing (ALWAYS)
+- Documentation: Generate documentation drafts from workflow artifacts (ALWAYS)
+
+**🟡 OPERATIONS PHASE** - Placeholder
+- Operations: Placeholder for future deployment and monitoring workflows (PLACEHOLDER)
+
+**Key Principles:**
+- Phases execute only when they add value
+- Each phase independently evaluated
+- INCEPTION focuses on "what" and "why"
+- CONSTRUCTION focuses on "how" plus "build and test"
+- OPERATIONS is placeholder for future expansion
+- Simple changes may skip conditional INCEPTION stages
+- Complex changes get full INCEPTION and CONSTRUCTION treatment
+
+## Approval Gate Safety Rule
+
+**CRITICAL**: NEVER present an approval gate while background agents are still running.
+
+All background agents and parallel tasks MUST complete — and their results MUST be fully incorporated — BEFORE presenting any approval prompt to the user.
+
+**Why**: When a background agent completes, it triggers a new processing turn for the orchestrator. If an approval gate has already been presented, the orchestrator will resume processing from the agent completion notification instead of waiting for the user's response. This bypasses the approval gate entirely.
+
+**Rule**: Before displaying any "You may: Request Changes / Continue" prompt:
+1. Confirm zero pending background agents or tasks
+2. Incorporate all returned results into the current artifact
+3. Only then present the approval prompt
+
+If exploration or file reading is needed during planning, either:
+- Run it in the **foreground** (blocking) so it completes before the approval gate, OR
+- Run it in the background but **wait for completion** before presenting the approval prompt — do NOT present the prompt while agents are still running