/gaia-init

user-facing

Category:: Getting Started
Lifecycle phase:: Any (greenfield setup)
Arguments:: [project-path]

What it does

/gaia-init bootstraps a brand-new project for GAIA. It walks you through a guided questionnaire -- project name, shape (single backend, microservices, mobile, etc.), tech stacks, compliance regimes, environments, and CI platform -- then generates a .gaia/config/project-config.yaml and a starter CI workflow file. No manual YAML authoring required.

When to use it

You are starting a new project from scratch (greenfield) and want GAIA to set up the configuration for you.
You want a guided experience instead of manually writing project-config.yaml.

If your project already has a .gaia/config/project-config.yaml, this command will refuse to run. Use /gaia-config-show to inspect the existing config, or /gaia-brownfield to onboard an existing codebase.

Prerequisites

No existing config. The project directory must not already contain .gaia/config/project-config.yaml. If it does, the command stops and directs you to the appropriate alternative.
GAIA plugin installed. The GAIA plugin must be registered in your Claude Code environment.

Orchestration mode

When /gaia-init starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:


────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-init skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at _memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

Caveat. The one-shot contract depends on CLAUDE_SESSION_ID being exported. Without it, the marker falls back to the orchestrator PID, so each fresh shell becomes a new "session" from the dedupe's point of view and the warning re-fires on every command invocation. Operators who see repeat warnings on every command should export CLAUDE_SESSION_ID (any stable per-session value).

How to invoke

/gaia-init

Runs in the current directory.

/gaia-init ./my-project

Runs against a specific project path.

What it does step by step

Greenfield guard Checks that no .gaia/config/project-config.yaml exists. If it does, the command stops immediately and suggests /gaia-config-show or /gaia-brownfield.
Discovery questionnaire Asks you a series of questions in order:
1. Project name
2. Project shape -- single backend, microservices, mobile only, mobile + backend, microservices + mobile, or Claude Code plugin
3. Stacks -- for each service: name, language, and file paths (iterative -- add as many as needed)
4. Compliance regimes -- optional: GDPR, HIPAA, PCI-DSS, SOX, CCPA, SOC2, ISO 27001, WCAG 2.1 AA/AAA
5. UI present? -- determines whether accessibility reviews are enabled
6. Environments -- name, URL, auth type, and credential env var name for each (optional)
7. CI/CD platform -- GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure Pipelines, Bitbucket Pipelines, or none
For mobile projects, additional follow-ups collect iOS/Android device targets (OS versions, form factors, screen sizes).
Validate answers Checks that your platform and stack choices are consistent (for example, declaring iOS without an iOS-capable stack is rejected). You can fix any issues before proceeding.
Generate config Writes .gaia/config/project-config.yaml from your answers. The file is validated against the configuration schema immediately after creation.
Generate CI scaffold If you selected a CI platform, writes a CI workflow file (for example, .github/workflows/ci.yml for GitHub Actions) plus a companion *.user-steps.yml file where you can add custom steps -- this companion file is preserved if you re-generate the CI scaffold later.
Next steps Shows the files that were created and suggests what to do next.

Security note

When asked about environment credentials, provide only the name of the environment variable (for example, STAGING_TOKEN), never the actual secret value. Set the real credentials in your CI provider's secret store.

Inputs

Input	Source	Description
`project-path`	Command argument (optional)	Path to the project directory. Defaults to the current working directory.
Questionnaire answers	Interactive prompts	Project name, shape, stacks, compliance, environments, CI platform.

Outputs

A successful /gaia-init run writes the following files. Most live under .gaia/ (the canonical GAIA runtime tree). Three files live at the repository root because their consumers (GitHub Actions, git) read from fixed locations.

Output	Location	Description
Project configuration	`.gaia/config/project-config.yaml`	The main GAIA configuration file for your project (canonical location).
Test-environment manifest template	`.gaia/config/test-environment.yaml.example`	Template you copy + edit to `test-environment.yaml` when you enable the Test Execution Bridge via `/gaia-bridge-enable`.
CI workflow	`.github/workflows/<name>.yml` at repo root	Starter CI pipeline matching your selected platform. Lives at repo root because GitHub Actions reads from `.github/` only.
CI user-steps companion	Same directory as CI workflow, `<name>.user-steps.yml`	A file for your custom CI steps, preserved across `/gaia-config-ci --regenerate` runs.
Git ignore seed	`.gitignore` at repo root	Seeds a default `.gitignore` (macOS `.DS_Store`, editor temp files, IDE config, build outputs) on a fresh project that doesn't have one. Lives at repo root because git reads from there only. Skipped if a `.gitignore` already exists.

Carve-out (files written outside .gaia/): .github/workflows/*.yml, .github/workflows/*.user-steps.yml, and .gitignore. These three are required at the repo root by GitHub Actions and git respectively — there is no way to relocate them under .gaia/. Every other GAIA artifact stays inside .gaia/.

Example session

> /gaia-init

Checking for existing configuration... none found. Proceeding.

1. Project name?
> TaskFlow

2. Project shape?
   (1) single backend  (2) microservices  (3) mobile only
   (4) mobile+backend  (5) microservices+mobile  (6) claude-code-plugin
> 1

3. Define your stack:
   Stack name?
> api
   Language?
> node
   Paths?
> src/
   Add another stack? (y/n)
> n

4. Compliance regimes? (comma-separated, or skip)
> gdpr, wcag-2.1-aa

5. UI present? (y/n)
> y

6. Environments (name, URL, auth, credential var name -- or skip):
> staging, https://staging.taskflow.io, bearer, STAGING_TOKEN
   Add another? (y/n)
> n

7. CI/CD platform?
   (1) github-actions  (2) gitlab-ci  (3) circleci
   (4) jenkins  (5) azure-pipelines  (6) bitbucket-pipelines  (7) none
> 1

Validating configuration... PASS.

Generated:
  - .gaia/config/project-config.yaml
  - .github/workflows/ci.yml
  - .github/workflows/ci.user-steps.yml

Reminders:
  - Set STAGING_TOKEN in GitHub Actions Secrets.
  - Re-running /gaia-init on this directory will refuse -- use
    /gaia-config-show to inspect or /gaia-brownfield to onboard.

Next steps:
  - Run /gaia-product-brief to define product vision.
  - Or run /gaia-brownfield if the codebase already exists.

What to run next

/gaia-product-brief -- define your product vision, users, and scope.
/gaia-brainstorm -- if you want to explore the idea before writing a brief.
/gaia-brownfield -- if the codebase already exists and you want GAIA to scan it.

Troubleshooting

".gaia/config/project-config.yaml already exists"

This command only runs on directories with no existing config. Use /gaia-config-show to view your current configuration, or the /gaia-config-* commands to edit specific sections.

"Platform/stack mismatch"

You declared a platform (for example, iOS) but did not add a stack with a compatible language (Swift, Objective-C, React Native, or Flutter). Either add the missing stack or remove the platform declaration.

"Schema validation failed"

The generated config did not pass schema validation. The error message will identify the invalid field. Correct the value when re-prompted and the config will be regenerated.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
.gaia/config/project-config.yaml contains:
```
orchestration:
  mode: team
```

If either is missing the framework silently uses Mode A and re-emits the warning each session.

Related commands

Command	Relationship
`/gaia-brownfield`	Alternative for existing codebases -- scans the code and generates config + artifacts.
`/gaia-config-show`	View the configuration this command creates.
`/gaia-config-validate`	Validate the generated config against the schema.
`/gaia-product-brief`	The typical next step after initializing a project.