gaia-framework 1.65.0 → 1.66.0

package/_gaia/lifecycle/templates/platform-prd-template.md

@@ -0,0 +1,431 @@
+---
+template: 'platform-prd'
+version: 1.0.0
+used_by: ['create-prd']
+domain: '{domain}'
+---
+
+# Platform PRD: {product_name}
+
+> **Project:** {project_name}
+> **Domain:** {domain}
+> **Date:** {date}
+> **Author:** {agent_name}
+> **Status:** Draft | In Review | Approved
+> **Project Type:** Platform (application + infrastructure)
+
+> Requirement IDs use prefixes to disambiguate scope: FR-### and NFR-### for application requirements, IR-###, OR-###, and SR-### for infrastructure requirements. IDs are globally unique within a project — each prefix defines a separate namespace.
+
+---
+
+# Part I: Application Requirements
+
+## 1. Overview
+
+{Brief product overview and context. What is being built and why.}
+
+## 2. Goals and Non-Goals
+
+### Goals
+- {Goal 1}
+- {Goal 2}
+
+### Non-Goals
+- {Explicitly out of scope item 1}
+
+## 3. User Stories
+
+| ID | As a... | I want to... | So that... | Priority |
+|----|---------|-------------|-----------|----------|
+| US-01 | {role} | {action} | {benefit} | {P0-P3} |
+
+## 4. Functional Requirements
+
+### 4.1 {Feature Area}
+
+- **FR-01:** {Requirement description}
+- **FR-02:** {Requirement description}
+
+## 5. Non-Functional Requirements
+
+| ID | Category | Requirement | Target |
+|----|----------|------------|--------|
+| NFR-001 | Performance | {requirement} | {target} |
+| NFR-002 | Security | {requirement} | {target} |
+| NFR-003 | Accessibility | {requirement} | {target} |
+
+## 6. Out of Scope
+
+| Exclusion | Reason |
+|-----------|--------|
+| {feature or integration} | {deferred / not needed / separate product} |
+
+## 7. UX Requirements
+
+{Key interaction patterns, wireframe references, accessibility needs.}
+
+## 8. Technical Constraints
+
+- {Platform, language, or integration constraint}
+
+## 9. Dependencies
+
+| Dependency | Type | Failure Mode | Fallback Behavior | SLA Expectation |
+|------------|------|-------------|-------------------|-----------------|
+| {service or system} | {API / Database / Message Queue / CDN / Auth Provider} | {What happens when it's unavailable} | {Graceful degradation / Retry / Queue / Circuit breaker / Hard fail} | {Expected uptime / latency / throughput} |
+
+## 10. Milestones
+
+| Milestone | Target Date | Deliverables |
+|-----------|------------|-------------|
+| {milestone} | {date} | {deliverables} |
+
+---
+
+# Part II: Infrastructure Requirements
+
+## 11. Platform Overview & Scope
+
+{Platform purpose, target environments, and team ownership.}
+
+### Platform Purpose
+
+{What this infrastructure provides and why it exists.}
+
+### Target Environments
+
+| Environment | Purpose | Region(s) | Owner |
+|-------------|---------|-----------|-------|
+| {env_name} | {purpose} | {regions} | {team} |
+
+### Team Ownership
+
+| Component | Owning Team | Escalation |
+|-----------|-------------|------------|
+| {component} | {team} | {contact} |
+
+## 12. Platform Capabilities
+
+{What the infrastructure enables. Each capability follows the format below.}
+
+| ID | Capability | SLO |
+|----|-----------|-----|
+| PC-01 | Enable {team/service} to {capability} with {SLO} | {target} |
+| PC-02 | Enable {team/service} to {capability} with {SLO} | {target} |
+
+## 13. Resource Specifications
+
+{Compute, storage, networking, IAM provisioning. Per-environment breakdown.}
+
+### Compute
+
+| Resource | Environment | Spec | Scaling |
+|----------|-------------|------|---------|
+| {resource} | {env} | {cpu/memory} | {auto/manual, min-max} |
+
+### Storage
+
+| Store | Type | Size | IOPS | Backup |
+|-------|------|------|------|--------|
+| {store} | {block/object/file} | {size} | {iops} | {policy} |
+
+### Networking
+
+| Component | CIDR/Range | Protocol | Purpose |
+|-----------|-----------|----------|---------|
+| {component} | {cidr} | {protocol} | {purpose} |
+
+### IAM Provisioning
+
+| Role/Policy | Scope | Permissions | Lifecycle |
+|-------------|-------|-------------|-----------|
+| {role} | {scope} | {permissions} | {create/rotate/revoke} |
+
+### State Management
+
+{State backend strategy — e.g., Terraform remote state, locking, encryption.}
+
+| Backend | Lock Provider | Encryption | Workspace Strategy |
+|---------|--------------|------------|-------------------|
+| {backend} | {lock} | {encryption} | {workspace} |
+
+### Data Persistence Requirements
+
+| Data Store | Durability | Replication | Retention |
+|------------|-----------|-------------|-----------|
+| {store} | {durability} | {replication} | {retention} |
+
+## 14. Operational SLOs
+
+{Availability targets, MTTR, RTO/RPO, error budgets, resource utilization targets.}
+
+### Availability & Recovery
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Availability | {99.x%} | {how measured} |
+| MTTR | {minutes} | {how measured} |
+| RTO | {minutes} | {recovery time objective} |
+| RPO | {minutes} | {recovery point objective} |
+| Error Budget | {x% per month} | {how calculated} |
+
+### Resource Utilization Targets
+
+| Resource | Target Utilization | Alert Threshold |
+|----------|-------------------|-----------------|
+| CPU | {target%} | {alert%} |
+| Memory | {target%} | {alert%} |
+| Storage IOPS | {target} | {threshold} |
+| Network Bandwidth | {target Gbps} | {threshold} |
+| Network Latency | {target ms} | {threshold} |
+
+## 15. Security Posture
+
+{Security requirements tailored for infrastructure projects.}
+
+### IAM/RBAC
+
+{Identity and access management, role-based access control policies.}
+
+| Principal | Role | Scope | MFA Required | Review Cadence |
+|-----------|------|-------|-------------|----------------|
+| {principal} | {role} | {scope} | {yes/no} | {quarterly/annually} |
+
+### Network Segmentation
+
+{Network isolation, security groups, firewall rules, zero-trust boundaries.}
+
+| Zone | CIDR | Ingress Rules | Egress Rules | Purpose |
+|------|------|---------------|-------------|---------|
+| {zone} | {cidr} | {rules} | {rules} | {purpose} |
+
+### Secrets Management
+
+{Secrets storage, rotation, injection, and audit strategy.}
+
+| Secret Type | Store | Rotation | Injection Method |
+|-------------|-------|----------|-----------------|
+| {type} | {vault/kms/ssm} | {cadence} | {env var/sidecar/init container} |
+
+### Image Provenance
+
+{Container image signing, scanning, and supply chain verification.}
+
+| Registry | Signing | Scanning | Admission Policy |
+|----------|---------|----------|-----------------|
+| {registry} | {cosign/notary} | {trivy/grype} | {policy} |
+
+### Compliance Mapping
+
+{Regulatory and compliance framework alignment.}
+
+| Framework | Controls | Evidence | Audit Frequency |
+|-----------|----------|----------|----------------|
+| {SOC2/HIPAA/PCI/ISO} | {control IDs} | {how demonstrated} | {cadence} |
+
+## 16. Environment Strategy & Developer Experience
+
+{Environment parity, promotion pipeline, drift detection, self-service provisioning.}
+
+### Environment Parity
+
+| Dimension | Dev | Staging | Production |
+|-----------|-----|---------|-----------|
+| {dimension} | {dev config} | {staging config} | {prod config} |
+
+### Promotion Pipeline
+
+{How changes flow from dev to production.}
+
+```
+{dev} → {staging} → {production}
+```
+
+### Drift Detection
+
+{How configuration drift is detected and remediated.}
+
+| Tool | Schedule | Remediation | Notification |
+|------|----------|-------------|-------------|
+| {tool} | {cron} | {auto/manual} | {channel} |
+
+### Self-Service Provisioning
+
+{Developer self-service capabilities and guardrails.}
+
+| Capability | Interface | Guardrails | Approval |
+|------------|-----------|-----------|----------|
+| {capability} | {CLI/portal/API} | {policy} | {auto/manual} |
+
+### Onboarding
+
+{New team member and new service onboarding procedures.}
+
+### Observability
+
+{Monitoring, logging, tracing, and alerting strategy.}
+
+| Signal | Tool | Retention | Alerting |
+|--------|------|-----------|---------|
+| Metrics | {prometheus/cloudwatch} | {retention} | {pagerduty/slack} |
+| Logs | {elk/cloudwatch} | {retention} | {rules} |
+| Traces | {jaeger/xray} | {retention} | {rules} |
+
+## 17. Dependencies & Provider Constraints
+
+{Cloud provider limits, Terraform provider versions, upstream service contracts.}
+
+### Cloud Provider Limits
+
+| Provider | Service | Limit | Current Usage | Headroom |
+|----------|---------|-------|--------------|----------|
+| {provider} | {service} | {limit} | {current} | {remaining} |
+
+### Terraform Provider Versions
+
+| Provider | Version | Constraint | Notes |
+|----------|---------|-----------|-------|
+| {provider} | {version} | {~> x.y} | {notes} |
+
+### Upstream Service Contracts
+
+| Service | SLA | API Version | Deprecation |
+|---------|-----|------------|-------------|
+| {service} | {sla} | {version} | {date or N/A} |
+
+## 18. Cost Model
+
+{Per-environment resource cost estimates, scaling cost projections, and cost-per-unit efficiency metrics.}
+
+### Per-Environment Resource Cost Estimates
+
+| Resource | Dev (monthly) | Staging (monthly) | Production (monthly) |
+|----------|--------------|-------------------|---------------------|
+| Compute | ${cost} | ${cost} | ${cost} |
+| Storage | ${cost} | ${cost} | ${cost} |
+| Networking | ${cost} | ${cost} | ${cost} |
+| Monitoring | ${cost} | ${cost} | ${cost} |
+| **Total** | **${total}** | **${total}** | **${total}** |
+
+### Scaling Cost Projections
+
+| Scenario | Trigger | Additional Cost | Timeline |
+|----------|---------|----------------|----------|
+| {scenario} | {trigger condition} | ${projection} | {timeframe} |
+
+### Cost-Per-Unit Efficiency Metrics
+
+| Metric | Current | Target | Optimization |
+|--------|---------|--------|-------------|
+| Cost per request | ${cost} | ${target} | {strategy} |
+| Cost per GB stored | ${cost} | ${target} | {strategy} |
+| Cost per environment | ${cost} | ${target} | {strategy} |
+
+## 19. Verification Strategy
+
+{Policy-as-code (OPA/Rego, Checkov, tfsec), plan validation, smoke tests, drift detection, chaos testing.}
+
+### Policy-as-Code
+
+| Tool | Scope | Rules | Enforcement |
+|------|-------|-------|-------------|
+| OPA/Rego | {scope} | {rule count} | {warn/deny} |
+| Checkov | {scope} | {rule count} | {warn/deny} |
+| tfsec | {scope} | {rule count} | {warn/deny} |
+
+### Plan Validation
+
+{Terraform plan review, cost estimation, blast radius analysis.}
+
+| Check | Tool | Gate | Threshold |
+|-------|------|------|-----------|
+| {check} | {tool} | {CI/manual} | {threshold} |
+
+### Smoke Tests
+
+{Post-deployment verification tests.}
+
+| Test | Target | Expected | Timeout |
+|------|--------|----------|---------|
+| {test} | {endpoint/resource} | {result} | {timeout} |
+
+### Drift Detection
+
+{Scheduled plan diffs, state file monitoring, compliance scanning.}
+
+### Chaos Testing
+
+{Failure injection, resilience validation.}
+
+| Experiment | Target | Hypothesis | Blast Radius |
+|-----------|--------|-----------|-------------|
+| {experiment} | {target} | {hypothesis} | {scope} |
+
+## 20. Operational Runbooks
+
+{Scaling, failover, incident response, rollback procedures.}
+
+### Scaling Procedures
+
+| Trigger | Action | Rollback | Owner |
+|---------|--------|----------|-------|
+| {trigger} | {action} | {rollback} | {team} |
+
+### Failover Procedures
+
+| Scenario | Detection | Response | RTO |
+|----------|-----------|----------|-----|
+| {scenario} | {detection} | {response steps} | {rto} |
+
+### Incident Response
+
+| Severity | Notification | Escalation | Runbook |
+|----------|-------------|------------|---------|
+| P1 | {channel} | {escalation path} | {link} |
+| P2 | {channel} | {escalation path} | {link} |
+
+### Rollback Procedures
+
+| Change Type | Rollback Method | Verification | Duration |
+|-------------|----------------|-------------|----------|
+| {type} | {method} | {verification} | {estimate} |
+
+---
+
+# Part III: Combined Requirements Summary
+
+## 21. Requirements Summary
+
+> IDs are globally unique within a project. The prefix disambiguates the requirement scope: FR/NFR for application, IR/OR/SR for infrastructure.
+
+### Application Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| FR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| NFR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+### Infrastructure Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| IR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| IR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+### Operational Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| OR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| OR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+### Security Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| SR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| SR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+## 22. Open Questions
+
+- [ ] {Unresolved question}

package/_gaia/lifecycle/templates/prd-template.md

@@ -81,3 +81,73 @@ used_by: ['create-prd']
 ## 12. Open Questions
 
 - [ ] {Unresolved question}
+
+<!-- BROWNFIELD-ONLY-START -->
+
+## Gap Analysis Summary
+
+| Category | Critical | High | Medium | Low | Total |
+|----------|----------|------|--------|-----|-------|
+| Config Contradictions | {count} | {count} | {count} | {count} | {count} |
+| Dead Code & Dead State | {count} | {count} | {count} | {count} | {count} |
+| Hard-Coded Business Logic | {count} | {count} | {count} | {count} | {count} |
+| Security Endpoints | {count} | {count} | {count} | {count} | {count} |
+| Runtime Behaviors | {count} | {count} | {count} | {count} | {count} |
+| Documentation Drift | {count} | {count} | {count} | {count} | {count} |
+| Integration Seams | {count} | {count} | {count} | {count} | {count} |
+| **Overall** | **{count}** | **{count}** | **{count}** | **{count}** | **{count}** |
+
+## Gap Analysis by Category
+
+### Config Contradictions (`configuration`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Dead Code & Dead State (`functional`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Hard-Coded Business Logic (`functional`, `behavioral`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Security Endpoints (`security`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Runtime Behaviors (`behavioral`, `operational`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Documentation Drift (`documentation`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Integration Seams (`data-integrity`, `operational`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Verified By Legend
+
+| Value | Description |
+|-------|-------------|
+| `machine-detected` | Gap found by automated scan subagent |
+| `adversarial-review-detected` | Gap found during adversarial review |
+| `code-verified` | Gap confirmed by code-verified review step |
+| `human-reported` | Gap reported manually by a human reviewer |
+
+<!-- BROWNFIELD-ONLY-END -->

package/_gaia/lifecycle/templates/story-template.md

@@ -11,6 +11,7 @@ size: "{S/M/L/XL}"
 points: "{story_points}"
 risk: "{high/medium/low}"
 sprint_id: null
+priority_flag: null
 depends_on: []
 blocks: []
 traces_to: []

package/_gaia/lifecycle/workflows/1-analysis/create-product-brief/workflow.yaml

@@ -7,6 +7,7 @@ config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/1-analysis/create-product-brief"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
+template: "{project-root}/_gaia/lifecycle/templates/product-brief-template.md"
 input_file_patterns:
   brainstorm:
     whole: "{planning_artifacts}/project-brainstorm.md"

package/_gaia/lifecycle/workflows/2-planning/create-prd/instructions.xml

@@ -63,7 +63,9 @@
   </template-output>
 </step>
 <step n="12" 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}/prd.md. Target label: prd. Follow the task instructions EXACTLY." This is required — findings will be incorporated back into the PRD.</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 PRD creation), default to "feature".</action>
