gaia-framework 1.58.0 → 1.58.2

package/.claude/commands/gaia-threat-model.md

@@ -0,0 +1,17 @@
+---
+name: 'threat-model'
+description: 'Create security threat model using STRIDE/DREAD. Use when "create threat model".'
+model: opus
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/lifecycle/workflows/3-solutioning/security-threat-model/workflow.yaml as 'workflow-config'
+4. Follow workflow.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-trace.md

@@ -0,0 +1,17 @@
+---
+name: 'trace'
+description: 'Generate requirements-to-tests traceability matrix. Use when "create traceability matrix".'
+model: sonnet
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/testing/workflows/traceability/workflow.yaml as 'workflow-config'
+4. Follow workflow.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-triage-findings.md

@@ -0,0 +1,20 @@
+---
+name: 'triage-findings'
+description: 'Triage development findings into backlog stories. Use when "triage findings".'
+model: sonnet
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. PARSE arguments from $ARGUMENTS:
+   - Check for "yolo" keyword (case-insensitive): if present, set yolo_mode=true
+2. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+3. READ its entire contents — this is the CORE OS
+4. Pass {project-root}/_gaia/lifecycle/workflows/4-implementation/triage-findings/workflow.yaml as 'workflow-config'
+5. If yolo_mode=true: tell the engine "Run in YOLO mode — auto-proceed past all template-outputs."
+6. Follow workflow.xml instructions EXACTLY
+7. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-val-validate-plan.md

@@ -0,0 +1,17 @@
+---
+name: 'val-validate-plan'
+description: 'Validate implementation plan before execution.'
+model: opus
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/lifecycle/workflows/4-implementation/val-validate-plan/workflow.yaml as 'workflow-config'
+4. Follow workflow.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-val-validate.md

@@ -0,0 +1,17 @@
+---
+name: 'val-validate'
+description: 'Validate an artifact against codebase and ground truth.'
+model: opus
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/lifecycle/workflows/4-implementation/val-validate-artifact/workflow.yaml as 'workflow-config'
+4. Follow workflow.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-validate-framework.md

@@ -0,0 +1,17 @@
+---
+name: 'validate-framework'
+description: 'Run GAIA framework self-validation. Use when "validate framework".'
+model: sonnet
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/task-runner.xml
+2. READ its entire contents — this is the TASK execution engine
+3. Pass {project-root}/_gaia/core/tasks/validate-framework.xml as 'task-config'
+4. Follow task-runner.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-validate-prd.md

@@ -0,0 +1,17 @@
+---
+name: 'validate-prd'
+description: 'Validate a PRD against standards. Use when "validate the PRD".'
+model: sonnet
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/lifecycle/workflows/2-planning/validate-prd/workflow.yaml as 'workflow-config'
+4. Follow workflow.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-validate-story.md

@@ -0,0 +1,22 @@
+---
+name: 'validate-story'
+description: 'Full story validation with factual verification. Use when "validate story".'
+model: opus
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. PARSE arguments from $ARGUMENTS:
+   - Extract story_key (optional): pattern like E1-S1, E2-S3, etc. (matching E\d+-S\d+)
+   - Check for "yolo" keyword (case-insensitive): if present, set yolo_mode=true
+2. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+3. READ its entire contents — this is the CORE OS
+4. Pass {project-root}/_gaia/lifecycle/workflows/4-implementation/validate-story/workflow.yaml as 'workflow-config'
+5. If story_key was extracted: pass story_key={extracted_story_key} as a resolved variable
+6. If yolo_mode=true: tell the engine "Run in YOLO mode — auto-proceed past all template-outputs."
+7. Follow workflow.xml instructions EXACTLY
+8. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia.md

