Configuration Schema

Complete reference for all SpecForge configuration files, environment variables, and schemas.

SpecForge uses three layers of configuration: global user settings, per-project settings, and MCP server configuration.

Configuration Precedence

When the same setting exists at multiple levels, the most specific value wins:


Environment variable     (highest)
    ↓
Project config           .specforge/config.json
    ↓
Global config            ~/.specforge/config.json
    ↓
Built-in defaults        (lowest)

✅ Run specforge configure without arguments to see the fully resolved configuration, showing which values come from which source.

Global Configuration

Location: ~/.specforge/config.json

Created by specforge login and managed with specforge configure. Applies to all projects unless overridden by project-level settings.


{
  "apiKey": "sf_live_your_key_here",
  "format": "text",
  "defaultProjectId": "proj_abc123"
}

Field	Type	Default	Description
`apiKey`	string	—	Your SpecForge API key. Set automatically by `specforge login`.
`format`	`"text"` \| `"json"`	`"text"`	Default output format for CLI commands.
`defaultProjectId`	string	—	Project ID used when no project context is available.

ℹ️ Global config is user-specific and should not be committed to version control. It’s stored in your home directory.

Project Configuration

Location: .specforge/config.json (relative to your repository root)

Created by specforge init. Contains project-specific settings that are typically committed to version control and shared with the team.


{
  "projectId": "proj_abc123",
  "specificationId": "spec_xyz789",
  "format": "text",
  "autoSetContext": true,
  "agentTeams": {
    "enabled": false,
    "strategy": "wave",
    "maxTicketsPerTeam": 3,
    "maxParallelEpics": 2,
    "branchPrefix": "specforge/"
  }
}

Field	Type	Default	Description
`projectId`	string	—	The SpecForge project this repository is linked to.
`specificationId`	string	—	The currently active specification.
`format`	`"text"` \| `"json"`	`"text"`	Output format override for this project.
`autoSetContext`	boolean	`true`	Automatically set project and specification context when running MCP tools.
`agentTeams`	object	—	Configuration for autonomous implementation with Agent Teams.

Agent Teams Configuration

The agentTeams object within project configuration controls how autonomous agent teams execute against your specification.


{
  "agentTeams": {
    "enabled": false,
    "strategy": "wave",
    "maxTicketsPerTeam": 3,
    "maxParallelEpics": 2,
    "branchPrefix": "specforge/"
  }
}

Field	Type	Default	Description
`enabled`	boolean	`false`	Whether Agent Teams mode is active for this project.
`strategy`	`"wave"` \| `"sequential"` \| `"priority"`	`"wave"`	How tickets are assigned to agent teams. `wave` processes dependency waves in parallel. `sequential` works one ticket at a time. `priority` assigns highest-priority tickets first.
`maxTicketsPerTeam`	number	`3`	Maximum simultaneous tickets a single agent team can work on.
`maxParallelEpics`	number	`2`	Maximum epics with active work sessions simultaneously.
`branchPrefix`	string	`"specforge/"`	Git branch prefix for agent-created branches. Each ticket gets a branch like `specforge/tkt-abc123`.

⚠️ Agent Teams requires a properly configured MCP server and sufficient API quota. Run specforge doctor to verify before enabling.

MCP Server Configuration

Location: .mcp.json (at your repository root)

Generated by specforge init or specforge scaffold. Tells your coding agent how to connect to the SpecForge MCP server.


{
  "mcpServers": {
    "specforge": {
      "command": "npx",
      "args": ["-y", "@specforge/cli", "mcp"],
      "env": {
        "SPECFORGE_API_KEY": "sf_live_your_key_here"
      }
    }
  }
}

The mcpServers object follows the standard MCP configuration format. The "specforge" key is the server name visible to your coding agent. The command and args fields start the SpecForge MCP server process.

✅ If you authenticated with specforge login, you can omit the env.SPECFORGE_API_KEY field. The MCP server reads credentials from your global config automatically.

Environment Variables

Variable	Description	Precedence
`SPECFORGE_API_KEY`	API key for authentication	Overrides `apiKey` in all config files

The environment variable has the highest precedence. When set, it overrides any API key configured in global or project config files. This is the recommended approach for CI/CD environments.


export SPECFORGE_API_KEY="sf_live_your_key_here"

Review Configuration

Quality gate settings (planning thresholds, implementation gates, evidence requirements) are configured at the project level through the dashboard or CLI.

For the complete ReviewConfig reference with all fields, defaults, and configuration profiles, see Quality Standards.

Quick access via CLI:


# View current review config
specforge configure reviewConfig
 
# Set values
specforge configure reviewConfig.readinessThreshold 85
specforge configure reviewConfig.gates.git_evidence false

Agent Configuration Files

Generated by specforge init or specforge scaffold. See Integrations for details on what each file contains and how agents use them.

File	Generated For	Purpose
`CLAUDE.md`	Claude Code	Project context anchor
`.claude/skills/`	Claude Code	Operational skills for MCP tool usage
`.claude/agents/`	Claude Code	Agent definitions for Agent Teams
`GEMINI.md`	Gemini CLI	Agent instructions
`AGENTS.md`	Codex CLI, OpenCode, others	Universal agent instructions
`.gemini/settings.json`	Gemini CLI	MCP configuration
`.codex/config.toml`	Codex CLI	MCP configuration
`opencode.json`	OpenCode	MCP configuration