Software Development Playbook

This repository is a set of composable skills for guiding AI-assisted software development from an unclear request to a reviewed, publishable change. It turns a large delivery process into small, explicit stages with clear inputs, outputs, handoffs, and mutation boundaries.

The playbook is designed to keep work understandable and safe: clarify uncertainty before designing, specify before implementing, split work into small vertical slices, verify changes before committing, and publish only the branch and draft pull request that the user requested. Each skill owns one responsibility and stops before the next stage unless it explicitly delegates an internal discipline such as TDD or review.

How to use it

Use the skills individually when a task needs one focused discipline, or combine them into the delivery path:

$clarify → $specify → $slice → $implement → $commit → $publish

The stages do not automatically invoke one another. Invoke the orchestration and publishing stages explicitly with their skill name, such as $specify, $slice, $commit, or $publish. The other skills can be invoked directly when the request clearly fits them.

After this repository is published, install it through the skills CLI:

npx skills@latest add https://github.com/ako-v/software-development-playbook.git

Then invoke the skill that matches the current stage of work. A task does not need to start at the beginning of the path: use $diagnose for an existing failure, $review for a read-only assessment, $tdd for one small behavior, or $summarize when a faithful handoff is needed.

Workflow

Stage	Skill	Outcome	Mutation boundary
Understand	clarify	Confirmed shared understanding	Read-only by default; approved domain documentation only in domain-modeling mode
Define	specify	Approval-ready or approved specification	The identified specification artifact or requested tracker issue only
Decompose	slice	Approved vertical-slice task set	Task artifacts or requested tracker issues only
Build	implement	Reviewed, verified, uncommitted code	Requested implementation and approved overlapping work only
Commit	commit	Logical local commits	Git index and new local commits only
Publish	publish	Pushed branch and draft pull request	Current branch and its draft pull request only

Three skills also work independently:

• diagnose finds a supported root cause without modifying or fixing the system.
• review reports severity-ranked correctness/spec and standards/design findings without editing code.
• summarize creates a faithful summary or an explicitly requested durable handoff.

tdd is the red-green-refactor discipline used for one small behavior and composed by implement when practical.

Invocation policy

The orchestration or publishing commands specify, slice, commit, publish, and summarize require explicit invocation with $skill-name. The reusable disciplines clarify, diagnose, implement, review, and tdd remain available for implicit invocation when a request clearly fits.

No skill automatically advances into the next delivery stage. Completion messages may suggest the next existing skill but do not invoke it.

Validation

Run the repository validator after changing a skill:

./scripts/validate-skills.ps1

It validates package structure, frontmatter, UI metadata, invocation policy, Markdown references, cross-skill references, line limits, and UTF-8 integrity. CI runs the same check.