framework-spec
Explicit framework workflow: spec
SKILL.md.claude/skills/framework-spec/SKILL.md
GitHub/spec — Feature or change specification
Use when starting non-trivial work. Produce a spec the team can review before implementation. Capture the product scenario and measurable outcomes first; let plan/tasks/code follow from that contract.
Inputs
- Problem statement or feature request (from user message or linked issue).
- Constraints: time, scope, tech stack (see AGENTS.md).
- Existing principles from
.agent/PROJECT_GUIDE.md,AGENTS.md, or project-specific governance docs.
Output
- Summary — One paragraph.
- Users / stakeholders — Who benefits.
- Product scenario — What user/business outcome changes; avoid implementation details unless they are hard constraints.
- Non-goals — What is explicitly out of scope.
- User stories — Short "As a … I want … so that …" bullets.
- Acceptance criteria — One EARS-form sentence per criterion (see below), numbered
AC-1,AC-2, … - Assumptions and dependencies — External systems, data, policy, migration, or rollout assumptions that must stay true.
- Open questions — Unknowns and decisions needed from humans.
Acceptance criteria (EARS)
Write each criterion as a single EARS sentence so it is testable without interpreting intent:
- Ubiquitous:
The <system> shall <response>. - Event-driven:
When <trigger>, the <system> shall <response>. - State-driven:
While <state>, the <system> shall <response>. - Unwanted behavior:
If <condition>, then the <system> shall <response>. - Optional feature:
Where <feature is present>, the <system> shall <response>.
Flag any criterion as AMBIGUOUS and ask for a rewrite before approval when it has:
- vague verbs ("handle", "support", "improve") with no observable outcome,
- more than one
shall(split it into separate criteria), or - an unclear subject (who/what responds?).
These IDs are the contract later verified by the validate-implementation skill. Use /clarify when material open questions remain before /plan.
Done when
- Every criterion is one EARS sentence with a stable
AC-nID; none are marked AMBIGUOUS. - Non-goals prevent scope creep.
- Assumptions/dependencies are explicit (not hidden).
Optional
- Save to
specs/<feature-slug>.mdusingtemplates/spec-feature.mdif the repo uses that layout.