mouredev/hello-sdd: a Spec-Driven Development course repo with templates and a Python CLI

The problem hello-sdd addresses: prompts that are improvised instead of agreed

The README frames the whole repository around one contrast: developing software with AI agents starting from an agreed specification rather than improvising prompts. That is the problem statement, and it is aimed at developers who already use coding agents and have noticed that the output drifts when the instruction is a one-line request. The audience is therefore people who write code with an agent in the loop, not people evaluating specification languages in the abstract.

The repository is not a library you import. It contains two things, in the README's own words: the templates used in the course under samples/, and a complete project built step by step with SDD under habits-cli/. The templates are AGENTS.md, spec.md, prompts.md and an Excalidraw whiteboard. The project is a Python CLI for logging study habits and viewing a consecutive-day streak, exposing habits add, habits done and habits list. The README is explicit that the app is not the point: what matters is how it was built, and each step of the SDD flow left an artifact behind. If you want a tool, this is the wrong repository. If you want to see what the artifacts of a spec-first workflow actually look like when someone finishes one, it is a readable example.

How the flow works: constitution, spec, clarification, plan, tasks, implementation, validation

The README compresses the method into one line: Constitution, Spec, Clarification, Plan, Tasks, Implementation (one task at a time, tests first), Validation, Change (spec first, then code). Each stage maps to a file you can open, which is the useful part. docs/constitution.md holds six non-negotiable principles. specs/001-habits-mvp/spec.md holds functional requirements RF-1 through RF-11 written in EARS notation. specs/001-habits-mvp/plan.md covers modules, the data model, the streak algorithm, the CLI contract and technical decisions. specs/001-habits-mvp/tasks.md lists T1 through T8 with checkboxes and a "Done when:" condition for each. Implementation lives in habits/ (split into core, storage and cli) plus tests/, and validation is described as walking requirement by requirement and checking which test covers each one.

Two details distinguish this from a folder of markdown. First, clarification is a separate stage: the spec is reviewed as QA to find ambiguities and gaps before planning, which means the plan is not allowed to paper over an unclear requirement. Second, change is ordered, spec before code. That ordering is the mechanism that keeps the artifacts from becoming stale documentation, and it is also the part that costs discipline. The agent context is split across AGENTS.md and CLAUDE.md, and the README notes CLAUDE.md can simply be @AGENTS.md. The template for AGENTS.md is described as covering what the project is, commands, style, rules and mandatory verification at the end, so the agent is told how to check its own work rather than only what to produce. There is also a reusable skill, spec-generator, under .claude/skills/spec-generator/, which guides the requirements interview and generates the spec from the template; it is linked for opencode under .opencode/skill/.

Getting the templates and running the habits CLI for the first time

There is no package to install. The repository is a clone-and-read collection, and the README states that watching the course is indispensable for understanding the content, so treat the video as the entry point rather than the code. The README does not give a git clone command; the repository layout it prints shows the two top-level pieces, samples/ and habits-cli/:

HelloSDD/
├── samples/            # Plantillas y material del curso
│   ├── AGENTS.md       # Plantilla de instrucciones para el agente
│   ├── spec.md         # Plantilla de especificación (RF en notación EARS)
│   ├── prompts.md      # Prompt esencial de cada fase del flujo SDD
│   └── sdd.excalidraw  # Pizarra del curso (guion por bloques y diagramas)
└── habits-cli/         # Proyecto práctico desarrollado con SDD

That is the whole map. The whiteboard file opens at excalidraw.com according to the README.

The CLI is written in Python using only the standard library, so no dependency installation is described. The README points to habits-cli/README.md for the exact prompts of each step and for how to run the app and its tests. The commands the CLI exposes are named in the README as habits add, habits done and habits list:

habits add
habits done
habits list

The README does not spell out the arguments, the output format, the storage file location or the exit codes, so read habits-cli/README.md and the storage module before assuming anything about how state is written.

