spec-workflow

Transform ambiguous change requests into requirements, design, and task plans.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/mrpersimmon/xiao-han-studio --skill spec-workflow-mrpersimmon
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spec-workflow
Source: https://github.com/mrpersimmon/xiao-han-studio/tree/main/.agents/skills/cloudbase/references/spec-workflow
Command: npx skills add https://github.com/mrpersimmon/xiao-han-studio --skill spec-workflow-mrpersimmon

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It prevents costly rework by turning ambiguous, medium-to-large change requests into confirmed requirements, design decisions, and executable tasks before implementation.

Core Features & Use Cases

  • Requirements with EARS acceptance criteria: Restates scope, writes user stories, and defines testable acceptance boundaries.
  • Architecture-first design: Clarifies module boundaries, technical choices, and supporting data/API/security/testing notes.
  • Traceable task planning: Breaks the design into reviewable implementation tasks tied back to requirements.
  • Use case: When you’re coordinating a multi-module feature (new pages, UI redesign, database changes, or unclear acceptance criteria), this workflow helps you align stakeholders step-by-step before any code is written.

Quick Start

Tell the AI to help you produce specs/<spec_name>/requirements.md using EARS-style acceptance criteria for the change: <your request>.

Frequently Asked Questions about spec-workflow

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

FAQPage Schema
How do I plan multi-module architecture changes before writing code?

To plan multi-module architecture changes, you can transform ambiguous requests into confirmed requirements, architecture design, and traceable tasks. This workflow generates requirements.md, design.md, and tasks.md files to enforce disciplined planning and prevent rework before implementation.

What's the best way to write testable acceptance criteria for ambiguous feature requests?

Writing testable acceptance criteria for ambiguous requests requires restating scope and defining boundaries using EARS format. This workflow generates user stories and testable acceptance criteria in requirements.md to clarify fuzzy project boundaries and align stakeholders.

How do I break down complex software design decisions into executable tasks?

To break down complex software design decisions into tasks, you must clarify module boundaries, technical choices, and security notes first. This workflow maps architecture-first design decisions into reviewable implementation tasks that trace directly back to confirmed requirements.

Does this spec workflow support projects with missing acceptance criteria?

Yes, this spec workflow explicitly supports projects with missing or fuzzy acceptance criteria. It applies to medium-to-large ambiguous change requests, restating scope and enforcing confirmation before execution to satisfy disciplined planning requirements.

When do I need an architecture-first workflow for new feature planning?

You need an architecture-first workflow when coordinating multi-module features like new pages, UI redesigns, or database changes. It clarifies technical choices, module boundaries, and supporting data/API notes to align stakeholders step-by-step before code execution.

Can I enforce stakeholder confirmation before task execution in multi-module projects?

Yes, you can enforce stakeholder confirmation before execution in multi-module projects. The workflow produces requirements, design, and task plans, requiring explicit confirmation to satisfy disciplined planning requirements and prevent costly rework.