gaia-framework 1.65.1 → 1.83.2

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

@@ -12,6 +12,8 @@ points: "{story_points}"
 risk: "{high/medium/low}"
 sprint_id: null
 priority_flag: null
+origin: null
+origin_ref: null
 depends_on: []
 blocks: []
 traces_to: []
@@ -116,4 +118,23 @@ As a {role}, I want to {action}, so that {benefit}.
 
 ## Definition of Done
 
-- [ ] Define all the Definition of Done
+### Acceptance
+
+- [ ] All acceptance criteria verified and checked off
+- [ ] All subtasks marked complete
+
+### Testing
+
+- [ ] All tests pass (unit, integration, e2e as applicable)
+- [ ] No linting or formatting errors
+
+### Code Quality & CI
+
+- [ ] Code compiles / builds without errors
+- [ ] Code follows project conventions
+- [ ] No hardcoded secrets or credentials
+- [ ] PR merged to staging with all CI checks passing
+
+### Documentation
+
+- [ ] Documentation updated (if applicable)

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

@@ -32,12 +32,61 @@
   <action>Plan keyboard navigation, screen reader support</action>
   <action>Define color contrast and text sizing standards</action>
 </step>
-<step n="7" title="Generate Output">
+<step n="7" title="Figma MCP Detection and Mode Selection">
+  <action>Probe for available Figma MCP server. Load figma-integration.md detection section JIT to determine if a design tool adapter is available.</action>
+  <action if="figma_mcp_available">Present mode selection to user: [Generate] Create Figma frames alongside ux-design.md | [Import] Import existing Figma designs (read-only) | [Skip] Text-only UX spec, no Figma integration</action>
+  <action if="not figma_mcp_available">Skip Figma integration — proceed with text-only UX design output. Log: "No Figma MCP server detected. Generating markdown-only ux-design.md."</action>
+</step>
+<step n="8" title="Generate Mode — UI Kit Page Creation" if="figma_mcp_available AND user_selected_generate">
+  <critical>
+    <mandate>Generate mode is the ONLY mode that performs write operations to Figma (FR-140). All other modes are read-only. Write operations: create pages, create frames, create component instances. Minimum required Figma API scopes: files:read + file_content:read + files:write.</mandate>
+  </critical>
+  <action>Load figma-integration.md frames section JIT from _gaia/dev/skills/figma-integration.md</action>
+  <action>Create a UI Kit page named "UI Kit — Generated" in the Figma design file via MCP</action>
+  <action>Extract design tokens from {planning_artifacts}/design-system/design-tokens.json (W3C DTCG format)</action>
+  <action>Create color styles with semantic aliases from token definitions (e.g., color.surface.primary, color.text.primary)</action>
+  <action>Create typography styles from composite token specs (heading-1, heading-2, body, caption)</action>
+  <action>Create spacing grid tokens and base components with state variants (default, hover, active, disabled, focus)</action>
+  <action>Error handling: on HTTP 429 rate limit, perform a single retry after backoff. If 429 persists, graceful fallback to markdown-only flow — log warning and skip remaining Figma operations.</action>
+</step>
+<step n="9" title="Generate Mode — Per-Screen Frame Generation" if="figma_mcp_available AND user_selected_generate">
+  <action>Parse PRD user journeys to determine screens needing frames</action>
+  <action>For each screen, generate frames at 6 viewports: 280px (foldable inner, FR-174), 375px (mobile), 600px (foldable outer, FR-174), 768px (tablet portrait), 1024px (tablet landscape, FR-174), 1280px (desktop)</action>
+  <action>Compose frames using UI Kit components from the previous step — apply auto-layout with responsive constraints from component specs</action>
+  <action>Label frames using naming convention: {ScreenName}/{Viewport} (e.g., Dashboard/Desktop, Login/Mobile)</action>
+  <action>Collect all generated Figma node IDs for downstream recording in ux-design.md</action>
+</step>
+<step n="10" title="Generate Mode — Prototype Flow Setup" if="figma_mcp_available AND user_selected_generate">
+  <action>Map PRD user journey steps to the generated screen frames</action>
+  <action>Create prototype flow connections between frames via Figma MCP, linking screens in the order defined by each user journey</action>
+  <action>Validate flow completeness: every user journey step must map to a generated frame. Flag any unmapped journey steps as warnings.</action>
+</step>
+<step n="11" title="Generate Mode — Asset Export Configuration" if="figma_mcp_available AND user_selected_generate">
+  <action>Configure PNG export at 1x, 2x, 3x densities for raster assets (images, illustrations)</action>
+  <action>Configure SVG export for icon components</action>
+  <action>Generate platform-specific asset catalogs per FR-175: iOS .xcassets catalog structure with Contents.json manifests, Android drawable-mdpi/drawable-hdpi/drawable-xhdpi/drawable-xxhdpi/drawable-xxxhdpi directories</action>
+  <action>Write export configuration and asset manifest to {planning_artifacts}/design-system/assets/ directory</action>
+  <action>Check {project-path}/.figma-cache/ for cached responses (1h TTL) before making MCP read calls — use cached data if fresh, fetch and cache if stale or missing</action>
+</step>
+<step n="12" title="Generate Mode — Record Figma Node IDs and Enhance ux-design.md" if="figma_mcp_available AND user_selected_generate">
+  <action>Build Screen-to-Frame mapping table from all generated Figma node IDs: columns Screen Name | Viewport | Figma Node ID | Page</action>
+  <action>Add figma: YAML frontmatter block to ux-design.md containing: file_key, pages array with node IDs for each generated page, and last_synced ISO 8601 timestamp</action>
+  <action>Add Design Tokens reference section linking to {planning_artifacts}/design-system/design-tokens.json with token category summary</action>
+  <action>Add Component Inventory section listing all generated UI Kit components with their Figma node IDs, variant counts, and state definitions</action>
+  <action>Add Screen-to-Frame mapping table with all generated frames across all viewports</action>
+  <action>Ensure backward compatibility: existing text-only ux-design.md content is preserved. Figma sections are additive — they appear after the standard UX design sections.</action>
+</step>
+<step n="13" title="Generate Output">
   <template-output file="{planning_artifacts}/ux-design.md">
