/gaia-create-arch

What it does

/gaia-create-arch designs the system architecture from your PRD. It covers technology selection, system component design, data architecture, API design, infrastructure planning, security architecture, and records every significant decision as an Architecture Decision Record (ADR). Supports both greenfield and brownfield modes.

When to use it

• Your PRD is complete (including adversarial review) and you are ready to design the technical architecture.

Prerequisites

• PRD must exist at .gaia/artifacts/planning-artifacts/prd.md with a "Review Findings Incorporated" section.
• UX design, brownfield assessment, and threat model are optional but improve quality when present.

Orchestration mode

When /gaia-create-arch 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-create-arch 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.

How to invoke

/gaia-create-arch

What it does step by step

1. Load upstream artifacts Indexes the PRD, UX design, brownfield assessment, and threat model (if they exist).
2. Detect mode Checks for "Mode: Brownfield" in the PRD header. Brownfield mode documents existing decisions; greenfield mode starts fresh.
3. Technology selection Selects the tech stack with rationale. In brownfield mode, discovers the existing stack. Presents the recommendation for your confirmation -- you can approve, modify, or reject.
4. System design Defines components, service boundaries, and communication patterns with Mermaid diagrams.
5. Data architecture Defines data models, storage strategy, and data flow.
6. API design Defines API contracts, versioning, and error handling.
7. Security architecture Defines authentication, authorization, and data protection strategies. Incorporates threat model findings when available.
8. Generate architecture Writes the full architecture document with all ADRs recorded inline.
9. Adversarial review Runs an adversarial review and incorporates critical findings.
10. Validation Quality checks and auto-fixes.

Inputs

Outputs

Example session

> /gaia-create-arch

Loading PRD... 22 FRs, 8 NFRs found.
Mode: greenfield.

Technology recommendation:
  Runtime: Node.js 20 (LTS)
  Framework: NestJS
  Database: PostgreSQL 16
  Cache: Redis 7
  Queue: BullMQ

Approve, modify, or reject? [a/m/r]
> a

Designing system components...
Designing data architecture...
Designing API contracts...
Designing security architecture...

Architecture written to: .gaia/artifacts/planning-artifacts/architecture.md
  7 ADRs recorded, 4 component diagrams

What to run next

• /gaia-threat-model -- security threat model from the architecture.
• /gaia-infra-design -- infrastructure design from the architecture.
• /gaia-create-epics -- break PRD + architecture into epics and stories.

Troubleshooting

"PRD review findings not found"

The PRD needs a "Review Findings Incorporated" section. This is added automatically by /gaia-create-prd during its adversarial review step. Re-run that command.

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