+  <action>Look up the trigger rule for change_type + artifact "prd". If adversarial is false for this combination: skip the adversarial review — log "Adversarial review skipped: change_type={change_type} does not trigger for PRD per adversarial-triggers.yaml" and proceed to next step. Add a "## Review Findings Incorporated" section with "Adversarial review not triggered — change type: {change_type}".</action>
+  <action>If adversarial is true: Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/prd.md. Target label: prd. Follow the task instructions EXACTLY." This is required — findings will be incorporated back into the PRD.</action>
   <action>When subagent returns: verify adversarial-review-prd-{date}.md exists in {planning_artifacts}/</action>
 </step>
 <step n="13" title="Incorporate Adversarial Findings">
@@ -75,6 +77,6 @@
   </template-output>
 </step>
 <next-step source="lifecycle-sequence.yaml">
-  <primary command="/gaia-validate-prd">Validate the PRD against quality standards before proceeding</primary>
+  <primary command="/gaia-create-ux">Create UX design specifications for the validated PRD</primary>
 </next-step>
 </workflow>

package/_gaia/lifecycle/workflows/2-planning/create-prd/workflow.yaml

@@ -2,6 +2,7 @@ name: create-prd
 description: 'Create a Product Requirements Document from scratch'
 module: lifecycle
 agent: pm
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/create-prd.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/2-planning/create-prd"

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