-    Generate UX design document with: personas, information architecture, wireframe descriptions, interaction patterns, component specifications, accessibility plan, and FR-to-Screen Mapping table (FR ID | Screen/Page | Wireframe Section).
+    Generate UX design document with: personas, information architecture, wireframe descriptions, interaction patterns, component specifications, accessibility plan, FR-to-Screen Mapping table (FR ID | Screen/Page | Wireframe Section). If Generate mode was active: include figma: frontmatter block, Design Tokens section, Component Inventory with Figma node IDs, and Screen-to-Frame mapping table.
   </template-output>
 </step>
-<step n="8" title="Optional: Accessibility Review">
+<step n="14" title="FR-140 Compliance Check" if="figma_mcp_available AND user_selected_generate">
+  <action>Audit all MCP calls executed during Generate mode: classify each as READ (get_file, get_styles, get_components, get_images, get_frames) or WRITE (create_frame, create_component_instance, create_page)</action>
+  <action>Verify FR-140 constraint: write operations only occurred during Generate mode steps (8–12). Import mode and Skip mode must have zero write calls.</action>
+  <action>Document minimum required Figma API scopes: files:read + file_content:read (default for all modes), files:write (Generate mode only)</action>
+</step>
+<step n="15" title="Optional: Accessibility Review">
   <ask>Would you like to review the UX design for WCAG 2.1 accessibility compliance? This spawns a subagent in a separate context. Recommended for user-facing applications. (yes / skip)</ask>
   <action>If yes: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-accessibility.xml. Read its entire contents. Target: {planning_artifacts}/ux-design.md. Follow the flow steps EXACTLY. Generate accessibility findings report."</action>
   <action>If skip: accessibility review can be run anytime later with /gaia-review-a11y</action>

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

@@ -32,7 +32,7 @@ validation-target: 'Feature/Enhancement/Patch Triage and Cascade'
 - [ ] Failed steps handled with retry/skip/abort options
 - [ ] Checkpoint saved for /gaia-resume recovery
 ## Story
-- [ ] Implementation stories created (or patch story recommended)
+- [ ] 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

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

@@ -148,7 +148,7 @@
   <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': create a single fix story inline or recommend /gaia-create-story.</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>
 
@@ -181,8 +181,7 @@
   <action>Present summary and recommended next actions based on classification and outcome:
 
   **Patch:**
-  - If story created: "Run /gaia-dev-story {story_key} to implement the fix."
-  - If no story: "The patch is straightforward — apply directly or create a story with /gaia-create-story."
+  - "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."

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