@@ -0,0 +1,32 @@
+---
+name: 'gaia'
+description: 'Start GAIA orchestrator. The primary entry point for all GAIA operations.'
+model: opus
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. PARSE arguments from $ARGUMENTS:
+   - Check for "sprint" keyword (case-insensitive): if present, set sprint_mode=true
+   - Check for "story" keyword (case-insensitive): if present, set story_mode=true
+     - Extract optional number after "story" → story_count (default: "all")
+     - Extract optional second number → parallel_count (default: 4)
+     - Examples: "story" → all/4, "story 10" → 10/4, "story 10 2" → 10/2, "story all 6" → all/6
+   - Check for "action" keyword (case-insensitive): if present, set action_mode=true
+     - Check for "status" keyword after "action": if present, set action_status_only=true
+     - Check for "yolo" keyword: if present, set yolo_mode=true
+     - Extract action_id if present (pattern A-\d+): process only that item
+     - Examples: "action" → process all, "action status" → dashboard only, "action A-001" → single item, "action yolo" → auto-resolve
+2. LOAD the FULL {project-root}/_gaia/core/agents/orchestrator.md
+3. READ its entire contents — this is the GAIA orchestrator persona
+4. If sprint_mode=true: skip the main menu, execute the Sprint Execution Protocol defined in the <sprint-execution> block
+5. If story_mode=true: skip the main menu, execute the Story Creation Protocol defined in the <story-creation> block. Pass story_count and parallel_count.
+6. If action_mode=true: skip the main menu, load and execute the action-items workflow:
+   Load {project-root}/_gaia/core/engine/workflow.xml, then process
+   {project-root}/_gaia/lifecycle/workflows/4-implementation/action-items/workflow.yaml as workflow-config.
+   Pass action_status_only, action_id, and yolo_mode as resolved variables.
+7. If none of the above: follow the activation protocol defined in the <activation> block EXACTLY, display the main menu and WAIT for user input
+</steps>
+
+$ARGUMENTS

package/CLAUDE.md

