teachingai/openspec-config

OpenSpec Config Skill

Manage OpenSpec configuration at two levels: project config (openspec/config.yaml) for project-specific context and rules, and global CLI config (openspec config subcommands) for user-level settings.

When to Use

• The user wants to add project context to improve AI artifact quality.
• Setting per-artifact rules (e.g. "specs must use Given/When/Then").
• Changing the default schema for the project.
• Managing global CLI settings (telemetry, editor, etc.).

Prerequisites

• OpenSpec initialized in the project (see openspec-initial).

Project Configuration

openspec/config.yaml

# Default schema for new changes
schema: spec-driven

# Project context injected into all artifact instructions
context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript

# Per-artifact rules
rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

Config Fields

| Field | Type | Description | |-------|------|-------------| | schema | string | Default schema for new changes (e.g. spec-driven) | | context | string | Project context injected into all artifact instructions (max 50KB) | | rules | object | Per-artifact rules, keyed by artifact ID |

How It Works

• Schema precedence (highest to lowest): CLI flag -> change metadata -> project config -> default (spec-driven).
• Context injection: Prepended to every artifact's instructions in <project-context> tags.
• Rules injection: Only for matching artifacts, in <project-rules> tags, after context.

Artifact IDs (spec-driven schema)

• proposal — Change proposal
• specs — Specifications
• design — Technical design
• tasks — Implementation tasks

Global CLI Configuration

openspec config list          # Show all settings
openspec config get <key>     # Get a value
openspec config set <key> <value>  # Set a value
openspec config unset <key>   # Remove a key
openspec config reset --all --yes  # Reset to defaults
openspec config edit          # Open in $EDITOR
openspec config path          # Show config file location

Common Settings

| Setting | Example | |---------|---------| | Disable telemetry | openspec config set telemetry.enabled false | | Set user name | openspec config set user.name "My Name" --string |

Outputs

• openspec/config.yaml with project context and rules.
• Improved AI artifact quality through context injection.

Next Steps

• Start working with openspec-new or openspec-explore.
• Create a custom schema with openspec-schema and set it as default in config.

Troubleshooting

• "Unknown artifact ID in rules": Check artifact IDs match your schema; run openspec schemas --json.
• Config not applied: Ensure file is at openspec/config.yaml (not .yml); check YAML syntax.
• Context too large: Limit is 50KB; summarize or link to external docs.

References

• OpenSpec CLI: config
• OpenSpec OPSX: Project Configuration