sdf
Scannednpx machina-cli add skill caiobrian/sdf-skills/sdf --openclawSDF — Spec-Driven Flow
Unified workflow for structured development. Routes to the right phase based on context.
Routing Logic
Detect the current situation and route:
1. Quick Track — Small, well-defined task (bug fix, UI tweak, rename, config change):
→ Read phases/quick.md and follow it.
2. Discovery — New problem described, no spec exists yet:
→ Read phases/discover.md and follow it.
3. Spec — Problem statement exists, needs specification:
→ Read phases/spec.md and follow it.
4. Build — Spec exists in specs/<feature>/, tasks need implementation:
→ Read phases/build.md. Execute each task as a subagent via Task() with fresh context.
5. Verify — Code implemented, needs validation against spec:
→ Read phases/verify.md. Execute as subagent via Task() with fresh context.
6. Document — Everything done, needs closure and PR description:
→ Read phases/document.md and follow it.
How to detect phase
No spec exists for this topic? → Discovery
Spec exists but tasks not started? → Build
Tasks done but no tests? → Verify
Tests pass, needs PR/docs? → Document
Small isolated fix? → Quick Track
User explicitly says "pula pra X"? → Go to X
If ambiguous, ask for clarification on which phase to run (e.g., "discovery / spec / build / verify / document / quick") using the user's preferred language.
Subagent Pattern for Build and Verify
Build and Verify phases run each task in a fresh subagent context to prevent context degradation.
When spawning a subagent via Task(), provide this context:
Task: Implement T-[XX] from specs/<feature>/tasks.md
Read these files for full context:
- specs/<feature>/requirements.md (requirements with IDs)
- specs/<feature>/plan.md (types/interfaces)
- specs/<feature>/tasks.md (task details)
- .claude/CLAUDE.md (project constitution)
- LessonsLearned.md (mistakes to avoid)
Rules:
- Use EXACTLY the types from plan.md
- Handle edge cases referenced in the task (EC-xx)
- Follow CLAUDE.md conventions
- No `any` types, no silenced errors, no scope creep
- Code in English
- After implementation, run self-review checklist (in phases/build.md)
- Report: code created, self-review result, trade-offs, risks
After each subagent completes, review its output in the main context and mark the task [x] in tasks.md.
Transition Between Phases
After each phase completes, suggest the next:
- Discovery done → Prompt to move to spec (e.g., "Problem statement ready. Move to spec?")
- Spec done → Prompt to move to build (e.g., "Spec approved. Start building?")
- Build done → Prompt to move to verify (e.g., "Build complete. Validate?")
- Verify done → Prompt to move to document (e.g., "Tests passing. Document and close?")
- Document done → State cycle is complete (e.g., "SDF cycle complete.")
Note: Always communicate these transitions in the user's preferred language.
Rules
- Read the specific phase file BEFORE acting
- Build and Verify: ALWAYS use subagents — never implement in main context
- Discovery and Spec: run in main context (interactive, needs approval)
- Document: runs in main context (interactive)
- Quick Track: runs in main context (small enough)
- If scope grows during Quick Track, escalate to full flow
- Always communicate in the user's preferred language
Overview
SDF provides a unified, spec-driven workflow that routes development requests to the appropriate phase—discovery, specification, build, verification, or documentation. It supports both full feature flows and quick, isolated tasks, activating on various triggers to streamline software development.
How This Skill Works
SDF detects the current context and routes to the correct phase (quick track, discovery, spec, build, verify, or document). Build and Verify run as fresh subagents via Task() to keep context clean, while Discovery/Spec/Document run in the main context. Transitions between phases are suggested after each stage and communicated in the user’s preferred language.
When to Use It
- Starting a new feature or bug fix: use discovery → spec → build → verify → document for a full flow.
- A small, isolated task like a UI tweak or rename: use Quick Track in the main context.
- A problem described with no spec: go to Discovery to flesh out requirements.
- Spec exists and tasks need implementation: move to Build, with subagents for each task.
- All work done and you need a PR description and closure: switch to Document to finalize.
Quick Start
- Step 1: Determine the current phase based on the task description (discovery, spec, build, verify, document, or quick).
- Step 2: If Build or Verify is required, spawn subagents via Task() with fresh context and follow phase-specific docs.
- Step 3: After each phase, read the suggested next phase prompt and proceed in the user’s preferred language.
Best Practices
- Read the specific phase file BEFORE acting (discovery, spec, build, verify, document).
- For Build and Verify, ALWAYS use subagents via Task() with fresh context.
- Keep phase-specific files in their designated locations (e.g., specs/, phases/).
- Follow edge-case guidelines and project conventions (EC-xx, CLAUDE.md) in your implementations.
- Communicate transitions and next steps in the user’s preferred language.
Example Use Cases
- End-to-end feature development: discovery → spec → build → verify → document with a cohesive PR.
- Quick bug fix that fits Quick Track, implemented directly in the main context.
- Generate tests from a formal spec and validate them in the Verify phase using a subagent.
- Refactor that requires a new specification and corresponding build steps.
- Completing a task and producing a PR description and closure notes in Document phase.
