spex-specify

Define software behavior specifications using given/when/then scenarios.

Updated Feb 12, 2026

Search Tags:#workflow #specification #scenarios #user-experience #acceptance-criteria #given-when-then

Ready to run

npx skills add https://github.com/dmayerdesign/spex --skill spex-specify

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: spex-specify
Source: https://github.com/dmayerdesign/spex/tree/main/.claude/skills/spex-specify
Command: npx skills add https://github.com/dmayerdesign/spex --skill spex-specify

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

The specification skill helps teams articulate expected software behavior before coding, focusing on user experiences and describing outcomes in a clear, testable way.

Core Features & Use Cases

Write scenarios in given/when/then format to capture user interactions and outcomes.
Maintain a technology-free narrative that guides design, tests, and implementation.
Support the full spec workflow from happy-path scenarios to edge cases and acceptance criteria.

Quick Start

Describe a feature by listing concrete given/when/then scenarios for immediate collaboration.

Frequently Asked Questions about spex-specify

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write testable acceptance criteria for vague feature ideas?▼

Testable acceptance criteria are written by defining concrete given/when/then scenarios that capture user interactions and outcomes. This specification workflow identifies actors, core nouns, and success criteria to ensure every feature description remains technology-free and testable.

What is the given/when/then format for software behavior specification?▼

The given/when/then format structures software behavior specification by outlining scenarios. "Given" sets the precondition, "when" describes the user interaction, and "then" defines the testable outcome, maintaining a technology-free narrative that guides design and implementation.

How do I structure specification scenarios from happy path to edge cases?▼

Specification scenarios are structured by following a process-guiding workflow that starts with happy-path interactions and progresses to error paths and edge cases. This ensures comprehensive coverage of actors, core nouns, and acceptance criteria across all features.

Can I use this specification workflow to maintain a consistent vocabulary across features?▼

Yes, the specification workflow identifies core nouns and actors to ensure a consistent vocabulary across features. It enforces technology-free descriptions and clear acceptance criteria, keeping the user experience narrative uniform and testable throughout the project.

Does this specification approach work without tying scenarios to specific technologies?▼

Yes, the specification approach explicitly maintains a technology-free narrative to describe expected software behavior. By focusing on user experiences and given/when/then outcomes, it guides design and tests without coupling scenarios to specific implementation technologies.

When do I need to define software behavior specifications before coding?▼

You need to define software behavior specifications before coding when teams must articulate expected user experiences and testable outcomes clearly. Using the spec workflow ensures edge cases and acceptance criteria are identified upfront, preventing ambiguous requirements during implementation.