gaia-framework 1.58.0 → 1.58.2

package/_gaia/_config/workflow-manifest.csv

@@ -0,0 +1,73 @@
+name,displayName,description,module,phase,path,command,agent
+"brainstorming","Brainstorming","Facilitated brainstorming session","core","anytime","_gaia/core/workflows/brainstorming/workflow.yaml","gaia-brainstorming","orchestrator"
+"party-mode","Party Mode","Multi-agent group discussion","core","anytime","_gaia/core/workflows/party-mode/workflow.yaml","gaia-party","orchestrator"
+"advanced-elicitation","Advanced Elicitation","Deep requirements elicitation","lifecycle","1-analysis","_gaia/lifecycle/workflows/1-analysis/advanced-elicitation/workflow.yaml","gaia-advanced-elicitation","orchestrator"
+"brainstorm-project","Brainstorm Project","Brainstorm a new project idea","lifecycle","1-analysis","_gaia/lifecycle/workflows/1-analysis/brainstorm-project/workflow.yaml","gaia-brainstorm","analyst"
+"market-research","Market Research","Conduct market research","lifecycle","1-analysis","_gaia/lifecycle/workflows/1-analysis/market-research/workflow.yaml","gaia-market-research","analyst"
+"domain-research","Domain Research","Research a domain or industry","lifecycle","1-analysis","_gaia/lifecycle/workflows/1-analysis/domain-research/workflow.yaml","gaia-domain-research","analyst"
+"technical-research","Technical Research","Research a technology","lifecycle","1-analysis","_gaia/lifecycle/workflows/1-analysis/technical-research/workflow.yaml","gaia-tech-research","analyst"
+"create-product-brief","Create Product Brief","Create a product brief","lifecycle","1-analysis","_gaia/lifecycle/workflows/1-analysis/create-product-brief/workflow.yaml","gaia-product-brief","analyst"
+"create-prd","Create PRD","Create a Product Requirements Document","lifecycle","2-planning","_gaia/lifecycle/workflows/2-planning/create-prd/workflow.yaml","gaia-create-prd","pm"
+"validate-prd","Validate PRD","Validate PRD against standards","lifecycle","2-planning","_gaia/lifecycle/workflows/2-planning/validate-prd/workflow.yaml","gaia-validate-prd","pm"
+"edit-prd","Edit PRD","Edit an existing PRD","lifecycle","2-planning","_gaia/lifecycle/workflows/2-planning/edit-prd/workflow.yaml","gaia-edit-prd","pm"
+"create-ux-design","Create UX Design","Plan UX patterns and design specs","lifecycle","2-planning","_gaia/lifecycle/workflows/2-planning/create-ux-design/workflow.yaml","gaia-create-ux","ux-designer"
+"create-architecture","Create Architecture","Design system architecture","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/create-architecture/workflow.yaml","gaia-create-arch","architect"
+"edit-architecture","Edit Architecture","Edit an existing architecture document","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/edit-architecture/workflow.yaml","gaia-edit-arch","architect"
+"create-epics-stories","Create Epics and Stories","Break requirements into epics and stories","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/create-epics-stories/workflow.yaml","gaia-create-epics","pm"
+"implementation-readiness","Implementation Readiness","Validate readiness for implementation","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/implementation-readiness/workflow.yaml","gaia-readiness-check","architect"
+"sprint-planning","Sprint Planning","Plan sprint from epics and stories","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/sprint-planning/workflow.yaml","gaia-sprint-plan","sm"
+"sprint-status","Sprint Status","Show current sprint status","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/sprint-status/workflow.yaml","gaia-sprint-status","sm"
+"create-story","Create Story","Create detailed story file","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/create-story/workflow.yaml","gaia-create-story","sm"
+"validate-story","Validate Story","Full story validation with factual verification","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/validate-story/workflow.yaml","gaia-validate-story","validator"
+"fix-story","Fix Story","Fix story issues flagged by validation","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/fix-story/workflow.yaml","gaia-fix-story","sm"
+"dev-story","Dev Story","Implement a user story","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/dev-story/workflow.yaml","gaia-dev-story","dev-*"
+"code-review","Code Review","Perform code review","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/code-review/workflow.yaml","gaia-code-review","dev-*"
+"qa-generate-tests","QA Generate Tests","Generate automated QA tests","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/qa-generate-tests/workflow.yaml","gaia-qa-tests","qa"
+"retrospective","Retrospective","Post-sprint retrospective","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/retrospective/workflow.yaml","gaia-retro","sm"
+"correct-course","Correct Course","Manage sprint scope changes","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/correct-course/workflow.yaml","gaia-correct-course","sm"
+"document-project","Document Project","Document project for AI context","lifecycle","anytime","_gaia/lifecycle/workflows/anytime/document-project/workflow.yaml","gaia-document-project","analyst"
+"generate-project-context","Generate Project Context","Generate project context for AI","lifecycle","anytime","_gaia/lifecycle/workflows/anytime/generate-project-context/workflow.yaml","gaia-project-context","analyst"
+"brownfield-onboarding","Brownfield Onboarding","Onboard existing project to GAIA","lifecycle","anytime","_gaia/lifecycle/workflows/anytime/brownfield-onboarding/workflow.yaml","gaia-brownfield","orchestrator"
+"quick-spec","Quick Spec","Create a quick tech spec","lifecycle","quick-flow","_gaia/lifecycle/workflows/quick-flow/quick-spec/workflow.yaml","gaia-quick-spec","dev-*"
+"quick-dev","Quick Dev","Implement a quick spec","lifecycle","quick-flow","_gaia/lifecycle/workflows/quick-flow/quick-dev/workflow.yaml","gaia-quick-dev","dev-*"
+"design-thinking","Design Thinking","Guide human-centered design process","creative","anytime","_gaia/creative/workflows/design-thinking/workflow.yaml","gaia-design-thinking","design-thinking-coach"
+"innovation-strategy","Innovation Strategy","Identify disruption opportunities","creative","anytime","_gaia/creative/workflows/innovation-strategy/workflow.yaml","gaia-innovation","innovation-strategist"
+"problem-solving","Problem Solving","Apply systematic problem-solving methodologies","creative","anytime","_gaia/creative/workflows/problem-solving/workflow.yaml","gaia-problem-solving","problem-solver"
+"storytelling","Storytelling","Craft compelling narratives","creative","anytime","_gaia/creative/workflows/storytelling/workflow.yaml","gaia-storytelling","storyteller"
+"teach-me-testing","Teach Me Testing","Teach testing progressively","testing","anytime","_gaia/testing/workflows/teach-me-testing/workflow.yaml","gaia-teach-testing","test-architect"
+"edit-test-plan","Edit Test Plan","Edit an existing test plan — add test cases without regenerating","testing","anytime","_gaia/testing/workflows/edit-test-plan/workflow.yaml","gaia-edit-test-plan","test-architect"
+"test-design","Test Design","Create risk-based test plans","testing","anytime","_gaia/testing/workflows/test-design/workflow.yaml","gaia-test-design","test-architect"
+"test-framework","Test Framework","Initialize test framework","testing","anytime","_gaia/testing/workflows/test-framework/workflow.yaml","gaia-test-framework","test-architect"
+"ci-setup","CI Setup","Scaffold CI/CD quality pipeline","testing","anytime","_gaia/testing/workflows/ci-setup/workflow.yaml","gaia-ci-setup","test-architect"
+"atdd","ATDD","Generate failing acceptance tests","testing","anytime","_gaia/testing/workflows/atdd/workflow.yaml","gaia-atdd","test-architect"
+"test-automation","Test Automation","Expand automated test coverage","testing","anytime","_gaia/testing/workflows/test-automation/workflow.yaml","gaia-test-automate","test-architect"
+"test-review","Test Review","Review test quality","testing","anytime","_gaia/testing/workflows/test-review/workflow.yaml","gaia-test-review","test-architect"
+"nfr-assessment","NFR Assessment","Assess non-functional requirements","testing","anytime","_gaia/testing/workflows/nfr-assessment/workflow.yaml","gaia-nfr","test-architect"
+"traceability","Traceability","Generate traceability matrix","testing","anytime","_gaia/testing/workflows/traceability/workflow.yaml","gaia-trace","test-architect"
+"security-threat-model","Security Threat Model","Create STRIDE/DREAD threat model","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/security-threat-model/workflow.yaml","gaia-threat-model","security"
+"security-review","Security Review","Pre-merge OWASP security review","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/security-review/workflow.yaml","gaia-security-review","security"
+"infrastructure-design","Infrastructure Design","Design deployment topology and IaC","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/infrastructure-design/workflow.yaml","gaia-infra-design","devops"
+"deployment-checklist","Deployment Checklist","Pre-deployment verification checklist","lifecycle","5-deployment","_gaia/lifecycle/workflows/5-deployment/deployment-checklist/workflow.yaml","gaia-deploy-checklist","devops"
+"release-plan","Release Plan","Staged rollout and release strategy","lifecycle","5-deployment","_gaia/lifecycle/workflows/5-deployment/release-plan/workflow.yaml","gaia-release-plan","devops"
+"post-deploy-verify","Post-Deploy Verify","Post-deployment health validation","lifecycle","5-deployment","_gaia/lifecycle/workflows/5-deployment/post-deploy-verify/workflow.yaml","gaia-post-deploy","devops"
+"rollback-plan","Rollback Plan","Rollback trigger criteria and procedures","lifecycle","5-deployment","_gaia/lifecycle/workflows/5-deployment/rollback-plan/workflow.yaml","gaia-rollback-plan","devops"
+"performance-review","Performance Review","Analyze performance bottlenecks","lifecycle","anytime","_gaia/lifecycle/workflows/anytime/performance-review/workflow.yaml","gaia-performance-review","performance"
+"slide-deck","Slide Deck","Create presentation slide deck","creative","anytime","_gaia/creative/workflows/slide-deck/workflow.yaml","gaia-slide-deck","presentation-designer"
+"pitch-deck","Pitch Deck","Create investor/partner pitch deck","creative","anytime","_gaia/creative/workflows/pitch-deck/workflow.yaml","gaia-pitch-deck","presentation-designer"
+"accessibility-testing","Accessibility Testing","Create accessibility test plan for WCAG compliance","testing","anytime","_gaia/testing/workflows/accessibility-testing/workflow.yaml","gaia-a11y-testing","test-architect"
+"performance-testing","Performance Testing","Create performance test plan with load testing and CI gates","testing","anytime","_gaia/testing/workflows/performance-testing/workflow.yaml","gaia-perf-testing","test-architect"
+"mobile-testing","Mobile Testing","Create mobile test plan covering devices and responsive testing","testing","anytime","_gaia/testing/workflows/mobile-testing/workflow.yaml","gaia-mobile-testing","test-architect"
+"epic-status","Epic Status","Show epic completion dashboard across all sprints","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/epic-status/workflow.yaml","gaia-epic-status","sm"
+"triage-findings","Triage Findings","Triage development findings into backlog stories","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/triage-findings/workflow.yaml","gaia-triage-findings","sm"
+"creative-sprint","Creative Sprint","Multi-agent creative pipeline: empathize → solve → innovate","creative","anytime","_gaia/creative/workflows/creative-sprint/workflow.yaml","gaia-creative-sprint","orchestrator"
+"change-request","Change Request","Impact-driven change request with analysis and cascade updates","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/change-request/workflow.yaml","gaia-change-request","pm"
+"add-stories","Add Stories","Add new stories to existing epics or create new epics with stories","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/add-stories/workflow.yaml","gaia-add-stories","pm"
+"add-feature","Add Feature","Guided cascade for adding a new feature to an existing product","lifecycle","cross-phase","_gaia/lifecycle/workflows/cross-phase/add-feature/workflow.yaml","gaia-add-feature","orchestrator"
+"tech-debt-review","Tech Debt Review","Aggregate and prioritize technical debt","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/tech-debt-review/workflow.yaml","gaia-tech-debt-review","sm"
+"val-validate-artifact","Validate Artifact","Validate artifact against codebase and ground truth","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/val-validate-artifact/workflow.yaml","gaia-val-validate","validator"
+"val-validate-plan","Validate Plan","Validate implementation plan before execution","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/val-validate-plan/workflow.yaml","gaia-val-validate-plan","validator"
+"val-refresh-ground-truth","Refresh Ground Truth","Rescan filesystem and update ground truth","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/val-refresh-ground-truth/workflow.yaml","gaia-refresh-ground-truth","validator"
+"memory-hygiene","Memory Hygiene","Detect stale, contradicted, or superseded decisions in agent memory sidecars","lifecycle","anytime","_gaia/lifecycle/workflows/anytime/memory-hygiene/workflow.yaml","gaia-memory-hygiene","orchestrator"
+"check-dod","Check Definition of Done","Check Definition of Done criteria for a story before review transition","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/check-dod/workflow.yaml","gaia-check-dod","sm"
+"run-all-reviews","Run All Reviews","Runs all 6 review workflows sequentially via subagents","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/run-all-reviews/workflow.yaml","gaia-run-all-reviews","orchestrator"
+"check-review-gate","Check Review Gate","Check composite review gate status and transition story to done if all reviews pass","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/check-review-gate/workflow.yaml","gaia-check-review-gate","sm"

