spec-as-source

Spec As Source

Overview

Use OpenSpec spec.md files as the executable source of truth. When this skill is active, fenced-Gherkin authoring, acceptance-first task ordering, spec-first implementation, and BDD zone isolation are one workflow.

REQUIRED SUB-SKILL: Use gherkin-authoring when drafting or modifying fenced Gherkin.

REQUIRED SUB-SKILL: Use acceptance-test-authoring when configuring or modifying the acceptance runner, extractor, linting, step definitions, or page objects.

Activation

This workflow is opt-in. Apply it only when the user or project instructions explicitly require spec-as-source.

Once active, the BDD zone rules below are mandatory. Do not activate or disable zone isolation separately.

Artifact References

• When this skill is active, its artifact references override the corresponding templates from the configured OpenSpec schema.
• Draft each spec.md from references/spec.md, not from openspec/schemas/intent-driven/templates/spec.md.
• Draft tasks.md from references/tasks.md, not from the schema task template, preserving acceptance-test-first ordering.

BDD Zone Rules

1. Code is written only for an active change under openspec/changes/ whose scenarios describe the behavior.
2. A unit of work edits either the specs zone (openspec/) or the code zone (everything else), never both while changes are uncommitted.
3. Before crossing zones, finish and commit or stash the current zone.
4. Never commit openspec/ files and code-zone files together.
5. Any file named tasks.md is exempt and may be edited from either zone.
6. Never revert or discard user-owned changes without explicit permission.

Use git status --porcelain before editing. Non-tasks.md paths under openspec/ select the specs zone; other changed paths select the code zone.

Workflow

1. Draft and validate the proposal and fenced-Gherkin delta specs.
2. Commit or stash specs-zone work before touching code.
3. Establish the failing acceptance scenario or pending step before implementation.
4. Implement the smallest change that makes the scenario pass.
5. Keep the effective acceptance suite green with no pending or undefined steps.
6. Commit or stash code-zone work before returning to specifications for sync or archive.

Red Flags

• Implementing behavior with no active spec change.
• Editing openspec/ and code-zone files in the same uncommitted unit of work.
• Writing implementation tasks before acceptance-test tasks.
• Treating generated .feature files as the source instead of spec.md.
• Running source-of-truth specs without active deltas when validating a change.

Stop and restore the workflow boundary when any red flag occurs.