gaia-framework 1.65.0 → 1.66.0

package/_gaia/lifecycle/workflows/2-planning/edit-ux-design/workflow.yaml

@@ -0,0 +1,27 @@
+name: edit-ux-design
+description: 'Edit an existing UX design document'
+module: lifecycle
+agent: ux-designer
+val_validate_output: true
+config_resolved: "{installed_path}/.resolved/edit-ux-design.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/2-planning/edit-ux-design"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+input_file_patterns:
+  ux_design:
+    whole: "{planning_artifacts}/ux-design.md"
+    load_strategy: "FULL_LOAD"
+  architecture:
+    whole: "{planning_artifacts}/architecture.md"
+    load_strategy: "SELECTIVE_LOAD"
+quality_gates:
+  pre_start:
+    - check: "ux_design_exists"
+      on_fail: "HALT: No ux-design.md found. Run /gaia-create-ux first."
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{planning_artifacts}/ux-design.md"

package/_gaia/lifecycle/workflows/3-solutioning/create-architecture/instructions.xml

@@ -78,7 +78,9 @@
   <action>If skip: API review can be run anytime later with /gaia-review-api</action>
 </step>
 <step n="11" title="Adversarial Review">
-  <action>Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/architecture.md. Target label: architecture. Follow the task instructions EXACTLY." This is required — findings will be incorporated back into the architecture document.</action>
+  <action>Read {project-root}/_gaia/_config/adversarial-triggers.yaml to evaluate trigger rules. Determine the current change_type: if this workflow was invoked with a change_type context (e.g., from add-feature triage), use that value. If no context is available (standalone architecture creation), default to "feature". Determine the current magnitude from the architecture scope classification (NONE/MINOR/SIGNIFICANT/BREAKING) — default to SIGNIFICANT for standalone creation.</action>
+  <action>Look up the trigger rule for change_type + artifact "architecture". If adversarial is false for this combination: skip the adversarial review — log "Adversarial review skipped: change_type={change_type} does not trigger for architecture per adversarial-triggers.yaml" and proceed to next step. If adversarial is true but the rule has a magnitude_threshold and the current magnitude is below it: skip — log "Adversarial review skipped: magnitude {magnitude} is below threshold {magnitude_threshold} per adversarial-triggers.yaml". Add "## Review Findings Incorporated" with "Adversarial review not triggered — change type: {change_type}, magnitude: {magnitude}".</action>
+  <action>If adversarial is true and magnitude meets or exceeds threshold: Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/architecture.md. Target label: architecture. Follow the task instructions EXACTLY." This is required — findings will be incorporated back into the architecture document.</action>
   <action>When subagent returns: verify adversarial-review-architecture-{date}.md exists in {planning_artifacts}/</action>
 </step>
 <step n="12" title="Incorporate Adversarial Findings">

package/_gaia/lifecycle/workflows/3-solutioning/create-architecture/workflow.yaml

@@ -2,6 +2,7 @@ name: create-architecture
 description: 'Create architecture and solution design'
 module: lifecycle
 agent: architect
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/create-architecture.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/3-solutioning/create-architecture"

package/_gaia/lifecycle/workflows/3-solutioning/create-epics-stories/workflow.yaml

@@ -2,6 +2,7 @@ name: create-epics-stories
 description: 'Break requirements into epics and user stories'
 module: lifecycle
 agent: pm
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/create-epics-stories.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/3-solutioning/create-epics-stories"

package/_gaia/lifecycle/workflows/3-solutioning/edit-architecture/instructions.xml

@@ -57,8 +57,10 @@
   <template-output file="{planning_artifacts}/architecture.md">
     Save updated architecture document with all edits applied, new ADRs appended, version incremented, and version note added.
   </template-output>
-  <check if="change_scope == SIGNIFICANT OR change_scope == BREAKING">
-    <action>Adversarial review is REQUIRED for SIGNIFICANT/BREAKING changes.</action>
+  <action>Read {project-root}/_gaia/_config/adversarial-triggers.yaml to evaluate trigger rules. Determine the current change_type: if this workflow was invoked with a change_type context (e.g., from add-feature triage), use that value. If no context is available, infer from the change scope and driver: adversarial-finding or technical-discovery maps to "feature", change-request depends on the CR classification.</action>
+  <action>Look up the trigger rule for change_type + artifact "architecture". If adversarial is false for this combination: skip adversarial review — mark "Review Findings Incorporated" as "Adversarial review not triggered — change type: {change_type} per adversarial-triggers.yaml". If adversarial is true but the rule has a magnitude_threshold and change_scope is below it (e.g., MINOR is below SIGNIFICANT): skip — mark "Review Findings Incorporated" as "Adversarial review not triggered — magnitude {change_scope} below threshold per adversarial-triggers.yaml".</action>
+  <check if="adversarial trigger rule is true AND magnitude meets or exceeds threshold">
+    <action>Adversarial review triggered per adversarial-triggers.yaml: change_type={change_type}, magnitude={change_scope}.</action>
     <action>Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/architecture.md. Target label: architecture. Follow the task instructions EXACTLY. Focus review on changed sections: {sections_affected}."</action>
     <action>When subagent returns: verify adversarial-review-architecture-{date}.md exists.</action>
     <action>Read findings — extract critical and high severity items.</action>