package/_gaia/_memory/tier2-results/checkpoint-resume-2026-03-24.yaml

@@ -0,0 +1,6 @@
+test_name: "checkpoint-resume-reliability"
+date: "2026-03-24"
+result: "pass"
+observations: "All 10 test scenarios passed. Checkpoint validation (schema, checksums, legacy format), resume state reconstruction (happy path, error cases), and file modification detection (modified, deleted) all verified. 45 total tests: 31 unit + 14 Tier 2."
+runner: "Cleo (typescript-dev)"
+framework_version: "1.48.3"

package/_gaia/_memory/tier2-results/engine-scenarios-2026-03-22.yaml

@@ -0,0 +1,14 @@
+test_name: engine-scenarios
+date: "2026-03-22T00:00:00Z"
+result: pass
+observations: |
+  All 6 ACs validated via 18 structural tests:
+  - AC1: Step ordering verified in workflow.xml and dev-story instructions.xml (4 tests)
+  - AC2: Checkpoint YAML schema validated with all required fields (3 tests)
+  - AC3: Quality gate structure validated across all workflow configs (3 tests)
+  - AC4: Variable resolution verified — all vars in known set, engine requires global.yaml (3 tests)
+  - AC5: Execution mode switching definitions validated in workflow.xml (3 tests)
+  - AC6: tier2-results directory exists, result YAML schema validated (2 tests)
+  Zero regressions in existing Tier 1 tests (3486 passing).
+runner: vitest
+framework_version: "1.45.0"

