Skip to content
Skills Library
Management & product · Planning

spec-workflow

/spec-workflow

Turn user requests into requirements, decisions, tasks and verified features. Use when the user asks for a new capability, changes or drops one, or when a request is too large for one task.

Licence
MIT
Last repository change
08.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Turn user requests into requirements, decisions, tasks and verified features. Use when the user asks for a new capability, changes or drops one, or when a request is too large for one task.

Original author description

Turn user requests into requirements, decisions, tasks and verified features. Use when the user asks for a new capability, changes or drops one, or when a request is too large for one task.

How it works

  1. New capability
  2. Before changing behavior
  3. Questions
  4. Changed request
  5. Retiring a feature
  6. Fixing a bug
  7. Tests that prove something
Original SKILL.md headings · 94 lines, 840 words
SKILL.md preview
---
name: spec-workflow
description: Turn user requests into requirements, decisions, tasks and verified features. Use when the user asks for a new capability, changes or drops one, or when a request is too large for one task.
---

# Specification workflow

Requests become requirements, requirements become tasks, verified tasks ship features.

```text
user request -> requirement (R) -> tasks (T) -> code + tests -> ws verify --done -> feature (F) shipped
                     |                 |
              open question (Q)   decision (D)
```

## New capability

1. Restate the request in one sentence and confirm it with the user if it is ambiguous.
   Unclear points become questions: `ws add question --set question=...`.
2. Add the requirement with an acceptance command or an observable result, in the same turn the
   user stated it. Do not wait until every detail is settled: record the confirmed part now and put
   only the open details in the Idea pool.
3. If the detail exceeds two lines, copy `.agents/template/spec/` to `docs/specs/<slug>/`, fill
   `requirements.md` and set the requirement's Detail to `docs/specs/<slug>/requirements.md`.
4. Record design choices and rejected options with `ws add decision`.
5. Split the work into tasks of a few hours each, each with its own acceptance command. Name in the
   Scope the paths the task changes, `new:<path>` for a file it creates and each outside system it
   touches as `resource:<name>`, for example `services/unpaywall/ new:tests/test_proxy.py
   resource:vps/unpaywall`. Parallel sessions claim tasks by these, and a task with no path in its
   Scope, or with `tree:`, blocks every other session.
6. Add the feature with status `planned`, naming the requirement and tasks.
7. Implement one task, run `ws verify T<n> --done -- <command>`, repeat.
8. When all tasks are done: `ws set F<n> --set status=shipped`.

## Before changing behavior

Write these into the task Scope or the spec before editing code. Each answers a question the next
session would otherwise ask again:

| Item | What to write |
| --- | --- |
| Impact | The callers and consumers of what changes, and the command that listed them (`grep -rn "fetch_pdf" services/`) |
| Keep | Behavior next to the change that must not move, with the test that covers it; with no such test, add one first and see it pass on the unchanged code |
| Change | The behavior that changes, as current and expected |
| Premise | What the change relies on, checked: a route that exists may have no caller, a table may have no writer |

Run the task's acceptance once before the first edit. A failure that was already there is the
baseline: record it in `recovery_notes`, so it is not blamed on the change.

## Questions

A question that changes what the user sees, or needs their authority, stays `open` and blocks the
work it affects. A question about internals is deferred: the work goes on with a stated default,
and the brief shows it so nobody asks again.

```text
ws add question --set "question=Cache size limit?" --set "context=T4 needs a number"
ws set Q3 --set status=deferred --set "answer=default: 500 MB until the user decides"
```

## Changed request

- Small change, same acceptance: edit the requirement text with `ws set`. The log keeps the old text.
- Different acceptance or scope: set the old requirement to `replaced` with a reason, add a new
  one and point affected tasks at it.
- Dropped: set the requirement to `removed`, the feature to `removed` and open tasks to `dropped`,
  each with a reason.

## Retiring a feature

1. Enumerate everything that uses it: callers, tests, configuration, documents, scheduled jobs and
   stored data. Write each command and its range, then one line per hit: removed, kept and why, or
   moved to another task. "Same as above" is not an answer.
2. Keep what must outlive the feature, such as reading data it already wrote, as a requirement with
   its own acceptance.
3. Set the feature to `removed` or `replaced` with the reason and the replacement, then delete code.
   Put the enumeration in the spec or a report and name its path in the feature's Reason.

## Fixing a bug

1. Write current, expected and unchanged behavior as separate lines. Ask the user when the symptom,
   the trigger or the expected result is missing.
2. Write a test that fails on the current code for the reported reason, and run it. If it passes,
   stop: the bug is gone, the cause is wrong, or the test misses it.
3. Search for the same pattern elsewhere. Write the search command and what you did with each hit.
4. Fix, then run the same tests again.

A one-line fix inside an existing requirement reuses that requirement and its task or test.

## Tests that prove something

- Mock only external services. A mock of the code under test proves nothing.
- Never narrow the input range or loosen an assertion to make a test pass, and never add a second
  test to route around a failing one.
- Cover the boundary that breaks: 0, empty, null, equal values, the day boundary. Shape test data on
  real samples, so two sides that share a wrong assumption do not both pass.
- A check of behavior names its output: `check: python ops/probe.py expect "HTTP 200"`.

Versions

RepositoryScoreLicence
This page · yourhoneypomelo-cell/agent-workspace-template100MIT
komluk/scaffolding100MIT
tencentcloudbase/cloudbase-ai-toolkit100MIT
sutchan/Agent-Skills-Hub100MIT
tzachbon/smart-ralph100MIT
ramboz/jig91MIT
ramboz/jig91MIT
ramboz/jig91MIT

Database snapshot: 13.11.2026 · package version 7648e046e852 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90dev-spec
    Turn rough software-development requests into clear, reviewable specifications before implementation. Use for new features, behavior changes, ambiguous bugfix scope, product requirements, technical designs, acceptance criteria, or when a coding task needs agreement on intent,…
  • 100flow-next-spec-completion-review
    Spec completion review - verifies all spec tasks implement the spec requirements. Triggers on /flow-next:spec-completion-review.
  • 100understanding-feature-requests
    This skill should be used when clarifying feature requests, gathering requirements, or checking for contradictions in proposed changes
  • 90spec
    Write a detailed spec document for a task before implementation begins. Use when the user wants to define requirements, acceptance criteria, or technical design for a task.
  • 100planning-and-task-breakdown
    Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.
  • 100spec-driven-planning
    Plan new features using spec-driven workflow — auto-picks Quick (single plan.md) or Full (3-file EARS spec) mode. Use when creating features, writing requirements, or designing architecture.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.