Adapting Spec-Driven Workflow to Your Team Without Burning Time

You adopt a spec-driven workflow. The default works for a week. Then you hit a project where it does not fit. Your team does research before specs. Your team needs a review step before implementation. Your team has artifact types the default does not cover.

Most teams stop here. The default does not fit, so they abandon the workflow. The alternative is customizing the workflow to match the team. That is what the customization layer is for.

Three levels, easiest first

Project config. The easiest level. You set defaults and inject context into every artifact the agent generates. Best for most teams. A YAML file, ten lines, covers eighty percent of customization needs.

Custom schemas. Define your own workflow artifacts and their dependencies. For teams with unique processes. More work to set up, more flexibility.

Global overrides. Share schemas across all your projects. For power users who want consistency everywhere. Useful only if you have multiple projects that share a workflow.

Most teams should stop at level one. The deeper levels pay off only when the project config provably cannot express what you need.

Project config: inject your context

The config file lives at openspec/config.yaml. It does three things.

Sets the default schema. If you only use the built-in spec-driven workflow, you do not need to touch this.

Injects project context that the agent sees on every artifact. Your stack. Your API conventions. Your test framework. Your coding standards. This context appears in proposals, specs, design, and tasks alike.

Adds per-artifact rules. Rules only appear for the matching artifact type. A rule for proposals does not clutter up your specs.

Example. Tell the workflow your stack is TypeScript with React and Node.js, your API is REST, you use Jest for testing. Add a rule that proposals must include a rollback plan. Add a rule that specs use Given/When/Then format.

Every artifact the agent generates now follows your context and your rules. You stop correcting the same things in review.

Custom schemas: define your workflow

When project config is not enough, you can create entirely custom workflows.

The fastest path is to fork the built-in schema. The fork copies the default to a directory you control. Edit the YAML and templates freely. Test immediately.

A real example. Your team prefers to do research before jumping into specs. You create a custom schema with three artifacts.

Research. No dependencies. Can start immediately. The artifact captures what you learned about the problem space.

Proposal. Requires research to be done first. Builds on the research findings.

Tasks. Requires proposal. The implementation checklist.

Your team goes straight from proposal to tasks. No specs. No design. The workflow enforces the dependency order but does not force you through phases you do not need.

Adding a review step

Another common customization. Add a review artifact between design and tasks.

Fork the default schema. Insert a review step with instructions. "Create a review checklist based on the design. Include security, performance, and testing considerations." Make tasks require review to be completed first.

Your workflow now has a built-in review gate. No code change. No tool swap. The schema expresses the policy.

This is the leverage of customization. The workflow becomes an expression of how your team actually works, not a constraint imposed by the tool.

Templates: shape the agent's output

Each artifact has a template. A markdown file that guides what the agent generates.

Templates include section headers the agent fills in. HTML comments with guidance. Example formats.

Edit templates to change the structure of generated artifacts without touching code. Want your proposals to always include a "rollback plan" section. Add it to the template. Every future proposal has it.

Change a template, test immediately. No rebuild. The iteration speed is what makes customization actually usable. Most teams do not customize because the feedback loop is slow. Here it is fast.

Validate before using

Before relying on a custom schema, validate it.

Run openspec schema validate my-workflow. The validator checks YAML syntax, template existence, no circular dependencies, valid artifact IDs.

If you are not sure which schema is being used at any moment, run openspec schema which my-workflow. It shows where the schema resolves from. Useful when you have local overrides and global ones competing.

Validation catches the failures that would otherwise surface mid-task. A typo in the schema file breaks every artifact generation until you find it. Better to find it before starting work.

When customization is the wrong answer

Customization is addictive. Once you know it exists, every quirk of your team feels like a reason to customize.

Most quirks are not. They are signal that the team should change how it works, not that the tool should accommodate how it works.

Before adding a custom schema, ask: would adopting the default workflow force us to drop a practice that is genuinely better than the default. If yes, customize. If no, change the practice.

The teams that get value from customization are the ones that use it sparingly. The teams that stop getting value are the ones that customize everything and end up maintaining a workflow instead of shipping code.

The smallest test

Open your openspec/config.yaml. Add three lines: your stack, your test runner, one rule you find yourself repeating in review.

Generate the next artifact. If it follows your context without being told, customization works. If not, the config is wrong and you fix it once.