/gaia-edit-arch

What it does

/gaia-edit-arch makes targeted edits to an existing architecture document. Edits are surgical -- unchanged sections are preserved. Every significant decision is recorded as a new ADR with auto-incremented ID. After editing, the command assesses cascade impact on downstream artifacts (epics, stories, test plan, infrastructure design).

When to use it

• You need to update the architecture after a PRD change, technical discovery, or adversarial review finding.
• You want GAIA to detect downstream cascade impact from the architecture change.

Prerequisites

• Architecture must exist at .gaia/artifacts/planning-artifacts/architecture.md.

Orchestration mode

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

What it does step by step

1. Load architecture Reads the current document and displays: section headers, ADR count, current version.
2. Capture change scope Asks what sections need to change, what the change is, why, and whether linked to a change request. Classifies scope: MINOR, SIGNIFICANT, or BREAKING.
3. Apply edits Applies changes section by section with your confirmation. Unchanged sections are preserved exactly.
4. Record ADRs Creates new ADR entries with auto-incremented IDs. Supersedes old ADRs when applicable.
5. Version and save Adds a version note and writes the updated document.
6. Adversarial review If triggered by the change type, runs an adversarial review.
7. Cascade assessment Checks impact on epics, stories, test plan, infrastructure design, and traceability matrix. Reports impact level and recommended next commands.

Inputs

Outputs

Example session

> /gaia-edit-arch

Current architecture: v1.0, 7 ADRs, 12 sections.

What sections need to change?
> API design -- add GraphQL endpoint alongside REST

Change scope: SIGNIFICANT (new API surface)

Applying edits...
  Updated: API Design section
  New ADR: ADR-8 (GraphQL API alongside REST)
  Version: v1.1

Cascade assessment:
  epics-and-stories.md: SIGNIFICANT -- new stories needed
  test-plan.md: MINOR -- add GraphQL test scenarios
  Recommended: /gaia-add-stories, then /gaia-edit-test-plan

What to run next

• /gaia-add-stories -- add stories for the new architecture scope.
• /gaia-edit-test-plan -- update test plan for architecture changes.

Troubleshooting

"No architecture document found"

Run /gaia-create-arch first.

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