gaia-framework 1.58.0 → 1.58.2

package/_gaia/lifecycle/workflows/4-implementation/add-stories/instructions.xml

@@ -0,0 +1,100 @@
+<workflow name="add-stories">
+<critical>
+  <mandate>Story protection is ENFORCED — stories with status in-progress, review, ready-for-dev, or done are READ-ONLY. Never modify them.</mandate>
+  <mandate>New stories MUST follow the exact format used in existing epics-and-stories.md</mandate>
+  <mandate>Story and epic IDs must not collide with existing IDs — auto-increment from highest existing</mandate>
+  <mandate>Append to existing content — never overwrite or reorder existing stories or epics</mandate>
+</critical>
+
+<step n="1" title="Load and Analyze Existing State">
+  <action>Read {planning_artifacts}/epics-and-stories.md in full</action>
+  <action>Read {implementation_artifacts}/sprint-status.yaml in full</action>
+  <action>Parse all existing epic IDs and names</action>
+  <action>Parse all existing story IDs per epic — identify highest ID per epic and overall</action>
+  <action>Build protection map: for each story, record its current status from sprint-status.yaml:
+    - LOCKED: done, review, in-progress, ready-for-dev — cannot be modified
+    - PROTECTED: invalid — cannot be modified by default
+    - CAUTIOUS: validating, backlog — modification requires explicit user confirmation
+    - OPEN: new stories not yet in sprint-status — full read/write</action>
+  <action>Display summary: total epics, total stories, stories by protection level (locked/protected/cautious/open)</action>
+</step>
+
+<step n="2" title="Identify New Requirements">
+  <check if="triggered_by_orchestrator">Inherit feature_description, prd_diff (new FR/NFR IDs), arch_diff (architecture changes), and cr_id from triggering workflow context. Skip user questions — proceed to Step 3.</check>
+  <ask>What new stories need to be added? Describe the feature or requirements.</ask>
+  <ask>Do these belong to an existing epic, or is a new epic needed?</ask>
+  <ask>Is this linked to a change request? If so, provide the CR ID.</ask>
+  <action>Read relevant sections of {planning_artifacts}/prd.md for context — focus on NEW requirements if prd_diff is available</action>
+  <action>Read relevant sections of {planning_artifacts}/architecture.md for technical context — focus on changes if arch_diff is available</action>
+</step>
+
+<step n="3" title="Epic Decision — New or Existing?">
+  <action>Analyze the new requirements against existing epics</action>
+  <action>For each requirement cluster, determine fit:
+    - Extends existing epic: new stories naturally belong under an existing epic's theme/goal
+    - New epic needed: the feature is a distinct capability that doesn't fit any existing epic
+    - Mixed: some stories extend existing epics, others need a new epic</action>
+  <ask>Present recommendation: "I recommend [creating new Epic {N}: {name} / adding to existing Epic {X}: {name}] for this feature. [Count] stories will be created. Do you agree?"</ask>
+  <action>User confirms or adjusts the epic assignment</action>
+</step>
+
+<step n="4" title="Create New Epic" optional="true" condition="new_epic_needed">
+  <action>Skip if all new stories fit into existing epics.</action>
+  <action>Auto-increment epic ID from highest existing (e.g., if E2 exists, new epic is E3)</action>
+  <action>Define epic with: name, description, goal, success criteria, estimated story count</action>
+  <action>Present epic definition to user for confirmation</action>
+</step>
+
+<step n="5" title="Define New Stories">
+  <action>For each new story:
+    - Title using "As a [user], I want to [action] so that [benefit]"
+    - Description with context
+    - Acceptance criteria (AC1, AC2, etc.)
+    - Size: S/M/L/XL
+    - Priority: P0/P1/P2
+    - Assign to correct epic (existing or newly created)
+    - Auto-increment story ID within the epic (e.g., if E2 has S1-S5, new stories start at E2-S6; if new E3, start at E3-S1)</action>
+  <action>If {test_artifacts}/test-plan.md exists: apply risk levels (high/medium/low) based on architectural complexity and test coverage</action>
+  <action>Declare depends_on and blocks against ALL existing stories</action>
+  <action>ENFORCE PROTECTION: dependency links FROM new stories TO locked/protected stories are allowed (read-only reference). But locked/protected stories themselves are NEVER modified.</action>
+  <action>Verify no circular dependencies introduced</action>
+  <action>If CR ID provided, add Source: CR-{cr_id} to each story</action>
+</step>
+
+<step n="6" title="Protection Validation">
+  <action>Scan all proposed changes against the protection map from Step 1</action>
+  <action>Verify: ZERO modifications to stories with status in-progress, review, ready-for-dev, done, or invalid</action>
+  <action>If any backlog or validating story would be modified: present the specific change and ask for explicit user confirmation with documented reason</action>
+  <action>Display protection report: "{count} locked stories verified READ-ONLY. {count} protected stories verified READ-ONLY. {count} new stories will be created."</action>
+  <action>If any protection violation detected: HALT — do not proceed until resolved</action>
+</step>
+
+<step n="7" title="Append to Epics and Stories">
+  <action>If new epic created: append entire epic section at end of document with all new stories</action>
+  <action>If adding to existing epic: append new stories after the last story in that epic</action>
+  <action>Add change log entry: date, feature name, CR ID (if applicable), epics affected, stories added</action>
+  <template-output file="{planning_artifacts}/epics-and-stories.md">
+    Append new stories to existing epics-and-stories.md. Each new story formatted as:
+    ### Story {epic-N}-{story-N}: {Title}
+    - Epic: {epic name}
+    - Priority: {P0/P1/P2}
+    - Size: {S/M/L/XL}
+    - Risk: {high/medium/low}
+    - Depends on: [{story-ids}]
+    - Blocks: [{story-ids}]
+    - Source: CR-{cr_id} (if applicable)
+    - Acceptance Criteria:
+      - AC1: {criteria}
+    If new epic: include epic header with name, description, goal, success criteria before its stories.
+    Prepend a Change Log entry if not already present.
+  </template-output>
+</step>
+
+<step n="8" title="Next Steps">
+  <action>Report summary: new epic(s) created (if any), stories added with IDs and epic assignments</action>
+  <action>For each new story: "Run /gaia-create-story {story_key} to elaborate before development"</action>
+  <action>If stories should enter current sprint: "Run /gaia-correct-course to inject into sprint"</action>
+  <action>If stories should wait: "Stories are in backlog. Include in next /gaia-sprint-plan"</action>
+  <action>Recommend: "Run /gaia-trace to update traceability matrix with new stories"</action>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/4-implementation/add-stories/workflow.yaml

