Sibling skills (local only)
Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.
If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.
Spec Workflow
Activation Contract
Use this first when
- The request is a new feature, multi-step product change, cross-module integration, or architecture/design task.
- Acceptance criteria are unclear and need to be made explicit before implementation.
- The work involves multiple files, user flows, database design, or UI design that needs staged confirmation.
Read before writing code if
- You are unsure whether the task should go straight to coding or should first go through requirements, design, and task planning.
- The request mentions a new page, a new system, a redesign, a workflow, or a multi-module refactor.
Then also read
- Frontend page or visual design work ->
../ui-design/SKILL.md
- Advanced data-model work ->
../data-model-creation/SKILL.md
Do NOT use for
- Small bug fixes with clear scope.
- One-file documentation updates.
- Straightforward config changes.
- Tiny refactors where the user already gave exact implementation instructions.
Common mistakes / gotchas
- Jumping into coding before acceptance criteria are explicit.
- Skipping user confirmation between requirements, design, and tasks.
- Writing vague tasks that do not map back to user-visible outcomes.
- Treating UI work as purely technical implementation without clarifying design intent.
Minimal checklist
- Decide whether the change really needs the full spec flow.
- If yes, stop and produce requirements first.
- If the change is small, low-risk, and acceptance is already clear, allow direct execution without forcing spec artifacts.
- Use EARS-style acceptance criteria.
- Get confirmation before moving to the next phase.
When to use this skill
Use this workflow for structured development when you need to:
- Define or refine a new feature
- Design complex architecture
- Coordinate changes across modules
- Plan database or UI-heavy work
- Improve requirement quality and acceptance boundaries
Decision rule
Use the full workflow when
- The task is medium or large
- The impact spans multiple modules
- Acceptance boundaries are fuzzy
- The user wants disciplined planning before implementation
Skip the full workflow when
- The task is small, low-risk, and already precise
- Goal, scope, and acceptance are already clear enough to execute directly
- The user explicitly wants a direct code change with no planning phase
Core workflow
Phase 1: Requirements
Create specs/<spec_name>/requirements.md.
What to do:
- Restate the problem and scope
- Write user stories
- Write acceptance criteria in EARS style
- Clarify business rules, constraints, and non-goals
EARS pattern:
While <optional precondition>, when <optional trigger>, the <system name> shall <system response>
Example:
When the user submits the form, the booking system shall validate required fields before creating the record.
Phase 2: Design
Create specs/<spec_name>/design.md.
What to do:
- Describe architecture and module boundaries
- Explain technology choices and trade-offs
- Define data model, API, security, and testing strategy as needed
- Use Mermaid only when a diagram materially improves clarity
Phase 3: Tasks
Create specs/<spec_name>/tasks.md.
What to do:
- Break the design into executable tasks
- Keep tasks specific and reviewable
- Link each task back to the relevant requirement
- Update task status as work progresses
Task format:
# Implementation Plan
- [ ] 1. Task title
- Specific work item
- Another concrete step
- _Requirement: 1
Phase 4: Execution
Only start implementation after the user confirms the task plan.
During execution:
- Keep task status current
- Finish one meaningful unit at a time
- Preserve traceability from change -> task -> requirement
Working rules for the agent
- Ask follow-up questions when the request is underspecified; do not guess core product behavior.
- Require confirmation between requirements, design, and task breakdown.
- Pull in
ui-design early when the change includes end-user pages or visual decisions.
- Keep documents concise but testable.
- Prefer user-visible outcomes over implementation-detail task names.
Output expectations
requirements.md -> problem, scope, user stories, EARS acceptance criteria
design.md -> architecture, technical approach, data/API/security/test notes
tasks.md -> actionable implementation checklist tied to requirements
1---
2name: spec-workflow
3description: Use when medium-to-large changes need explicit requirements, technical design, and task planning before implementation, especially for multi-module work, unclear acceptance criteria, or architecture-heavy requests.
4version: 2.32.5
5alwaysApply: false
6metadata:
7 source: https://skillmd.com/skills/ahang1598/spec-workflow
8---
9
10## Sibling skills (local only)
11
12Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`.
13
14If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do **not** HTTP-fetch remote skill or protocol markdown into the agent context.
15
16# Spec Workflow
17
18## Activation Contract
19
20### Use this first when
21
22- The request is a new feature, multi-step product change, cross-module integration, or architecture/design task.
23- Acceptance criteria are unclear and need to be made explicit before implementation.
24- The work involves multiple files, user flows, database design, or UI design that needs staged confirmation.
25
26### Read before writing code if
27
28- You are unsure whether the task should go straight to coding or should first go through requirements, design, and task planning.
29- The request mentions a new page, a new system, a redesign, a workflow, or a multi-module refactor.
30
31### Then also read
32
33- Frontend page or visual design work -> `../ui-design/SKILL.md`
34- Advanced data-model work -> `../data-model-creation/SKILL.md`
35
36### Do NOT use for
37
38- Small bug fixes with clear scope.
39- One-file documentation updates.
40- Straightforward config changes.
41- Tiny refactors where the user already gave exact implementation instructions.
42
43### Common mistakes / gotchas
44
45- Jumping into coding before acceptance criteria are explicit.
46- Skipping user confirmation between requirements, design, and tasks.
47- Writing vague tasks that do not map back to user-visible outcomes.
48- Treating UI work as purely technical implementation without clarifying design intent.
49
50### Minimal checklist
51
52- Decide whether the change really needs the full spec flow.
53- If yes, stop and produce requirements first.
54- If the change is small, low-risk, and acceptance is already clear, allow direct execution without forcing spec artifacts.
55- Use EARS-style acceptance criteria.
56- Get confirmation before moving to the next phase.
57
58## When to use this skill
59
60Use this workflow for structured development when you need to:
61
62- Define or refine a new feature
63- Design complex architecture
64- Coordinate changes across modules
65- Plan database or UI-heavy work
66- Improve requirement quality and acceptance boundaries
67
68## Decision rule
69
70### Use the full workflow when
71
72- The task is medium or large
73- The impact spans multiple modules
74- Acceptance boundaries are fuzzy
75- The user wants disciplined planning before implementation
76
77### Skip the full workflow when
78
79- The task is small, low-risk, and already precise
80- Goal, scope, and acceptance are already clear enough to execute directly
81- The user explicitly wants a direct code change with no planning phase
82
83## Core workflow
84
85### Phase 1: Requirements
86
87Create `specs/<spec_name>/requirements.md`.
88
89What to do:
90
91- Restate the problem and scope
92- Write user stories
93- Write acceptance criteria in EARS style
94- Clarify business rules, constraints, and non-goals
95
96EARS pattern:
97
98```text
99While <optional precondition>, when <optional trigger>, the <system name> shall <system response>
100```
101
102Example:
103
104```text
105When the user submits the form, the booking system shall validate required fields before creating the record.
106```
107
108### Phase 2: Design
109
110Create `specs/<spec_name>/design.md`.
111
112What to do:
113
114- Describe architecture and module boundaries
115- Explain technology choices and trade-offs
116- Define data model, API, security, and testing strategy as needed
117- Use Mermaid only when a diagram materially improves clarity
118
119### Phase 3: Tasks
120
121Create `specs/<spec_name>/tasks.md`.
122
123What to do:
124
125- Break the design into executable tasks
126- Keep tasks specific and reviewable
127- Link each task back to the relevant requirement
128- Update task status as work progresses
129
130Task format:
131
132```markdown
133# Implementation Plan
134
135- [ ] 1. Task title
136 - Specific work item
137 - Another concrete step
138 - _Requirement: 1
139```
140
141### Phase 4: Execution
142
143Only start implementation after the user confirms the task plan.
144
145During execution:
146
147- Keep task status current
148- Finish one meaningful unit at a time
149- Preserve traceability from change -> task -> requirement
150
151## Working rules for the agent
152
1531. Ask follow-up questions when the request is underspecified; do not guess core product behavior.
1542. Require confirmation between requirements, design, and task breakdown.
1553. Pull in `ui-design` early when the change includes end-user pages or visual decisions.
1564. Keep documents concise but testable.
1575. Prefer user-visible outcomes over implementation-detail task names.
158
159## Output expectations
160
161- `requirements.md` -> problem, scope, user stories, EARS acceptance criteria
162- `design.md` -> architecture, technical approach, data/API/security/test notes
163- `tasks.md` -> actionable implementation checklist tied to requirements