@@ -2,6 +2,7 @@ name: create-ux-design
 description: 'Plan UX patterns and design specifications'
 module: lifecycle
 agent: ux-designer
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/create-ux-design.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/2-planning/create-ux-design"

package/_gaia/lifecycle/workflows/2-planning/edit-prd/instructions.xml

@@ -25,10 +25,10 @@
   </template-output>
 </step>
 <step n="5" title="Adversarial Review">
-  <ask>The PRD has been updated. Would you like to run an adversarial review? This spawns a subagent in a separate context — recommended for significant changes. (yes / skip for minor edits)</ask>
-  <action>If yes: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/prd.md. Target label: prd. Follow the task instructions EXACTLY."</action>
-  <action>If skip: proceed to step 7 — mark "Review Findings Incorporated" as "Incremental edit — adversarial review skipped (minor change)"</action>
-  <action>If ok: wait for user to confirm adversarial-review-prd-{date}.md exists</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: minor edits map to "low-risk-enhancement", significant feature additions map to "feature".</action>
+  <action>Look up the trigger rule for change_type + artifact "prd". If adversarial is false: skip adversarial review — mark "Review Findings Incorporated" as "Adversarial review not triggered — change type: {change_type} per adversarial-triggers.yaml". Proceed to step 7.</action>
+  <action>If adversarial is true: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/prd.md. Target label: prd. Follow the task instructions EXACTLY."</action>
+  <action>When subagent returns: verify adversarial-review-prd-{date}.md exists in {planning_artifacts}/</action>
 </step>
 <step n="6" title="Incorporate Review Findings" optional="true" condition="adversarial_completed">
   <action>Read {planning_artifacts}/adversarial-review-prd-{date}.md — extract critical and high severity findings</action>

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

