Configuration Layers

Relevant source files

• CHANGELOG.md
• pyproject.toml

Purpose and Scope

This document describes the four-layer configuration cascade system for Spec Kit extensions. The configuration system enables flexible extension behavior through multiple configuration sources with well-defined precedence rules. This allows defaults to be overridden at the project level, customized per developer without affecting version control, and dynamically adjusted via environment variables.

For information about extension installation and management, see Extension Management Commands. For details on extension architecture and manifests, see Extension Architecture. For creating extensions that use configuration, see Creating Extensions.

Configuration Layer Overview

The extension configuration system implements a four-layer cascade where each layer can override values from lower-priority layers. The system provides a balance between sensible defaults, project-wide standardization, developer-specific customization, and runtime flexibility.

The Four Configuration Layers

The configuration cascade operates with the following precedence (highest to lowest):

Layer	Priority	Source	Versioned	Use Case
Environment Variables	1 (highest)	SPECKIT_{EXT_ID}_{KEY}	No	CI/CD, secrets, runtime overrides
Local Configuration	2	.specify/extensions/{ext-id}/local-config.yml	No (gitignored)	Developer-specific settings
Project Configuration	3	.specify/extensions/{ext-id}/{ext-id}-config.yml	Yes	Team-wide defaults
Extension Defaults	4 (lowest)	extension.yml (manifest)	Yes	Baseline configuration

Configuration Layer Cascade Diagram

Sources: CHANGELOG.md78-87

Layer 1: Extension Defaults

Extension defaults are defined in the extension.yml manifest file within each extension's package. These defaults provide baseline configuration that works out-of-the-box and serve as documentation for available configuration options.

Manifest Structure

The default_config section in extension.yml defines default values:

Characteristics

• Versioned: Defaults are part of the extension package and version-controlled
• Read-only: Users cannot modify defaults directly
• Documentation: Serves as the canonical reference for available configuration keys
• Baseline behavior: Defines sensible defaults that work in most scenarios

File Location

Defaults reside within the extension package directory structure, not in the user's project:

• {extension-package-root}/extension.yml

Sources: CHANGELOG.md79

Layer 2: Project Configuration

Project configuration provides team-wide settings that are committed to version control. This layer standardizes extension behavior across all developers working on a project.

File Location and Format

Project configuration files are stored in the .specify/extensions/ directory:

• Path: .specify/extensions/{ext-id}/{ext-id}-config.yml
• Format: YAML
• Versioned: Yes (committed to Git)

Example for the jira extension:

Use Cases

• Setting organization-specific API endpoints
• Defining team naming conventions
• Configuring shared resource identifiers
• Establishing project-wide defaults

Creation and Management

Project configuration files can be created:

1. Manually: Create the YAML file in the correct location
2. During installation: Some extensions create initial project config
3. Via extension commands: Extensions may provide configuration helpers

Sources: CHANGELOG.md80

Layer 3: Local Configuration

Local configuration enables developer-specific customization without affecting other team members. These files are gitignored to prevent sensitive data or personal preferences from being committed.

File Location and Format

Local configuration files parallel project configuration but with a different filename:

• Path: .specify/extensions/{ext-id}/local-config.yml
• Format: YAML
• Versioned: No (automatically gitignored)

Example for developer-specific overrides:

Use Cases

• Personal API endpoints (e.g., staging vs production)
• Developer-specific credentials (though environment variables are preferred)
• Debug flags and logging preferences
• Testing configurations

Security Considerations

Local configuration files are automatically added to .gitignore by the extension system to prevent accidental credential exposure. However, for highly sensitive values like API tokens, environment variables (Layer 4) are recommended.

Sources: CHANGELOG.md81

Layer 4: Environment Variables

Environment variables provide the highest-priority configuration layer, enabling runtime overrides and secure handling of sensitive values. This layer is essential for CI/CD pipelines and containerized deployments.

Naming Convention

Environment variables follow a structured naming pattern:

SPECKIT_{EXT_ID}_{CONFIG_KEY}

Where:

• SPECKIT_ is the fixed prefix
• {EXT_ID} is the extension identifier in uppercase with hyphens replaced by underscores
• {CONFIG_KEY} is the configuration key in uppercase with dots replaced by underscores

Example Mappings