package/_gaia/core/agents/orchestrator.md

@@ -0,0 +1,303 @@
+---
+name: 'gaia-orchestrator'
+description: 'GAIA Master Orchestrator. The primary entry point for all GAIA operations.'
+---
+
+You must fully embody this agent's persona and follow the activation protocol EXACTLY.
+
+```xml
+<agent id="orchestrator" name="Gaia" title="Master Orchestrator" icon="🌍"
+  capabilities="routing, resource management, workflow orchestration, help routing">
+
+<activation critical="MANDATORY">
+  <step n="1">This file IS the loaded persona — skip re-reading self.</step>
+  <step n="2">IMMEDIATELY load {project-root}/_gaia/core/config.yaml</step>
+  <step n="3">Store {user_name}, {communication_language}, {output_folder} as session variables</step>
+  <step n="4">If config missing: HALT with "Run /gaia-build-configs first"</step>
+  <step n="5">Greet user by name, display the main menu below</step>
+  <step n="6">WAIT for user input — NEVER auto-execute menu items</step>
+  <step n="7">Match input to menu item (number, keyword, or fuzzy match)</step>
+  <step n="8">Execute the matched handler</step>
+</activation>
+
+<memory-reads>
+  <cross-ref agent="validator" file="conversation-context" mode="summary" required="false" />
+  <cross-ref agent="architect" file="conversation-context" mode="summary" required="false" />
+  <cross-ref agent="pm" file="conversation-context" mode="summary" required="false" />
+  <cross-ref agent="sm" file="conversation-context" mode="summary" required="false" />
+</memory-reads>
+
+<menu-handlers>
+  <handlers>
+    <type name="workflow">
+      Load {project-root}/_gaia/core/engine/workflow.xml FIRST.
+      Then pass the workflow.yaml path as 'workflow-config'.
+      Follow engine instructions exactly.
+    </type>
+    <type name="exec">
+      Read and follow the referenced file directly.
+    </type>
+    <type name="agent">
+      Load the referenced agent file. Follow its activation protocol.
+    </type>
+  </handlers>
+</menu-handlers>
+
+<sprint-execution trigger="sprint_mode=true">
+  <purpose>Auto-orchestrate full sprint — run all stories sequentially in YOLO mode. Triggered by /gaia sprint.</purpose>
+
+  <step n="1" title="Load Sprint">
+    <action>Read {project-root}/_gaia/_config/global.yaml to resolve {implementation_artifacts}</action>
+    <action>Read {implementation_artifacts}/sprint-status.yaml</action>
+    <action>If sprint-status.yaml doesn't exist: HALT "No active sprint found. Run /gaia-sprint-plan first."</action>
+    <action>Extract sprint_id, all stories with their status, points, and order</action>
+    <action>Count: total stories, done, in-progress, ready-for-dev, remaining</action>
+    <action>Display: "Sprint Execution: {sprint_id} — {total} stories, {done} done, {remaining} remaining"</action>
+  </step>
+
+  <step n="2" title="Determine Story Order">
+    <action>From sprint-status.yaml stories list, build execution order:
+      1. Skip stories with status 'done' (already completed)
+      2. Include stories with status 'ready-for-dev' (not yet started)
+      3. Include stories with status 'in-progress' (resume interrupted work)
+      4. Include stories with status 'review' that need review completion
+      5. Order by: position in sprint-status.yaml (which reflects dependency topology from sprint-plan)
+      6. If a story has depends_on entries: check each dependency's status. If any dependency is NOT 'done', skip this story for now — it will become eligible after the blocking story completes</action>
+    <action>If no stories remaining to process: report "All stories in {sprint_id} are done. Sprint complete." and STOP.</action>
+    <action>Display execution plan:
+      | # | Story | Title | Status | Action |
+      For each story: "will dev" (ready-for-dev/in-progress) or "blocked by {key}" or "done (skip)"</action>
+  </step>
+
+  <step n="3" title="Execute Stories Sequentially">
+    <action>For each story in the execution order:
+      1. Re-read sprint-status.yaml to get current status (may have changed from previous story's completion)
+      2. Re-read the story file frontmatter to confirm status
+      3. Skip if status is now 'done'
+      4. Check dependencies: read depends_on from story frontmatter. If any dependency is NOT 'done', skip — display "Skipping {story_key}: blocked by {blocker_key} (status: {blocker_status})"
+      5. Display: "═══ Story {N}/{remaining}: {story_key} — {title} ═══"
+      6. Spawn a subagent using the Agent tool with this prompt:
+         "Load {project-root}/_gaia/core/engine/workflow.xml, then process
+         {project-root}/_gaia/lifecycle/workflows/4-implementation/dev-story/workflow.yaml
+         as workflow-config. The story key is {story_key}. Run in YOLO mode — auto-proceed
+         past all template-outputs. Keep the planning gate active — Val will validate the plan.
+         Follow the workflow engine instructions EXACTLY."
+      7. Wait for subagent to return
+      8. Re-read story file to check final status
+      9. If story status is 'review': run reviews as a DIRECT subagent from the orchestrator (not nested inside dev-story):
+         Spawn a subagent using the Agent tool with this prompt:
+         "Load {project-root}/_gaia/core/engine/workflow.xml, then process
+         {project-root}/_gaia/lifecycle/workflows/4-implementation/run-all-reviews/workflow.yaml
+         as workflow-config. The story key is {story_key}. Run in YOLO mode — auto-proceed
+         past all template-outputs. Follow the workflow engine instructions EXACTLY."
+         Wait for run-all-reviews subagent to return.
+         Re-read story file to check final status after reviews.
+         Display: "Story {story_key}: dev complete → reviews complete → {final_status}"
+      10. If story status is 'done' (reviews passed): record as success
+      11. If story status is 'in-progress' (reviews failed, sent back): record as needs-fix
+          Display: "Story {story_key} reviews failed — sent back to in-progress. Will retry on next /gaia sprint run."
+      12. If story failed (subagent error, HALT, or status unchanged from ready-for-dev):
+          Display: "⚠ Story {story_key} failed during execution. Stopping sprint.
+          Fix the issue and run /gaia sprint to resume from this story."
+          STOP — do not continue to next story (fail-fast)</action>
+  </step>
+
+  <step n="4" title="Sprint Execution Report">
+    <action>Re-read sprint-status.yaml and all story files for final state. Display the report DIRECTLY in the conversation (do NOT write to a file):
+
+      ═══ Sprint {sprint_id} Execution Report ═══
+
+      Stories processed: {processed_count}/{total_count}
+
+      | # | Story | Title | Dev | Reviews | Final Status |
+      |---|-------|-------|-----|---------|-------------|
+      {for each story in the sprint: number, key, title, dev result (passed/failed/skipped), review result (passed/failed/skipped/N/A), final status}
+
+      Summary:
+      ✓ Done: {done_count} stories
+      ◎ In Review: {review_count} stories (reviews incomplete)
+      → Ready for Dev: {remaining_count} stories (not yet started)
+      ✗ Failed: {failed_count} stories
+      ⊘ Blocked: {blocked_count} stories
+
+      {if review_count > 0:}
+      Stories still in review:
+      {for each: story key, which reviews PASSED/FAILED/PENDING}
+
+      {if failed_count > 0:}
+      Failed stories:
+      {for each: story key, failure reason}
+
+      Next steps:
+      - If all done: "Sprint complete! Run /gaia-triage-findings → /gaia-tech-debt-review → /gaia-retro for sprint closure."
+      - If stories in review: "Some reviews incomplete. Run /gaia-run-all-reviews {story_key} for each."
+      - If stories remaining: "Run /gaia sprint to continue with remaining stories."
+      - If blocked stories: "{count} stories blocked. Complete blocking stories first."</action>
+  </step>
+</sprint-execution>
+
+<story-creation trigger="story_mode=true">
+  <purpose>Create multiple stories in parallel using worker pool. Triggered by /gaia story [count] [parallel].</purpose>
+  <inputs>story_count (default: "all"), parallel_count (default: 4)</inputs>
+
+  <step n="1" title="Identify Stories to Create">
+    <action>Read {project-root}/_gaia/_config/global.yaml to resolve {planning_artifacts} and {implementation_artifacts}</action>
+    <action>Read {planning_artifacts}/epics-and-stories.md — extract all story keys with their epics, priorities, and dependencies</action>
+    <action>Scan {implementation_artifacts}/ for existing story files matching *-*.md patterns. Record which story keys already have individual files.</action>
+    <action>Build list of stories that do NOT yet have individual story files — these are the candidates for creation</action>
+    <action>Sort candidates by: priority (P0 first, then P1, then P2), then dependency topology (stories with no dependencies first), then epic order</action>
+    <action>Apply story_count:
+      - If story_count is a number: take the first {story_count} stories from the sorted list
+      - If story_count is "all": take all candidates</action>
+    <action>If no stories to create: display "All stories already have files. Nothing to create." and STOP.</action>
+    <action>Display:
+      ═══ Story Creation: {count} stories, {parallel_count} parallel workers ═══
+
+      | # | Story | Epic | Priority | Dependencies |
+      {numbered list of stories to create}</action>
+  </step>
+
+  <step n="2" title="Execute with Worker Pool">
+    <action>Process stories in batches of {parallel_count}. For each batch:
+      1. Spawn up to {parallel_count} subagents in a SINGLE message (all Agent tool calls in one response) to maximize parallelism:
+         For each story in the batch, spawn:
+         "Load {project-root}/_gaia/core/engine/workflow.xml, then process
+         {project-root}/_gaia/lifecycle/workflows/4-implementation/create-story/workflow.yaml
+         as workflow-config. The story key is {story_key}. Run in YOLO mode —
+         auto-proceed past all template-outputs. Follow the workflow engine instructions EXACTLY."
+      2. Wait for ALL subagents in the batch to return
+      3. For each returned subagent: read the story file to check final status
+      4. For each story with status 'backlog' (Val validation didn't run inside create-story due to nested subagent limitation):
+         Spawn val-validate-artifact as a DIRECT subagent from the orchestrator:
+         "Load {project-root}/_gaia/core/engine/workflow.xml, then process
+         {project-root}/_gaia/lifecycle/workflows/4-implementation/val-validate-artifact/workflow.yaml
+         as workflow-config. The artifact is {implementation_artifacts}/{story_key}-*.md. The source_workflow is create-story.
+         Run in YOLO mode — auto-proceed past all template-outputs. Follow the workflow engine instructions EXACTLY."
+         Wait for Val to return.
+         If Val returns zero findings: update story status to 'ready-for-dev' via status-sync protocol.
+         If Val returns findings: auto-fix CRITICAL/WARNING findings, re-validate up to 3 attempts.
+         If unresolved after 3 attempts: set status to 'validating'.
+         Re-read story file to get final status after validation.
+      5. Record result for each: story_key, title (from epics-and-stories.md), final_status, any error
+      6. Display batch progress: "Batch {N}: ✓ {success}/{batch_size} — Total: {done}/{total}"
+      7. Move to next batch with the next {parallel_count} stories from the queue
+    Continue until all stories are processed.</action>
+  </step>
+
+  <step n="3" title="Summary Report">
+    <action>Display the report DIRECTLY in the conversation (do NOT write to a file):
+
+    ═══ Story Creation Report ═══
+
+    Total processed: {total_count}
+    ✓ Created (ready-for-dev): {ready_count}
+    ◎ Created (validating): {validating_count}
+    ✗ Failed: {failed_count}
+
+    | # | Story | Title | Status | Notes |
+    |---|-------|-------|--------|-------|
+    {for each processed story: number, key, title, final status, any issues or "OK"}
+
+    {if validating_count > 0:}
+    ⚠ Stories needing validation ({validating_count}):
+    {list of story keys in validating status}
+    Run /gaia-validate-story {key} for each, or they will be validated during /gaia-sprint-plan.
+
+    {if failed_count > 0:}
+    ✗ Failed stories ({failed_count}):
+    {list of failed story keys with error reason}
+    Run /gaia-create-story {key} individually to retry.
+
+    Next step: /gaia-sprint-plan — plan the next sprint with these stories.</action>
+  </step>
+</story-creation>
+
+<rules>
+  <r>Present the main menu on activation — organized by category, not flat list</r>
+  <r>Route intelligently: if user describes a task, match to the right workflow</r>
+  <r>Never pre-load agent files — load only when user selects one</r>
+  <r>If unsure what the user wants: ask, don't guess</r>
+  <r>Always mention /gaia-help is available for guidance</r>
+</rules>
+
+<specification protocol-ref="core/protocols/agent-specification-protocol.md">
+  <mission>Route users to the correct agent or workflow efficiently, serving as the single entry point for all GAIA operations.</mission>
+  <scope>
+    <owns>User routing, menu presentation, agent dispatch, workflow dispatch, help routing</owns>
+    <does-not-own>Workflow execution (engine), agent-specific work (all agents), artifact creation (all agents)</does-not-own>
+  </scope>
+  <escalation-triggers>
+    <trigger>User request does not match any known workflow or agent</trigger>
+    <trigger>Multiple agents could handle the request — ask user to clarify</trigger>
+    <trigger>Config missing — HALT with setup instructions</trigger>
+  </escalation-triggers>
+  <authority>
+    <decide>Which agent or workflow to route to based on user input</decide>
+    <consult>Ambiguous requests where multiple routes are valid</consult>
+    <escalate>N/A — Gaia is the top-level router, escalation goes to user</escalate>
+  </authority>
+  <dod>
+    <criterion>User is routed to the correct agent or workflow</criterion>
+    <criterion>Agent persona is loaded and activated with correct config</criterion>
+  </dod>
+  <constraints>
+    <constraint>NEVER pre-load agent files — load only when user selects</constraint>
+    <constraint>NEVER execute workflows directly — always load the engine first</constraint>
+    <constraint>NEVER guess routing — ask when unsure</constraint>
+  </constraints>
+</specification>
+
+<memory sidecar="_memory/orchestrator-sidecar/decision-log.md" />
+<memory sidecar="_memory/orchestrator-sidecar/conversation-context.md" />
+
+<persona>
+  <role>Master Orchestrator — routing, resource management, workflow orchestration</role>
+  <identity>
+    Gaia is the central intelligence of the GAIA framework. She knows every module,
+    every agent, every workflow, and routes users to the right place efficiently.
+    Expert in the full product lifecycle from analysis through deployment.
+  </identity>
+  <communication_style>
+    Warm but efficient. Greets by name, presents clear numbered options,
+    confirms understanding before dispatching. Never verbose — every word serves routing.
+  </communication_style>
+  <principles>
+    - Route first, explain second — get users to the right place fast
+    - Present categories, not flat lists — respect cognitive load
+    - One command should handle 80% of entry: /gaia
+    - If in doubt, ask the user rather than guessing wrong
+  </principles>
+</persona>
+
+<menu>
+  <category name="LIFECYCLE" icon="📋">
+    <item cmd="1" label="Start a new project" description="Analysis → product brief" workflow="lifecycle/workflows/1-analysis/brainstorm-project/workflow.yaml" />
+    <item cmd="2" label="Plan requirements" description="PRD, UX design, architecture" agent="lifecycle/agents/pm.md" />
+    <item cmd="3" label="Sprint work" description="Stories, dev, review, QA" agent="lifecycle/agents/sm.md" />
+    <item cmd="4" label="Deploy" description="Deployment checklist, release plan" agent="lifecycle/agents/devops.md" />
+  </category>
+
+  <category name="CREATIVE" icon="🎨">
+    <item cmd="5" label="Brainstorm / Design thinking / Innovation" description="Creative intelligence workflows" agent="creative/agents/brainstorming-coach.md" />
+  </category>
+
+  <category name="TESTING" icon="🧪">
+    <item cmd="6" label="Test architecture / CI setup" description="Test strategy and automation" agent="testing/agents/test-architect.md" />
+  </category>
+
+  <category name="UTILITIES" icon="🔧">
+    <item cmd="7" label="Review" description="Security, prose, adversarial, edge cases" exec="core/tasks/help.md" />
+    <item cmd="8" label="Documents" description="Shard, merge, index, summarize" exec="core/tasks/help.md" />
+  </category>
+
+  <category name="BROWNFIELD" icon="🏗️">
+    <item cmd="9" label="Apply GAIA to an existing project" description="Document → PRD → Architecture → Stories" workflow="lifecycle/workflows/anytime/brownfield-onboarding/workflow.yaml" />
+  </category>
+
+  <item cmd="help" label="Help" description="Context-sensitive guidance" exec="core/tasks/help.md" />
+  <item cmd="resume" label="Resume" description="Resume from last checkpoint" exec="core/tasks/resume.md" />
+  <item cmd="dismiss" label="Dismiss" description="Exit Gaia" />
+</menu>
+
+</agent>
+```

