Initial commit

.claude/skills/openspec-authoring/SKILL.md

@@ -0,0 +1,38 @@
+---
+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.