@@ -68,11 +70,6 @@
       Update architecture with adversarial review findings incorporated. Append to existing "Review Findings Incorporated" section with amendment date.
     </template-output>
   </check>
-  <check if="change_scope == MINOR">
-    <ask>The architecture has been updated with MINOR changes. Would you like to run an adversarial review? (yes / skip for minor edits)</ask>
-    <action>If yes: spawn subagent as above, incorporate findings.</action>
-    <action>If skip: mark "Review Findings Incorporated" as "Incremental edit — adversarial review skipped (minor change)"</action>
-  </check>
 </step>
 <step n="7" title="Cascade Impact Analysis">
   <action>Classify cascade impact on downstream artifacts:</action>

package/_gaia/lifecycle/workflows/3-solutioning/edit-architecture/workflow.yaml

@@ -2,6 +2,7 @@ name: edit-architecture
 description: 'Edit an existing architecture document'
 module: lifecycle
 agent: architect
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/edit-architecture.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/3-solutioning/edit-architecture"

package/_gaia/lifecycle/workflows/3-solutioning/security-threat-model/workflow.yaml

@@ -2,6 +2,7 @@ name: security-threat-model
 description: 'Create security threat model using STRIDE/DREAD methodology'
 module: lifecycle
 agent: security
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/security-threat-model.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/3-solutioning/security-threat-model"

package/_gaia/lifecycle/workflows/4-implementation/add-feature/checklist.md