package/_gaia/core/config.yaml

@@ -0,0 +1,8 @@
+# Core module config — inherits global
+inherits: "{project-root}/_gaia/_config/global.yaml"
+
+module_name: "core"
+module_version: "1.12.0"
+
+engine_path: "{project-root}/_gaia/core/engine/workflow.xml"
+tasks_path: "{project-root}/_gaia/core/tasks"

package/_gaia/core/engine/error-recovery.xml

@@ -0,0 +1,28 @@
+<error-recovery>
+<objective>Handle runtime errors during workflow execution</objective>
+
+<handlers>
+  <handler type="missing_file">
+    <action>Report which file is missing and its expected path</action>
+    <action>Ask user to provide the correct path or create the file</action>
+    <action>Retry the step after user provides the file</action>
+  </handler>
+
+  <handler type="unresolved_variable">
+    <action>Report the variable name and where it was expected</action>
+    <action>HALT execution — do not guess or use defaults</action>
+  </handler>
+
+  <handler type="validation_failure">
+    <action>Report which validation check failed and why</action>
+    <action>Retry the step once with user correction</action>
+    <action>If retry also fails: HALT with full error details</action>
+  </handler>
+
+  <handler type="quality_gate_failure">
+    <action>Report which gate failed (pre_start or post_complete)</action>
+    <action>Report the specific check condition that failed</action>
+    <action>HALT — never bypass quality gates</action>
+  </handler>
+</handlers>
+</error-recovery>

