gaia-framework 1.58.0 → 1.59.0

package/_gaia/lifecycle/workflows/anytime/memory-hygiene/checklist.md

@@ -0,0 +1,66 @@
+---
+title: 'Memory Hygiene Validation'
+validation-target: 'Memory hygiene report'
+---
+
+## Dynamic Sidecar Discovery
+- [ ] All sidecar directories discovered dynamically from config + on-disk union
+- [ ] Sidecars classified by tier (Tier 1, Tier 2, Tier 3, untiered)
+- [ ] Empty sidecars identified and skipped
+- [ ] Archive subdirectories excluded from active scanning
+- [ ] Legacy filenames detected and flagged for migration
+
+## Tier-Aware Multi-File Scanning
+- [ ] Tier 1 sidecars scanned for ground-truth.md, decision-log.md, conversation-context.md
+- [ ] Tier 2 sidecars scanned for decision-log.md, conversation-context.md
+- [ ] Tier 3 and untiered sidecars scanned for decision-log.md only
+- [ ] Missing expected files logged with warning
+
+## Cross-Reference Validation
+- [ ] Standardized decision-log entries parsed (Status, Related fields)
+- [ ] Cross-agent references validated against cross-reference matrix from config
+- [ ] References to superseded/archived entries flagged as STALE
+- [ ] Pre-standard format entries flagged as UNVERIFIABLE-FORMAT
+- [ ] Orphaned artifact paths and story/epic keys detected
+
+## Stale Detection via Skill
+- [ ] stale-detection section loaded JIT from memory-management skill
+- [ ] No inline reimplementation of stale/contradicted/orphaned detection
+- [ ] All three detection categories applied (stale, contradicted, orphaned)
+
+## Token Budget Reporting
+- [ ] Token usage calculated per agent (file size bytes / 4 chars-per-token)
+- [ ] Compared against session budget and ground truth budget from config
+- [ ] Threshold status indicators applied (OK / warning at 80% / critical at 90% / over-budget at 100%)
+- [ ] Tier 3 and untiered agents reported with "no budget enforced"
+- [ ] Token Budget Table included in report
+
+## Archival Recommendations
+- [ ] Budget pressure recommendations (agents at or above 90%)
+- [ ] Staleness recommendations (superseded/archived entries not in archive/)
+- [ ] Age-based recommendations (entries older than 3 sprints / 42-day fallback)
+- [ ] Recommendations classified as actionable vs advisory
+- [ ] Archival never auto-executed — requires user confirmation per entry
+
+## Ground Truth Refresh
+- [ ] Tier 1 agents checked for stale ground-truth.md (Sprint gap > 1)
+- [ ] /gaia-refresh-ground-truth recommended for stale agents
+- [ ] Tier 2 and Tier 3 agents excluded from ground truth check
+- [ ] Graceful degradation if sprint data unavailable
+
+## Untiered Agent Handling
+- [ ] Untiered agents (on-disk sidecar, no config entry) scanned as Tier 3
+- [ ] Reported with "untiered — no budget config" in budget table
+- [ ] Recommendation emitted to add to _memory/config.yaml as Tier 3
+
+## Enhanced Report Output
+- [ ] Report contains all 7 sections: Summary, Token Budget Table, Detailed Findings, Archival Recommendations, Ground Truth Refresh Recommendations, Untiered Agent Report, Skipped Sidecars
+- [ ] Summary includes counts by status across all tiers and budget usage summary
+- [ ] Detailed Findings grouped by sidecar and sorted by severity
+- [ ] Report saved to {implementation_artifacts}/memory-hygiene-report-{date}.md
+
+## User Actions
+- [ ] All flagged entries presented to user with evidence
+- [ ] User confirmed action (Keep/Archive/Delete) for each flagged entry
+- [ ] Sidecar files updated per user choices
+- [ ] Sidecar headers and marker comments preserved after edits

package/_gaia/lifecycle/workflows/anytime/memory-hygiene/instructions.xml

