Spec-driven development as agentic GitHub Actions workflows.
spectacles is a suite of agentic workflows (built on
gh-aw) that move a feature from a plain
GitHub issue to a merged implementation through a disciplined pipeline:
spec then architecture then triage then execute then validate then review.
The whole pipeline is operated through GitHub primitives only: issues,
comments, labels, and pull requests. There is no separate tool and no UI.
| Stage | Agent | Output |
|---|---|---|
| Spec | sdd-spec |
a structured spec, delivered as a PR |
| Architecture and triage | sdd-triage |
an architecture record, then a task graph of linked sub-issues |
| Execute | sdd-execute |
an implementation PR with captured proof artifacts |
| Validate | sdd-validate |
advisory gate findings at every phase boundary |
| Review | sdd-review |
correctness, security, and spec-compliance review comments |
needs-human is the single agent-to-human hand-off label: an agent applies it
when it cannot safely proceed, and a human clears it to resume the pipeline.
See decisions/0001-needs-human.md.
The suite is built. The repository foundation, the human-interaction
contract, the shared MCP tooling, and all five pipeline agents are in place;
the issue-native SDD spec
defines the full design across ten demoable units. The first live pipeline
run is an operator acceptance step: see the
install guide and
decisions/0003-bootstrapping-policy.md.
spectacles installs onto a consumer repo, including one with an existing
codebase, with scripts/quick-setup.sh --suite sdd. See the
install guide for the steps, the required
configuration, and a post-install smoke test, and
workflows/README.md for the reusable-workflow plus
thin-wrapper distribution model.
MIT. See LICENSE.