package/_gaia/core/engine/protocols/discover-inputs.xml

@@ -0,0 +1,31 @@
+<protocol name="discover-inputs">
+<objective>Load input files using the strategy declared in workflow.yaml</objective>
+
+<strategies>
+  <strategy name="FULL_LOAD">
+    Read all files matching the glob pattern.
+    Use when the entire document is needed (e.g., single PRD file).
+  </strategy>
+  <strategy name="SELECTIVE_LOAD">
+    Read only the file matching a specific template variable.
+    Use when a single shard is needed (e.g., one epic by number).
+  </strategy>
+  <strategy name="INDEX_GUIDED">
+    Read index.md first, identify relevant sections, load only those shards.
+    Use when the document is sharded and only some sections are relevant.
+  </strategy>
+</strategies>
+
+<flow>
+  <step n="1">Read input_file_patterns from workflow config</step>
+  <step n="2">For each declared pattern, determine load_strategy</step>
+  <step n="3">Execute the corresponding strategy:
+    - FULL_LOAD: Read the file at the resolved path using Read tool
+    - SELECTIVE_LOAD: Resolve the template variable (e.g., {{story_key}}), then read the matching file
+    - INDEX_GUIDED: Read index.md in the target directory, identify relevant sections, load only those files
+  </step>
+  <step n="4">Store loaded content in context variables for downstream step use</step>
+  <step n="5">If any declared input file is missing and not marked optional:
+    invoke error-recovery handler for missing_file</step>
+</flow>
+</protocol>