@@ -2,6 +2,7 @@ name: edit-prd
 description: 'Edit an existing PRD'
 module: lifecycle
 agent: pm
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/edit-prd.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/2-planning/edit-prd"

package/_gaia/lifecycle/workflows/2-planning/edit-ux-design/checklist.md

@@ -0,0 +1,18 @@
+---
+title: 'UX Design Edit Validation'
+validation-target: 'Edited UX Design'
+---
+## Edit Quality
+- [ ] Requested changes applied correctly
+- [ ] Unchanged sections preserved exactly
+- [ ] Consistency maintained across sections
+## Version History
+- [ ] Version note added with date, reason, and CR ID (if applicable)
+## Review Gate
+- [ ] Adversarial review completed OR explicitly skipped for minor edits
+- [ ] "Review Findings Incorporated" section updated (if review ran)
+## Cascade Assessment
+- [ ] Impact classified for: architecture, stories, test plan
+- [ ] Next steps communicated to user
+## Output Verification
+- [ ] Output file saved to {planning_artifacts}/ux-design.md

package/_gaia/lifecycle/workflows/2-planning/edit-ux-design/instructions.xml

@@ -0,0 +1,66 @@
+<workflow name="edit-ux-design">
+<critical>
+  <mandate>Preserve existing content not being changed — no silent drops, reorders, or modifications</mandate>
+  <mandate>Add version note documenting what changed and why</mandate>
+  <mandate>Update "Review Findings Incorporated" section after adversarial review</mandate>
+</critical>
+<step n="1" title="Load Existing UX Design">
+  <action>Read {planning_artifacts}/ux-design.md in full</action>
+  <action>Identify existing sections: personas, information architecture, wireframes, interaction patterns, accessibility</action>
+  <action>Identify existing Version History entries — note last version for auto-increment</action>
+  <action>Display current structure summary to user: section headers, persona count, wireframe count, current version</action>
+</step>
+<step n="2" title="Identify Changes">
+  <ask>What sections need to change?</ask>
+  <ask>Why are these changes needed?</ask>
+  <ask>Is this linked to a change request? If so, provide the CR ID.</ask>
+  <action>Classify change scope: MINOR (section update, text change) / SIGNIFICANT (new persona, new flow, navigation restructure) / BREAKING (complete redesign of major section)</action>
+  <action>Confirm scope of changes before proceeding</action>
+</step>
+<step n="3" title="Apply Edits">
+  <action>For each affected section: present current content, propose edits, wait for user confirmation or modification</action>
+  <action>Preserve all unchanged sections exactly as-is — no reordering, no reformatting, no content loss</action>
+  <action>Validate consistency between edited sections and remaining unchanged sections</action>
+  <action>If edits affect FR-to-Screen Mapping: verify traceability remains accurate</action>
+</step>
+<step n="4" title="Add Version Note">
+  <action>Append a new row to the Version History table:
+    | {date} | {change summary} | {driver} | {CR ID or reference} |
+  </action>
+  <action>If no Version History section exists, create one:
+    ## Version History
+    | Date | Change | Reason | CR/Reference |
+    |------|--------|--------|-------------|
+    | {date} | {change summary} | {driver} | {CR ID or reference} |
+  </action>
+</step>
+<step n="5" title="Save Updated UX Design">
+  <action>Generate a diff summary showing exactly what changed</action>
+  <template-output file="{planning_artifacts}/ux-design.md">
+    Save updated UX design document with all edits applied, unchanged sections preserved, and version note added.
+  </template-output>
+</step>
+<step n="6" title="Adversarial Review">
+  <ask>The UX design has been updated. Would you like to run an adversarial review? This spawns a subagent in a separate context — recommended for significant changes. (yes / skip for minor edits)</ask>
+  <action>If yes: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/ux-design.md. Target label: ux-design. Follow the task instructions EXACTLY."</action>
+  <action>If skip: proceed to step 7 — mark "Review Findings Incorporated" as "Incremental edit — adversarial review skipped (minor change)"</action>
+  <action>If ok: wait for user to confirm adversarial-review-ux-design-{date}.md exists</action>
+</step>
+<step n="7" title="Incorporate Review Findings" optional="true" condition="adversarial_completed">
+  <action>Read {planning_artifacts}/adversarial-review-ux-design-{date}.md — extract critical and high severity findings</action>
+  <action>For each critical/high finding: incorporate into UX design document</action>
+  <action>Update the "Review Findings Incorporated" section — append new entries with amendment date</action>
+  <template-output file="{planning_artifacts}/ux-design.md">
+    Update the UX design with adversarial review findings incorporated. Append to existing "Review Findings Incorporated" section with amendment date.
+  </template-output>
+</step>
+<step n="8" title="Cascade Impact Check">
+  <action>Read {planning_artifacts}/architecture.md section headers</action>
+  <action>Compare UX design changes against architecture and downstream artifacts</action>
+  <action>Classify cascade impact:</action>
+  <action>  NONE: UX-only changes — architecture and stories unaffected</action>
+  <action>  MINOR: architecture needs a section update — recommend /gaia-edit-arch</action>
+  <action>  SIGNIFICANT: new components or interaction patterns affecting architecture — recommend /gaia-edit-arch with adversarial review, then /gaia-add-stories</action>
+  <action>Report cascade assessment to user with recommended next command(s)</action>
+</step>
+</workflow>