---
name: openspec-authoring
description: Enforces OpenSpec authoring conventions including metadata blocks, section ordering, requirement/scenario structure, and validation steps.
category: documentation
---

# OpenSpec Authoring Patterns

**Trigger Keywords**: openspec, proposal, change-id, tasks.md, spec delta, requirement, scenario, validation, archive

**Agent Integration**: Used by `spec-writer` and planning agents when creating or updating OpenSpec proposals, tasks, and spec files.

## Metadata & Frontmatter
- Proposals/Tasks: include `Change ID`, `Status`, `Date`, and `Author` near the top.
- Specs: start with `# Spec: <Title>` plus capability/status/related lines.
- Use verb-led, kebab-case `change-id` (e.g., `add-doc-spec-writer-agent`).
- Keep managed instruction blocks intact when present.

## Required Section Ordering
- **proposal.md**: Executive Summary → Background → Goals → Scope/Non-Goals → Approach → Risks & Mitigations → Validation → Open Questions.
- **tasks.md**: Overview → Phase/Task grouping with checklists; include validation notes where possible.
- **spec.md (delta)**: Overview → `## ADDED|MODIFIED|REMOVED Requirements` → Scenarios per requirement with Given/When/Then.

## Requirement & Scenario Patterns
- Each requirement MUST have at least one `#### Scenario:` block.
- Scenario steps use bolded **Given/When/Then** lines on their own lines.
- Keep requirements testable and behavior-focused; avoid solutions in "Then".
- Use backticks for capability or file references when helpful.

## Validation Checklist
- ✅ Run `openspec validate <change-id> --strict` when available.
- ✅ Ensure every referenced skill/agent/capability exists or is added in the change.
- ✅ Confirm paths use workspace-relative notation (`openspec/specs/...`).
- ✅ Keep documentation generic and reusable across Python projects.

## Archiving Notes
- Archive changes only after deployment, using date-prefixed folder under `openspec/archive/`.
- Use `openspec archive <id> --skip-specs --yes` only for tooling-only changes.