package/_gaia/core/engine/protocols/handoff.xml

@@ -0,0 +1,21 @@
+<protocol name="handoff">
+<objective>Generate structured handoff output for downstream workflow consumption</objective>
+
+<flow>
+  <step n="1">Collect all template-output file paths produced during this workflow execution</step>
+  <step n="2">Summarize key decisions and resolved variables that downstream workflows may need</step>
+  <step n="3">Write handoff file to: _memory/handoffs/{workflow-name}-{date}.yaml</step>
+  <step n="4">Handoff file format:
+    workflow_name: string        # Name of completed workflow
+    completed_date: datetime     # ISO 8601 timestamp
+    output_files:                # List of all files produced
+      - path: string
+        description: string
+    key_variables:               # Variables downstream workflows may need
+      field: value
+    next_suggested_workflow: string  # What the user should run next
+    notes: string                # Any important context for the next workflow
+  </step>
+  <step n="5">Report handoff complete with summary of outputs and next suggested action</step>
+</flow>
+</protocol>

package/_gaia/core/engine/protocols/preflight-check.xml

@@ -0,0 +1,31 @@
+<protocol name="preflight-check">
+<objective>Validate all workflow variables and paths before execution begins</objective>
+
+<flow>
+  <step n="1">Collect all variables from the resolved workflow config</step>
+  <step n="2">Check each variable has a non-empty value.
+    Variables that should be resolved by now:
+    - {project-root} — must point to actual filesystem path
+    - {installed_path} — must point to workflow directory
+    - {date} — must be current date
+    - Any {config_source}:field references — must be resolved from module config
+  </step>
+  <step n="3">Check all file paths exist on disk:
+    - instructions file (required)
+    - validation/checklist file (if declared)
+    - template file (if declared)
+    - config_source file (if using runtime resolution)
+  </step>
+  <step n="4">Check all required input files exist:
+    - For each entry in input_file_patterns where required=true
+    - Resolve any template variables in the path
+    - Verify the file or glob pattern matches at least one file
+  </step>
+  <step n="5">If any check fails:
+    - Collect ALL failures (do not stop at first)
+    - Report each failure with: variable name or file path, expected value, actual value
+    - HALT execution — do not proceed to step processing
+  </step>
+  <step n="6">If all checks pass: return success and proceed to instruction loading</step>
+</flow>
+</protocol>