@@ -0,0 +1,206 @@
+<workflow name="memory-hygiene">
+<critical>
+  <mandate>User-initiated cross-sidecar reads are explicitly allowed per agent-specification-protocol</mandate>
+  <mandate>Never modify a sidecar file without explicit user confirmation for each entry</mandate>
+  <mandate>Preserve the sidecar file header and marker comment in all modifications</mandate>
+  <mandate>Process sidecars one at a time — release previous sidecar content before loading next (JIT)</mandate>
+  <mandate>Archival is recommendation-only — never auto-execute without user confirmation</mandate>
+  <mandate>Cross-reference validation scope is limited to the declared matrix in _memory/config.yaml</mandate>
+  <mandate>Token approximation: 4 chars per token (file size in bytes / 4)</mandate>
+</critical>
+
+<step n="1" title="Dynamic Sidecar Discovery">
+  <action>Read {memory_path}/config.yaml to get tier assignments, token budgets, and cross-reference matrix</action>
+  <action>Extract tier_1, tier_2, tier_3 agent lists from config. For each agent, resolve sidecar directory name from the agents.{agent-id}.sidecar field</action>
+  <action>Enumerate all on-disk {memory_path}/*-sidecar/ directories</action>
+  <action>Union config-declared sidecars and on-disk sidecars into a master list. For each sidecar, classify by tier:
+    - If agent is in tiers.tier_1.agents → Tier 1 (3 files: ground-truth.md, decision-log.md, conversation-context.md)
+    - If agent is in tiers.tier_2.agents → Tier 2 (2 files: decision-log.md, conversation-context.md)
+    - If agent is in tiers.tier_3.agents → Tier 3 (1 file: decision-log.md)
+    - If agent has on-disk sidecar but no tier in config → classify as Untiered (scan decision-log.md only, no budget enforced)</action>
+  <action>Exclude archive/ subdirectories from active scanning — these contain archived entries and are gitignored</action>
+  <action>Build categorized sidecar lists:
+    - Tier 1 sidecars with expected files
+    - Tier 2 sidecars with expected files
+    - Tier 3 sidecars with expected files
+    - Untiered sidecars (decision-log.md only)
+    - Empty sidecars (no content files found)
+    - Sidecars with legacy filenames (architecture-decisions.md, infrastructure-decisions.md, threat-model-decisions.md, velocity-data.md) — flag for migration to standard names</action>
+  <check if="zero sidecars have content">Report "All sidecars are empty — nothing to review" and complete the workflow</check>
+  <action>Report to user: "{N} sidecars discovered ({T1} Tier 1, {T2} Tier 2, {T3} Tier 3, {U} untiered), {E} empty. {L} legacy filenames detected. Proceeding with review."</action>
+</step>
+
+<step n="2" title="Tier-Aware Multi-File Scanning">
+  <action>For each sidecar (JIT — release previous sidecar content before loading next):
+    - Determine expected files based on tier classification from Step 1
+    - Tier 1: read ground-truth.md, decision-log.md, conversation-context.md
+    - Tier 2: read decision-log.md, conversation-context.md
+    - Tier 3: read decision-log.md
+    - Untiered: read decision-log.md</action>
+  <action>For each expected file:
+    - Check if file exists
+    - If missing: log warning "Expected {filename} for {tier} agent {agent} — file not found"
+    - If exists: check for content beyond template header (text after marker comment)
+    - Record file size in bytes for token budget calculation</action>
+  <action>Detect legacy filenames in each sidecar:
+    - architecture-decisions.md → should be decision-log.md (architect-sidecar)
+    - infrastructure-decisions.md → should be decision-log.md (devops-sidecar)
+    - threat-model-decisions.md → should be decision-log.md (security-sidecar)
+    - velocity-data.md → should be decision-log.md (sm-sidecar)
+    If legacy file found: scan it as decision-log content but flag for migration</action>
+  <action>Build content inventory: list of all files scanned with size, tier, and content status (has-content / empty / missing / legacy-name)</action>
+</step>
+
+<step n="3" title="Load Reference Artifacts">
+  <action>Attempt to read each reference artifact (record which exist and which are missing):
+    - {planning_artifacts}/architecture.md — for architectural decision validation
+    - {planning_artifacts}/prd.md — for product decision validation
+    - {planning_artifacts}/infrastructure-design.md — for infrastructure validation
+    - {test_artifacts}/test-plan.md — for test strategy validation
+    - {implementation_artifacts}/sprint-status.yaml — for sprint references and current sprint ID
+    - {planning_artifacts}/epics-and-stories.md — for story/epic key validation</action>
+  <action>For each artifact that exists: retain its key sections and structure for comparison</action>
+  <action>Extract current sprint ID from sprint-status.yaml if it exists. If not found, note "sprint data unavailable — will use 42-day calendar fallback for age calculations"</action>
+  <check if="no reference artifacts exist">Warn user: "No reference artifacts found. Hygiene will be limited to structural checks and budget reporting."</check>
+</step>
+
+<step n="4" title="Cross-Reference Validation">
+  <action>For each sidecar with content (JIT — release previous before loading next):
+    Parse decision-log entries using the standardized format (E9-S3):
+    - Header: ### [YYYY-MM-DD] Decision Title
+    - Fields: Agent, Sprint, Status: active | superseded | archived, Related: {paths, keys}
+    - If entry does not follow standardized format (no Status field, no ### header): flag as UNVERIFIABLE-FORMAT</action>
+  <action>For entries with Status field:
+    - If Status: superseded or Status: archived → flag entry itself as already-archived (candidate for archive/ move)
+    - If Status: active → validate Related field references</action>
+  <action>For entries with Related field pointing to other agents' decisions:
+    - Use the cross-reference matrix from {memory_path}/config.yaml to determine valid cross-agent reads
+    - For each cross-agent reference: look up the referenced entry's Status in the source agent's decision-log
+    - If referenced entry has Status: superseded or archived → flag as STALE with evidence
+    - If referenced entry not found → flag as ORPHANED
+    - If source agent's file not parseable → flag reference as UNVERIFIABLE-FORMAT</action>
+  <action>For all entries: scan Related field for artifact paths and story/epic keys
+    - Cross-reference paths against filesystem — if not found, flag as potential STALE or ORPHANED
+    - Cross-reference story/epic keys against epics-and-stories.md — if not found, flag as ORPHANED
+    - For ORPHANED candidates: search for semantically similar names and suggest likely renames</action>
+</step>
+
+<step n="5" title="Stale Detection via Skill">
+  <action>JIT-load the stale-detection section from {project-root}/_gaia/lifecycle/skills/memory-management.md
+    Load only the content between &lt;!-- SECTION: stale-detection --&gt; and &lt;!-- END SECTION --&gt; markers</action>
+  <action>Apply the canonical stale detection logic from the memory-management skill:
+    1. Stale entries — decision references an artifact path that no longer exists on the filesystem
+    2. Contradicted entries — two active decisions in the same sidecar that conflict
+    3. Orphaned entries — decision references a story or epic removed from epics-and-stories.md</action>
+  <action>Merge stale detection results with cross-reference validation results from Step 4 — deduplicate entries flagged by both checks</action>
+</step>
+
+<step n="6" title="Classify Entries">
+  <action>Assign each sidecar entry one of five statuses:
+    - ACTIVE: Entry is consistent with current reference artifacts — no action needed
+    - STALE: The referenced artifact has changed or the cross-referenced decision is superseded/archived
+    - CONTRADICTED: Current artifact explicitly states the opposite of what this entry records
+    - ORPHANED: The component, service, story, or epic referenced no longer exists in any current artifact
+    - UNVERIFIABLE-FORMAT: Entry does not follow standardized format (no Status field) — cannot validate programmatically</action>
+  <action>Record evidence for each classification: which artifact section confirms or contradicts, what changed, or what is missing</action>
+</step>
+
+<step n="7" title="Token Budget Reporting">
+  <action>For each agent sidecar, calculate token usage:
+    - Sum file sizes in bytes across all sidecar files (from Step 2 inventory)
+    - Convert to approximate token count: file size in bytes / 4 (chars-per-token approximation from config archival.token_approximation)
+    - For Tier 1 agents: also calculate ground-truth.md token usage separately</action>
+  <action>Compare against budgets from {memory_path}/config.yaml:
+    - Tier 1 session budget: tiers.tier_1.session_budget (300K tokens)
+    - Tier 1 ground truth budget: agents.{agent}.ground_truth_budget (per-agent: Val 200K, Theo 150K, Derek 100K, Nate 100K)
+    - Tier 2 session budget: tiers.tier_2.session_budget (100K tokens)
+    - Tier 3: no budget enforced
+    - Untiered: no budget enforced</action>
+  <action>Apply threshold status indicators per archival config:
+    - OK: below 80% of budget
+    - warning: at or above 80% but below 90%
+    - critical: at or above 90% but below 100%
+    - over-budget: at or above 100%</action>
+  <action>Build Token Budget Table with columns:
+    | Agent | Tier | Files Scanned | Token Usage | Session Budget | GT Budget | % Used | Status |
+    For Tier 3 and untiered agents: budget column shows "no budget enforced" with actual token count reported</action>
+</step>
+
+<step n="8" title="Archival Recommendations">
+  <action>Generate archival recommendations based on three criteria:
+    (a) Budget pressure — for agents at or above 90% of budget: identify oldest entries as archival candidates (oldest first). Mark as "actionable — budget pressure"
+    (b) Staleness — entries with Status: superseded or Status: archived that have not been moved to the archive/ subdirectory. Mark as "actionable — stale status"
+    (c) Age — entries older than 3 sprints (determined from current sprint ID minus 3; fallback to 42 calendar days if no sprint data). Only flag if the entry has no Related field pointing to an active story. Mark as "advisory — age"</action>
+  <action>Classify each recommendation:
+    - Actionable: budget pressure and staleness recommendations — should be acted on
+    - Advisory: age-based recommendations — informational, user decides</action>
+  <action>Archival is never auto-executed — all recommendations require user confirmation per entry before any file changes are made</action>
+</step>
+
+<step n="9" title="Ground Truth Refresh Trigger">
+  <action>For each Tier 1 agent (Val, Theo, Derek, Nate) that has a ground-truth.md file:
+    - Read the most recent entry's Sprint field from ground-truth.md
+    - Compare against current sprint ID from sprint-status.yaml
+    - If the gap is more than 1 sprint behind: recommend /gaia-refresh-ground-truth for that agent</action>
+  <action>If sprint-status.yaml does not exist or has no sprint ID: skip ground truth refresh check (cannot determine staleness without sprint data)</action>
+  <action>If E9-S11 (--agent parameter) is not yet implemented: recommend base command /gaia-refresh-ground-truth without --agent flag. Once E9-S11 ships, recommend /gaia-refresh-ground-truth --agent {agent-id}</action>
+  <action>Tier 2 and Tier 3 agents have no ground-truth.md — exclude from this check entirely</action>
+</step>
+
+<step n="10" title="Present Enhanced Report">
+  <action>Generate the enhanced findings report with these 7 sections:
+
+    **1. Summary**
+    - Total sidecars scanned (by tier: Tier 1, Tier 2, Tier 3, untiered)
+    - Total entries scanned
+    - Counts by status: ACTIVE, STALE, CONTRADICTED, ORPHANED, UNVERIFIABLE-FORMAT
+    - Budget usage summary: agents OK, warning, critical, over-budget
+
+    **2. Token Budget Table**
+    | Agent | Tier | Files Scanned | Token Usage | Session Budget | GT Budget | % Used | Status |
+    (One row per agent, sorted by tier then agent name)
+
+    **3. Detailed Findings**
+    | Sidecar | Entry | Status | Evidence | Reference Artifact |
+    (Grouped by sidecar, sorted by severity: CONTRADICTED, STALE, ORPHANED, UNVERIFIABLE-FORMAT, ACTIVE)
+
+    **4. Archival Recommendations**
+    | # | Agent | Entry | Reason | Type | Action |
+    (Budget pressure first, then staleness, then age)
+
+    **5. Ground Truth Refresh Recommendations**
+    | Agent | Last Sprint | Current Sprint | Gap | Recommendation |
+    (Tier 1 agents only)
+
+    **6. Untiered Agent Report**
+    | Agent | Sidecar Dir | Files Found | Recommendation |
+    For each untiered agent: recommend adding to _memory/config.yaml as Tier 3
+
+    **7. Skipped Sidecars**
+    List of sidecars with no content or explicitly skipped</action>
+  <template-output file="{implementation_artifacts}/memory-hygiene-report-{date}.md">
+    Enhanced memory hygiene report with all 7 sections: Summary, Token Budget Table, Detailed Findings, Archival Recommendations, Ground Truth Refresh Recommendations, Untiered Agent Report, Skipped Sidecars.
+  </template-output>
+</step>
+
+<step n="11" title="User Action on Flagged Items">
+  <action>For each entry with status other than ACTIVE, ask the user to choose one action:
+    - Keep: Add a [Reviewed: {date}] annotation to the entry — confirms user saw and accepted it
+    - Archive: Move the entry to the archive/ subdirectory of the sidecar (if directory exists; create if not). Prefix with [Archived: {date} — Reason: {status}]
+    - Delete: Remove the entry from the sidecar file entirely</action>
+  <action>When modifying sidecar files:
+    - ALWAYS preserve the file header (title, description, marker comment)
+    - ALWAYS keep the &lt;!-- Decisions will be appended below this line --&gt; marker intact
+    - Active entries remain between the marker comment and end of file
+    - Archived entries go to archive/ subdirectory, not inline section</action>
+  <action>After all user actions are processed: report summary of changes made to each sidecar file</action>
+</step>
+
+<step n="12" title="Optional: Prune Completed Checkpoints" optional="true">
+  <ask>Would you like to prune old completed checkpoints? (yes / skip)</ask>
+  <action if="yes">Read {checkpoint_path}/completed/ and list all .yaml files with dates</action>
+  <ask if="yes">How many sprints of checkpoints to retain? (default: 2)</ask>
+  <action if="yes">Delete checkpoint files older than the retention window</action>
+  <action if="yes">Report: "Pruned {N} completed checkpoint(s). Retained {M} within the {retention} sprint window."</action>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/anytime/memory-hygiene/workflow.yaml

@@ -0,0 +1,15 @@
+name: memory-hygiene
+description: 'Detect stale, contradicted, or superseded decisions in agent memory sidecars'
+module: lifecycle
+agent: orchestrator
+config_resolved: "{installed_path}/.resolved/memory-hygiene.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/anytime/memory-hygiene"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{implementation_artifacts}/memory-hygiene-report-{date}.md"

package/_gaia/lifecycle/workflows/anytime/performance-review/checklist.md

@@ -0,0 +1,25 @@
+---
+title: 'Performance Review Validation'
+validation-target: 'Performance review report'
+required-inputs: []
+---
+## Scope
+- [ ] Performance scope defined (endpoints, flows, system)
+- [ ] Frontend vs backend scope clarified
+## Baseline
+- [ ] Current metrics documented or baseline plan established
+- [ ] SLOs identified
+## Load Testing
+- [ ] Test scenarios match real user behavior
+- [ ] Traffic patterns defined
+- [ ] Tooling recommended
+## Bottlenecks
+- [ ] Database access patterns reviewed
+- [ ] Blocking operations identified
+- [ ] Caching strategy evaluated
+## Recommendations
+- [ ] Improvements are specific and prioritized
+- [ ] Each has estimated impact
+- [ ] Categorized by effort level
+## Output Verification
+- [ ] Report file generated at {test_artifacts}/

package/_gaia/lifecycle/workflows/anytime/performance-review/instructions.xml

@@ -0,0 +1,62 @@
+<workflow name="performance-review">
+<critical>
+  <mandate>Story must be in review status before performance review</mandate>
+  <mandate>Auto-pass if no performance-relevant code changes detected</mandate>
+  <mandate>Always measure before recommending optimizations</mandate>
+  <mandate>Report in percentiles (P50, P95, P99), not averages</mandate>
+  <mandate>Output must include machine-readable PASSED or FAILED verdict</mandate>
+  <mandate>When reading or running application source code, use {project-path} as the base directory — NOT {project-root}. {project-path} is resolved by the engine from global.yaml.</mandate>
+</critical>
+<step n="1" title="Load Story">
+  <action>Resolve story file: search for {story_key}-*.md in {implementation_artifacts}/ using glob pattern to match the full filename ({story_key}-{title_slug}.md)</action>
+  <action>Read story file, identify files changed</action>
+  <action>Extract the list of files changed from the story file</action>
+</step>
+<step n="2" title="Status Gate">
+  <action>Verify story is in 'review' status</action>
+  <check if="status != review">HALT: Story must be in review status before performance review</check>
+</step>
+<step n="3" title="Auto-Pass Classification">
+  <action>Classify each changed file as performance-relevant or not:</action>
+  <action>Performance-relevant: files containing DB queries, API endpoints, data processing, rendering logic, loops/algorithms, middleware, caching, network calls</action>
+  <action>Not relevant: markdown (.md), config/yaml/json, test files, static assets, CSS-only, copy/translations, .gitignore, lock files</action>
+  <check if="zero performance-relevant files">
+    Verdict is PASSED with note "No performance-relevant code changes — auto-passed". Skip to step 8 (Generate Output) with this verdict.
+  </check>
+  <action>If ANY performance-relevant files exist: proceed to full review (step 4)</action>
+</step>
+<step n="4" title="N+1 and Database Analysis">
+  <action>Analyze for N+1 queries and inefficient database access patterns</action>
+  <action>Check for missing indexes on queried columns</action>
+  <action>Identify unbounded queries (missing LIMIT, pagination)</action>
+</step>
+<step n="5" title="Memory and Bundle Analysis">
+  <action>Identify memory leaks, large payloads, unoptimized loops</action>
+  <action>Check frontend: bundle size impact, render blocking, unnecessary re-renders</action>
+  <action>Review image optimization and lazy loading</action>
+</step>
+<step n="6" title="Caching and Complexity Review">
+  <action>Review caching strategy: what's cached, what should be, cache invalidation</action>
+  <action>Check for blocking operations and synchronous bottlenecks</action>
+  <action>Analyze algorithm complexity — flag O(n^2) or worse in hot paths</action>
+</step>
+<step n="7" title="Verdict">
+  <action>If NO critical or high severity performance issues: verdict is PASSED</action>
+  <action>If ANY critical or high severity issue found: verdict is FAILED — list blocking findings</action>
+</step>
+<step n="8" title="Generate Output">
+  <template-output file="{implementation_artifacts}/{story_key}-performance-review.md">
+    Generate performance review report with: auto-pass classification result (if applicable), N+1 analysis, memory/bundle findings, caching review, algorithm complexity, and machine-readable verdict (PASSED/FAILED).
+  </template-output>
+</step>
+<step n="9" title="Update Review Gate and Transition">
+  <action>Read story file, locate Review Gate table</action>
+  <action>If PASSED: update Performance Review row status to PASSED, link report file</action>
+  <action>If FAILED: update Performance Review row status to FAILED, link report file. Do NOT change story status — the review-gate-check protocol or run-all-reviews orchestrator handles status transitions.</action>
+  <template-output file="{implementation_artifacts}/{story_key}-*.md">
+    Update story file Review Gate table with performance review result and report link.
+  </template-output>
+  <action>Inform user: "Note: sprint-status.yaml may now be out of sync. Run /gaia-sprint-status to reconcile."</action>
+  <invoke-protocol name="review-gate-check" file="{project-root}/_gaia/core/protocols/review-gate-check.xml" />
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/anytime/performance-review/workflow.yaml

@@ -0,0 +1,15 @@
+name: performance-review
+description: 'Analyze performance bottlenecks and recommend optimizations'
+module: lifecycle
+agent: performance
+config_resolved: "{installed_path}/.resolved/performance-review.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/anytime/performance-review"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{test_artifacts}/performance-review-{date}.md"

package/_gaia/lifecycle/workflows/cross-phase/add-feature/checklist.md

@@ -0,0 +1,30 @@
+---
+title: 'Add Feature Validation'
+validation-target: 'Feature Addition Cascade'
+---
+## Orchestration
+- [ ] Feature scope captured and confirmed by user
+- [ ] Context flows forward between steps (prd_diff → arch_diff → test_diff → stories)
+- [ ] Steps intelligently skipped when not needed
+## PRD Update
+- [ ] PRD edited with new requirements
+- [ ] New FR/NFR IDs captured for downstream steps
+- [ ] Cascade to architecture classified (NONE/MINOR/SIGNIFICANT)
+## Architecture Update (if applicable)
+- [ ] Architecture edited with changes supporting new requirements
+- [ ] New ADRs recorded
+- [ ] Skipped with justification if cascade_to_arch == NONE
+## Test Plan Update (if applicable)
+- [ ] Test plan edited with new test cases
+- [ ] New test cases map to new FR/NFR IDs
+- [ ] Skipped with justification if no test-plan.md or no new testable behavior
+## Story Creation
+- [ ] New stories created with correct format
+- [ ] Epic assignment confirmed (new or existing)
+- [ ] Story protection enforced (no modification of locked stories)
+## Traceability
+- [ ] Traceability matrix regenerated
+- [ ] New requirements → test cases → stories linked
+## Summary
+- [ ] Final summary presented to user with all artifact statuses
+- [ ] Next steps communicated

package/_gaia/lifecycle/workflows/cross-phase/add-feature/instructions.xml

@@ -0,0 +1,85 @@
+<workflow name="add-feature">
+<critical>
+  <mandate>This is an orchestrator — delegate to sub-workflows via subagents, do not perform edits directly</mandate>
+  <mandate>Context flows forward: PRD diff feeds arch edit, which feeds test plan edit, which feeds story creation</mandate>
+  <mandate>Intelligently skip steps when not needed — do not force all sub-workflows on every feature</mandate>
+</critical>
+
+<step n="1" title="Capture Feature Scope">
+  <ask>Describe the new feature you want to add.</ask>
+  <ask>What is the business driver? (customer request / market opportunity / technical improvement / regulatory)</ask>
+  <ask>Is this linked to a change request? If so, provide the CR ID.</ask>
+  <action>If CR exists: read {planning_artifacts}/change-request-{cr_id}.md for context (impact analysis, approval status)</action>
+  <action>Classify initial scope: how many artifacts will likely need changes?</action>
+  <action>Present scope summary to user for confirmation before proceeding:
+    - Feature: {feature_description}
+    - Driver: {driver}
+    - CR: {cr_id or "none"}
+    - Expected cascade: PRD (always) → Architecture ({likely/unlikely}) → Test Plan ({if exists}) → Stories (always) → Traceability (always)</action>
+</step>
+
+<step n="2" title="Edit PRD">
+  <action>Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/2-planning/edit-prd/workflow.yaml as workflow-config. Run in YOLO mode. Follow the workflow engine instructions EXACTLY. Context: Adding new feature: {feature_description}. Driver: {driver}. CR ID: {cr_id}. Add new functional and non-functional requirements for this feature. Use CR ID {cr_id} when prompted."</action>
+  <action>When subagent returns: capture the PRD diff — identify NEW requirement IDs (FR-*, NFR-*) added</action>
+  <action>Capture the cascade classification from edit-prd Step 7 (architecture impact: NONE/MINOR/SIGNIFICANT)</action>
+  <action>Store: prd_diff = {new FR/NFR IDs and descriptions}, cascade_to_arch = {NONE/MINOR/SIGNIFICANT}</action>
+</step>
+
+<step n="3" title="Adversarial Review on PRD" optional="true" condition="edit_prd_offered_adversarial">
+  <action>If edit-prd Step 5 ran adversarial review: the subagent already handled it — capture any refined requirements</action>
+  <action>If adversarial findings were incorporated: update prd_diff with refined requirement IDs</action>
+  <action>If adversarial was skipped: proceed to Step 4</action>
+</step>
+
+<step n="4" title="Edit Architecture" optional="true" condition="cascade_to_arch != NONE">
+  <check if="cascade_to_arch == NONE">
+    <action>Inform user: "No architecture changes needed for this feature — PRD changes are requirements-only." Skip to Step 5.</action>
+  </check>
+  <action>Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/3-solutioning/edit-architecture/workflow.yaml as workflow-config. Run in YOLO mode. Follow the workflow engine instructions EXACTLY. Context: PRD updated with new feature: {feature_description}. New requirements: {prd_diff}. Update architecture to support these requirements. CR ID: {cr_id}."</action>
+  <action>When subagent returns: capture the architecture diff — new ADRs, changed sections, version note</action>
+  <action>Store: arch_diff = {architecture changes made}</action>
+</step>
+
+<step n="5" title="Edit Test Plan" optional="true" condition="test_plan_exists">
+  <check if="test_plan_not_found">
+    <action>Inform user: "No test-plan.md exists. Recommend running /gaia-test-design to create an initial test plan." Skip to Step 6.</action>
+  </check>
+  <ask>Does this feature add new testable behavior? (yes / skip)</ask>
+  <action>If skip: proceed to Step 6.</action>
+  <action>If yes: spawn a subagent using the Agent tool: "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. Follow the workflow engine instructions EXACTLY. Context: New feature: {feature_description}. New PRD requirements: {prd_diff}. Architecture changes: {arch_diff}. Add test cases for the new feature."</action>
+  <action>When subagent returns: capture test plan additions (new test case IDs)</action>
+  <action>Store: test_diff = {new test cases added}</action>
+</step>
+
+<step n="6" title="Add Feature Stories">
+  <action>Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/4-implementation/add-stories/workflow.yaml as workflow-config. Run in YOLO mode. Follow the workflow engine instructions EXACTLY. Context: New feature: {feature_description}. New PRD requirements: {prd_diff}. Architecture changes: {arch_diff}. Create stories for this feature. Determine if a new epic is needed or if stories belong to an existing epic. CR ID: {cr_id}."</action>
+  <action>When subagent returns: capture new story keys and epic assignments</action>
+  <action>Store: new_stories = {list of new story keys created}</action>
+</step>
+
+<step n="7" title="Update Traceability">
+  <action>Spawn a subagent using the Agent tool: "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. Follow the workflow engine instructions EXACTLY. Regenerate traceability matrix to include new requirements, test cases, and stories."</action>
+  <action>When subagent returns: verify new FR/NFR IDs → test cases → stories are linked</action>
+</step>
+
+<step n="8" title="Readiness Re-check and Summary">
+  <ask>Run readiness check to validate consistency? (yes / skip — recommended for significant features)</ask>
+  <action>If yes: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/3-solutioning/implementation-readiness/workflow.yaml as workflow-config. Run in YOLO mode. Follow the workflow engine instructions EXACTLY."</action>
+  <action>Present final summary:
+    **Feature Addition Complete: {feature_description}**
+
+    | Artifact | Status | Details |
+    |----------|--------|---------|
+    | PRD | Updated | {new FR/NFR IDs added} |
+    | Architecture | {Updated/Skipped} | {new ADRs or "No changes needed"} |
+    | Test Plan | {Updated/Skipped/Not found} | {new test case IDs or reason} |
+    | Stories | Created | {new story keys} in {epic assignment} |
+    | Traceability | Regenerated | {linkage verified} |
+    | Readiness | {Passed/Skipped} | {status} |
+
+    **Next steps:**
+    - For each new story: run /gaia-create-story {story_key} to elaborate
+    - To start development: run /gaia-sprint-plan or /gaia-correct-course
+  </action>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/cross-phase/add-feature/workflow.yaml

@@ -0,0 +1,37 @@
+name: add-feature
+description: 'Guided orchestrator for adding a new feature — cascades through PRD, architecture, test plan, stories, traceability, and readiness'
+module: lifecycle
+agent: orchestrator
+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"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+input_file_patterns:
+  prd:
+    whole: "{planning_artifacts}/prd.md"
+    load_strategy: "SELECTIVE_LOAD"
+  architecture:
+    whole: "{planning_artifacts}/architecture.md"
+    load_strategy: "SELECTIVE_LOAD"
+  test_plan:
+    whole: "{test_artifacts}/test-plan.md"
+    load_strategy: "SELECTIVE_LOAD"
+  epics:
+    whole: "{planning_artifacts}/epics-and-stories.md"
+    load_strategy: "SELECTIVE_LOAD"
+  sprint_status:
+    whole: "{implementation_artifacts}/sprint-status.yaml"
+    load_strategy: "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"

package/_gaia/lifecycle/workflows/quick-flow/quick-dev/checklist.md

@@ -0,0 +1,11 @@
+---
+title: 'Quick Dev Validation'
+validation-target: 'Quick dev implementation'
+---
+## Implementation
+- [ ] Spec followed
+- [ ] Tests pass
+- [ ] Acceptance criteria met
+## Checkpoint
+- [ ] WIP checkpoint checked on start
+- [ ] Checkpoint archived on completion

package/_gaia/lifecycle/workflows/quick-flow/quick-dev/instructions.xml

@@ -0,0 +1,26 @@
+<workflow name="quick-dev">
+<critical>
+  <mandate>Check for WIP checkpoint before starting</mandate>
+</critical>
+<step n="1" title="Load Spec">
+  <action>Read quick spec file</action>
+  <action>Check for WIP checkpoint at _memory/checkpoints/quick-dev-{spec_name}.yaml</action>
+</step>
+<step n="2" title="Check WIP">
+  <check if="checkpoint_exists and has files_touched">Validate checksums (shasum -a 256) for each entry in files_touched — flag DELETED or MODIFIED files, offer Proceed / Start fresh / Review before resuming</check>
+  <check if="checkpoint_exists">Offer to resume from last checkpoint or start fresh</check>
+</step>
+<step n="3" title="Implement">
+  <action>Follow spec implementation steps</action>
+  <action>Apply TDD where practical</action>
+  <action>Write checkpoint after each step — include files_touched with path, checksum (shasum -a 256), last_modified (ISO 8601) for all files created/modified</action>
+</step>
+<step n="4" title="Verify">
+  <action>Run tests</action>
+  <action>Validate against spec acceptance criteria</action>
+</step>
+<step n="5" title="Complete">
+  <action>Archive checkpoint to completed/</action>
+  <action>Report implementation complete with files changed</action>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/quick-flow/quick-dev/workflow.yaml

@@ -0,0 +1,19 @@
+name: quick-dev
+description: 'Implement a quick spec'
+module: lifecycle
+agent: dev-*
+config_resolved: "{installed_path}/.resolved/quick-dev.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/quick-flow/quick-dev"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+input_file_patterns:
+  spec:
+    whole: "{implementation_artifacts}/quick-spec-{{spec_name}}.md"
+    load_strategy: "FULL_LOAD"
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "source_code"

package/_gaia/lifecycle/workflows/quick-flow/quick-spec/checklist.md

@@ -0,0 +1,13 @@
+---
+title: 'Quick Spec Validation'
+validation-target: 'Quick spec document'
+---
+## Scope
+- [ ] Change clearly described
+- [ ] Files identified
+- [ ] Escape hatch offered if scope is large
+## Spec Quality
+- [ ] Implementation steps defined
+- [ ] Acceptance criteria included
+## Output Verification
+- [ ] Quick spec exists at {implementation_artifacts}/quick-spec-{spec_name}.md