spec-driven-development
npx machina-cli add skill a5c-ai/babysitter/spec-driven-development --openclawspec-driven-development
You are spec-driven-development -- the specification creation and management skill for Pilot Shell processes.
Overview
This skill provides the methodology for creating complete, reviewable specifications through semantic codebase search, clarifying question resolution, and structured spec generation.
Capabilities
1. Semantic Codebase Search
- Search for files and code related to the task description
- Identify existing patterns that the spec should follow
- Map the impact area of proposed changes
- Generate SEARCH-CONTEXT.md with findings
2. Clarifying Question Resolution
- Identify ambiguities in the task description
- Generate targeted clarifying questions
- Resolve assumptions with explicit choices
- Document decisions for traceability
3. Spec Generation
- Structure specs with: title, goals, tasks, acceptance criteria
- Decompose into atomic, testable tasks
- Define dependency graphs between tasks
- Include rollback plans and risk assessments
- Generate SPEC.md document
4. Iterative Refinement
- Accept plan-reviewer feedback
- Apply revision requests by severity
- Refine task decomposition
- Update acceptance criteria
Spec Structure
# Specification: [Title]
## Goals
- [ ] Goal 1 with measurable outcome
## Tasks
### Task 1: [Description]
- **Acceptance Criteria**: ...
- **Test Strategy**: RED->GREEN->REFACTOR
- **Complexity**: low/medium/high
- **Dependencies**: [task-ids]
## Assumptions
- Assumption 1 (validated: yes/no)
## Risks
- Risk 1: Mitigation strategy
Source
git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/methodologies/pilot-shell/skills/spec-driven-development/SKILL.mdView on GitHub Overview
A repeatable process to create complete, reviewable specs using semantic codebase search, clarifying questions, and structured SPEC.md. It yields traceable decisions, atomic tasks, dependencies, and upfront rollback and risk assessments within Pilot Shell workflows.
How This Skill Works
It begins with semantic codebase search to surface patterns and scope. It then uses targeted clarifying questions to resolve ambiguities and record explicit choices. Finally, it generates a structured SPEC.md (title, goals, atomic tasks, acceptance criteria, dependencies, rollback plans, risks) and supports iterative refinement after reviews.
When to Use It
- Starting a Pilot Shell task with unclear scope to establish a concrete plan
- Changes that touch multiple modules requiring a dependency graph and traceability
- Creating an auditable, reviewable SPEC.md document for governance
- Resolving ambiguities in user stories with targeted clarifying questions
- Planning risk, rollback strategies, and test approaches upfront
Quick Start
- Step 1: Perform semantic search to gather context and patterns (generate SEARCH-CONTEXT.md).
- Step 2: Identify ambiguities, generate clarifying questions, and capture decisions.
- Step 3: Generate SPEC.md with title, goals, atomic tasks, acceptance criteria, dependencies, rollback, and risk assessments; prepare for review.
Best Practices
- Begin with a thorough semantic codebase search to ground scope and patterns
- Capture clarifying questions and explicit decisions in the spec for traceability
- Decompose work into atomic, testable tasks with measurable acceptance criteria
- Define dependencies, rollback plans, and risk assessments within the spec
- Iterate after plan-reviewer feedback, revising tasks and acceptance criteria
Example Use Cases
- Spec for integrating a new SEARCH-CONTEXT.md workflow across a module
- Spec for clarifying ambiguous user stories into concrete tasks and criteria
- Spec for a feature flag rollout across microservices with dependencies and rollback
- Spec for refactoring Pilot Shell task orchestration to improve traceability
- Spec for migrating logging to a unified framework with tests and rollback