To reuse the templates, the two files that carry the method are the agent context and the spec. Copy them into your own project and fill in the numbered requirements using EARS notation, as the template does, keeping the "Done when:" style when you break the spec into tasks. The prompts.md file is a table mapping each phase (constitution, spec, clarification, plan, tasks, implementation, validation, change) to its essential prompt, which is the piece you paste into the agent at each stage.

The limits: a course repository, not a maintained framework

The most important limitation is written into the README in bold: watching the course is indispensable for understanding the repository content. That is an unusual thing for a project to say about itself, and it should be read literally. The templates are teaching material. AGENTS.md and spec.md are starting points you adapt, not a specification format with a parser, a validator or a schema behind it. Nothing in the repository checks that your RF-x entries are well formed or that every requirement has a test; the validation step is described as a manual walkthrough, requirement by requirement.

The habits-cli project is a demonstration, and its scope is deliberately small: three commands, standard library only, one feature folder under specs/. It is not a template for a multi-service system, and it says nothing about how the flow behaves when several people edit the same spec, when a requirement changes after implementation, or when an agent produces code that passes tests but misses a requirement. The repository also has no releases, so there is no versioned artifact to pin and no upgrade path to follow. The last push to the default branch was on 2026-08-27, which is recent, but recency of commits is not the same as a support commitment, and the README offers no support channel beyond the author's community links.

One more practical constraint: the skill is tied to two specific agent environments, Claude under .claude/skills/spec-generator/ and opencode under .opencode/skill/. If you use a different agent, the spec-generator interview is not wired up for you, and you would be copying the template by hand.

Alternatives: OpenSpec, Spec Kit and Kiro take the tooling route

The searches around this repository are dominated by other names, which is a fair signal about where the category sits. OpenSpec, GitHub's Spec Kit and AWS Kiro all attack the same problem, and the difference is where the specification lives and who enforces it. hello-sdd keeps the spec as plain markdown in a specs/ directory next to the code, with the discipline carried by the developer and the agent context file. The tooling-oriented projects put the spec inside a workflow: Spec Kit ships commands and templates that scaffold a feature's spec, plan and tasks inside the editor, and Kiro builds the spec step into the IDE itself. In both cases the structure is generated for you, which reduces the chance of an empty template sitting unfilled, at the cost of adopting that tool's conventions.

The honest comparison is that hello-sdd teaches the reasoning and the others automate it. If you want a worked example of what a constitution with six principles looks like, or how RF-1 through RF-11 read in EARS, hello-sdd gives you the artifact. If you want the agent to be unable to skip the spec stage, you need tooling that enforces the stage, because a markdown file cannot. The search results also suggest people look for how to apply these flows to existing projects and monorepos; the repository's single-feature example does not address either case, so those questions have to be answered elsewhere.

Licence, maintenance and the cost of keeping specs current

The repository is licensed Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved; the LICENSE file is at the top level. The templates are documents rather than code, so if you copy AGENTS.md and spec.md into a proprietary repository, the practical question is whether you keep an attribution notice. That is a question for your own legal review, not something this article can settle, and the repository does not state a position on it. The habits-cli code carries the same licence.

Maintenance is the weaker side. There are no releases, so there is nothing to pin and no changelog to read before upgrading. The last push to the default branch was on 2026-08-27. Since the value here is the method and the templates rather than a dependency, the upgrade cost is mostly your own: every time the spec changes, the plan, the tasks and the tests are supposed to follow, and the README's ordering rule puts the spec edit first. That is cheap for one feature and expensive for a codebase where requirements arrive faster than anyone rewrites them. Budget for the discipline, not for a version bump.

Editorial conclusion

Adopt hello-sdd if you want a worked example of writing an EARS specification before letting an agent generate code, and you are willing to watch the linked course video first, because the README states it is indispensable for understanding the repository contents. Skip it if you are looking for a pip-installable tool or a drop-in framework: the repository holds course templates in samples/ and one demo project in habits-cli/, and the README does not document any packaging, versioning or rollback process. Before relying on the templates, open samples/spec.md and samples/AGENTS.md and check whether the RF-x numbering and the verification rule at the end of AGENTS.md match how your team already reviews changes.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. mouredev/hello-sdd on GitHub
4. Project website
5. README