wolneydev/slate-sdd

Spec-Driven Development (SDD) — guided mode

The user should never have to know the SDD flow. You drive it: on every turn you work out where the project is, do everything you can on your own, ask only what you cannot infer, and end by telling the user exactly what happens next.

Every feature moves through spec.md → design.md → tasks.md → implementation → review.md. Templates live in ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/. Start every shell command that copies templates with T="${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates"; (the snippets below use $T).

The loop (run this every time the skill is used)

1. Detect the state (see State detection). Do this silently — read files, don't ask the user where they are.
2. Absorb the input. Whatever the user sent — a task.md path, a pasted document, a sentence, "continue", "ok" — map it onto the current step (see Handling input).
3. Do the step's work yourself. Draft the document from what you know: the input, docs/PRODUCT.md, docs/PRINCIPLES.md, docs/ARCHITECTURE.md, docs/GLOSSARY.md, and the code itself. Inspect the codebase instead of asking things the code answers (stack, commands, file paths, existing patterns). Write every document per Writing style and run its self-check before you show the document.
4. Ask only the gaps (see Asking questions). Never ask for something you already drafted with reasonable confidence — show it and let the user correct it.
5. Close with the guide block (see Guide block). Every reply ends with it, no exceptions.

Speak to the user in the language they write in. Write the documents in the language the project's existing docs use (English if there are none yet, unless the user asks otherwise).

State detection

Check in this order and stop at the first match:

#	Condition	Current step
1	No docs/PRODUCT.md or docs/PRINCIPLES.md	Setup — project docs
2	PRODUCT.md/PRINCIPLES.md still contain [placeholder] text	Setup — finish filling them
3	User sent new work (file, text, idea) that is not the active feature	Triage the new work
4	Active feature has spec.md with status: draft	Spec
5	spec.md approved, design.md missing or status: draft	Design
6	design.md approved, tasks.md still has template placeholders	Tasks (planning)
7	tasks.md has any T not done	Implement — next T
8	All T done, review.md status: pending	Review
9	review.md approved / approved-with-notes	Close — memory + state, then offer the next feature

Active feature = the one named in docs/MEMORY.md → Current State → In progress; if that is empty, the highest-numbered docs/specs/NNN-*/ whose review.md is not approved. If several are open and the user didn't name one, ask which (one question, list them).

A quick way to read the state:

ls docs/ docs/specs/ 2>/dev/null
grep -H '^status:' docs/specs/*/*.md 2>/dev/null
grep -H -- '- \*\*Status:\*\*' docs/specs/*/tasks.md 2>/dev/null

Handling input

• A path to a task.md (or any .md/.txt) — read it fully. Treat it as raw requirements, not as a finished tasks.md: harvest problem, behaviors, examples, edge cases, constraints, file hints. Then triage.
• Pasted text or a one-line idea — same as above.
• "continue" / "próximo" / "ok" / "aprovado" / "pode seguir" — if the current document is awaiting approval, this is approval: set its status and move to the next step in the same reply. Otherwise just run the current step.
• A correction or answer — apply it to the current document, update any Q it resolves, re-check for gaps, continue.
• A question about the flow — answer briefly, then resume with the guide block.

Triage (new work)

Decide the size and say what you decided in one line:

• Small — obvious, reversible, ~1–3 files, no design choice (typo, small bug, config change). Create only tasks.md (in docs/specs/NNN-name/), fill it, and go straight to Implement. Skip spec/design/review unless the user wants them.
• Feature — anything with behavior to define or a design choice. Run the full flow.
• Needs research — a key choice is genuinely unknown (library, approach, vendor). Full flow plus research.md before design.

When in doubt between small and feature, pick feature and say the user can ask to shortcut it.

Then create the folder:

1. Next number = highest NNN- in docs/specs/ + 1 (start at 001). Name = short kebab-case from the input; don't ask for it.
2. Copy templates:

D=docs/specs/NNN-feature-name; mkdir -p "$D"
cp $T/specs/spec.md $T/specs/design.md $T/specs/tasks.md $T/specs/review.md "$D"/
# only if research is needed:
cp $T/specs/research.md "$D"/

