gaia-foundation

Use after the target solution is current to turn Gaia's approved design into an executable branch plan with dependencies, parallelism, QA checkpoints, release gates, and proof expectations. This role owns the shape of the work: branch boundaries, ordering, acceptance criteria, retry triggers, and the handoff package that makes implementation and validation predictable. Invoke it when architecture is ready but delivery still lacks sequencing; when implementation, testing, or release work need explicit gate criteria; or when downstream execution reveals new branches or dependencies that require re-planning. Do not use it to invent a target solution, code features, or approve release readiness. Its output should be an actionable plan that exposes both serial dependencies and safe parallel branches without hiding QA or proof requirements behind vague follow-up work.

Use for new requests, ambiguous follow-ups, workflow resets, or definition maintenance that touches multiple Gaia roles before there is a safe delivery owner. This role owns request framing, complexity classification, drift detection, the smallest-effective-role-set decision, and the first execution graph. Invoke it when the user goal, constraints, success signals, blockers, or ownership boundaries are still unclear; when the workflow is looping and needs a fresh routing decision; or when a repo-wide maintenance effort spans architecture, planning, agents, and skills. Do not use it for direct editing, code delivery, or final release decisions. Its output should be a crisp problem statement, explicit goals and non-goals, identified drift, the next owner, and a handoff package that makes downstream work executable.

Use for final gate evaluation, CI and deployment readiness, proof recording, and ready-or-not-ready decisions once implementation and validation are far enough along to judge closure. This role owns release-facing evidence, unresolved gate status, blocker ownership at the finish line, and the final interpretation of whether the work can be treated as complete. Invoke it when QA has produced a meaningful validation outcome, when CI or deployment gates must be interpreted, when proof needs to be gathered and recorded, or when a change needs a formal readiness call with rollback and follow-up concerns made explicit. Do not use it to author feature fixes, redesign the system, or hide unresolved blockers behind a "mostly ready" summary. Its output should be a precise ready or not-ready decision, the owning blocker when readiness fails, and the evidence that supports closure when readiness passes.

Use for planned implementation work, definition-file maintenance after the target solution is current, and fast stabilization before broader validation and release gating begin. This role owns code and configuration changes, localized cleanup needed to keep a branch coherent, and the implementation side of Gaia definition upkeep when the architecture and plan already explain what must change. Invoke it when a branch in the plan is ready for delivery; when agent, skill, or contract files need concrete edits against a current operating model; or when targeted stabilization is needed before formal QA. Do not use it to redefine architecture, publish the execution tree, or make the final release-ready decision. Its output should be implemented changes, concise stabilization notes, and a branch that testers and release reviewers can evaluate directly.

Use for changes that affect Gaia's target operating model, architectural boundaries, documented behavior, or high-level product story before planning and delivery proceed. This role owns `docs/architecture`, README alignment when the system story changes, and design decisions that tell downstream roles what is in or out of scope. Invoke it when the implemented behavior and the documented system have drifted apart, when a request changes system structure, interfaces, boundaries, workflows, or trust assumptions, or when planning and testing are blocked on missing design clarity. Do not use it for direct code delivery, release approval, or broad test execution. Its output should be a concrete architecture delta, explicit assumptions and invariants, and a clean handoff that makes planning and definition maintenance deterministic.

Use for formal validation, regression coverage, browser-assisted checks, and pass-fail-blocked decisions after a branch is stable enough to evaluate. This role owns test artifacts, validation outcomes, QA evidence, and the authority to veto weak completion claims. Invoke it when a planned branch needs formal verification; when high-risk behavior needs targeted early validation without waiting for full hardening; when browser flows, visual correctness, or integration boundaries need direct observation; or when release readiness depends on a clear QA signal. Do not use it to own feature delivery, redefine the target solution, or approve release gates in isolation. Its output should be explicit evidence, clear pass-fail-blocked routing, and actionable feedback that goes to the real failure owner instead of reflexively bouncing to the last role in the chain.

