sdd-agentic-flow

Coding agents can start writing code before the request is understood, drift outside the task, and report work as done without executable proof. Reviewers then have to reconstruct intent from the diff before they can check behavior.

I wanted a way to delegate work to agents that keeps the intent written down, the scope bounded, and the evidence inspectable, without handing over decisions that should stay with a person.

The specification comes first and lives in the repository. Twelve Markdown skills cover the path from plan to prompt, implementation, task check, pull request, review, fix and validation. Each phase writes artifacts a reviewer can open.

A small CLI acts as the control plane: it installs the skill bundle, initializes a workspace and diagnoses the setup. It never runs skills itself. The coding-agent host (Codex, Cursor, Claude Code or VS Code with Copilot) executes the work.

Skills are the capability layer and the host owns execution. That keeps the toolkit portable across agents. The cost is that it cannot force runtime behavior, so it relies on contracts, gates and evidence instead.

No runtime npm dependencies, a user-local install by default and configuration only when you create it. The trust surface stays small and setup is reversible with an uninstall plan.

Autonomy has explicit limits. Manual, supervised and autonomous modes decide how much progression the agent owns, but commit, push, merge, publish and deploy always stay with a person.

Claims stay measured. The project does not quote token or speed gains without data, and its contract parser rejects unknown keys and executable YAML features.

Unit tests cover the CLI modules, and scripted CLI journeys exercise install, init, doctor, upgrade and uninstall end to end. Golden example walkthroughs document the artifact shapes each workflow produces, labeled as illustrations rather than evidence of agent behavior.