Project Configuration Structure

Project Configuration Structure¶

Project configuration is stored in .prodigy/config.yml within your project repository. These settings override global configuration for this specific project and are typically committed to version control (except for secrets).

Location¶

File: .prodigy/config.yml (in project root)
Created: Manually or via prodigy init
Format: YAML
Version Control: Committed to git (recommended, except for secrets)

Fields¶

`name` (required)¶

Type: String Default: None (required field)

Project identifier used in logs, events, and UI.

name: my-project

`description`¶

Type: String (optional) Default: None

Human-readable project description.

description: "AI-powered code analysis tool"

`version`¶

Type: String (optional) Default: None

Project version (semantic versioning recommended).

version: "1.2.3"

`spec_dir`¶

Type: Path (optional) Default: specs

Directory containing Prodigy specification files.

spec_dir: custom/specs

`claude_api_key`¶

Type: String (optional) Default: None (inherits from global config or environment)

Project-specific Claude API key. Overrides global config and is overridden by environment variable.

claude_api_key: "sk-ant-api03-..."

Security Warning: Do NOT commit API keys to version control. Use environment variables or .prodigy/config.local.yml (gitignored) instead.

`auto_commit`¶

Type: Boolean (optional) Default: Inherits from global config (default: true)

Whether to automatically commit changes after successful command execution.

auto_commit: false

`variables`¶

Type: Object (optional) Default: {}

Project-specific variables available in workflows and commands.

variables:
  deploy_branch: production
  test_timeout: 300
  feature_flags:
    new_ui: true
    beta_features: false

These variables can be referenced in workflows using ${variable_name} syntax.

Note: For workflow-level environment variables (with secrets, profiles, and step-level overrides), use the env: block in workflow files instead. See Environment Variables for details.

`storage`¶

Type: Object (optional) Default: Inherits from global config

Project-specific storage configuration. See Storage Configuration for details.

storage:
  backend: file
  backend_config:
    base_dir: /custom/project/storage

Complete Example¶

# .prodigy/config.yml
name: prodigy
description: "Workflow orchestration tool for Claude Code"
version: "0.1.0"
spec_dir: specs

auto_commit: true

variables:
  default_branch: master
  test_suite: full
  timeout_seconds: 600

Secrets Management¶

For sensitive values like API keys, use one of these approaches:

Option 1: Environment Variables (Recommended)¶

# .prodigy/config.yml (committed)
name: my-project
# No claude_api_key here

# Set in environment
export PRODIGY_CLAUDE_API_KEY="sk-ant-api03-..."

Option 2: Local Config File (Not Committed)¶

Create .prodigy/config.local.yml and add it to .gitignore:

# .prodigy/config.local.yml (gitignored)
claude_api_key: "sk-ant-api03-..."

# .gitignore
.prodigy/config.local.yml

Option 3: Secret Management Service¶

Use a secret management service (AWS Secrets Manager, HashiCorp Vault, etc.) and retrieve the key at runtime via environment variables.

Relationship to Global Config¶

Project config overrides global config on a per-field basis:

Fields specified in project config replace global config values
Fields NOT specified in project config inherit global config values
See Configuration Precedence Rules

Example:

# ~/.prodigy/config.yml (global)
log_level: info
auto_commit: true
max_concurrent_specs: 1

# .prodigy/config.yml (project)
name: my-project
log_level: debug  # Override global
# auto_commit and max_concurrent_specs inherited from global

Result: Project uses log_level: debug but inherits auto_commit: true and max_concurrent_specs: 1 from global config.

Project Variables in Workflows¶

Variables defined in project config are available in workflows:

# .prodigy/config.yml
name: my-project
variables:
  environment: staging
  api_url: https://staging.api.example.com

# .prodigy/workflow.yml
commands:
  - name: deploy
    args: ["${environment}"]
    options:
      api_url: "${api_url}"

Creating Project Config¶

Initialize a new project:

cd my-project
mkdir -p .prodigy
cat > .prodigy/config.yml << 'EOF'
name: my-project
auto_commit: true
EOF

Or use the init command (if available):

prodigy init

Project Configuration Structure