3. Put everything harvested from the input into the right documents right away: problem/ACs/constraints/out-of-scope → spec.md; implementation hints and file paths → keep as notes for design.md/tasks.md (don't lose them; add them under the relevant section once you reach it).
4. Update docs/MEMORY.md → Current State → In progress with the feature ID and step.
5. Continue directly into the Spec step in the same reply.

Steps

Setup

mkdir -p docs/decisions docs/specs
for f in PRODUCT PRINCIPLES ARCHITECTURE GLOSSARY MEMORY; do [ -f docs/$f.md ] || cp $T/$f.md docs/$f.md; done
[ -f docs/decisions/0000-template.md ] || cp $T/decisions/0000-template.md docs/decisions/
[ -f CLAUDE.md ] || cp $T/CLAUDE.md CLAUDE.md

Never overwrite existing files. Then pre-fill from the repo before asking anything: read package.json / pyproject.toml / go.mod / Cargo.toml / Makefile / CI files / README to fill Stack, Commands, Directory Map and Components. Ask the user only for what the code cannot tell: what the product is and for whom, goals, non-goals, business rules, team rules. If the user came with a feature, keep setup short (PRODUCT + PRINCIPLES essentials) and move on to the feature; ARCHITECTURE and GLOSSARY can be filled incrementally later.

Spec

Fill spec.md from the input. Every AC must be Given/When/Then and testable on its own — rewrite vague requirements into ACs yourself and show them. Each unknown that blocks design becomes a Q [blocking]; minor unknowns become Q [non-blocking] with your suggested answer. Present a short summary (Problem, ACs, Out of Scope, open Qs) and ask for approval. Gate: design starts only when no blocking Q is open and the user approved (or told you to proceed without asking) → set status: approved.

Design

Read docs/PRINCIPLES.md and docs/ARCHITECTURE.md, and inspect the code paths involved. Draft the full design.md yourself; cover every AC (say which part covers which). Make the local decisions yourself as D entries with a reason; only bring to the user decisions that are costly to reverse or a matter of preference, each with your recommendation. A decision affecting the whole project → propose an ADR in docs/decisions/. Show a short summary and ask for approval. Gate: same as spec.

Tasks

Fill tasks.md from spec + design: small Ts in dependency order, each with Covers, Files, and a real Verify command from PRINCIPLES.md → Commands. Every AC is covered by at least one T; every edge case E has a test. No approval gate unless the user asked for one — show the task list and move to Implement.

Implement

One T at a time: set in-progress, implement, run its Verify, set done (or blocked with the reason). After each T, report in 2–3 lines and continue to the next one unless something failed, a T conflicts with PRINCIPLES.md, or finishing needs something in Out of Scope — then stop and ask. Keep docs/MEMORY.md → In progress pointing at the current T.

Review

Fill review.md: Implementation Report, every AC with result and evidence, run the full test/lint/build commands, apply the PRINCIPLES review checklist, list findings. Check the feature documents against Writing style. Record each violation as a minor finding. Present the verdict. Fix blocker/major findings if the user agrees, then re-review.

Close

Move lasting lessons to docs/MEMORY.md, update Current State (Done += this feature, In progress cleared), add the capability to PRODUCT.md → Capabilities, create any ADR from Follow-ups. Then offer the next item (from Next, from review Follow-ups, or "send me the next task").

Asking questions

• Ask at most 3–5 questions per turn, most important first. Numbered, short.
• Every question carries your suggested answer, so the user can reply "ok" / "1 ok, 2 não" instead of writing: 1. Should expired links show an error page? → suggestion: yes, with a "send again" button.
• When the AskUserQuestion tool is available and the answer is a choice among a few options, use it, with the recommended option first.
• Never ask what the code, the docs or the input already answer. Never ask the user which SDD step to do next — that's your job.
• If the user says "decide you" / "tanto faz" / "pode seguir", take your suggestions, record them (as Q → answer or D), and continue.

Guide block

End every reply with this block (in the user's language), so the user never has to think about what to do:

---
📍 Feature: NNN-feature-name · Step: Spec (2/6)   [Setup · Spec · Design · Tasks · Implement · Review]
✅ Done now: <one line>
❓ I need from you: <numbered questions, or "nothing">
➡️ Next: <exactly what happens after the user replies — e.g. "reply 'ok' to approve the spec and I'll write the design">

If nothing is needed from the user, say so and say what you'll do next on "continue".

The guide block and chat messages do not need the full Writing style self-check. Keep them short and direct.

Document rules

• Replace every [placeholder], NNN and YYYY-MM-DD. An empty section becomes None. — never delete the heading.
• Use IDs (AC, Q, D, T, E, F) to cross-reference between documents instead of copying text.
• Read docs/PRINCIPLES.md before design.md and before implementing any task.
• If a requirement is unclear, add a Q and ask rather than guess. If a task conflicts with PRINCIPLES.md, stop and ask.
• Each fact lives in one document; others point to it.

Writing style (every document)

The next model reads these documents and acts on them. Write so that each sentence has one meaning only. These rules apply in every language. Portuguese equivalents are in parentheses.

Clarity & Precision (inspired by ASD-STE100)

1. One idea per sentence. Use a maximum of 20 words in an instruction. Use a maximum of 25 words in a description.
2. One instruction per sentence. Use the imperative for actions. Write "Return 404." Do not write "The system should probably return 404."
3. Active voice, present tense. Name the actor: the user, the system, or a component by its name.
4. One term = one meaning. Use the exact term from docs/GLOSSARY.md. Do not use synonyms for the same concept. When you use a new domain term, add the term to GLOSSARY.md.
5. Requirement keywords: use only must / must not / may (deve / não deve / pode). Do not use "should", "ideally", "try to", "if possible" ("deveria", "idealmente", "tentar", "se possível").
6. Quantify. Replace each vague word with a number, a unit or an observable result. Do not use these words without a number: fast, slow, many, few, large, small, robust, easy, simple, properly, user-friendly, some, "etc.", "and so on" (rápido, lento, muitos, poucos, grande, robusto, fácil, adequado, alguns, "etc.").
   • Wrong: "The page loads fast." Correct: "The page loads in less than 2 s (p95)."
7. No idioms, metaphors, jokes, filler words or marketing tone.
8. No unclear pronouns. If "it", "this" or "that" ("ele", "isso", "este") can refer to two nouns, repeat the noun.
9. Structure over prose. Prefer lists and tables. A paragraph has a maximum of 3 sentences.
10. Exact names in code. Write identifiers, paths, commands, fields and values in backticks. Do not paraphrase them.

First Principles

1. Start from facts. Habit and analogy are not reasons. "Other projects do X" is not a reason.
2. Label each claim that matters:
   • Fact — verified. Give the source: file path, command output, data or document.
   • Assumption — not verified. Write how to verify it.
   • Decision — a choice. Give the reason, derived from facts or constraints.
3. Trace each decision to a problem, an AC or a constraint. If a decision has no trace, remove it.
4. Need before solution. Write in this order: problem → constraints → the simplest solution that satisfies them.
5. Simplest option first. Choose the simplest option that satisfies all ACs. Each added component, dependency or step needs a stated reason.

Self-check (run before you show a document)

• No [placeholder], NNN or YYYY-MM-DD remains.
• No banned word from rules 5 and 6 remains.
• Each sentence is within the word limit of rule 1.
• Each domain term is in docs/GLOSSARY.md.
• Each D and each Decision has a reason.
• Each unverified claim is labeled Assumption and has a verification method.

Reference

Templates in $T = ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/:

• PRODUCT.md, PRINCIPLES.md, ARCHITECTURE.md, GLOSSARY.md, MEMORY.md, CLAUDE.md — project level, created once.
• decisions/0000-template.md — one ADR per project-wide decision.
• specs/spec.md, design.md, tasks.md, review.md, research.md — one set per feature.