@@ -0,0 +1,35 @@
+name: add-stories
+description: 'Add new stories to existing epics or create new epics with stories'
+module: lifecycle
+agent: pm
+config_resolved: "{installed_path}/.resolved/add-stories.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/add-stories"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+input_file_patterns:
+  prd:
+    whole: "{planning_artifacts}/prd.md"
+    load_strategy: "SELECTIVE_LOAD"
+  architecture:
+    whole: "{planning_artifacts}/architecture.md"
+    load_strategy: "SELECTIVE_LOAD"
+  epics:
+    whole: "{planning_artifacts}/epics-and-stories.md"
+    load_strategy: "FULL_LOAD"
+  test_plan:
+    whole: "{test_artifacts}/test-plan.md"
+    load_strategy: "SELECTIVE_LOAD"
+  sprint_status:
+    whole: "{implementation_artifacts}/sprint-status.yaml"
+    load_strategy: "FULL_LOAD"
+quality_gates:
+  pre_start:
+    - check: "epics_exists"
+      on_fail: "HALT: epics-and-stories.md does not exist. Run /gaia-create-epics first."
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{planning_artifacts}/epics-and-stories.md"

package/_gaia/lifecycle/workflows/4-implementation/change-request/checklist.md

@@ -0,0 +1,25 @@
+---
+title: 'Change Request Validation'
+validation-target: 'Change request with impact analysis'
+---
+## Capture
+- [ ] Change description documented
+- [ ] Source/driver identified
+- [ ] Urgency classified (critical/high/normal)
+- [ ] CR ID assigned (CR-{date}-{seq})
+## Impact Analysis
+- [ ] Requirements impact assessed (NONE/MINOR/SIGNIFICANT/BREAKING)
+- [ ] Technical impact assessed (NONE/MINOR/SIGNIFICANT/BREAKING)
+- [ ] Sprint/effort impact assessed (ABSORBABLE/NEXT_SPRINT/MULTI_SPRINT)
+- [ ] Affected artifacts identified
+- [ ] Effort estimated (story points)
+## Approval
+- [ ] Impact analysis presented to user
+- [ ] User APPROVED or REJECTED the change
+## Cascade Updates (if approved)
+- [ ] PRD updated (or skipped — requirements_impact = NONE)
+- [ ] Architecture updated (or skipped — technical_impact = NONE)
+- [ ] Stories created/modified (or skipped — no story changes needed)
+## Output
+- [ ] Change request record generated at {planning_artifacts}/change-request-{cr_id}.md
+- [ ] Downstream next steps communicated