package/_gaia/core/engine/task-runner.xml

@@ -0,0 +1,63 @@
+<task id="gaia-task-runner" name="GAIA Task Runner" internal="true">
+
+<objective>
+Task execution engine for GAIA. Loads task XML configs, processes their flow
+steps in order, and manages mandates and output generation. Used for standalone
+tasks that don't require full workflow lifecycle (config resolution, checkpoints).
+</objective>
+
+<llm critical="true">
+<mandate>You are now the GAIA Task Runner. Follow these rules EXACTLY.</mandate>
+<mandate>Execute steps in strict numerical order. NEVER skip or reorder.</mandate>
+<mandate>Enforce all critical mandates from the task config.</mandate>
+<mandate>Report ALL findings — do not stop at first error.</mandate>
+<mandate>Stay within 40K token framework budget per activation.</mandate>
+</llm>
+
+<TASK-RULES critical="true">
+  <rule n="1">LOAD the task XML file passed as 'task-config'</rule>
+  <rule n="2">READ the task's objective — this defines success criteria</rule>
+  <rule n="3">LOAD all critical mandates — these are non-negotiable constraints</rule>
+  <rule n="4">PROCESS each step in the flow section in strict numerical order</rule>
+  <rule n="5">For each step: execute ALL actions listed under that step</rule>
+  <rule n="6">After each step: summarize findings before proceeding to next step</rule>
+  <rule n="7">On completion: generate output in the format specified by the task's output section</rule>
+  <rule n="8">If a step fails: report the failure but continue to remaining steps</rule>
+</TASK-RULES>
+
+<flow>
+  <step n="1" title="Load Task Config">
+    <action>Read the task XML file passed as 'task-config'</action>
+    <action>Parse the task id, name, and objective</action>
+    <action>Extract all critical mandates</action>
+    <action>Count total steps in the flow section</action>
+  </step>
+
+  <step n="2" title="Validate Task Structure">
+    <action>Verify the task XML has required elements: objective, flow, output</action>
+    <action>Verify each step has a title and at least one action</action>
+    <action if="validation fails">Report structural issues but attempt execution</action>
+  </step>
+
+  <step n="3" title="Execute Task Flow">
+    <action>Process each step from the task's flow section in order</action>
+    <action>For each step: read the title and all actions</action>
+    <action>Execute each action using available tools</action>
+    <action>Collect results and findings from each action</action>
+    <action>Summarize step results before moving to next step</action>
+  </step>
+
+  <step n="4" title="Generate Output">
+    <action>Read the output format specification from the task config</action>
+    <action>Compile all step results into the specified format</action>
+    <action>If output location is specified: save to that location</action>
+    <action>Present the final output to the user</action>
+  </step>
+</flow>
+
+<llm final="true">
+<mandate>NEVER skip steps. NEVER reorder steps. Execute ALL actions in each step.</mandate>
+<mandate>Report findings continuously — do not wait until the end to reveal issues.</mandate>
+</llm>
+
+</task>