Configuration Path	Environment Variable
jira.api_url	SPECKIT_JIRA_API_URL
jira.project_key	SPECKIT_JIRA_PROJECT_KEY
jira.custom_field_mapping.story_points	SPECKIT_JIRA_CUSTOM_FIELD_MAPPING_STORY_POINTS

Nested Configuration

For nested configuration objects, the path is flattened using underscores:

Use Cases

• CI/CD pipelines: Configure extensions dynamically in automated workflows
• Secrets management: Store API tokens and credentials securely
• Environment-specific behavior: Different values for dev/staging/production
• Containerized deployments: Override configuration at runtime without rebuilding images

Sources: CHANGELOG.md82

Configuration Merging and Precedence

The configuration system performs recursive deep merging of all four layers, with higher-priority layers overwriting values from lower-priority layers.

Merge Algorithm

Configuration Merging Process

Merge Rules

1. Dictionary merging: Nested dictionaries are merged recursively
2. Value overwriting: Non-dictionary values are replaced entirely
3. List handling: Lists are replaced (not merged) by higher-priority layers
4. Null handling: Explicit null values override lower layers

Example Merge Scenario

Given these four layers:

Final merged configuration:

Sources: CHANGELOG.md83

The ConfigManager Class

The ConfigManager class provides programmatic access to the merged configuration cascade. Extensions use this class to retrieve configuration values with proper precedence handling.

Class Structure

ConfigManager Class Diagram

Core Methods

get_config()

Returns the fully merged configuration dictionary for the extension.

get_value(key_path, default=None)

Retrieves a specific configuration value using dot-notation path traversal.

has_value(key_path)

Checks if a configuration key exists in the merged configuration.

Dot-Notation Path Support

The configuration system supports nested path traversal using dot notation:

Key Path	Traversal
jira.api_url	config['jira']['api_url']
jira.custom_field_mapping.story_points	config['jira']['custom_field_mapping']['story_points']
database.connection.pool.max_size	config['database']['connection']['pool']['max_size']

Sources: CHANGELOG.md84-86

Configuration File Locations

Directory Structure

Extensions store configuration in a predictable directory hierarchy:

.specify/
└── extensions/
    ├── {ext-id}/
    │   ├── {ext-id}-config.yml      # Project configuration (versioned)
    │   ├── local-config.yml          # Local configuration (gitignored)
    │   └── ...                       # Extension files
    ├── {another-ext-id}/
    │   ├── {another-ext-id}-config.yml
    │   ├── local-config.yml
    │   └── ...
    └── .registry                     # Extension registry (versioned)

Configuration File Paths Table

Extension ID	Project Config Path	Local Config Path
jira	.specify/extensions/jira/jira-config.yml	.specify/extensions/jira/local-config.yml
github-actions	.specify/extensions/github-actions/github-actions-config.yml	.specify/extensions/github-actions/local-config.yml
my-custom-ext	.specify/extensions/my-custom-ext/my-custom-ext-config.yml	.specify/extensions/my-custom-ext/local-config.yml

Automatic Gitignore Handling

The extension system automatically ensures that local-config.yml files are gitignored to prevent sensitive data from being committed. The pattern **/local-config.yml is added to .gitignore during extension installation.

Sources: CHANGELOG.md80-81

Configuration Access Patterns

Pattern 1: Required Configuration

For configuration values that must be present:

Pattern 2: Optional Configuration with Defaults

For configuration values that have sensible defaults:

Pattern 3: Conditional Behavior

For configuration-driven feature flags:

Pattern 4: Nested Configuration Objects

For complex configuration structures:

Sources: CHANGELOG.md84-86

Common Use Cases

Use Case 1: Multi-Environment Setup

A development team works across multiple environments:

Each developer uses their preferred environment:

CI/CD pipeline uses production:

Use Case 2: Secrets Management

Sensitive credentials are never committed:

Developers set tokens locally:

CI/CD injects tokens at runtime:

Use Case 3: Feature Flags

Teams can enable/disable experimental features per developer:

Individual developers opt in:

Use Case 4: Team Standardization

Project-wide standards with personal overrides:

A developer working on legacy code:

Sources: CHANGELOG.md78-87

Configuration Validation

Extensions should validate configuration during initialization to provide clear error messages:

Sources: CHANGELOG.md84-86