package/_gaia/lifecycle/workflows/4-implementation/change-request/instructions.xml

@@ -0,0 +1,123 @@
+<workflow name="change-request">
+<critical>
+  <mandate>Every change request must have a formal impact analysis before any artifact updates begin</mandate>
+  <mandate>User must APPROVE the change after reviewing impact analysis — this is a hard gate</mandate>
+  <mandate>Cascade updates to downstream artifacts via subagents after approval</mandate>
+</critical>
+
+<step n="1" title="Capture Change Request">
+  <ask>Describe the change request: What needs to change and why?</ask>
+  <ask>What is driving this change? (user feedback / stakeholder request / technical discovery / market shift / regulatory)</ask>
+  <ask>Urgency level? (critical — blocks current sprint / high — next sprint / normal — backlog)</ask>
+  <action>Assign CR ID: CR-{date}-{seq} (e.g., CR-2026-03-09-1). Check {planning_artifacts}/ for existing CR files to determine next sequence number.</action>
+</step>
+
+<step n="2" title="Load All Artifacts">
+  <action>Read {planning_artifacts}/prd.md — extract requirement IDs (FR-*, NFR-*), feature section headers, user personas, NFR targets</action>
+  <action>Read {planning_artifacts}/architecture.md — extract component list, API endpoints, data models, ADR references, tech stack</action>
+  <action>Read {planning_artifacts}/epics-and-stories.md — extract all story IDs, statuses, dependencies, sizes, risk levels</action>
+  <action>Read {implementation_artifacts}/sprint-status.yaml — current sprint ID, story statuses, velocity used vs available</action>
+  <action>Read {test_artifacts}/test-plan.md if exists — extract risk areas and high-risk components</action>
+  <action>Read {test_artifacts}/traceability-matrix.md if exists — extract requirement-to-test coverage mappings</action>
+  <action>Note any missing artifacts as INFO — they limit analysis depth but do not block the workflow</action>
+</step>
+
+<step n="3" title="Requirements Impact Analysis">
+  <action>Analyze the change against PRD content:</action>
+  <action>— Identify PRD sections affected (features, personas, user journeys, NFRs, constraints)</action>
+  <action>— List requirement IDs (FR-*, NFR-*) that need modification, addition, or removal</action>
+  <action>— Assess NFR impact: does this change performance, security, scalability, or availability targets?</action>
+  <action>— Identify user journeys affected — which personas and flows change?</action>
+  <action>Classify requirements_impact: NONE (no PRD changes) / MINOR (wording, clarification) / SIGNIFICANT (new requirements, modified scope) / BREAKING (removes or contradicts existing requirements)</action>
+</step>
+
+<step n="4" title="Technical Impact Analysis">
+  <action>Analyze the change against architecture:</action>
+  <action>— Identify architecture components affected (services, modules, layers)</action>
+  <action>— Assess API changes: new endpoints, modified contracts, breaking changes, versioning impact</action>
+  <action>— Assess data model changes: schema migrations needed, new entities, modified relationships</action>
+  <action>— Identify infrastructure impact: new services, scaling changes, deployment topology</action>
+  <action>— Check ADR implications: existing decisions invalidated? New architectural decisions needed?</action>
+  <action>Classify technical_impact: NONE / MINOR (config, minor refactor) / SIGNIFICANT (new component, API change) / BREAKING (architectural shift, tech stack change)</action>
+</step>
+
+<step n="5" title="Sprint and Effort Impact Analysis">
+  <action>Analyze the change against current sprint and stories:</action>
+  <action>— Identify existing stories directly affected (scope changes, new blockers, invalidated acceptance criteria)</action>
+  <action>— If stories in 'in-progress' or 'review' are affected: flag as HIGH_RISK — these may need rework</action>
+  <action>— Estimate new stories needed: count and size (S=1pt, M=3pt, L=5pt, XL=8pt)</action>
+  <action>— Calculate total effort: sum of new story points + rework estimate for affected existing stories</action>
+  <action>— Assess sprint absorption: compare effort against remaining sprint velocity capacity</action>
+  <action>Classify sprint_impact: ABSORBABLE (fits in current sprint) / NEXT_SPRINT (defer to next sprint) / MULTI_SPRINT (requires multiple sprints)</action>
+  <action>If traceability-matrix.md exists: flag test coverage gaps that this change will create</action>
+</step>
+
+<step n="6" title="Impact Summary and Approval Gate">
+  <action>Present consolidated impact analysis:
+
+  **Change Request: {cr_id}**
+  | Dimension | Impact Level | Details |
+  |-----------|-------------|---------|
+  | Requirements | {requirements_impact} | {affected PRD sections and requirement IDs} |
+  | Technical | {technical_impact} | {affected components, APIs, data models} |
+  | Sprint/Effort | {sprint_impact} | {story points estimate, sprint absorption capacity} |
+
+  **Artifacts to be modified:**
+  - {list each artifact and what will change}
+
+  **New artifacts to be created:**
+  - {list new stories, ADRs, etc.}
+
+  **Risk flags:**
+  - {HIGH_RISK stories, breaking changes, test coverage gaps}
+  </action>
+  <ask>Review the impact analysis above. Do you APPROVE or REJECT this change request?</ask>
+  <check if="user_rejects">Set cr_status = REJECTED. Skip steps 7-9 — proceed directly to step 10 to generate the CR record.</check>
+  <check if="user_approves">Set cr_status = APPROVED. Proceed with artifact cascade updates.</check>
+</step>
+
+<step n="7" title="Update PRD" optional="true" condition="requirements_impact != NONE AND cr_status == APPROVED">
+  <action>Skip if requirements_impact = NONE.</action>
+  <action>Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/2-planning/edit-prd/workflow.yaml as workflow-config. Run in YOLO mode. Follow the workflow engine instructions EXACTLY. Context: This is change request {cr_id}. Apply these changes to the PRD: {change_description}. Use CR ID {cr_id} when prompted."</action>
+  <action>When subagent returns: verify prd.md version note references {cr_id}. Record: prd_updated = true.</action>
+</step>
+
+<step n="8" title="Update Architecture" optional="true" condition="technical_impact != NONE AND cr_status == APPROVED">
+  <action>Skip if technical_impact = NONE.</action>
+  <action>If technical_impact = MINOR: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/3-solutioning/edit-architecture/workflow.yaml as workflow-config. Run in YOLO mode. Follow the workflow engine instructions EXACTLY. Context: This is change request {cr_id}. Apply these changes to the architecture: {change_description}. Technical impact is MINOR. Use CR ID {cr_id} when prompted."</action>
+  <action>If technical_impact = SIGNIFICANT: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/3-solutioning/edit-architecture/workflow.yaml as workflow-config. Run in YOLO mode. Follow the workflow engine instructions EXACTLY. Context: This is change request {cr_id}. Apply these changes to the architecture: {change_description}. Technical impact is SIGNIFICANT — adversarial review is required. Use CR ID {cr_id} when prompted."</action>
+  <action>If technical_impact = BREAKING: warn user — "BREAKING architectural change detected. Consider /gaia-create-arch for full regeneration, or /gaia-edit-arch for targeted major changes." Let user choose approach.</action>
+  <action>When subagent returns: verify architecture.md version note references {cr_id}. Record: architecture_updated = true.</action>
+</step>
+
+<step n="9" title="Update Stories" optional="true" condition="new_stories_needed OR existing_stories_affected AND cr_status == APPROVED">
+  <action>Skip if no new stories needed AND no existing stories affected.</action>
+  <action>If new stories needed: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/4-implementation/add-stories/workflow.yaml as workflow-config. Run in YOLO mode. Follow the workflow engine instructions EXACTLY. Context: Adding stories for change request {cr_id}. Requirements: {new_story_descriptions}."</action>
+  <action>When subagent returns: verify epics-and-stories.md has new stories with Source: {cr_id}. Record: stories_added = {count}.</action>
+  <action>If existing stories need scope changes: list affected stories with what needs to change — flag for manual update via /gaia-fix-story.</action>
+  <action>If sprint injection needed: inform user — "Run /gaia-correct-course with CR ID {cr_id} to inject new stories into current sprint."</action>
+</step>
+
+<step n="10" title="Generate Change Request Record">
+  <template-output file="{planning_artifacts}/change-request-{cr_id}.md">
+    Generate change request document with YAML frontmatter:
+    ---
+    cr_id: "{cr_id}"
+    date: "{date}"
+    status: "{APPROVED|REJECTED}"
+    urgency: "{critical|high|normal}"
+    driver: "{source}"
+    requirements_impact: "{NONE|MINOR|SIGNIFICANT|BREAKING}"
+    technical_impact: "{NONE|MINOR|SIGNIFICANT|BREAKING}"
+    sprint_impact: "{ABSORBABLE|NEXT_SPRINT|MULTI_SPRINT}"
+    effort_estimate_points: {number}
+    ---
+    Then detailed sections: Change Description, Impact Analysis (requirements, technical, sprint),
+    Affected Artifacts (what changed, what still needs manual update), Stories Created/Modified,
+    Cascade Status (completed updates vs pending), and Recommended Next Actions.
+    If REJECTED: include rejection reason and impact analysis for future reference.
+  </template-output>
+  <action>If cr_status == APPROVED and stories were added: recommend "/gaia-correct-course with CR ID {cr_id}" or "/gaia-create-story {story_key}" as next steps.</action>
+  <action>If cr_status == APPROVED and architecture update needed: recommend "/gaia-edit-arch to update architecture".</action>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/4-implementation/change-request/workflow.yaml

