Configuration Reference

SuperSpec is configured through the superspec.config.json file. This document covers all configuration options in detail.

Configuration File Location

The configuration file is located in the project root:

your-project/
└── superspec.config.json

Complete Configuration Example

{
  "lang": "en",
  "aiEditor": "cursor",
  "specDir": "superspec",
  "branchPrefix": "",
  "branchTemplate": "{prefix}{intentType}-{date}-{feature}-{user}",
  "changeNameTemplate": "{prefix}{intentType}-{date}-{feature}-{user}",
  "boost": false,
  "strategy": "follow",
  "context": [
    ".cursor/rules/coding-style.mdc",
    "AGENTS.md",
    "docs/conventions.md"
  ],
  "templates": {
    "spec": "spec.md",
    "proposal": "proposal.md",
    "tasks": "tasks.md",
    "clarify": "clarify.md",
    "checklist": "checklist.md",
    "design": "design.md"
  },
  "archive": {
    "dir": "archive",
    "datePrefix": true
  },
  "limits": {
    "targetLines": 300,
    "hardLines": 400
  },
  "artifacts": ["proposal"],
  "boostArtifacts": ["proposal", "spec", "design", "tasks", "checklist"]
}

Configuration Options

lang

Language for templates and CLI prompts.

Value	Description
"en"	English (default)
"zh"	Chinese

{
  "lang": "en"
}

aiEditor

AI editor type, used to install corresponding rules and commands.

Value	Description
"cursor"	Cursor (default)
"claude"	Claude Code
"gemini"	Gemini
"copilot"	GitHub Copilot
"windsurf"	Windsurf
"qwen"	Qwen
"opencode"	OpenCode
"codex"	Codex
"codebuddy"	CodeBuddy
"qoder"	Qoder

{
  "aiEditor": "claude"
}

specDir

Spec directory name.

{
  "specDir": "superspec"
}

Directory structure:

your-project/
└── superspec/          # specDir
    ├── changes/        # Changes directory
    └── templates/      # Templates directory

branchPrefix

Git branch prefix.

{
  "branchPrefix": ""
}

branchTemplate

Git branch name template.

Available variables:

• {prefix} - branchPrefix value
• {intentType} - Intent type (feature/hotfix/bugfix/refactor/chore)
• {feature} - Feature name
• {date} - Date (YYYYMMDD)
• {user} - Developer identifier

{
  "branchTemplate": "{prefix}{intentType}-{date}-{feature}-{user}"
}

Example output: feature-20240115-add-auth-jay

changeNameTemplate

Change folder name template. Uses the same variables as branchTemplate.

{
  "changeNameTemplate": "{prefix}{intentType}-{date}-{feature}-{user}"
}

Example output: feature-20240115-add-auth-jay

boost

Whether to enable Boost mode by default.

{
  "boost": false
}

strategy

Default strategy.

Value	Description
"follow"	Follow project rules (default)
"create"	Can propose new approaches

{
  "strategy": "follow"
}

context

List of project rule files for AI to read.

{
  "context": [
    ".cursor/rules/coding-style.mdc",
    "AGENTS.md",
    "docs/conventions.md"
  ]
}

templates

Template file name mapping.

{
  "templates": {
    "spec": "spec.md",
    "proposal": "proposal.md",
    "tasks": "tasks.md",
    "clarify": "clarify.md",
    "checklist": "checklist.md",
    "design": "design.md"
  }
}

archive

Archive configuration.

Field	Description	Default
dir	Archive subdirectory name	"archive"
datePrefix	Whether to add date prefix	true

{
  "archive": {
    "dir": "archive",
    "datePrefix": true
  }
}

limits

Artifact size limits.

Field	Description	Default
targetLines	Target maximum line count	300
hardLines	Hard maximum line count	400

{
  "limits": {
    "targetLines": 300,
    "hardLines": 400
  }
}

artifacts

List of artifacts generated in Standard mode.

{
  "artifacts": ["proposal"]
}

boostArtifacts

List of artifacts generated in Boost mode.

{
  "boostArtifacts": ["proposal", "spec", "design", "tasks", "checklist"]
}

Configuration Overrides

Command-line arguments can override configuration file values:

# Override lang
superspec create add-feature --lang en

# Override boost
superspec create add-feature -b

# Override branchPrefix
superspec create add-feature --branch-prefix hotfix/

Configuration Validation

SuperSpec validates the configuration file at startup:

• Whether JSON format is correct
• Whether field types match
• Whether required fields exist

If the configuration file has issues, a warning is displayed and default values are used.