@@ -0,0 +1,42 @@
+---
+title: 'Add Feature Triage Validation'
+validation-target: 'Feature/Enhancement/Patch Triage and Cascade'
+---
+## Intake
+- [ ] User description captured
+- [ ] Driver identified (user feedback / stakeholder / technical / market / regulatory)
+- [ ] Urgency classified (critical / high / normal)
+- [ ] Feature ID assigned (AF-{date}-{seq})
+## Classification
+- [ ] Change classified as patch / enhancement / feature
+- [ ] Affected artifacts list built based on classification
+- [ ] Classification confirmed by user
+## Impact Scan
+- [ ] Each affected artifact scanned for specific sections impacted
+- [ ] Impact summary generated per artifact
+## Val Review
+- [ ] Proposed changes validated by Val
+- [ ] CRITICAL findings addressed before proceeding
+- [ ] WARNING findings noted
+## Approval
+- [ ] Triage plan presented to user
+- [ ] User APPROVED or REJECTED the plan
+## CR Record (if applicable)
+- [ ] CR record created for enhancements and features
+- [ ] Skipped for patches with justification
+## Cascade
+- [ ] Cascade follows corrected lifecycle order: PRD → UX → Architecture → Test Plan → Threat Model → Traceability
+- [ ] Only affected artifacts processed — patches skip most steps
+- [ ] Each step spawned as subagent (owning agent's workflow)
+- [ ] Cascade manifest tracks state across steps
+- [ ] Failed steps handled with retry/skip/abort options
+- [ ] Checkpoint saved for /gaia-resume recovery
+## Story
+- [ ] Implementation stories created (patch, enhancement, and feature all create stories via subagent)
+- [ ] Story keys captured
+## Assessment Doc
+- [ ] Assessment document generated at {planning_artifacts}/add-feature-{feature_id}.md
+- [ ] All sections populated (classification, impact, cascade results, stories, next steps)
+## Completion
+- [ ] Next steps communicated based on classification
+- [ ] Cascade manifest finalized

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

@@ -0,0 +1,196 @@
+<workflow name="add-feature">
+<critical>
+  <mandate>This is a PM-owned triage workflow — classify the change before cascading</mandate>
+  <mandate>Only cascade through AFFECTED artifacts — patches skip most steps</mandate>
+  <mandate>Cascade follows corrected lifecycle order: PRD → UX → Architecture → Test Plan → Threat Model → Traceability</mandate>
+  <mandate>Each cascade step spawns the owning agent's workflow as a subagent — do not perform edits directly</mandate>
+  <mandate>In yolo mode: auto-proceed through all steps EXCEPT CRITICAL Val findings which require user confirmation</mandate>
+  <mandate>On cascade failure: halt at the failed step, record partial state in assessment doc and checkpoint, present retry/skip/abort options (FR-89a)</mandate>
+  <mandate>Track cascade state via a lightweight manifest — do not hold subagent context in memory. Stay within the 40K token framework budget (FR-89b)</mandate>
+</critical>
+
+<step n="1" title="Intake">
+  <ask>Describe the fix, enhancement, or feature you want to add.</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 a feature ID: AF-{date}-{seq} (e.g., AF-2026-03-26-1). Check {planning_artifacts}/ for existing add-feature-*.md files to determine next sequence number.</action>
+  <action>Record: feature_id, description, driver, urgency</action>
+</step>
+
+<step n="2" title="Classify">
+  <action>Analyze the user's description against the classification matrix:
+
+  **Patch** — bug fix, typo, config correction. Characteristics:
+  - Affects 1-2 files in a single module
+  - No new requirements (FR/NFR) needed
+  - No architecture changes
+  - No UX changes
+  - Existing tests cover the fix (or need minor additions)
+
+  **Enhancement** — improvement to existing feature. Characteristics:
+  - Modifies existing requirements or adds minor new ones
+  - May require architecture adjustments (MINOR)
+  - May affect UX flows
+  - Needs test updates for changed behavior
+
+  **Feature** — wholly new capability. Characteristics:
+  - Adds new requirements (FR/NFR)
+  - Requires architecture review (SIGNIFICANT)
+  - Adds new UX flows or screens
+  - Needs new test cases and possibly threat model updates
+  </action>
+  <action>Determine classification: patch | enhancement | feature</action>
+  <action>Build the affected artifacts list based on classification:
+  - **Patch**: PRD (optional — if wording fix), Traceability (if test changes)
+  - **Enhancement**: PRD, UX (if UI changes), Architecture (if technical changes), Test Plan, Traceability
+  - **Feature**: PRD, UX, Architecture, Test Plan, Threat Model, Traceability (all artifacts)
+  </action>
+  <action>Present classification and affected artifacts list to user for confirmation.</action>
+</step>
+
+<step n="3" title="Impact Scan">
+  <action>For each affected artifact, scan current content to identify specific sections impacted:</action>
+  <action>— PRD: identify affected requirement IDs (FR-*, NFR-*), feature sections, user personas</action>
+  <action>— UX Design: identify affected screens, interaction patterns, navigation flows</action>
+  <action>— Architecture: identify affected components, APIs, data models, ADRs</action>
+  <action>— Test Plan: identify affected test suites, risk areas, coverage gaps</action>
+  <action>— Threat Model: identify new attack surfaces or changed trust boundaries</action>
+  <action>— Traceability: identify requirement-to-test-to-story linkages that will change</action>
+  <action>Build impact summary: for each affected artifact, list specific sections and what will change.</action>
+</step>
+
+<step n="4" title="Val Review">
+  <action>Present the proposed changes (classification, affected artifacts, impact summary) to Val for validation.</action>
+  <action>Invoke val-validate-artifact as a subagent, passing the impact summary as the artifact to validate.</action>
+  <action>If Val returns CRITICAL findings: present findings to user. In yolo mode, HALT and require user confirmation before proceeding. In normal mode, present [c]ontinue / [r]evise / [x]abort options.</action>
+  <action>If Val returns WARNING findings: present findings. In yolo mode, auto-proceed with findings noted. In normal mode, present options.</action>
+  <action>If Val returns no findings or INFO only: auto-proceed.</action>
+</step>
+
+<step n="5" title="User Approval">
+  <action>Present the complete triage plan:
+
+  **Add-Feature Triage: {feature_id}**
+
+  | Field | Value |
+  |-------|-------|
+  | Description | {description} |
+  | Classification | {patch/enhancement/feature} |
+  | Driver | {driver} |
+  | Urgency | {urgency} |
+
+  **Affected Artifacts:**
+  {list each artifact and what will change}
+
+  **Cascade Steps:**
+  {numbered list of cascade steps that will execute, with skipped steps noted}
+
+  **Val Review:** {passed/warnings noted/findings summary}
+  </action>
+  <ask>Review the triage plan above. Do you APPROVE or REJECT? [approve / reject / revise]</ask>
+  <check if="user_rejects">Set status = REJECTED. Skip steps 6-8 — proceed directly to step 9 (Assessment Doc) to record the rejection.</check>
+</step>
+
+<step n="6" title="CR Record" optional="true" condition="classification != patch">
+  <action>Skip if classification is 'patch' — patches do not need a formal change request record.</action>
+  <action>For enhancements and features: create a change request record.</action>
+  <action>Assign CR ID: CR-{date}-{seq}. Check {planning_artifacts}/ for existing CR files.</action>
+  <action>Record: cr_id, feature_id, classification, driver, urgency, affected_artifacts, impact_summary.</action>
+</step>
+
+<step n="7" title="Cascade">
+  <action>Initialize cascade manifest:
+  ```yaml
+  cascade_manifest:
+    feature_id: "{feature_id}"
+    classification: "{classification}"
+    steps_total: {count of affected artifacts}
+    steps_completed: 0
+    steps_failed: 0
+    status: "in_progress"
+    steps: []
+  ```
+  </action>
+
+  <action>Execute cascade in corrected lifecycle order, skipping unaffected artifacts:
+
+  **7a. PRD Update** (if affected)
+  Spawn subagent: "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. Context: {classification} — {description}. Impact: {prd_impact}. Feature ID: {feature_id}."
+  On success: record prd_diff (new FR/NFR IDs), update cascade manifest.
+  On failure: record failure in manifest, present retry/skip/abort to user (FR-89a). If skip: note in assessment. If abort: halt cascade, save checkpoint.
+
+  **7b. UX Update** (if affected — skip for patches)
+  Spawn subagent: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/3-solutioning/edit-ux/workflow.yaml as workflow-config. Run in YOLO mode. Context: {classification} — {description}. PRD changes: {prd_diff}. Impact: {ux_impact}. Feature ID: {feature_id}."
+  On success: record ux_diff, update manifest. On failure: retry/skip/abort.
+
+  **7c. Architecture Update** (if affected — skip for patches)
+  Spawn subagent: "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. Context: {classification} — {description}. PRD changes: {prd_diff}. UX changes: {ux_diff}. Impact: {arch_impact}. Feature ID: {feature_id}."
+  On success: record arch_diff, update manifest. On failure: retry/skip/abort.
+
+  **7d. Test Plan Update via test-design** (if affected — skip for patches unless test changes needed)
+  Spawn subagent: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/testing/workflows/edit-test-plan/workflow.yaml as workflow-config. Run in YOLO mode. Context: {classification} — {description}. PRD changes: {prd_diff}. Architecture changes: {arch_diff}. Feature ID: {feature_id}." Alternative: use /gaia-test-design for full test plan regeneration when the scope warrants it.
+  On success: record test_diff, update manifest. On failure: retry/skip/abort.
+
+  **7e. Threat Model Update** (if affected — features only, skip for patches and enhancements)
+  Spawn subagent: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/testing/workflows/threat-model/workflow.yaml as workflow-config. Run in YOLO mode. Context: {classification} — {description}. Architecture changes: {arch_diff}. Feature ID: {feature_id}."
+  On success: record threat_diff, update manifest. On failure: retry/skip/abort.
+
+  **7f. Traceability Update** (if affected)
+  Spawn subagent: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/testing/workflows/traceability/workflow.yaml as workflow-config. Run in YOLO mode. Context: Regenerate traceability to include changes from {feature_id}."
+  On success: record trace_updated, update manifest. On failure: retry/skip/abort.
+  </action>
+
+  <action>After all cascade steps complete (or are skipped/failed): finalize cascade manifest with status summary.</action>
+  <action>Save cascade checkpoint to {checkpoint_path}/add-feature-{feature_id}.yaml for /gaia-resume recovery.</action>
+</step>
+
+<step n="8" title="Story">
+  <action>If classification is 'feature' or 'enhancement': spawn subagent to create implementation stories.</action>
+  <action>Spawn subagent: "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. Context: {classification} — {description}. New requirements: {prd_diff}. Architecture changes: {arch_diff}. Feature ID: {feature_id}."</action>
+  <action>When subagent returns: capture new story keys and epic assignments.</action>
+  <action>If classification is 'patch': spawn subagent to create a fix story. Spawn subagent: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/4-implementation/create-story/workflow.yaml as workflow-config. Run in YOLO mode. Context: patch fix — {description}. Feature ID: {feature_id}." When subagent returns: capture the new story key.</action>
+  <action>Priority flag integration: if the feature driver is high-urgency (P0 priority, business-critical, or regulatory driver), set priority_flag: "next-sprint" in each created story's frontmatter. This signals sprint planning to auto-include these stories in the next sprint cycle. For non-urgent features, priority_flag remains null (default).</action>
+</step>
+
+<step n="9" title="Assessment Doc">
+  <template-output file="{planning_artifacts}/add-feature-{feature_id}.md">
+    Generate assessment document with YAML frontmatter:
+    ---
+    feature_id: "{feature_id}"
+    date: "{date}"
+    classification: "{patch|enhancement|feature}"
+    status: "{APPROVED|REJECTED}"
+    urgency: "{critical|high|normal}"
+    driver: "{source}"
+    cr_id: "{cr_id or null}"
+    ---
+    Then detailed sections:
+    - Description: what was requested and why
+    - Classification: how it was classified with reasoning
+    - Impact Analysis: per-artifact impact summary
+    - Val Review: findings summary
+    - Cascade Results: for each artifact — updated/skipped/failed with details
+    - Stories Created: list of new story keys (or N/A for patches)
+    - Cascade Manifest: final manifest state (steps completed, failed, skipped)
+    - Recommended Next Actions: what to do next based on outcome
+    If REJECTED: include rejection reason and impact analysis for future reference.
+  </template-output>
+</step>
+
+<step n="10" title="Next Steps">
+  <action>Present summary and recommended next actions based on classification and outcome:
+
+  **Patch:**
+  - "Run `/gaia-dev-story {story_key}` to implement the fix."
+
+  **Enhancement:**
+  - "New stories created: {story_keys}. Run /gaia-sprint-plan or /gaia-correct-course to schedule."
+  - If architecture updated: "Architecture changes recorded. Review with /gaia-agent-architect."
+
+  **Feature:**
+  - "Full cascade complete. New stories: {story_keys}."
+  - "Run /gaia-sprint-plan to schedule implementation."
+  - "Consider running /gaia-implementation-readiness to verify consistency."
+  </action>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/{cross-phase → 4-implementation}/add-feature/workflow.yaml

@@ -1,10 +1,14 @@
 name: add-feature
-description: 'Guided orchestrator for adding a new feature — cascades through PRD, architecture, test plan, stories, traceability, and readiness'
+description: 'PM-owned triage workflow for adding a fix, enhancement, or feature — classifies, scans impact, cascades only through affected artifacts'
 module: lifecycle
-agent: orchestrator
+agent: pm
+execution_mode: planning
+val_validate_output: true
+val_auto_in_yolo: true
+val_auto_in_yolo_steps: [4, 9]
 config_resolved: "{installed_path}/.resolved/add-feature.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
-installed_path: "{project-root}/_gaia/lifecycle/workflows/cross-phase/add-feature"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/add-feature"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 input_file_patterns:
@@ -14,24 +18,31 @@ input_file_patterns:
   architecture:
     whole: "{planning_artifacts}/architecture.md"
     load_strategy: "SELECTIVE_LOAD"
-  test_plan:
-    whole: "{test_artifacts}/test-plan.md"
-    load_strategy: "SELECTIVE_LOAD"
+  ux_design:
+    whole: "{planning_artifacts}/ux-design.md"
+    load_strategy: "INDEX_GUIDED"
   epics:
     whole: "{planning_artifacts}/epics-and-stories.md"
     load_strategy: "SELECTIVE_LOAD"
   sprint_status:
     whole: "{implementation_artifacts}/sprint-status.yaml"
     load_strategy: "SELECTIVE_LOAD"
+  test_plan:
+    whole: "{test_artifacts}/test-plan.md"
+    load_strategy: "SELECTIVE_LOAD"
+  threat_model:
+    whole: "{test_artifacts}/threat-model.md"
+    load_strategy: "SELECTIVE_LOAD"
+  traceability:
+    whole: "{test_artifacts}/traceability-matrix.md"
+    load_strategy: "SELECTIVE_LOAD"
 quality_gates:
   pre_start:
     - check: "prd_exists"
       on_fail: "HALT: prd.md does not exist. Run /gaia-create-prd first."
-    - 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"
+  primary: "{planning_artifacts}/add-feature-{feature_id}.md"

package/_gaia/lifecycle/workflows/4-implementation/add-stories/checklist.md

@@ -22,6 +22,11 @@ validation-target: 'Updated epics-and-stories.md'
 - [ ] Source: CR-{cr_id} added (if change request linked)
 ## Change Log
 - [ ] Change log entry added with date, feature name, and CR ID
+## Inline Validation
+- [ ] Inline validation invoked for each new story
+- [ ] Fix loop executed if CRITICAL/WARNING findings found (max 3 attempts)
+- [ ] Validation results recorded per story (validated / validating / degraded)
+- [ ] Graceful degradation handled if Val unavailable (prerequisites missing or invocation failure)
 ## Existing Content
 - [ ] Existing stories not modified
 - [ ] Existing epic structure preserved

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

@@ -88,9 +88,81 @@
     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>
+  <action>Recount epic overview table story counts and update in-place:
+    1. Parse all `### Story (E\d+)-S\d+:` headers in the saved epics-and-stories.md file
+    2. Group and count story headers per epic key (E1, E2, etc.)
+    3. Locate the Epic Overview table in epics-and-stories.md (the markdown table with columns: epic ID, name, goal, count, priority)
+    4. For each epic row in the table, update the count column to match the actual count of story headers for that epic
+    5. If a new epic was created in Step 4 and does not yet have a row in the Epic Overview table, insert a new row with the correct initial story count
+    6. If an existing epic row in the overview table has zero matching story headers after recount, preserve the row as-is (do not delete it) — log a warning: "Epic {EN} has 0 story headers but overview row preserved"
+    7. Table format: `| E{N} | {name} | {goal} | {count} | {priority} |` — only the `{count}` column cell is updated; do not modify other columns
+    8. Save the updated epics-and-stories.md file</action>
 </step>
 
-<step n="8" title="Next Steps">
+<step n="8" title="Inline Validation">
+  <action>Check Val prerequisites: verify {project-root}/_gaia/lifecycle/agents/validator.md exists AND {project-root}/_memory/validator-sidecar/ directory exists. If either prerequisite is missing, log warning "Val prerequisites unavailable — skipping inline validation. Stories will be marked as validating." Set val_available = false.</action>
+
+  <action>For each newly created story from Step 5 (batch iteration — each story validated independently):
+    Set story_validation_status = "pending"
+    Set validation_attempt = 0
+
+    If val_available == false:
+      Set story_validation_status = "degraded"
+      Mark story status as 'validating' in the story entry
+      Log: "Story {story_key}: Val unavailable — marked as validating"
+      Continue to next story
+    End If
+
+    VALIDATION LOOP (maximum 3 attempts):
+      Increment validation_attempt
+
+      Invoke Val validation directly within workflow context (no subagent nesting — works at both standalone level 1 and subagent level 2 from add-feature, never exceeding 2-level nesting max):
+      <invoke-workflow
+        target="{project-root}/_gaia/lifecycle/workflows/4-implementation/val-validate-artifact/workflow.yaml"
+        input_artifact="{planning_artifacts}/epics-and-stories.md"
+        story_scope="{story_key}"
+        on_error="warn_and_continue" />
+
+      If Val invocation fails (timeout, context overflow, crash, or missing prerequisites):
+        Log warning: "Val validation failed for {story_key}: {reason}"
+        Set story_validation_status = "degraded"
+        Mark story status as 'validating'
+        Break loop — continue to next story
+      End If
+
+      Separate findings by severity:
+        - CRITICAL and WARNING findings → actionable_findings (trigger fix loop)
+        - INFO findings → info_findings (do not trigger fix loop, non-blocking — log only)
+
+      Log all INFO findings to output (INFO does not block progression and does not trigger re-validation)
+
+      If actionable_findings is empty:
+        Set story_validation_status = "validated"
+        Note story as "validated" in output validation summary
+        Break loop — continue to next story
+      End If
+
+      If validation_attempt less than 3:
+        Auto-fix each CRITICAL and WARNING finding in the story content
+        Re-invoke Val validation (loop continues)
+      Else (validation_attempt == 3, maximum reached):
+        Set story_validation_status = "failed"
+        Mark story status as 'validating' (not 'ready-for-dev')
+        Log remaining unresolved findings
+        Break loop — continue to next story
+      End If
+    END VALIDATION LOOP
+  End For Each
+
+  Report batch validation summary:
+    - Stories validated successfully: {count} ({list})
+    - Stories marked validating (failed after 3 attempts): {count} ({list})
+    - Stories marked validating (Val unavailable/degraded): {count} ({list})
+    - INFO findings logged: {count}
+  </action>
+</step>
+
+<step n="9" 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>

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

@@ -2,6 +2,7 @@ name: add-stories
 description: 'Add new stories to existing epics or create new epics with stories'
 module: lifecycle
 agent: pm
+val_validate_output: true
 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"

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

@@ -7,6 +7,7 @@ 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"
+template: "{project-root}/_gaia/lifecycle/templates/review-template.md"
 input_file_patterns:
   architecture:
     whole: "{planning_artifacts}/architecture.md"

package/_gaia/lifecycle/workflows/4-implementation/correct-course/workflow.yaml

@@ -2,6 +2,7 @@ name: correct-course
 description: 'Manage significant sprint scope changes'
 module: lifecycle
 agent: sm
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/correct-course.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/correct-course"

package/_gaia/lifecycle/workflows/4-implementation/create-story/checklist.md

@@ -3,7 +3,7 @@ title: 'Story Creation Validation'
 validation-target: 'Story file'
 ---
 ## Structure
-- [ ] YAML frontmatter present with all 14 required fields: key, title, epic, status, priority, size, points, risk, sprint_id, depends_on, blocks, traces_to, date, author
+- [ ] YAML frontmatter present with all 15 required fields: key, title, epic, status, priority, size, points, risk, sprint_id, depends_on, blocks, traces_to, date, author, priority_flag
 - [ ] Acceptance criteria section complete
 - [ ] Technical notes included
 - [ ] Subtasks defined

package/_gaia/lifecycle/workflows/4-implementation/create-story/instructions.xml

@@ -1,6 +1,6 @@
 <workflow name="create-story">
 <critical>
-  <mandate>Story files must include complete YAML frontmatter with ALL required fields: key, title, epic, status, priority, size, points, risk, sprint_id, depends_on, blocks, traces_to, date, author</mandate>
+  <mandate>Story files must include complete YAML frontmatter with ALL required fields: key, title, epic, status, priority, size, points, risk, sprint_id, depends_on, blocks, traces_to, date, author, priority_flag. The priority_flag field accepts only null (default) or "next-sprint" as valid values.</mandate>
   <mandate>All acceptance criteria MUST use Given/When/Then format: "Given {context}, when {action}, then {expected result}"</mandate>
   <mandate>Check web access availability if story references external APIs</mandate>
 </critical>
@@ -92,7 +92,7 @@
   <action>Append DoD checklist: all AC met, tests pass, code reviewed, docs updated</action>
 </step>
 <step n="6" title="Generate Output">
-  <action>Read the story template from {project-root}/_gaia/lifecycle/templates/story-template.md</action>
+  <action>Read the story template from the engine-resolved template path. The engine resolves this in Step 1 (Load and Resolve Config): if {project-root}/custom/templates/story-template.md exists and is non-empty, the custom template is used; otherwise it falls back to {project-root}/_gaia/lifecycle/templates/story-template.md. Use whichever path the engine resolved.</action>
   <action>Read sizing_map from {project-root}/_gaia/_config/global.yaml to resolve T-shirt size to story points (S→2, M→5, L→8, XL→13).</action>
   <action>Populate ALL YAML frontmatter fields from epics-and-stories.md data:
     - key: story key from epics (e.g., E1-S1)
@@ -109,9 +109,10 @@
     - traces_to: requirement IDs this story traces to (from epics)
     - date: current date
     - author: agent name (e.g., "Nate (Scrum Master)")
+    - priority_flag: null (default — set to "next-sprint" by add-feature for high-urgency stories)
   </action>
   <template-output file="{implementation_artifacts}/{story_key}-{story_title_slug}.md">
-    Generate the story file following the story-template.md structure. The filename must use the story key and slugified title (e.g., E1-S1-user-login.md). Include complete YAML frontmatter with ALL 14 fields populated. Fill all template sections: User Story, Acceptance Criteria, Tasks/Subtasks (linked to AC numbers), Dev Notes, Technical Notes, Dependencies, Test Scenarios, Project Structure Notes, References, Dev Agent Record, and Estimate. IMPORTANT: The body "**Status:**" line MUST match the frontmatter status field exactly. Both must say the same status value.
+    Generate the story file following the story-template.md structure. The filename must use the story key and slugified title (e.g., E1-S1-user-login.md). Include complete YAML frontmatter with ALL 15 fields populated. Fill all template sections: User Story, Acceptance Criteria, Tasks/Subtasks (linked to AC numbers), Dev Notes, Technical Notes, Dependencies, Test Scenarios, Project Structure Notes, References, Dev Agent Record, and Estimate. IMPORTANT: The body "**Status:**" line MUST match the frontmatter status field exactly. Both must say the same status value.
   </template-output>
   <action>Add the new story to {implementation_artifacts}/story-index.yaml:
     1. Read story-index.yaml (create with header if doesn't exist)
@@ -122,7 +123,7 @@
 <step n="7" title="Val Full Validation">
   <action>Invoke Val as a subagent to perform full validation on the saved story file. Val validates:
 
-  (a) Completeness — all 14 YAML frontmatter fields present and valid, all template sections present
+  (a) Completeness — all 15 YAML frontmatter fields present and valid, all template sections present
   (b) Clarity — all ACs in Given/When/Then format, subtasks linked to AC numbers, DoD items measurable
   (c) Semantic quality — duplicate detection across epic, ADR cross-references against architecture.md
   (d) Dependencies — all declared dependencies exist and resolve

package/_gaia/lifecycle/workflows/4-implementation/dev-story/workflow.yaml

@@ -28,7 +28,7 @@ quality_gates:
     - check: "story_file_exists({implementation_artifacts}/{story_key}-*.md)"
       on_fail: "HALT: Story file not found. Expected {implementation_artifacts}/{story_key}-*.md. Run /gaia-create-story first."
     - check: "story_status in ['ready-for-dev', 'in-progress']"
-      on_fail: "HALT: Story must be in ready-for-dev or in-progress status."
+      on_fail: "HALT: Story must be in ready-for-dev or in-progress status. Check {implementation_artifacts}/{story_key}-*.md frontmatter or run /gaia-sprint-status to verify."
   post_complete:
     - check: "all_tests_pass == true"
       on_fail: "HALT: All tests must pass before marking complete. Run test suite in {project-path}/ and fix failing tests."

package/_gaia/lifecycle/workflows/4-implementation/retrospective/instructions.xml

@@ -96,7 +96,27 @@
   <action>For each related skill, propose a concrete addition or modification: what section should change, what content to add, and why (link back to the retro finding)</action>
   <action if="yolo_mode">In YOLO mode: auto-approve all recommended skill improvements. Skip the user prompt below.</action>
   <ask>Here are the proposed skill improvements based on this sprint's findings. Approve, modify, or skip each. [approve all / select / skip]</ask>
-  <action>If approved: append to the relevant skill file with comment: "<!-- Added from retro-{sprint_id}: {reason} -->"</action>
+  <action>If approved: write the skill improvement to {project-root}/custom/skills/{skill-name}.md (NOT _gaia/dev/skills/).
+    Follow this sequence for each approved skill improvement:
+
+    1. Ensure directory exists: create {project-root}/custom/skills/ if it does not already exist (mkdir -p equivalent).
+
+    2. Base-skill copy guard: check if {project-root}/custom/skills/{skill-name}.md already exists.
+       - If the custom skill file does NOT exist: copy the base skill from _gaia/dev/skills/{skill-name}.md (resolved at {project-root}) to {project-root}/custom/skills/{skill-name}.md, preserving all &lt;!-- SECTION: xxx --&gt; markers intact. This ensures the engine's sectioned loading continues to work for the custom copy.
+       - If the base skill does NOT exist at _gaia/dev/skills/{skill-name}.md (e.g., removed in a framework update): log a warning ("Base skill {skill-name} not found at _gaia/dev/skills/ — creating custom skill from scratch") and write the improvement content directly to custom/skills/{skill-name}.md without a base copy.
+       - If the custom skill file already exists: preserve existing content and apply the improvement on top.
+
+    3. Apply the improvement: append to or modify the relevant section in custom/skills/{skill-name}.md with comment "<!-- Added from retro-{sprint_id}: {reason} -->".
+
+    4. Register in .customize.yaml: after writing the custom skill file, register it in {project-root}/_gaia/_config/agents/all-dev.customize.yaml so the engine loads from the custom path on subsequent runs.
+       - If all-dev.customize.yaml does not exist: create it with proper YAML structure:
+         ```yaml
+         skill_overrides:
+           {skill-name}:
+             source: "custom/skills/{skill-name}.md"
+         ```
+       - If all-dev.customize.yaml already exists: read current content, check if a skill_overrides entry for this skill already exists. If it does not exist, append the new entry under skill_overrides. Preserve all existing entries — only add the new one. If it already exists (duplicate), skip registration to prevent duplicate entries.
+  </action>
   <action>If no skill improvements identified, state: "No skill improvements identified this sprint."</action>
 </step>
 <step n="7" title="Cross-Retro Pattern Detection">