Planning

Planning commands produce the core documents that define what you are building and how. They cover Phases 2 (Planning) and 3 (Solutioning) of the GAIA lifecycle: PRDs, architecture documents, UX designs, threat models, infrastructure plans, and the epic/story breakdown.

Product requirements

• /gaia-create-prd user-facing Create a Product Requirements Document through collaborative discovery.
• /gaia-edit-prd user-facing Edit an existing PRD while preserving downstream consistency.
• /gaia-validate-prd deprecated Redirects to /gaia-val-validate. Kept for backward compatibility.

Architecture

• /gaia-create-arch user-facing Design system architecture covering technology selection, components, data layer, APIs, and security.
• /gaia-edit-arch user-facing Edit an existing architecture document with cascade-aware downstream detection.

UX design

• /gaia-create-ux user-facing Plan UX patterns, wireframes, interaction design, and accessibility specs.
• /gaia-edit-ux user-facing Edit an existing UX design while maintaining consistency with downstream artifacts.
• /gaia-validate-design-a11y user-facing Planning-phase accessibility review of design artifacts against WCAG 2.1 criteria.

Security and infrastructure

• /gaia-threat-model user-facing Create a STRIDE/DREAD threat model with asset identification, threat analysis, and mitigation strategies.
• /gaia-infra-design user-facing Design deployment topology, environment layout, infrastructure-as-code structure, and observability plan.

Work breakdown

• /gaia-create-epics user-facing Break requirements into epics and stories from your PRD and architecture documents.
• /gaia-readiness-check user-facing Validate that all planning artifacts are complete and consistent before starting implementation.
• /gaia-edit-test-plan user-facing Add new test cases to an existing test plan without regenerating it.
• /gaia-add-stories user-facing Add new stories to existing epics or create new epics with stories.

Artifact layout — where planning outputs live

Planning outputs are intentionally dispersed across four roots rather than consolidated under a single planning-artifacts/ tree. The dispersion is forced by the framework's existing gate and writer contracts — relocating any of these files would break the readiness and review gates until the underlying resolvers are refactored. The four roots:

• .gaia/artifacts/planning-artifacts/ — the bulk of planning outputs: prd.md, architecture.md, ux-design.md, epics-and-stories.md, readiness-report.md, dated NFR and performance-test-plan snapshots, adversarial reviews, brownfield scan reports.
• .gaia/artifacts/test-artifacts/ — test-plan.md, traceability-matrix.md, ci-setup.md, and dependency-audit-{date}.md. Pinned here by validate-gate.sh's test_plan_exists / traceability_exists / ci_setup_exists resolvers.
• .gaia/config/ — test-environment.yaml and the .example form (pinned by the config-layout contract).
• .gaia/state/ — sprint-status.yaml (the live runtime state; pinned by sprint-state.sh's writer contract).

Test-artifacts mirror absence. The test-lens review reports (qa-tests, test-automate-review, test-review) and the per-tier execution-evidence.json are written ONLY under implementation-artifacts/epic-*/{key}-*/reviews/, co-located with the code / security / performance reviews. The framework does not yet emit a symmetric test-artifacts/epic-*/{key}-*/ mirror, and execution evidence is a single execution-evidence.json rather than a per-tier split. The per-story resolver supports the mirror direction in code; consumers have not yet been retrofitted. Until that refactor lands, expect every test-lens artifact at the implementation-artifacts/…/reviews/ path only.