{"id":47594431,"url":"https://github.com/mariano-aguero/spec-driven-development-skill","last_synced_at":"2026-05-11T03:58:21.247Z","repository":{"id":345395117,"uuid":"1185738126","full_name":"mariano-aguero/spec-driven-development-skill","owner":"mariano-aguero","description":"Agent skill that brings spec-driven development to AI coding agents: constitution → specify → plan → tasks → implement → validate, with drift detection, MoSCoW priorities, and quality gates. Works with Claude Code, Cursor, Copilot, Junie, Windsurf.","archived":false,"fork":false,"pushed_at":"2026-05-11T01:12:40.000Z","size":292,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T02:25:40.123Z","etag":null,"topics":["ai-agent","ai-coding","claude-code","claude-skill","cursor","github-copilot","spec-driven-development","workflow"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mariano-aguero.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"mariano-aguero"}},"created_at":"2026-03-18T22:31:53.000Z","updated_at":"2026-05-11T01:12:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mariano-aguero/spec-driven-development-skill","commit_stats":null,"previous_names":["mariano-aguero/spec-driven-development-skill"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/mariano-aguero/spec-driven-development-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariano-aguero%2Fspec-driven-development-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariano-aguero%2Fspec-driven-development-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariano-aguero%2Fspec-driven-development-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariano-aguero%2Fspec-driven-development-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mariano-aguero","download_url":"https://codeload.github.com/mariano-aguero/spec-driven-development-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariano-aguero%2Fspec-driven-development-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32880788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-coding","claude-code","claude-skill","cursor","github-copilot","spec-driven-development","workflow"],"created_at":"2026-04-01T17:55:28.989Z","updated_at":"2026-05-11T03:58:21.241Z","avatar_url":"https://github.com/mariano-aguero.png","language":null,"funding_links":["https://github.com/sponsors/mariano-aguero"],"categories":[],"sub_categories":[],"readme":"# Spec-Driven Development Skill\n\n[![skills.sh](https://img.shields.io/badge/skills.sh-spec--driven--development-blue?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMiAxNWwtNS01IDEuNDEtMS40MUwxMCAxNC4xN2w3LjU5LTcuNTlMMTkgOGwtOSA5eiIvPjwvc3ZnPg==)](https://skills.sh)\n[![npm](https://img.shields.io/badge/npx_skills_add-mariano--aguero%2Fspec--driven--development--skill-brightgreen)](https://github.com/mariano-aguero/spec-driven-development-skill)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Latest release](https://img.shields.io/github/v/release/mariano-aguero/spec-driven-development-skill?label=release\u0026color=orange)](https://github.com/mariano-aguero/spec-driven-development-skill/releases/latest)\n[![Last commit](https://img.shields.io/github/last-commit/mariano-aguero/spec-driven-development-skill?color=informational)](https://github.com/mariano-aguero/spec-driven-development-skill/commits/main)\n[![GitHub stars](https://img.shields.io/github/stars/mariano-aguero/spec-driven-development-skill?style=social)](https://github.com/mariano-aguero/spec-driven-development-skill/stargazers)\n\n[![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-purple)](https://claude.ai/code)\n[![Cursor](https://img.shields.io/badge/Cursor-compatible-purple)](https://cursor.sh)\n[![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-compatible-purple)](https://github.com/features/copilot)\n[![JetBrains Junie](https://img.shields.io/badge/JetBrains_Junie-compatible-purple)](https://www.jetbrains.com/junie/)\n[![Windsurf](https://img.shields.io/badge/Windsurf-compatible-purple)](https://codeium.com/windsurf)\n\n\u003e **Stop vibe-coding. Specify, then implement.**\n\u003e An **Agent Skill** that turns informal prompts into structured, traceable, drift-resistant\n\u003e specifications — so AI coding agents build what you actually asked for.\n\nCompatible with Claude Code, Cursor, GitHub Copilot, JetBrains Junie, Windsurf, and similar tools.\n\n---\n\n## Why Spec-Driven Development?\n\nWithout a spec, AI agents make thousands of micro-decisions silently. Each one is a\npotential divergence from intent — and they compound.\n\n| Without SDD | With SDD |\n|---|---|\n| \"Add user auth\" → AI picks a stack, invents schema, guesses error behavior | Constitution + spec + contracts define every decision upfront |\n| Same prompt, three sessions, three different implementations | Specs are the source of truth — regeneration is deterministic |\n| Drift discovered in code review (or production) | Drift detected in Phase 5 against the locked contracts |\n| Pivots = manual rewrites | Pivots = systematic re-specification |\n| Implicit assumptions baked into acceptance criteria | Assumptions surfaced and corrected *before* the spec is written |\n\n## What is Spec-Driven Development?\n\nSDD makes **specifications the source of truth**. The workflow:\n\n0. **Constitution** — project-level immutable constraints (one-time per project)\n1. **Specify** — requirements, MoSCoW acceptance criteria, boundaries\n2. **Plan** — architecture, data model, locked API contracts\n3. **Tasks** — atomic, dependency-mapped, test-first\n4. **Implement** — AI runs with fresh context per task, constrained by all artifacts above\n5. **Validate** — drift detection + traceability matrix\n\n```mermaid\nflowchart LR\n    P0[\"Phase 0\u003cbr/\u003e\u003cb\u003e/sdd:init\u003c/b\u003e\u003cbr/\u003econstitution.md\"]:::once --\u003e P1\n    P1[\"Phase 1\u003cbr/\u003e\u003cb\u003e/sdd:specify\u003c/b\u003e\u003cbr/\u003espec.md\"] --\u003e CL[\"Clarify\u003cbr/\u003eresolve [NEEDS CLARIFICATION]\"]\n    CL --\u003e G1{Gate 1}\n    G1 --\u003e|approved| P2[\"Phase 2\u003cbr/\u003e\u003cb\u003e/sdd:plan\u003c/b\u003e\u003cbr/\u003eplan + data-model + contracts\"]\n    P2 --\u003e G2{Gate 2}\n    G2 --\u003e|approved \u0026 contracts LOCKED| P3[\"Phase 3\u003cbr/\u003e\u003cb\u003e/sdd:tasks\u003c/b\u003e\u003cbr/\u003etasks.md\"]\n    P3 --\u003e G3{Gate 3}\n    G3 --\u003e|approved| P4[\"Phase 4\u003cbr/\u003eImplement\u003cbr/\u003efresh context per task\"]\n    P4 --\u003e P5[\"Phase 5\u003cbr/\u003e\u003cb\u003e/sdd:validate\u003c/b\u003e\u003cbr/\u003edrift detection\"]\n\n    classDef once fill:#f0e6ff,stroke:#7c3aed,stroke-width:2px\n```\n\n## Installation\n\n```bash\nnpx skills add mariano-aguero/spec-driven-development-skill\n```\n\nThe skill activates automatically when you reference spec-driven development, spec authoring,\nSDD, requirements planning, or AI implementation guidance.\n\n## Workflow at a Glance\n\n```text\n/sdd:init                                 # once per project\n  → creates constitution.md\n\n/sdd:specify \"add user authentication\"\n  → creates specs/user-auth/spec.md       (MoSCoW ACs + Boundaries + open questions)\n\n/sdd:clarify\n  → resolves [NEEDS CLARIFICATION] before Plan\n\n/sdd:plan\n  → specs/user-auth/plan.md               (architecture, risks)\n  → specs/user-auth/data-model.md         (entities + migrations)\n  → specs/user-auth/contracts/auth-api.md (LOCKED after Gate 2 approval)\n\n/sdd:tasks\n  → specs/user-auth/tasks.md              (ordered, test-first, [P] for parallel)\n\n# implement each task with fresh AI context; commit after each\n\n/sdd:validate\n  → traceability matrix + drift report\n```\n\nOther commands: `/sdd:analyze` (cross-feature conflict check), `/sdd:amend` (cascade spec updates).\n\n## What's Included\n\n| File | Contents |\n|------|---------|\n| `SKILL.md` | Entry point: 6-phase workflow, spec levels, reference index |\n| `references/artifact-templates.md` | Templates for `constitution.md`, `spec.md`, `plan.md`, `data-model.md`, `contracts/`, `tasks.md`, `research.md`, `decision_log.md` |\n| `references/prompt-patterns.md` | Prompts for every phase + Assumptions Surface, Clarify, Critics, `/sdd:analyze`, `/sdd:amend`, Constitution-from-Codebase |\n| `references/workflow-phases.md` | Step-by-step instructions for Phases 0–5 |\n| `references/quality-gates.md` | Gate 0–5 checklists + CI/CD integration (AC coverage, drift detection) |\n| `references/ai-agent-patterns.md` | Multi-agent orchestration, context management, critic subagents, capability profiles |\n| `references/anti-patterns.md` | 16 common failure modes with wrong/correct examples and fixes |\n| `references/quick-reference.md` | One-page cheat sheet |\n| `references/INDEX.md` | Topic navigation across all references |\n\n## Complete Example\n\nSee [`examples/`](examples/) for a full end-to-end demonstration of every SDD artifact:\na magic-link login feature with `constitution.md`, `spec.md`, `plan.md`, `data-model.md`,\nlocked `contracts/`, and a dependency-mapped `tasks.md`. Use it as a reference or as a\nstarter you can clone into a new project.\n\n## When to Use SDD\n\n**Use it when:**\n\n- AI generates code that ignores your constraints\n- The same prompt produces different implementations across sessions\n- Requirements are complex or have multiple stakeholders\n- The feature touches auth, database schema, or public APIs\n- Your team needs shared technical understanding before writing code\n\n**Skip it for:**\n\n- Bug fixes under 30 minutes\n- Refactors with no behavior change\n- Throwaway prototypes\n\n## Key Principles\n\n**Specifications are not suggestions.** API contracts define the exact shape. Code that\ndeviates from the contract is drift — fix the code, not the spec.\n\n**Surface assumptions before specifying.** Ask the AI to list its implicit assumptions\nabout roles, permissions, error behavior, and scope *before* writing the spec. Correcting\na wrong assumption takes seconds; correcting a wrong AC takes a full `/sdd:amend` cycle.\n\n**Reframe vague requirements.** \"Make it faster\" is not a spec. \"LCP \u003c 2.5s on a 4G\nconnection\" is. Every AC must be independently testable — if you cannot write a failing\ntest for it, it is not concrete enough.\n\n**Fresh context per task.** Each task gets its own AI session. Accumulated context from\nprior sessions introduces wrong assumptions.\n\n**Commit after each task.** Not at the end of Phase 4. After each individual task.\nClean history enables precise rollback when drift is discovered.\n\n**Commit specs with code.** Spec files belong in the same PR as the implementation they\ndrive. Treat them as first-class source artifacts, not throwaway documents.\n\n**Human gates are non-negotiable.** `spec.md`, `plan.md`, and `tasks.md` each require human\napproval before the next phase begins. AI cannot approve its own output.\n\n## AI Tool Compatibility\n\n| Tool | Status | Notes |\n|------|--------|-------|\n| Claude Code | ✅ Native | Skill loaded via `skills.sh`; Format A prompts (filesystem access) |\n| Cursor | ✅ Supported | Reference files loaded via `@` mentions |\n| GitHub Copilot Chat | ✅ Supported | Format B prompts (stateless) for web/chat interfaces |\n| JetBrains Junie | ✅ Supported | Reference files loaded as context |\n| Windsurf | ✅ Supported | Skill activates on SDD keyword triggers |\n| Any LLM (ChatGPT, Gemini, etc.) | ✅ Manual | Copy reference files into context; use Format B prompts |\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a full history of changes per version.\n\nLatest: **v1.4.0** — AP-15, AP-16, Constitution from Existing Codebase, Cross-Feature Conflict Detector.\nSee the [latest release](https://github.com/mariano-aguero/spec-driven-development-skill/releases/latest) for full notes.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines on\nadding anti-patterns, prompts, templates, and workflow improvements.\n\nPlease follow our [Code of Conduct](.github/CODE_OF_CONDUCT.md).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariano-aguero%2Fspec-driven-development-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmariano-aguero%2Fspec-driven-development-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariano-aguero%2Fspec-driven-development-skill/lists"}