Glossary

GAIA uses terms from agile development, testing, and its own framework conventions. This glossary defines the most common terms you will encounter in this documentation and in GAIA's output.

ADR (Architecture Decision Record): A short document that captures one architecture decision, its context, the options considered, and the rationale for the chosen option. GAIA records ADRs in the architecture document and references them by number throughout planning and implementation artifacts.
Adapter (tool adapter): A small plugin module that connects GAIA to a specific external tool. Examples include the Playwright adapter for E2E tests, the k6 adapter for load tests, the OWASP ZAP adapter for DAST scans, and the Firebase Test Lab adapter for mobile device testing. Built-in adapters live under plugins/gaia/scripts/adapters/; project-local adapters go in custom/adapters/ (which take precedence over built-in adapters of the same name). View available adapters with /gaia-list-tools and inspect a specific adapter with /gaia-tool-info.
Band: A single summary line rendered above the Claude Code prompt by the sprint status mod. It shows sprint progress at a glance and switches to a warning variant when ACTION NEEDED items are present. The band is absent when no sprint is active. Toggle the sidebar from the band by pressing the digit 9 on an empty prompt.
Blocker: A demonstrated failure, or a credible unresolved risk, to required behaviour, security, data integrity, supported platforms, reliability, or an agreed performance limit. Only blockers cause a review gate to fail. Everything else is non-blocking and goes to triage with an owner and a priority. The shared findings rubric defines the blocker criteria used by all review skills.
ATDD (Acceptance Test-Driven Development): A testing methodology where acceptance tests are written before implementation, directly from a story's acceptance criteria. In GAIA, /gaia-atdd generates failing Given/When/Then test skeletons that the developer makes pass during implementation. High-risk stories require ATDD before /gaia-dev-story can proceed.
Artifact: A document that GAIA creates or reads during a workflow. Artifacts are stored in subdirectories of .gaia/artifacts/: planning artifacts (PRD, architecture, UX design, test plan, test strategy, traceability matrix) go in .gaia/artifacts/planning-artifacts/, implementation artifacts (sprint plans, story files) in .gaia/artifacts/implementation-artifacts/, test artifacts (ci-setup.md and test reports) in .gaia/artifacts/test-artifacts/, and creative artifacts (brainstorms, design thinking outputs) in .gaia/artifacts/creative-artifacts/.
Claude Design: The framework's sole design surface. Claude Design hosts two project types: a design-system project (tokens and components, accessed through DesignSync) and a product design project (screens and flows, accessed through the Artifact tool as a Design-type artifact). The integration is checked for availability before the first call in any design-touching skill. See the design lifecycle overview.
Concurrent Sprints: Multiple sprints active simultaneously, each in its own session, with per-sprint state files and session binding. When enabled (sprint.max_concurrent_active > 1 in .gaia/config/project-config.yaml), each session binds to one sprint and operates on its own sprint-status file. A cross-session resource ledger coordinates dev-slot budgets and promotion-chain merges across sessions. Single-sprint mode (the default, max_concurrent_active: 1) is byte-identical to the original single-sprint behavior. Concurrent sprints and phase-parallel execution are orthogonal features that can be used independently or together: concurrent sprints run separate sprints in separate sessions, while phase-parallel execution runs stories within one sprint concurrently.
Design Gate: A prerequisite that blocks phase-three entry points (/gaia-dev-story, /gaia-create-arch, /gaia-readiness-check, /gaia-adversarial, /gaia-threat-model, and others) until the design record is in the approved state. Projects without a UI (compliance.ui_present: false or absent) skip the gate. An audited override (--force-design --reason "<text>") is available; the reason is sanitised (control characters are neutralised) and the override entry records the sprint scope.
Design Record: The YAML state machine at .gaia/state/design-record.yaml that tracks the design's approval lifecycle. It moves through draft → review → approved → stale (stale loops back to review after changes). All writes go through a sole writer script; no skill writes the file directly. The record references both the design-system project and the product design project, and carries an append-only audit trail with a hash chain.
Design-system Project: The Claude Design project that holds design tokens (colours, spacing, typography) and component specifications. Accessed through DesignSync (create_project, finalize_plan, write_files). When the stack does not include React, the project is built as a brand-style artifact (fonts, colours, guidelines) instead of a compiled component bundle.
Edge types (knowledge layer): The seven typed relationships the GAIA Brain knowledge index recognizes between artifacts: implements, governed-by, decomposes, verified-by, reviewed-in, traces-to, and designs. Each edge is directional (UP, DOWN, or LATERAL) and is harvested deterministically from frontmatter, the epics registry, and the traceability matrix at index time. See the GAIA Brain edge-types table for definitions.
Epic: A large body of work that can be broken down into multiple stories. Epics are defined in .gaia/artifacts/planning-artifacts/epics-and-stories.md and identified by keys like E3, E15. An epic groups related stories that together deliver a significant capability.
Findings register: A per-story YAML file that holds every review finding from all review gates in one place. Each finding has a unique ID, a severity, a blocking status, and a disposition. The register is the single source of truth for the verdict rule: a gate is failed only when an unresolved blocker exists in the register. The register writer is the sole sanctioned writer; the verdict resolver reads it to compute the verdict.
Fork Context: An isolated execution environment used by some GAIA commands (particularly reviews and validations). When a command runs in fork context, it cannot modify files in the main workspace -- it can only read and report. This prevents review commands from accidentally changing your code.
FR (Functional Requirement): A requirement that describes specific behavior or functionality the system must support. FRs are defined in the PRD and traced through architecture, stories, and tests. Referenced in GAIA artifacts by identifiers like FR-001.
GAIA Brain (knowledge layer): A read-only knowledge layer that turns a project's artifacts into a queryable governance graph. It lives at .gaia/knowledge/ as an Obsidian-native Markdown vault with brain-index.yaml as the single-source-of-truth manifest and brain-index.md as a human-readable Map of Content. Retrieval uses grep, tags, and the manifest only -- no vectors, no embeddings, no external service. Six commands expose the Brain: /gaia-brain-reindex, /gaia-brain-query, /gaia-brain-health, /gaia-feed, /gaia-knowledge-refresh, and /gaia-unfeed. See the GAIA Brain concept page.
Gate: A checkpoint in a workflow where progress is blocked until a condition is met. GAIA uses gates at several points: the planning gate pauses /gaia-dev-story for plan approval, the ATDD gate blocks high-risk stories without acceptance tests, and the Review Gate blocks the done transition until all reviews pass. See also Review Gate.
Lifecycle Phase: One of the five ordered stages of GAIA's delivery process: (1) Analysis, (2) Planning, (3) Solutioning, (4) Implementation, (5) Deployment. Each phase has its own set of commands and artifacts. See the lifecycle diagram on the home page.
Governance envelope: The complete set of artifacts related to a story, grouped into three directions: UP (requirements, architecture decisions, parent epic), DOWN (tests, reviews), and LATERAL (UX and design companions). Returned by /gaia-brain-query in a single read-only call. See the GAIA Brain concept page.
Ground Truth: A snapshot of your project's actual filesystem state -- which files exist, their locations, and key metadata. The validator compares claims in your artifacts against ground truth to detect stale references, missing files, or incorrect paths. Refreshed by /gaia-refresh-ground-truth.
Map of Content (MOC): A human-readable Markdown file (.gaia/knowledge/brain-index.md) rendered from the GAIA Brain manifest on every reindex sweep. Entries are grouped by artifact type with wikilinks, synopses, tags, and edge summaries. Browse it in Obsidian or any Markdown viewer to navigate the knowledge layer. The MOC is a derived convenience -- the YAML manifest is the authority.
NFR (Non-Functional Requirement): A requirement that describes quality attributes rather than specific behavior: performance targets, scalability limits, reliability SLAs, security standards. NFRs are assessed by /gaia-nfr.
Phase-Parallel Execution: Concurrent execution of stories within a single sprint's dependency phase, capped at the configured dev-slot budget (parallel_execution.max_parallel_dev_slots in .gaia/config/project-config.yaml). When enabled (GAIA_PARALLEL_EXECUTION=1), /gaia-run-sprint develops the stories of one phase concurrently, each in its own worktree, with a barrier before the next phase. The orchestrator falls back to one story at a time whenever concurrency is unavailable. Phase-parallel execution and concurrent sprints are orthogonal features that can be used independently or together: phase-parallel execution runs stories within one sprint concurrently, while concurrent sprints run separate sprints in separate sessions.
Product Design Project: The Claude Design project that holds screen specifications and user flows. It is a Design-type artifact accessed through the Artifact tool. Screens carry the full resolved token block, so a token change in the design-system project also refreshes the product design project's screens. Created or bound during /gaia-create-ux and reviewed during /gaia-design-review.
Promotion chain: An ordered list of branches or environments that a change moves through before reaching production -- for example, feature -> develop -> staging -> main. Configured under ci_cd.promotion_chain in .gaia/config/project-config.yaml. Used by /gaia-dev-story (to decide which branch a PR targets), /gaia-deploy (to determine deployment order), and CI gates (to enforce that changes pass checks at each stage before advancing). The chain itself is unaffected by worktree mode: a story branch is prefixed feat/ and, when worktree mode is enabled, lives in that story's own linked worktree, but it enters the promotion chain at the same point either way.
Red / Green / Refactor (TDD): The three phases of Test-Driven Development (TDD) used by /gaia-dev-story. Red: write tests that fail because the implementation does not exist yet. Green: write the minimum code to make those tests pass. Refactor: improve the code quality while keeping all tests green.
Review Gate: A table in a story file that tracks the status of six review types: Code Review, QA Tests, Security Review, Test Automation, Test Review, and Performance Review. Each row starts as UNVERIFIED and is updated to PASSED or FAILED when the corresponding review command runs. A story cannot transition to done status until all Review Gate rows are PASSED. Checked by /gaia-check-review-gate.
Rubric: A JSON or YAML file that defines the criteria and thresholds used by review commands to evaluate code, tests, or artifacts. GAIA uses a four-layer rubric pipeline (base, compliance, project, custom) that merges into a single effective rubric at runtime. Configured in .gaia/config/project-config.yaml under the rubrics section. Severity mapping and per-gate overrides are managed with /gaia-config-severity and /gaia-config-gates.
Sidecar (Memory Sidecar): A per-agent memory file stored in .gaia/memory/ that persists decisions, context, and session state across conversations. Each GAIA agent (pm, architect, dev, test-architect, validator, etc.) has its own sidecar. The /gaia-memory-hygiene command detects stale or contradicted entries in sidecars.
Sidebar (Sprint Status): A pane rendered by the sprint status mod showing detailed sprint progress: an ACTION NEEDED banner, aggregate stats, a segmented bar, the NOW block with active stories, a phase matrix, and selected-story detail. Toggle with /sprint, the digit 9 on an empty prompt, or the band button. Claude Code decides the placement: sidebar on the right in a wide fullscreen terminal, inline above the prompt otherwise.
Sprint: A time-boxed work iteration containing a set of stories selected from the backlog. Sprints are planned with /gaia-sprint-plan and tracked in .gaia/state/sprint-status.yaml. Each sprint has an ID (e.g., sprint-3), a velocity target, and a set of committed stories.
sprint-status.yaml: The file at .gaia/state/sprint-status.yaml that records the current sprint's state: which stories are committed, their statuses, and aggregate metrics. This file is managed exclusively through GAIA commands (never edited by hand). Viewed with /gaia-sprint-status.
Story: A unit of work small enough to complete in a single sprint. Each story has its own Markdown file under .gaia/artifacts/implementation-artifacts/ with YAML frontmatter (status, risk, dependencies, etc.) and sections for acceptance criteria, subtasks, Definition of Done, and findings. Identified by keys like E3-S7 (Epic 3, Story 7).
Story Status: The lifecycle state of a story. The progression is: backlog (not yet planned) -> ready-for-dev (planned into a sprint, story file created) -> in-progress (being implemented) -> review (implementation done, reviews pending) -> done (all reviews passed). Additional states: validating (being validated by Val) and blocked. Status changes are managed by GAIA commands and should never be edited by hand.
Test Execution Bridge: The integration layer that lets GAIA dispatch test suites to external test runners such as Playwright, k6, or OWASP ZAP. When enabled, GAIA executes real tests through adapters and reports pass/fail verdicts. When disabled, GAIA produces test plans and acceptance criteria but does not execute tests against your code. Toggle the bridge with /gaia-bridge-enable and /gaia-bridge-disable. Configured in .gaia/config/project-config.yaml under test_execution_bridge.bridge_enabled.
YOLO Mode: An optional mode that automatically confirms prompts and runs validation loops without pausing for user approval. When YOLO mode is active, commands like /gaia-dev-story auto-approve the implementation plan, auto-run validation loops, and auto-fire all reviews after implementation. YOLO mode never auto-answers genuine open questions or skips critical safety halts.