Spec-Driven Development (SDD) — a structured, phase-based agentic AI development workflow for VS Code / GitHub Copilot. Ships skills, workflows, and doc templates that guide AI agents from product requirements through design, specification, incremental implementation, review, and integration.
npm install @aldoawp/workflowThe postinstall script copies two directories into your project root and then removes itself from package.json:
| Source (package) | Destination (your repo) | Purpose |
|---|---|---|
.agents/ |
.agents/ |
Skills & workflow definitions for Copilot |
templates/docs/ |
docs/ |
Versioned doc scaffolds (PRD, design, specs) |
After install the package self-uninstalls — only the copied files remain.
The workflow follows six phases. Each phase has dedicated skills that can be invoked directly or composed by the bundled workflows.
Write high-level and module-level Product Requirements Documents.
docs/prd/main-v1.md
docs/prd/[module]-v1.md
Skill: prd
Create separate design documents covering architecture, security, conventions, data model, and (for UI apps) sitemap.
docs/design/architecture_v1.md
docs/design/security_v1.md
docs/design/conventions_v1.md
docs/design/data-model_v1.md
Skills: software-architect, design-system (UI projects)
Write implementation specs referencing PRD and design docs, then break each spec into discrete tasks.
docs/specs/<spec-name>/spec.md
docs/specs/<spec-name>/checklist.md
docs/specs/<spec-name>/tasks/task-[n]-[task-name].md
Skills: spec, plan, compress
Execute one task at a time through an implement → review cycle. Optionally use TDD (red → green → refine).
Skills: implement, tdd, review, branch
After completing a task, close it out: mark the checklist, write a rolling summary, and commit.
docs/specs/<spec-name>/summaries/task-[n]-summary.md
Skills: checklist, summarize, commit
Periodically review completed specs holistically for cross-feature consistency.
Skill: integration-review (planned)
docs/ is the living knowledge base for your project, seeded by the install and populated as you progress through the workflow:
| Path | Created during | Contents |
|---|---|---|
docs/prd/ |
Phase 1 | Versioned PRDs (main-v1.md, module PRDs) |
docs/design/ |
Phase 2 | Architecture, security, conventions, data model, UI/UX design system, sitemap |
docs/specs/<spec>/spec.md |
Phase 3 | Implementation spec with decisions, invariants, contracts |
docs/specs/<spec>/checklist.md |
Phase 3 | Task checklist tracking progress |
docs/specs/<spec>/tasks/ |
Phase 3 | Individual task files with acceptance criteria |
docs/specs/<spec>/summaries/ |
Phase 5 | Rolling session summaries carrying context between AI sessions |
All documents follow a _vN.md versioning convention — never overwrite, always increment.
20 skills ship in .agents/skills/. Each is a standalone SKILL.md that Copilot loads on demand.
| Skill | Purpose |
|---|---|
| brainstorm | Critical thinking partner — challenge assumptions, refine ideas |
| branch | Create or switch to a traceable Git branch for a task |
| checklist | Mark a task complete on a spec checklist |
| commit | Stage changes and create a conventional commit |
| compress | Shrink agent-facing instructions without changing behavior |
| design-system | Generate a token-level UI design system (docs/design/uiux-design.md) |
| enhance-note | Clean up a messy note into a structured working document |
| implement | Execute one scoped change: understand → plan → implement → test → verify |
| integration-review | (planned) Holistic cross-feature consistency check |
| merge-notes | Merge overlapping notes into a single comprehensive document |
| page-detail | Produce implementation-ready page breakdowns for UI pages |
| plan | Break a spec or request into discrete, agent-sized tasks |
| prd | Write a Product Requirements Document |
| review | Code review for correctness, security, simplicity, and robustness |
| skill-creator | Create, iterate, and benchmark new skills |
| software-architect | Write system-level design docs (architecture, security, conventions, data model) |
| spec | Write an implementation spec and pause for human review |
| summarize | Produce a rolling task summary for session continuity |
| tdd | Test-first implementation: red → green → refine |
| update-note | Integrate new information into an existing note |
3 workflow files in .agents/workflows/ compose skills into end-to-end sequences:
| Workflow | Description |
|---|---|
| start-task | Locate task → branch → implement → review loop (up to 3 passes) |
| start-task-tdd | Same as start-task but uses TDD (failing test first, then implement) |
| end-task | Verify completion → update checklist → write summary → commit |
> start-task user-auth # picks first unchecked task, branches, implements, reviews
> end-task user-auth task 1 # marks checklist, writes summary, commits
> start-task user-auth # picks next unchecked task automatically
- Document everything with versioning — PRDs, design docs, specs, and reviews all use
_vN.md. - Specs are the bridge — they reference PRDs and design docs, giving the AI rich context for accurate implementation.
- Review every task — never batch AI output without checking for bugs, security issues, and performance.
- Track progress explicitly — per-spec checklists and per-session rolling summaries.
- Integrate periodically — catch cross-feature issues before they compound.
MIT