OpenSpec Customization Guide: Tailoring AI Development Workflows to Your Team

Why customize OpenSpec

OpenSpec provides a generic AI‑assisted development workflow, but teams differ in technology stacks, iteration speed, and review requirements. Using the default configuration can require repeated command‑line flags and produce AI‑generated artifacts that do not match team conventions, leading to extra communication and rework. Customization lets OpenSpec understand team context, enforce bespoke rules, and streamline commands.

Customization levels

Project config – a single openspec/config.yaml file for quick, file‑based settings.

Custom schemas – workflow definitions stored under openspec/schemas/, version‑controlled with the codebase.

Global overrides – user‑level schemas placed in ~/.local/share/openspec/schemas/ and shared across projects.

Level 1: Project config

The basic method edits openspec/config.yaml to set defaults, inject team context, and add exclusive rules.

Quick init : run openspec init and follow the interactive prompts to generate the file.

Manual edit : create or edit openspec/config.yaml directly. Example content:

# openspec/config.yaml
schema: spec-driven
context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs
rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

Default mode : schema: spec-driven removes the need to pass --schema on every command.

Team context : declaring stack, API style, testing tools, etc., makes the AI generate matching code (e.g., specifying TypeScript+React+PostgreSQL prevents Python snippets).

Exclusive rules : enforce document formats such as requiring a rollback plan in proposals or using Given/When/Then in specifications.

After configuration, all subsequent openspec commands automatically read these settings, e.g. openspec new change my-feature works without --schema spec-driven.

Level 2: Custom schemas

When project config is insufficient, create a custom schema under openspec/schemas/. Two creation methods are provided.

Fork an existing schema (new users) : openspec schema fork spec-driven my-workflow copies the default schema into openspec/schemas/my-workflow/.

openspec/schemas/my-workflow/
├── schema.yaml   # core workflow definition
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

Initialize from scratch (advanced users) :

openspec schema init rapid \
    --description "Rapid iteration workflow" \
    --artifacts "proposal,tasks" \
    --default

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead
artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []
  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    instruction: |
      Create a checklist of implementation steps.
    requires: [proposal]
apply:
  requires: [tasks]
  tracks: tasks.md

The core of a custom schema is schema.yaml, which defines artifacts, templates, instructions, and dependencies. Key fields: id: unique identifier used in commands and rules. generates: output file name (supports glob patterns). template: path under templates/ for the markdown scaffold. instruction: prompt given to the AI. requires: document dependencies that enforce execution order.

Example: adding a pre‑implementation review step.

# openspec/schemas/with-review/schema.yaml (excerpt)
- id: review
  generates: review.md
  description: Pre‑implementation review checklist
  template: review.md
  instruction: |
    Create a review checklist based on the design.
    Include security, performance, and testing considerations.
  requires:
    - design

- id: tasks
  requires:
    - specs
    - design
    - review

Also add templates/review.md to define the document structure.

Level 3: Global overrides

Power users can place custom schemas in the user‑level directory ~/.local/share/openspec/schemas/, making them available to every local project without duplication. Project‑level schemas are generally preferred because they live in the repository and are shared via version control.

Debugging and validation

To verify a custom schema, run: openspec schema validate my-workflow The tool checks syntax, template existence, circular dependencies, and artifact IDs, reporting any issues before use.

Other useful commands: openspec schema which my-workflow – shows the source and path of a schema. openspec schema which --all – lists all available schemas.

Practical tips

Use project config for quick injection of team context (covers the majority of cases).

When a unique process is needed, fork an existing schema and modify it rather than building from zero.

Run the validation command after editing a schema to avoid runtime failures.

Prefer project‑level schemas for version control and team synchronization.