@@ -0,0 +1,165 @@
+
+# GAIA Framework v1.58.2
+
+This project uses the **GAIA** (Generative Agile Intelligence Architecture) framework — an AI agent framework for Claude Code that orchestrates software product development through 26 specialized agents, 65 workflows, and 8 shared skills.
+
+## How to Start
+
+The primary entry point is `/gaia` — this activates the orchestrator (Gaia) who routes you to the right agent or workflow. You do not need to memorize all commands.
+
+**5 essential commands:**
+- `/gaia` — Start here. Gaia shows categories and routes you.
+- `/gaia-dev-story` — Implement a user story
+- `/gaia-quick-spec` — Rapid spec for small changes
+- `/gaia-quick-dev` — Rapid implementation of a quick spec
+- `/gaia-help` — Context-sensitive help
+
+## Responding to `/gaia-*` Commands
+
+When any `/gaia-*` command is invoked:
+1. Load `{project-root}/_gaia/core/engine/workflow.xml` — this is the execution engine
+2. The command file specifies a workflow.yaml or agent.md to process
+3. If a workflow: load the pre-resolved config from `{installed_path}/.resolved/` first; fall back to runtime resolution
+4. Follow the engine instructions EXACTLY — execute steps in order, save outputs at checkpoints
+5. Write a checkpoint to `_memory/checkpoints/` after each significant step
+
+## Framework Location
+
+```
+_gaia/                    # Framework root
+├── core/                 # Engine, protocols, shared tasks
+├── lifecycle/            # Product lifecycle (5 phases: analysis → deployment)
+├── dev/                  # Developer agents (6 stacks) + shared skills (8)
+├── creative/             # Creative intelligence workflows
+├── testing/              # Test architecture + knowledge base
+├── _config/              # Global config, manifests
+│   └── global.yaml       # Shared settings — single source of truth
+└── _memory/              # Persistent agent memory + checkpoints
+```
+
+**Artifact outputs:**
+- `docs/planning-artifacts/` — PRDs, UX, architecture, epics
+- `docs/implementation-artifacts/` — Sprint status, stories, changelogs
+- `docs/test-artifacts/` — Test plans, traceability
+- `docs/creative-artifacts/` — Design thinking, innovation outputs
+
+## Project Path
+
+GAIA supports separating the framework from the application source code. The `project_path` setting in `global.yaml` controls where application code lives:
+
+- `project_path: "."` (default) — project code lives at the root alongside `_gaia/`. This is backward compatible.
+- `project_path: "my-app"` — project code lives in a subdirectory. GAIA framework stays at root, code goes in `my-app/`.
+
+**Resolved variables:**
+- `{project-root}` — always the root directory where `_gaia/` lives. Used for framework paths, docs, and artifacts.
+- `{project-path}` — where application source code lives. Equals `{project-root}` if project_path is `"."`, otherwise `{project-root}/{project_path}`.
+
+**Rules:**
+- NEVER replace `{project-path}/_gaia/` with symlinks to `{project-root}/_gaia/` — they are different things
+- NEVER delete files from `{project-path}/_gaia/` thinking they are "stale copies" — they are the product
+- Dev agents MUST write application code to `{project-path}`, not `{project-root}`
+- Brownfield onboarding scans `{project-path}` for codebase discovery
+- Framework artifacts (docs/, _gaia/) always stay at `{project-root}`
+- Commands like `npm install`, `git`, test runners use `{project-path}` as working directory
+
+## Global Rules (apply to ALL agents and workflows)
+
+### Config Resolution
+1. Check for pre-resolved config in `{installed_path}/.resolved/{workflow}.yaml`
+2. If not found: load `workflow.yaml` → module `config.yaml` (which inherits `global.yaml`)
+3. Resolve `{project-root}`, `{project-path}`, `{installed_path}`, system-generated values
+4. After any config change, run `/gaia-build-configs` to regenerate resolved configs
+
+### Context Budget
+- **40K token max** for framework content per activation
+- Never pre-load skills or knowledge fragments — load JIT when a step references them
+- Use sectioned skill loading when only a subset of a skill is needed
+- Release prior step content before loading the next step
+- Agent persona files: max 400 lines
+- Instruction step files: max 150 lines each
+- Skill files: max 500 lines (or load individual sections at ~50 lines each)
+
+### Step Execution
+- Execute ALL steps in exact order — no skipping, no reordering
+- Read the ENTIRE step file before acting on it
+- Save output at every `<template-output>` checkpoint
+- In normal mode: WAIT for user confirmation at template-outputs
+- In YOLO mode: auto-proceed (user can toggle back to normal with "switch to normal mode")
+- In planning mode: present execution plan BEFORE processing steps; wait for user approval; user selects normal or yolo for runtime
+
+### Checkpoint Discipline
+- Write a checkpoint to `_memory/checkpoints/` after each step completes
+- Include: workflow name, step number, key variables, output file path
+- Include `files_touched` with sha256 checksums (`shasum -a 256`) for every file created/modified during the workflow
+- On resume: validate checksums — warn user of changed files, offer Proceed / Start fresh / Review
+- If context is lost, `/gaia-resume` recovers from the last checkpoint
+
+### Quality Gates
+- Gates are **enforced**, not advisory — workflow HALTS on gate failure
+- Pre-start gates must pass before workflow execution begins
+- Post-complete gates must pass before marking a workflow done
+- Never mark a task complete without all tests passing
+
+**Testing integration gates (enforced):**
+- `create-epics-stories` requires `test-plan.md` — run `/gaia-test-design` after architecture
+- `implementation-readiness` requires `traceability-matrix.md` + `ci-setup.md` — run `/gaia-trace` + `/gaia-ci-setup`
+- `dev-story` requires `atdd-{story_key}.md` for high-risk stories — run `/gaia-atdd`
+- `deployment-checklist` requires traceability + CI + readiness report PASS
+- `brownfield-onboarding` requires NFR assessment + performance test plan (output to `test-artifacts/`)
+
+### Sprint-Status Write Safety
+- **Story file is source of truth** — sprint-status.yaml is a derived/cached view
+- **All status transitions** MUST use the `status-sync` protocol (`_gaia/core/protocols/status-sync.xml`) — this updates both the story file and sprint-status.yaml atomically
+- **Review workflows (6)** update only the Review Gate table — the `review-gate-check` protocol handles the `review → done` transition via status-sync
+- Running `/gaia-sprint-status` reconciles sprint-status.yaml with story files (catches any remaining drift)
+
+## Naming Conventions
+
+- Slash commands: `gaia-{action}` for workflows, `gaia-agent-{name}` for agents
+- Workflow dirs: `{phase}/{workflow-name}/`
+- Workflow files: `workflow.yaml` + `instructions.xml` + `checklist.md` + optional `template.md`
+- Agent files: `{agent-id}.md` with XML `<agent>` block
+- Skill files: `{skill-name}.md` in `_gaia/dev/skills/`
+- Knowledge fragments: `{topic}.md` in `_gaia/{module}/knowledge/{category}/`
+- Story files: `{story_key}-{story_title_slug}.md` (e.g., `E1-S1-user-login.md`) — canonical name set by `/gaia-create-story`
+- Story file lookups use glob `{story_key}-*.md` to match regardless of slug
+
+## Developer Agent System
+
+- 6 specialized developers extend `_gaia/dev/agents/_base-dev.md`
+- Stack agents: angular (Lena), typescript (Cleo), flutter (Freya), java (Hugo), python (Ravi), mobile (Talia)
+- 8 shared skills: git-workflow, api-design, database-design, docker-workflow, testing-patterns, code-review-standards, documentation-standards, security-basics
+- Skills use sectioned loading — only the sections needed by the current step are loaded
+
+## Sprint State Machine
+
+```
+backlog → validating → ready-for-dev → in-progress → invalid → review → done
+```
+
+**Review Gate:** A story in `review` requires ALL six reviews to pass before moving to `done`:
+- `/gaia-code-review` — APPROVE or REQUEST_CHANGES
+- `/gaia-qa-tests` — PASSED or FAILED
+- `/gaia-security-review` — PASSED or FAILED
+- `/gaia-test-automate` — PASSED or FAILED
+- `/gaia-test-review` — PASSED or FAILED
+- `/gaia-review-perf` — PASSED or FAILED
+
+Run `/gaia-run-all-reviews` to execute all six reviews sequentially via subagents — one command instead of six.
+
+If any review fails, the story returns to `in-progress`. The Review Gate table in the story file tracks progress.
+
+## Memory Hygiene
+
+Agent memory sidecars accumulate decisions across sessions. Run `/gaia-memory-hygiene` periodically (recommended before each sprint) to detect stale, contradicted, or orphaned entries by cross-referencing sidecar decisions against current planning and architecture artifacts.
+
+## Do Not
+
+- Pre-load files — load at runtime when needed
+- Skip steps in a workflow — execute ALL steps in order
+- Proceed past a template-output without user confirmation (unless YOLO mode)
+- Modify files outside the workflow's declared output locations
+- Commit secrets, credentials, or .env files
+- Create agent files over 400 lines — delegate depth to skills and knowledge fragments
+- Chase config inheritance chains at runtime — use pre-resolved configs
+- Load more than 40K tokens of framework content in a single activation