Provides Gaia architecture documentation guidance that keeps docs, README messaging, and design decisions aligned to the current operating model. Use it by updating the relevant files under /docs/architecture/ (system components, use cases, class diagrams, UI) before any planning or implementation that changes structure, then resolving doc↔code drift before resuming feature work. Use it when system structure, trust boundaries, interfaces, workflows, ownership, or architectural assumptions change, or when architecture drift blocks planning or delivery.

Provides Gaia's default full-stack baseline with React, TypeScript, Redux Toolkit, Tailwind CSS, and shadcn/ui on the frontend plus .NET, EF Core, PostgreSQL, and MCP exposure on the backend. Use it by adopting the documented baseline (versions, scaffolds, references) for any new app or unspecified-stack request, and by declaring the stack explicitly before planning when the request leaves it implicit. Use it when the request or repo leaves stack choice open, when bootstrapping a new application, or when standardizing an existing codebase onto Gaia's preferred platform.

Provides planned implementation delivery guidance that keeps a branch coherent, stabilized, and ready for testing without redefining the target solution. Use it by implementing the planned tasks against existing repo conventions, keeping diffs scoped, running lint/build locally, and updating tasks_update as work progresses. Use it when a current plan branch is ready for code or definition-file edits, when implementation-side cleanup is needed, or when targeted early QA support is useful during delivery.

Provides execution planning guidance that turns approved architecture into a branch-aware plan with dependencies, QA checkpoints, release gates, and proof expectations. Use it by translating the current architecture into MCP tasks (tasks_create) sequenced by branch, with explicit required_gates and blockers, then keeping the plan current as new work is discovered. Use it after architecture is current, when work needs explicit sequencing instead of informal next steps, or when new branches, blockers, or gate definitions require re-planning.

Provides Gaia's end-to-end workflow orchestration guidance for intake, routing, QA checkpoints, release gates, and proof expectations. Use it by routing every meaningful request through the intake → architecture → planning → engineering → testing → release sequence and only completing tasks once the corresponding gates and proof are recorded. Use it for meaningful requests, workflow resets after drift or blockers, and maintenance work that changes Gaia's operating model.

Provides Gaia skill-definition maintenance guidance with clear naming, descriptions, ownership boundaries, references, and reuse decisions. Use it by following the skills-specification reference (naming, frontmatter shape, scope sections, references) when adding or revising a SKILL.md, and by mirroring changes across both /skills/ and /.github/skills/ trees. Use it when adding, revising, auditing, or rationalizing skills, improving invocation quality, or consolidating drifting procedural guidance.

Provides Gaia's formal validation guidance across unit, integration, manual regression, automated regression, and evidence review. Use it by running the test layers required by each task's gates (unit → integration → e2e → manual regression), recording proof labels (e.g. 'curl', 'playwright-mcp') on tasks_complete, and vetoing completion when evidence is missing. Use it when a branch is stable enough for hardening, when high-risk behavior needs targeted early validation, or when release readiness depends on a clear QA signal.

Provides React UI implementation guidance that enforces the design system, shadcn/ui composition, semantic Tailwind tokens, and responsive layout discipline. Use it by composing shadcn/ui primitives with semantic Tailwind tokens (no raw color/spacing literals), respecting the responsive layout rules, and removing dead tokens as you go. Use it when building or refactoring user-facing React components, screens, forms, dialogs, or styling where UI consistency and token cleanup matter.

Provides Gaia custom-agent definition guidance with clear role boundaries, strong descriptions, valid tool scopes, delegation rules, and overlap control. Use it by following the agents-specification reference (frontmatter, role contract, tool allow-list, delegation rules) when adding or revising an agent file, and by mirroring changes across both /agents/ and /.github/agents/ trees. Use it when adding, revising, auditing, or rationalizing agent files, role ownership, naming, or contract alignment.