Schema de Configuração

Referência completa de todos os arquivos de configuração, variáveis de ambiente e schemas do SpecForge.

O SpecForge usa três camadas de configuração: configurações globais de usuário, configurações por projeto e configuração do servidor MCP.

Precedência de Configuração

Quando a mesma configuração existe em múltiplos níveis, o valor mais específico vence:

Variável de ambiente     (mais alta)
    ↓
Config do projeto        .specforge/config.json
    ↓
Config global            ~/.specforge/config.json
    ↓
Padrões embutidos        (mais baixa)

✅ Execute specforge configure sem argumentos para ver a configuração totalmente resolvida, mostrando quais valores vêm de qual fonte.

Configuração Global

Localização: ~/.specforge/config.json

Criada por specforge login e gerenciada com specforge configure. Aplica-se a todos os projetos a menos que sobrescrita por configurações de nível de projeto.

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

ℹ️ A configuração global é específica do usuário e não deve ser commitada no controle de versão. Ela é armazenada no seu diretório home.

Configuração do Projeto

Localização: .specforge/config.json (relativo à raiz do seu repositório)

Criada por specforge init. Contém configurações específicas do projeto que tipicamente são commitadas no controle de versão e compartilhadas com a equipe.

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

Configuração de Agent Teams

O objeto agentTeams dentro da configuração do projeto controla como equipes autônomas de agentes executam contra sua especificação.

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

⚠️ Agent Teams requer um servidor MCP propriamente configurado e quota de API suficiente. Execute specforge doctor para verificar antes de habilitar.

Configuração do Servidor MCP

Localização: .mcp.json (na raiz do seu repositório)

Gerado por specforge init ou specforge scaffold. Diz ao seu agente de código como se conectar ao servidor MCP do SpecForge.

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

O objeto mcpServers segue o formato padrão de configuração MCP. A chave "specforge" é o nome do servidor visível para seu agente de código. Os campos command e args iniciam o processo do servidor MCP do SpecForge.

✅ Se você autenticou com specforge login, pode omitir o campo env.SPECFORGE_API_KEY. O servidor MCP lê credenciais da sua configuração global automaticamente.

Variáveis de Ambiente

A variável de ambiente tem a precedência mais alta. Quando definida, sobrescreve qualquer chave de API configurada em arquivos de configuração global ou de projeto. Esta é a abordagem recomendada para ambientes de CI/CD.

export SPECFORGE_API_KEY="sf_live_your_key_here"

Configuração de Review

Configurações de gates de qualidade (limites de planejamento, gates de implementação, requisitos de evidência) são configuradas no nível do projeto pelo painel ou pela CLI.

Para a referência completa de ReviewConfig com todos os campos, padrões e perfis de configuração, veja Padrões de Qualidade.

Acesso rápido via CLI:

# Ver configuração de review atual
specforge configure reviewConfig
 
# Definir valores
specforge configure reviewConfig.readinessThreshold 85
specforge configure reviewConfig.gates.git_evidence false

Arquivos de Configuração de Agente

Gerados por specforge init ou specforge scaffold. Veja Integrações para detalhes sobre o que cada arquivo contém e como agentes os usam.

Veja Também

• Padrões de Qualidade — Referência completa de ReviewConfig com perfis
• Comandos CLI — Comandos configure, init, scaffold
• Instalar CLI — Walkthrough de setup inicial