@@ -0,0 +1,38 @@
+name: change-request
+description: 'Impact-driven change request with analysis, approval gate, and cascade updates'
+module: lifecycle
+agent: pm
+config_resolved: "{installed_path}/.resolved/change-request.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/change-request"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+input_file_patterns:
+  prd:
+    whole: "{planning_artifacts}/prd.md"
+    load_strategy: "SELECTIVE_LOAD"
+  architecture:
+    whole: "{planning_artifacts}/architecture.md"
+    load_strategy: "SELECTIVE_LOAD"
+  epics:
+    whole: "{planning_artifacts}/epics-and-stories.md"
+    load_strategy: "SELECTIVE_LOAD"
+  sprint_status:
+    whole: "{implementation_artifacts}/sprint-status.yaml"
+    load_strategy: "FULL_LOAD"
+  test_plan:
+    whole: "{test_artifacts}/test-plan.md"
+    load_strategy: "SELECTIVE_LOAD"
+  traceability:
+    whole: "{test_artifacts}/traceability-matrix.md"
+    load_strategy: "SELECTIVE_LOAD"
+quality_gates:
+  pre_start:
+    - check: "prd.md exists"
+      on_fail: "HALT: No PRD to assess impact against. Run /gaia-create-prd first."
+on_error:
+  missing_file: "skip_and_note"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{planning_artifacts}/change-request-{cr_id}.md"

