SDD Skills

Reusable AI coding-agent skills for running a lightweight Spec-Driven Development (SDD) workflow in real projects.

This repository packages two complementary skills:

• spec-architect turns a feature request, bug report, or design change into a structured, testable specification.
• spec-implementer implements one active specification with strict TDD, verifies the acceptance criteria, and moves the spec through the workflow.

Together they create a small but disciplined loop:

request -> specification -> tests -> implementation -> verification -> done

Why This Exists

AI coding agents are most useful when the work is explicit, scoped, and verifiable. These skills help keep that discipline by separating planning from implementation:

• the architect writes the spec but does not implement code;
• the implementer writes tests first and only implements behavior covered by the active spec;
• acceptance criteria are named consistently so tests and specs can be traced back to each other;
• completed work is documented by moving specs from todo to done.

The result is a simple workflow that is easy to review in pull requests and easy for humans to interrupt, audit, or continue.

Included Skills

spec-architect

Use this skill when you want an agent to turn an idea into a spec before any code is changed.

It will:

• inspect only the repository context needed to write a correct spec;
• classify the work as small, medium, or large;
• create a numbered spec in specs/todo;
• use one of the bundled templates from spec-architect/assets/templates;
• write observable, testable acceptance criteria;
• keep the spec in Draft status.

spec-implementer

Use this skill when you want an agent to implement an existing spec.

It will:

• select a spec from specs/todo or use the spec named by the user;
• move it to specs/inprogress;
• follow red-green-refactor TDD for each acceptance criterion;
• keep implementation scoped to the active spec;
• run the relevant verification;
• check off acceptance criteria only after they are verified;
• move the completed spec to specs/done.

Repository Layout

.
|-- justfile
|-- spec-architect
|   |-- SKILL.md
|   `-- assets
|       `-- templates
|           |-- spec-s.md
|           |-- spec-m.md
|           `-- spec-l.md
`-- spec-implementer
    `-- SKILL.md

Installation

The repository includes a justfile that can install the skills into common agent skill directories by creating symlinks.

By default, installation targets these directories inside a project:

• .claude/skills
• .codex/skills
• .roo/skills

Install All Skills Into a Project

just install /path/to/project

Install One Skill Into a Project

just install /path/to/project spec-architect
just install /path/to/project spec-implementer

Install Globally for the Current User

just install -g

Install One Skill Globally

just install spec-architect -g
just install spec-implementer -g

List Available Skills

just list

Uninstall

just uninstall /path/to/project
just uninstall /path/to/project spec-architect
just uninstall -g

You can customize the destination directories with INSTALL_LOCATIONS:

INSTALL_LOCATIONS=".codex/skills" just install /path/to/project

You can also point the installer at a different source directory with SKILLS_DIR:

SKILLS_DIR=/path/to/skills just list

Expected Project Workflow

In a project that uses these skills, specs normally live in:

specs/
|-- todo
|-- inprogress
`-- done

A typical flow looks like this:

1. Ask the agent to use spec-architect for a feature, bug fix, or design change.
2. Review the generated spec in specs/todo.
3. Ask the agent to use spec-implementer for that spec.
4. Review the tests, implementation, and completed spec in specs/done.

Spec Naming and Traceability

Specs use numeric priority prefixes, for example:

specs/todo/0001-add-calendar-sync.md

Acceptance criteria use stable IDs:

S01AC1
S01AC2
S01AC3

Tests should reference those IDs:

test_S01AC1_creates_calendar_event
it('S01AC1: should create a calendar event')

This makes it easy to see which test proves which requirement.

Contributing

Contributions are welcome. Good changes usually fall into one of these areas:

• improving the wording or boundaries of a skill;
• adding better spec templates;
• making installation work across more agent ecosystems;
• documenting real-world usage patterns;
• tightening the SDD workflow without making it heavy.

When changing a skill, please keep the contract clear:

• spec-architect plans and writes specs, but does not implement code;
• spec-implementer implements active specs, but does not invent missing scope;
• acceptance criteria should remain observable and testable;
• tests should remain traceable to acceptance criteria.

License

This project is licensed under the MIT License. See LICENSE for details.