package/README.md

@@ -1,6 +1,6 @@
 # GAIA — Generative Agile Intelligence Architecture
 
-[![Framework](https://img.shields.io/badge/framework-v1.54.0-blue)]()
+[![Framework](https://img.shields.io/badge/framework-v1.57.1-blue)]()
 [![License](https://img.shields.io/badge/license-AGPL--3.0-green)]()
 [![Agents](https://img.shields.io/badge/agents-26-purple)]()
 [![Workflows](https://img.shields.io/badge/workflows-73-orange)]()
@@ -43,7 +43,7 @@ GAIA is built on a few core beliefs about how AI-assisted development should wor
 ## Prerequisites
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (requires Anthropic account)
-- Node.js 18+
+- Node.js 20+
 - Git
 
 ---
@@ -460,7 +460,7 @@ The single source of truth is `_gaia/_config/global.yaml`:
 
 ```yaml
 framework_name: "GAIA"
-framework_version: "1.58.0"
+framework_version: "1.58.2"
 user_name: "your-name"
 project_name: "your-project"
 ```

package/_gaia/_config/agent-manifest.csv

@@ -0,0 +1,29 @@
+name,displayName,title,icon,module,path
+"orchestrator","Gaia","Master Orchestrator","🌍","core","_gaia/core/agents/orchestrator.md"
+"analyst","Elena","Strategic Business Analyst","📊","lifecycle","_gaia/lifecycle/agents/analyst.md"
+"pm","Derek","Product Manager","📋","lifecycle","_gaia/lifecycle/agents/pm.md"
+"architect","Theo","System Architect","🏗️","lifecycle","_gaia/lifecycle/agents/architect.md"
+"ux-designer","Christy","UX Designer","🎨","lifecycle","_gaia/lifecycle/agents/ux-designer.md"
+"sm","Nate","Scrum Master","🏃","lifecycle","_gaia/lifecycle/agents/sm.md"
+"qa","Vera","QA Engineer","🧪","lifecycle","_gaia/lifecycle/agents/qa.md"
+"tech-writer","Iris","Technical Writer","📚","lifecycle","_gaia/lifecycle/agents/tech-writer.md"
+"_base-dev","(abstract)","Base Developer","💻","dev","_gaia/dev/agents/_base-dev.md"
+"typescript-dev","Cleo","TypeScript Developer","💻","dev","_gaia/dev/agents/typescript-dev.md"
+"angular-dev","Lena","Angular Developer","💻","dev","_gaia/dev/agents/angular-dev.md"
+"flutter-dev","Freya","Flutter Developer","💻","dev","_gaia/dev/agents/flutter-dev.md"
+"java-dev","Hugo","Java Developer","💻","dev","_gaia/dev/agents/java-dev.md"
+"python-dev","Ravi","Python Developer","💻","dev","_gaia/dev/agents/python-dev.md"
+"mobile-dev","Talia","Mobile Developer","📱","dev","_gaia/dev/agents/mobile-dev.md"
+"go-dev","Kai","Go Developer","💻","dev","_gaia/dev/agents/go-dev.md"
+"brainstorming-coach","Rex","Brainstorming Facilitator","🧠","creative","_gaia/creative/agents/brainstorming-coach.md"
+"problem-solver","Nova","Problem-Solving Expert","🔬","creative","_gaia/creative/agents/problem-solver.md"
+"design-thinking-coach","Lyra","Design Thinking Expert","🎨","creative","_gaia/creative/agents/design-thinking-coach.md"
+"innovation-strategist","Orion","Innovation Strategist","⚡","creative","_gaia/creative/agents/innovation-strategist.md"
+"storyteller","Elara","Master Storyteller","📖","creative","_gaia/creative/agents/storyteller.md"
+"presentation-designer","Vermeer","Presentation Designer","🎨","creative","_gaia/creative/agents/presentation-designer.md"
+"test-architect","Sable","Master Test Architect","🧪","testing","_gaia/testing/agents/test-architect.md"
+"security","Zara","Application Security Expert","🔒","lifecycle","_gaia/lifecycle/agents/security.md"
+"devops","Soren","DevOps/SRE Engineer","🚀","lifecycle","_gaia/lifecycle/agents/devops.md"
+"data-engineer","Milo","Data Pipeline Architect","📊","lifecycle","_gaia/lifecycle/agents/data-engineer.md"
+"performance","Juno","Performance Specialist","⚡","lifecycle","_gaia/lifecycle/agents/performance.md"
+"validator","Val","Artifact Validator","🔍","lifecycle","_gaia/lifecycle/agents/validator.md"

package/_gaia/_config/agents/CUSTOMIZATION-README.md

@@ -0,0 +1,117 @@
+# Agent Customization
+
+Place `{agent-id}.customize.yaml` files here to override agent defaults.
+
+## Scope Files
+
+- `{agent-id}.customize.yaml` — applies to one specific agent
+- `all-dev.customize.yaml` — applies to all 6 dev agents (angular-dev, typescript-dev, flutter-dev, java-dev, python-dev, mobile-dev)
+
+**Precedence:** agent-specific > all-dev > default. If both `flutter-dev.customize.yaml` and `all-dev.customize.yaml` define the same key, the agent-specific value wins.
+
+These files are loaded AFTER the agent's base `.md` file and merged at runtime.
+
+## Available Override Keys
+
+- `persona_overrides` — Modify persona fields (communication_style, principles, etc.)
+- `menu_additions` — Add extra menu items
+- `menu_removals` — Remove menu items by cmd number
+- `skill_additions` — Add extra skills to the agent's skill set (accepts `{name, path}` objects for custom skills)
+- `rule_additions` — Add extra rules
+- `skill_overrides` — Replace an entire skill file with a custom one (dev agents only)
+- `skill_section_overrides` — Replace specific sections within a skill (dev agents only)
+
+> **Note:** `skill_overrides` and `skill_section_overrides` apply only to dev agents (agents that extend `_base-dev.md`). Other agents use knowledge fragments, which are not currently overridable via this mechanism.
+
+## Examples
+
+### Persona Override
+
+`architect.customize.yaml`:
+
+```yaml
+persona_overrides:
+  communication_style: "More detailed, include architecture diagrams"
+  additional_principles:
+    - "Always consider serverless-first"
+```
+
+### Adding a Custom Skill to a Developer
+
+`flutter-dev.customize.yaml`:
+
+```yaml
+skill_additions:
+  - name: "aws-patterns"
+    path: "{project-root}/custom/skills/aws-patterns.md"
+```
+
+This gives Freya (flutter-dev) access to a custom `aws-patterns` skill. The `path` points to a file in the user-owned `custom/skills/` directory, which survives framework updates.
+
+### Full Skill Override
+
+Replace the entire `git-workflow` skill with a custom version for all dev agents:
+
+`all-dev.customize.yaml`:
+
+```yaml
+skill_overrides:
+  git-workflow:
+    source: "{project-root}/custom/skills/git-workflow.md"
+```
+
+When any dev agent loads `git-workflow`, it reads from the custom path instead of `_gaia/dev/skills/git-workflow.md`. The custom file must use the same `<!-- SECTION: name -->` delimiter format as framework skills.
+
+A relative path (no `{project-root}` prefix) is resolved against `custom_skills_path` from `dev/config.yaml`:
+
+```yaml
+skill_overrides:
+  git-workflow:
+    source: "git-workflow.md"  # resolves to {project-root}/custom/skills/git-workflow.md
+```
+
+### Section Override
+
+Replace only the `branching` and `commits` sections of `git-workflow`, keeping `pull-requests` and `conflict-resolution` from the default:
+
+`all-dev.customize.yaml`:
+
+```yaml
+skill_section_overrides:
+  git-workflow:
+    branching: "{project-root}/custom/skills/git-branching.md"
+    commits: "{project-root}/custom/skills/git-commits.md"
+```
+
+Relative paths also resolve against `custom_skills_path`.
+
+### Override for One Agent Only
+
+Give Hugo (java-dev) a different database-design skill while all other devs keep the default:
+
+`java-dev.customize.yaml`:
+
+```yaml
+skill_overrides:
+  database-design:
+    source: "{project-root}/custom/skills/database-design-postgres.md"
+```
+
+## Override Resolution Order
+
+When the engine JIT-loads a skill or skill section, it checks in this order:
+
+1. Active agent's `{agent-id}.customize.yaml` — `skill_overrides` then `skill_section_overrides`
+2. `all-dev.customize.yaml` (for dev agents only) — same check
+3. Default path from `<skill-registry>` in `_base-dev.md`
+
+When loading from an override path, the engine scans the file for `<!-- SECTION: xxx -->` markers dynamically instead of using `_skill-index.yaml` cached line ranges.
+
+## Custom Skills Directory
+
+Custom skill files should be placed in `custom/skills/` at the project root (outside `_gaia/`). This directory:
+
+- Survives framework updates (`gaia-install.sh update` only touches `_gaia/` contents)
+- Should be committed to version control
+- Files must use the same `<!-- SECTION: name -->` delimiter format as framework skills
+- Is referenced by `custom_skills_path` in `_gaia/dev/config.yaml`

package/_gaia/_config/files-manifest.csv

@@ -0,0 +1,30 @@
+path,type,module,description
+"_gaia/_config/global.yaml","config","core","Global framework configuration"
+"_gaia/core/config.yaml","config","core","Core module configuration"
+"_gaia/lifecycle/config.yaml","config","lifecycle","Lifecycle module configuration"
+"_gaia/dev/config.yaml","config","dev","Developer module configuration"
+"_gaia/creative/config.yaml","config","creative","Creative module configuration"
+"_gaia/testing/config.yaml","config","testing","Testing module configuration"
+"_gaia/core/engine/workflow.xml","engine","core","Workflow execution engine"
+"_gaia/core/engine/protocols/discover-inputs.xml","protocol","core","Input file discovery protocol"
+"_gaia/core/engine/protocols/preflight-check.xml","protocol","core","Pre-execution validation protocol"
+"_gaia/core/engine/protocols/handoff.xml","protocol","core","Workflow handoff protocol"
+"_gaia/core/engine/error-recovery.xml","engine","core","Error recovery handlers"
+"_gaia/core/agents/orchestrator.md","agent","core","Master orchestrator agent"
+"_gaia/core/tasks/help.md","task","core","Context-sensitive help routing"
+"_gaia/core/tasks/index-docs.xml","task","core","Document index generator"
+"_gaia/core/tasks/shard-doc.xml","task","core","Document sharding task"
+"_gaia/core/tasks/editorial-review-prose.xml","task","core","Prose editorial review"
+"_gaia/core/tasks/editorial-review-structure.xml","task","core","Structural editorial review"
+"_gaia/core/tasks/review-adversarial.xml","task","core","Adversarial review task"
+"_gaia/core/tasks/review-edge-case-hunter.xml","task","core","Edge case hunter task"
+"_gaia/core/tasks/review-security.xml","task","core","OWASP-focused security review"
+"_gaia/core/tasks/review-api-design.xml","task","core","REST API design review"
+"_gaia/core/tasks/review-dependency-audit.xml","task","core","Dependency vulnerability audit"
+"_gaia/core/tasks/review-accessibility.xml","task","core","WCAG 2.1 accessibility review"
+"_gaia/core/tasks/review-performance.xml","task","core","Performance issue review"
+"_gaia/core/tasks/merge-docs.xml","task","core","Merge multiple markdown files"
+"_gaia/core/tasks/generate-changelog.xml","task","core","Generate changelog from git history"
+"_gaia/core/tasks/summarize-doc.xml","task","core","Generate executive summary"
+"_gaia/core/tasks/validate-framework.xml","task","core","Framework self-validation"
+"_gaia/core/engine/task-runner.xml","engine","core","Task execution engine"