package/_gaia/lifecycle/workflows/4-implementation/check-dod/checklist.md

@@ -0,0 +1,18 @@
+---
+title: 'Definition of Done Check'
+validation-target: 'DoD validation for story review readiness'
+---
+
+## Checks
+
+- [ ] Story file found and loaded
+- [ ] Story status is in-progress or review
+- [ ] All acceptance criteria checked (- [x])
+- [ ] All tasks/subtasks checked (- [x])
+- [ ] Test scenarios table populated
+- [ ] Dev Agent Record has content
+- [ ] Definition of Done section items all checked
+- [ ] DoD items are not just template placeholder
+- [ ] DoD Check Report appended to story file
+- [ ] Overall verdict determined (PASS/FAIL)
+- [ ] Next step suggestion provided

package/_gaia/lifecycle/workflows/4-implementation/check-dod/instructions.xml

@@ -0,0 +1,54 @@
+<workflow name="check-dod">
+<critical>
+  <mandate>This is a validation check — do NOT modify story status or sprint-status.yaml</mandate>
+  <mandate>Report results by appending a DoD Check Report section to the story file</mandate>
+  <mandate>Use glob {story_key}-*.md to find the story file</mandate>
+</critical>
+<step n="1" title="Load Story">
+  <ask>Which story to check? (provide story key, e.g., E1-S1)</ask>
+  <action>Find and read the story file matching {story_key}-*.md in {implementation_artifacts}/</action>
+  <action>Verify story status is 'in-progress' or 'review' — HALT if story is in backlog, validating, ready-for-dev, or done</action>
+  <action>Read the story template from {project-root}/_gaia/lifecycle/templates/story-template.md for reference on expected sections</action>
+</step>
+<step n="2" title="Check Implicit DoD Criteria">
+  <action>Check: All acceptance criteria are marked complete (- [x]) in the "Acceptance Criteria" section. Count total vs checked.</action>
+  <action>Check: All tasks and subtasks are marked complete (- [x]) in the "Tasks / Subtasks" section. Count total vs checked.</action>
+  <action>Check: Test Scenarios table is populated (at least one non-placeholder row)</action>
+  <action>Check: Dev Agent Record section has content (agent, files changed list populated)</action>
+</step>
+<step n="3" title="Check Explicit DoD Items">
+  <action>Read the "Definition of Done" section of the story file</action>
+  <action>For each checkbox item: record whether it is checked (- [x]) or unchecked (- [ ])</action>
+  <action>If the DoD section only contains the template placeholder "Define all the Definition of Done" — report WARNING: DoD items were never defined for this story</action>
+</step>
+<step n="4" title="Generate DoD Check Report">
+  <action>Determine overall verdict: PASS (all implicit + explicit items checked) or FAIL (any unchecked)</action>
+  <action>Append DoD Check Report at the END of the story file, after a horizontal rule (---) separator</action>
+  <template-output file="{implementation_artifacts}/{story_key}-{story_title_slug}.md">
+    Append a section titled "## DoD Check Report" at the very end of the story file, preceded by a --- separator. Include:
+    - Date of check
+    - Overall verdict: PASS or FAIL
+    - Implicit criteria results table:
+
+    | Criterion | Status | Details |
+    |-----------|--------|---------|
+    | Acceptance Criteria | n/m checked | list unchecked if any |
+    | Subtasks | n/m checked | list unchecked if any |
+    | Test Scenarios | populated/empty | — |
+    | Dev Agent Record | populated/empty | — |
+
+    - Explicit DoD items results table:
+
+    | # | Item | Status |
+    |---|------|--------|
+    | 1 | {item text} | PASS/FAIL |
+
+    - If FAIL: list all unchecked items and recommend actions
+    - If PASS: confirm story is ready for review gate (/gaia-run-all-reviews)
+  </template-output>
+  <next-step>
+    <on_pass>/gaia-run-all-reviews — Start the review gate</on_pass>
+    <on_fail>/gaia-dev-story — Resume implementation to address unchecked DoD items</on_fail>
+  </next-step>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/4-implementation/check-dod/workflow.yaml

