sifter-ai/sifter / .agents/skills/sdd
sdd
VerifiedStory Driven Development workflow. Use this skill whenever working in a project that has `.sdd/config.yaml`, or when the user mentions SDD, sdd sync, story driven development, spec-driven development, change requests, bugs, or asks to implement a feature described in `product/` or `system/`. Also trigger on phrases like "sync the docs", "mark synced", "apply this CR", "fix this bug" when an SDD project is detected.
SDD — Story Driven Development
What this is
SDD keeps documentation (product/, system/) and code (code/) in sync.
Specs change → sdd sync surfaces what's pending → agent implements → sdd mark-synced commits the state → repeat.
The engine behind it is git: SDD uses git diff on the doc files to know what changed since the last sync. That's why committing immediately after every mark-synced is non-negotiable — skip a commit and the next sync will see phantom changes.
Detection
This project uses SDD if .sdd/config.yaml exists in the project root.
The core loop
Every session on an SDD project starts the same way — clear the backlog from highest priority down, then move new work forward:
-
Bugs first. Run
sdd bug open. If there are open bugs, fix the code/docs and runsdd mark-bug-resolved. Bugs block everything else. -
Then Change Requests. Run
sdd cr pending. If there are pending CRs, apply them to the docs inproduct//system/(this flips docs tonew/changed/deleted), then runsdd mark-cr-applied. CRs are the intended way to modify specs — never edit docs arbitrarily to reflect user requests; turn them into CRs first if scope justifies it. -
Then sync. Run
sdd sync. It returns a structured prompt listing every pending file and (forchangedfiles) the exact git diff of what changed in the spec. Read only what the prompt tells you to read. -
Implement. Write code inside
code/matching what each doc describes. Fordeletedfiles, remove the corresponding code — the doc itself gets deleted automatically on mark-synced. -
Mark synced + commit. This is one atomic step:
sdd mark-synced # or sdd mark-synced <specific files>
git add -A && git commit -m "sdd sync: <what you implemented>"
Every mark-synced MUST be followed by a commit in the same turn. No exceptions. See "Why the commit is mandatory" below.
- Publish (if remote configured). If
.sdd/config.yamlhas aremote:section and an API key is set, remind the user they can push withsdd push.
Why the commit is mandatory
sdd mark-synced records a snapshot of the doc files as the new sync baseline. On the next sdd sync, SDD runs git diff between HEAD and the working tree for each doc — that's how it detects what changed. If you mark-sync without committing, the diff machinery breaks: either the next sync sees nothing (false "all synced") or it re-surfaces already-implemented changes. The commit is what makes the sync loop durable.
Available commands
sdd status— All doc files and their state (new/changed/deleted/synced)sdd diff— Spec changes since last syncsdd sync— Structured prompt for pending files (with git diff forchanged)sdd validate— Check for broken references and issuessdd mark-synced [files...]— Mark files (or all) as syncedsdd cr list/sdd cr pending/sdd mark-cr-applied [files...]sdd bug list/sdd bug open/sdd mark-bug-resolved [files...]
Rules
- Always commit after mark-synced, in the same turn. This is the one rule you cannot break — see rationale above.
- Always check bugs + CRs before sync; they take priority over new work.
- Only implement what the sync prompt asks for. Don't wander into unrelated code.
- All generated code goes inside
code/. Nothing incode/should exist that isn't described by a doc. - Respect constraints in
## Agent Notessections of doc files when present. - Never edit files inside
.sdd/manually — it's SDD's internal state. - If remote is configured, suggest
sdd pushafter a successful local sync + commit.
Project structure
product/— What to build (vision, users, features)system/— How to build it (entities, architecture, tech-stack, interfaces)code/— All generated source codechange-requests/— Proposed modifications to the docsbugs/— Bug reports.sdd/— Config and sync state (do not edit by hand)
References
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |