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"
}

ℹ️ 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",
  "mcpOutputFormat": "toon",
  "autoSetContext": true,
  "agentTeams": {
    "enabled": false,
    "strategy": "auto",
    "maxTicketsPerTeam": 10,
    "maxParallelEpics": 3,
    "branchPrefix": "ticket/"
  }
}

Agent Teams Configuration

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

{
  "agentTeams": {
    "enabled": false,
    "strategy": "auto",
    "maxTicketsPerTeam": 10,
    "maxParallelEpics": 3,
    "branchPrefix": "ticket/"
  }
}

⚠️ 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

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"

Quality Standards Configuration

Quality gate settings — per-layer readiness thresholds and the implementation gates {acceptance, step, file, test} — are project-level validator settings, not configure keys (configure accepts only the five flat keys above). They are managed through the dashboard.

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

Agent Configuration Files

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

See Also

• Quality Standards — Full ReviewConfig reference with profiles
• CLI Commands — configure, init, scaffold commands
• Install CLI — First-time setup walkthrough