@@ -0,0 +1,19 @@
+name: check-dod
+description: 'Check Definition of Done criteria for a story before review transition'
+module: lifecycle
+agent: sm
+config_resolved: "{installed_path}/.resolved/check-dod.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/check-dod"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+quality_gates:
+  pre_start:
+    - check: "story_status in ['in-progress', 'review']"
+      on_fail: "HALT: Story must be in-progress or review status to check DoD. Run /gaia-dev-story to start implementation first."
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{implementation_artifacts}/{story_key}-{story_title_slug}.md"

package/_gaia/lifecycle/workflows/4-implementation/check-review-gate/checklist.md

@@ -0,0 +1,18 @@
+---
+title: 'Review Gate Check'
+validation-target: 'Composite review gate evaluation and status transition'
+---
+
+## Checks
+
+- [ ] Story file found and loaded
+- [ ] Story status is review or done
+- [ ] Review Gate table has exactly 6 rows
+- [ ] All 6 review statuses parsed (PASSED/FAILED/PENDING)
+- [ ] Shared protocol review-gate-check.xml loaded and executed
+- [ ] DoD validation performed before transition
+- [ ] Status transition applied correctly (or blocked with reason)
+- [ ] Gate Status Report appended to story file
+- [ ] Overall verdict determined
+- [ ] Next step suggestion provided
+- [ ] sprint-status.yaml NOT modified

package/_gaia/lifecycle/workflows/4-implementation/check-review-gate/instructions.xml

