/gaia-add-feature

What it does

/gaia-add-feature triages and routes a new feature, enhancement, or patch through only the affected artifacts. It classifies the change scope (patch, enhancement, or feature) and cascades updates through the PRD, architecture, epics, test plan, threat model, and traceability matrix as needed. Each cascade step is validated before proceeding.

When to use it

• You want to add a new capability, fix a bug, or enhance an existing feature.
• A change request needs to be routed through the planning artifacts.
• You are unsure which artifacts need updating -- this command figures it out for you.

Prerequisites

• Planning artifacts should exist. The PRD, architecture, and epics-and-stories documents provide context for classification and cascade.

Orchestration mode

When /gaia-add-feature 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. See the orchestration contract for details.

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

Why Mode B is better for this command

The /gaia-add-feature 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-add-feature

The command asks for a description of the change interactively.

What it does step by step

1. Capture scope Asks for the change description, urgency, driver (user request, bug, tech debt, opportunity), and optional change request ID. Classifies as patch, enhancement, or feature.
2. Validation gate Validates the intake against the codebase. Halts on critical findings.
3. Execute cascade Updates only the artifacts affected by the classification: patches touch nothing downstream; enhancements update epics, test plan, and traceability; features cascade through all artifacts including PRD, architecture, and threat model.
4. Create stories For enhancements and features, creates new stories in the relevant epics.
5. Emit assessment document Writes an audit trail documenting the classification, cascade, and validation results.

Inputs

Outputs

Example session

> /gaia-add-feature

Describe the change: Add webhook retry with exponential backoff.
Urgency: medium
Driver: user-request
Change request: none

Classification: enhancement
  Scope: story-level change. Cascades to epics + test plan + traceability.
  PRD and architecture: not touched.

Validation: PASS (0 critical findings).

Cascade:
  Epics: E5 updated with new story E5-S18.
  Test plan: 2 new test cases added.
  Traceability: regenerated.

Assessment written to .gaia/artifacts/planning-artifacts/assessment-{feature_id}.md.

Next: run /gaia-create-story E5-S18 to elaborate, then /gaia-sprint-plan.

What to run next

• /gaia-create-story -- elaborate the new stories.
• /gaia-sprint-plan or /gaia-correct-course -- include the work in a sprint.

Troubleshooting

"CRITICAL validation finding"

The validation gate found a critical issue with the change proposal. Resolve the finding and re-invoke.

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