git:20260815.02a4647 to git:20261015.b5bda46

6 added, 6 removed. Audit A to A.

---

name: spec-as-source

description: Use when a user or project explicitly adopts OpenSpec spec-as-source, fenced Gherkin specifications as executable acceptance tests, or acceptance-test-first OpenSpec tasks.

---

# 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](references/spec.md), not from

`openspec/schemas/intent-driven/templates/spec.md`.

- Draft `tasks.md` from [references/tasks.md](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.

+ 2. A unit of work edits either the specs zone (non-`tasks.md` files under `openspec/`) or the code zone (non-`tasks.md` files outside `openspec/`), 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.

+ 4. Never commit specs-zone files and code-zone files together.

+ 5. Any file named `tasks.md` is zone-neutral: it may be edited alongside and committed with either zone. Task updates do not select or cross a zone and do not require a separate commit or stash.

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.

+ Use `git status --porcelain` before editing. Ignore files named `tasks.md` when selecting the zone. Of the remaining changed paths, those under `openspec/` select the specs zone; those outside it select the code zone. If only `tasks.md` files are changed, no zone is selected.

## 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.

+ 4. Implement the smallest change that makes the scenario pass. During OpenSpec apply, keep the active change's `tasks.md` updated as work completes, marking each completed task immediately. These progress updates may accompany implementation edits and commits.

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.

+ - Editing specs-zone and code-zone files in the same uncommitted unit of work (`tasks.md` is zone-neutral).

- 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.