@@ -0,0 +1,53 @@
+<workflow name="check-review-gate">
+<critical>
+  <mandate>Do NOT re-run any reviews — this workflow only inspects the current Review Gate state</mandate>
+  <mandate>Do NOT write to sprint-status.yaml — story file frontmatter is the source of truth</mandate>
+  <mandate>Use the shared protocol at {project-root}/_gaia/core/protocols/review-gate-check.xml for gate evaluation</mandate>
+  <mandate>Use glob {story_key}-*.md to find the story file</mandate>
+</critical>
+<step n="1" title="Load Story">
+  <ask>Which story to check? (provide story key, e.g., E1-S1)</ask>
+  <action>Find and read the story file matching {story_key}-*.md in {implementation_artifacts}/</action>
+  <action>Verify story status is 'review' or 'done' — HALT if story is in any other status</action>
+</step>
+<step n="2" title="Evaluate Review Gate">
+  <action>Load and execute the shared protocol: {project-root}/_gaia/core/protocols/review-gate-check.xml</action>
+  <action>Parse the Review Gate table — verify exactly 6 rows exist (Code Review, QA Tests, Security Review, Test Automation, Test Review, Performance Review)</action>
+  <action>Classify each row as PASSED, FAILED, or PENDING</action>
+  <action>If any row is missing or has an invalid status, flag it as an error</action>
+</step>
+<step n="3" title="Execute Gate Transition">
+  <action>If ALL 6 rows PASSED AND all Definition of Done items checked AND story status is 'review': transition story status to 'done' in story file frontmatter ONLY</action>
+  <action>If ALL 6 rows PASSED but DoD incomplete: log "BLOCKED: DoD incomplete" — do NOT transition</action>
+  <action>If ALL 6 rows PASSED AND story already 'done': log "Story already done. No update needed."</action>
+  <action>If any row FAILED or PENDING: do NOT change story status</action>
+</step>
+<step n="4" title="Generate Gate Status Report">
+  <action>Append Gate Status Report at the END of the story file, after a horizontal rule (---) separator</action>
+  <template-output file="{implementation_artifacts}/{story_key}-{story_title_slug}.md">
+    Append a section titled "## Review Gate Status Report" at the very end of the story file, preceded by a --- separator. Include:
+    - Date of check
+    - Overall verdict: ALL PASSED | HAS FAILURES | HAS PENDING
+    - Gate summary table:
+
+    | Review | Status | Report |
+    |--------|--------|--------|
+    | Code Review | PASSED/FAILED/PENDING | link or — |
+    | QA Tests | PASSED/FAILED/PENDING | link or — |
+    | Security Review | PASSED/FAILED/PENDING | link or — |
+    | Test Automation | PASSED/FAILED/PENDING | link or — |
+    | Test Review | PASSED/FAILED/PENDING | link or — |
+    | Performance Review | PASSED/FAILED/PENDING | link or — |
+
+    - Transition result: what action was taken (transitioned to done / blocked by DoD / no change)
+    - If FAILED: list failed reviews and recommend re-running them individually
+    - If PENDING: list pending reviews and recommend running them or /gaia-run-all-reviews
+    - If ALL PASSED: confirm story is done
+  </template-output>
+  <next-step>
+    <on_all_passed>Story is done — proceed to /gaia-sprint-status to update sprint tracking</on_all_passed>
+    <on_failures>Re-run failed reviews individually, then run /gaia-check-review-gate again</on_failures>
+    <on_pending>Run /gaia-run-all-reviews to complete remaining reviews</on_pending>
+  </next-step>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/4-implementation/check-review-gate/workflow.yaml

@@ -0,0 +1,19 @@
+name: check-review-gate
+description: 'Check composite review gate status and transition story to done if all reviews pass'
+module: lifecycle
+agent: sm
+config_resolved: "{installed_path}/.resolved/check-review-gate.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/check-review-gate"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+quality_gates:
+  pre_start:
+    - check: "story_status in ['review', 'done']"
+      on_fail: "HALT: Story must be in review or done status to check review gate. Complete /gaia-dev-story first."
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{implementation_artifacts}/{story_key}-{story_title_slug}.md"

package/_gaia/lifecycle/workflows/4-implementation/code-review/checklist.md

@@ -0,0 +1,18 @@
+---
+title: 'Code Review Validation'
+validation-target: 'Code review report'
+---
+## Review
+- [ ] All changed files reviewed
+- [ ] Security issues checked
+- [ ] Performance concerns noted
+- [ ] Test coverage verified
+## Decision
+- [ ] APPROVE or REQUEST_CHANGES clearly stated
+## Review Gate
+- [ ] Review Gate table updated in story file
+- [ ] If APPROVE: Code Review row shows PASSED with report link
+- [ ] If REQUEST_CHANGES: Code Review row shows FAILED, story status set to in-progress
+- [ ] Review gate check protocol invoked
+## Output Verification
+- [ ] Review report exists at {implementation_artifacts}/{story_key}-review.md

package/_gaia/lifecycle/workflows/4-implementation/code-review/instructions.xml

