skills.rest
truongnat
truongnatCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

story-spec

Generates Cockburn use cases, user stories, and Given/When/Then acceptance criteria from templates.

Updated Jul 28, 2026
Search Tags:#requirements#acceptance criteria#user stories#backlog#use case#business analysis#given when then
One-click install
npx skills add https://github.com/truongnat/Restly --skill story-spec-truongnat
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: story-spec
Source: https://github.com/truongnat/Restly/tree/main/.agents/skills/story-spec
Command: npx skills add https://github.com/truongnat/Restly --skill story-spec-truongnat

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing consistent story-layer artifacts (use cases, user stories, acceptance criteria) is slow and error-prone, often producing vague acceptance criteria or missing exception flows. This Skill standardizes the process by seeding structured templates with traceable IDs and enforcing quality rules. ## Core Features & Use Cases - Three output modes: usecase produces a Cockburn-style USECASE.md, userstory produces a prioritized USER_STORIES.md backlog, and ac produces Given/When/Then acceptance criteria in AC.md. - Hard quality contract: Blocks vague acceptance criteria ("works", "as per spec"), requires extension/exception flows on use cases, and mandates actor/need/value plus priority on stories. - Traceability: Links UC/US/AC/BR IDs across artifacts and records open questions with blocking flags for handoff to testers or business analysts. - Use Case: A business analyst needs acceptance criteria for a login feature. Run mode ac to generate AC.md with testable Given/When/Then statements mapped to US and FR IDs. ## Quick Start Use the story-spec skill with mode=ac to generate Given/When/Then acceptance criteria for the login epic from the AC template.

Frequently Asked Questions about story-spec

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

FAQPage Schema
How do I write Given/When/Then acceptance criteria?▼

Use mode `ac` to generate an AC.md file where each criterion states a Given precondition, a When action, and a Then observable outcome. The Then clause must describe who sees what, never vague phrases like "works" or "as per spec".

How to write a Cockburn use case with exception flows?▼

Use mode `usecase` to seed a USECASE.md template with primary actor, scope, preconditions, guarantees, and a main success scenario. The contract requires at least one extension or exception branch when realistic, documented in the extensions table.

What is the difference between usecase, userstory, and ac modes?▼

Mode `usecase` produces a Cockburn-style use case document, `userstory` produces a prioritized backlog of As/I need/so that stories, and `ac` produces testable Given/When/Then acceptance criteria. Each mode outputs its own file from a matching template.

When should I use business-analysis instead of story-spec?▼

Use business-analysis first when working on Lite or Full paths with open Spec quality gates, since story-spec only deepens one story-layer artifact. Story-spec is the right choice once the broader analysis is done and you need a specific use case, story backlog, or AC document.

Can acceptance criteria be written in a non-English language?▼

Yes, prose follows the configured settings language while the structural keywords Given, When, and Then stay in English. Headings in the templates also remain English for consistency.

Related Skills

Explore More Product & Management Skills→
robotics-playgroundrobotics-playground

bmad-create-epics-and-stories

Decompose PRD, Architecture, and UX documents into epics and stories.

Official
Advanced
solace-illsolace-ill

team-qa

Coordinate qa-lead and qa-tester to generate test plans, cases, and sign-off reports.

Community
Advanced
chrisstinelinechrisstineline

business

Translate ambiguous business requests into structured, validation-ready requirements and artifacts.

Community
Intermediate
cncorpcncorp

feature-spec-writer

Translates product analysis into structured feature specifications with Quick Spec and Full Spec templates.

Official
Advanced