@@ -0,0 +1,50 @@
+<workflow name="code-review">
+<critical>
+  <mandate>Story must be in review status before code review</mandate>
+  <mandate>Output must include machine-readable APPROVE or REQUEST_CHANGES</mandate>
+  <mandate>When reading or running application source code, use {project-path} as the base directory — NOT {project-root}. {project-path} is resolved by the engine from global.yaml.</mandate>
+</critical>
+<step n="1" title="Load Story">
+  <action>Resolve story file: search for {story_key}-*.md in {implementation_artifacts}/ using glob pattern to match the full filename ({story_key}-{title_slug}.md)</action>
+  <action>Read story file, identify files changed</action>
+</step>
+<step n="2" title="Status Gate">
+  <action>Verify story is in 'review' status</action>
+  <check if="status != review">HALT: Story must be in review status</check>
+</step>
+<step n="3" title="Code Review">
+  <action>Review each changed file for: correctness, security, performance, readability, test coverage</action>
+</step>
+<step n="3b" title="Architecture Conformance">
+  <action>Load {planning_artifacts}/architecture.md — extract ADRs, component hierarchy, layer boundaries, and API patterns</action>
+  <action>For each changed file, verify:
+    - Component placement follows the documented hierarchy (e.g., controllers in controller layer, services in service layer)
+    - Dependencies flow in the correct direction per architecture (no upward dependencies across layers)
+    - API patterns match the architecture specification (naming, versioning, error format)
+    - Referenced ADRs exist and have status Accepted — flag if implementation contradicts an ADR decision
+  </action>
+  <action>Include an "Architecture Conformance" section in findings with PASS/FAIL per check</action>
+</step>
+<step n="4" title="Generate Findings">
+  <action>List issues by severity: critical, warning, suggestion</action>
+</step>
+<step n="5" title="Decision">
+  <action>If no critical issues: verdict is APPROVE</action>
+  <action>If critical issues found: verdict is REQUEST_CHANGES</action>
+</step>
+<step n="6" title="Generate Output">
+  <template-output file="{implementation_artifacts}/{story_key}-review.md">
+    Generate review report with machine-readable verdict (APPROVE/REQUEST_CHANGES) and findings.
+  </template-output>
+</step>
+<step n="7" title="Update Review Gate and Transition">
+  <action>Read story file, locate Review Gate table</action>
+  <action>If APPROVE: update Code Review row status to PASSED, link report file</action>
+  <action>If REQUEST_CHANGES: update Code Review row status to REQUEST_CHANGES, link report file. Do NOT change story status — the review-gate-check protocol or run-all-reviews orchestrator handles status transitions.</action>
+  <template-output file="{implementation_artifacts}/{story_key}-*.md">
+    Update story file Review Gate table with code review result and report link.
+  </template-output>
+  <action>Inform user: "Note: sprint-status.yaml may now be out of sync. Run /gaia-sprint-status to reconcile."</action>
+  <invoke-protocol name="review-gate-check" file="{project-root}/_gaia/core/protocols/review-gate-check.xml" />
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/4-implementation/code-review/workflow.yaml

@@ -0,0 +1,24 @@
+name: code-review
+description: 'Perform code review on implemented story'
+module: lifecycle
+agent: dev-*
+config_resolved: "{installed_path}/.resolved/code-review.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/code-review"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+input_file_patterns:
+  architecture:
+    whole: "{planning_artifacts}/architecture.md"
+    load_strategy: "INDEX_GUIDED"
+quality_gates:
+  pre_start:
+    - check: "story_status == 'review'"
+      on_fail: "HALT: Story must be in review status before code review. Complete /gaia-dev-story first."
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{test_artifacts}/{story_key}-code-review.md"
+  secondary: "{implementation_artifacts}/{story_key}-*.md"

package/_gaia/lifecycle/workflows/4-implementation/correct-course/checklist.md

@@ -0,0 +1,21 @@
+---
+title: 'Course Correction Validation'
+validation-target: 'Updated sprint plan'
+---
+## Change
+- [ ] Reason for change documented
+- [ ] Impact analysis completed
+- [ ] CR ID recorded (if applicable)
+## Adjustment
+- [ ] Sprint plan updated
+- [ ] sprint-status.yaml updated
+- [ ] Changes approved by user
+## New Story Injection (if applicable)
+- [ ] Injected stories exist in epics-and-stories.md
+- [ ] Velocity impact assessed
+- [ ] Story file creation recommended for new stories
+## Action Item Tracking
+- [ ] Action items persisted to sprint-status.yaml with tracking fields (id, description, assigned_to, due_date, status)
+- [ ] Existing correction_action_items preserved (append only)
+## Change Request (if applicable)
+- [ ] Change request record updated with sprint assignment