|
| 1 | +# How Spec Kit Develops Spec Kit: An Agentic SDLC |
| 2 | + |
| 3 | +Spec Kit's own development combines agentic work with conventional software |
| 4 | +delivery. Agents assess feature requests, help develop substantial changes, |
| 5 | +and investigate reported bugs. The project also uses Spec Kit itself where |
| 6 | +its processes fit, while deterministic tests and releases remain ordinary |
| 7 | +GitHub Actions and maintainers make the decisions to proceed or merge. |
| 8 | + |
| 9 | +Public workflows and a historical feature provide the evidence for this case |
| 10 | +study. They show different paths through the project's SDLC, including where |
| 11 | +the project uses Spec Kit itself. |
| 12 | + |
| 13 | +## The project's software development life cycle |
| 14 | + |
| 15 | +The traditional stages locate the project's practices across its SDLC. |
| 16 | + |
| 17 | +```mermaid |
| 18 | +flowchart LR |
| 19 | + P["Planning"] --> Q["Requirements"] --> D["Design"] --> I["Development"] |
| 20 | + I --> T["Testing"] --> R["Deployment"] --> M["Maintenance"] |
| 21 | +``` |
| 22 | + |
| 23 | +These stages are a map, not a required sequence. Work can begin wherever |
| 24 | +its starting material and goal call for it: a feature request in planning, |
| 25 | +an existing change in testing, or a bug report in maintenance. Stages can |
| 26 | +overlap, repeat, or be skipped; one feature issue can feed an assessment, |
| 27 | +record requirements, and carry design discussion. The arrows show one |
| 28 | +familiar path, not mandatory transitions between SDLC stages. |
| 29 | +Feedback from maintenance can inform the next planning cycle. |
| 30 | + |
| 31 | +## Who does the work |
| 32 | + |
| 33 | +These modes illustrate how work gets done here; they are not an exhaustive |
| 34 | +taxonomy or inventory of activities. A stage can combine them. |
| 35 | + |
| 36 | +**Regular automation.** Scripts and bots follow predefined rules to run |
| 37 | +checks, propose dependency updates, and publish releases. They do not |
| 38 | +interpret feature requests or choose designs. |
| 39 | + |
| 40 | +**Agent automation.** A coding agent interprets context and produces an |
| 41 | +assessment, SDD artifacts, a proposed change, or a test report. It may run |
| 42 | +through a contributor-invoked Spec Kit command, a contributor's own agent, |
| 43 | +or a label-triggered repository workflow. Running an agent on GitHub |
| 44 | +Actions does not make its reasoning a deterministic script. |
| 45 | + |
| 46 | +A star (★) marks agentic work: before prose paragraphs and after |
| 47 | +timeline items. A person (👤) highlights human contributions in the |
| 48 | +stage narratives, including work done with an agent's help. |
| 49 | + |
| 50 | +**Human work.** People can frame issues, discuss approaches, write or revise |
| 51 | +changes, and review evidence, with or without an agent's help. Maintainers |
| 52 | +apply labels to start repository workflows and decide whether to proceed |
| 53 | +or merge. Those handoffs are human decisions, not evidence that people |
| 54 | +authored every assessment, specification, fix, or test report. |
| 55 | + |
| 56 | +## How the project works at each stage |
| 57 | + |
| 58 | +### 1. Planning: assess feature requests |
| 59 | + |
| 60 | +A feature can enter planning through the |
| 61 | +[feature request form](https://github.com/github/spec-kit/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml). |
| 62 | +It asks for the problem, proposed solution, alternatives, component, and use |
| 63 | +cases. The resulting issue starts with `needs-triage`; filing it does not |
| 64 | +automatically launch an agent. |
| 65 | + |
| 66 | +★ When a feature request is labeled for assessment, the |
| 67 | +[feature-assess agentic workflow](https://github.com/github/spec-kit/blob/main/.github/workflows/feature-assess.md) |
| 68 | +provisions the Specify CLI from the checkout, installs Spec Kit's bundled |
| 69 | +[`assess` extension](assessment.md), and follows its intake, research, define, |
| 70 | +shape, and decide stages. The agent posts its evidence and a `go`, |
| 71 | +`needs-clarification`, or `kill` verdict to the issue. **This is an agentic |
| 72 | +workflow using Spec Kit itself.** |
| 73 | + |
| 74 | +👤 Contributors frame the request; maintainers decide whether to |
| 75 | +initiate assessment and how to act on its verdict. A `go` finding informs |
| 76 | +that planning decision; it does not automatically open a feature PR or |
| 77 | +start SDD. |
| 78 | + |
| 79 | +### 2. Requirements: record the intent in issues or specs |
| 80 | + |
| 81 | +👤 Contributors can record early requirements in the same feature issue |
| 82 | +through its problem statement, use cases, and acceptance criteria, then |
| 83 | +clarify or revise the intent during discussion. For a bounded change, that |
| 84 | +may be enough; it does not have to become an SDD `spec.md`. |
| 85 | + |
| 86 | +★ For substantial changes, contributors can instead expand the requirements |
| 87 | +with Spec Kit's core SDD commands against the project's constitution. Spec Kit |
| 88 | +used this process on itself in the |
| 89 | +[historical bundler work](https://github.com/github/spec-kit/commit/3fd1e54d4b237af6124bb967e2eae24c93685a89): |
| 90 | +the commit contains a constitution and feature specification for the |
| 91 | +`specify bundle` command. This is evidence of **SDD dogfooding for that |
| 92 | +feature**; the bundler work is distinct from the current `feature-assess` |
| 93 | +workflow. The |
| 94 | +[contribution guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#does-spec-kit-use-spec-kit) |
| 95 | +asks contributors to test relevant changes with SDD while allowing small fixes |
| 96 | +to use the normal issue and PR process. Generated `specs/` artifacts are |
| 97 | +normally gitignored; the linked commit preserves a historical snapshot. |
| 98 | + |
| 99 | +### 3. Design: choose an approach at the right scale |
| 100 | + |
| 101 | +👤 The feature form's proposed solution and alternatives can seed a |
| 102 | +design discussion; contributors and maintainers can refine the approach |
| 103 | +during PR review. A separate SDD plan is not required for every issue. |
| 104 | +Larger changes need prior discussion and agreement with maintainers, as the |
| 105 | +[contribution guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#submitting-a-pull-request) |
| 106 | +explains. When decisions should remain useful across changes, the repository |
| 107 | +keeps [CLI](https://github.com/github/spec-kit/blob/main/design/cli.md), |
| 108 | +[integration](https://github.com/github/spec-kit/blob/main/design/integration.md), |
| 109 | +and [workflow-step](https://github.com/github/spec-kit/blob/main/design/workflow-step.md) |
| 110 | +design documents. |
| 111 | + |
| 112 | +★ The [bundler SDD snapshot](https://github.com/github/spec-kit/commit/3fd1e54d4b237af6124bb967e2eae24c93685a89) |
| 113 | +illustrates the deeper path: its plan, research, data model, contracts, and |
| 114 | +tasks made the design actionable through `/speckit.plan` and |
| 115 | +`/speckit.tasks`. This shows where Spec Kit itself was used without |
| 116 | +presenting that level of detail as the default for every change. |
| 117 | + |
| 118 | +### 4. Development: make reviewable changes |
| 119 | + |
| 120 | +The [bundler implementation](https://github.com/github/spec-kit/pull/3070) |
| 121 | +added `specify bundle` after the recorded SDD work. This is a concrete |
| 122 | +specification-led feature in the project. Other bounded changes use the |
| 123 | +ordinary issue, PR, review, and test process. |
| 124 | + |
| 125 | +👤 Contributors can implement and revise changes directly or with an |
| 126 | +agent's help. Maintainers review the resulting PR and its evidence, even |
| 127 | +when an agent produced the proposed change. |
| 128 | + |
| 129 | +★ Contributors can use their own agents, independently of the repository's |
| 130 | +workflows. Because that work may not be visible in a diff, the |
| 131 | +[contribution policy](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit) |
| 132 | +requires disclosure of the tool, model, settings or mode, and extent of AI |
| 133 | +assistance. Agent-authored commits and comments need their own attribution; |
| 134 | +the known bug-fix and community-catalog workflows are exempt because their |
| 135 | +agent identity is inherent. Disclosure provides provenance, not a lower |
| 136 | +evidence or review bar. |
| 137 | + |
| 138 | +### 5. Testing: verify both intent and behavior |
| 139 | + |
| 140 | +★ The bundler work includes a |
| 141 | +[convergence pass](https://github.com/github/spec-kit/commit/de1c8ce6765f07cd1c4728a251b95adbfa3a8d07) |
| 142 | +that appended a missing task. This is one example of Spec Kit's SDD process |
| 143 | +checking implementation against intent rather than treating the first pass |
| 144 | +as complete. The |
| 145 | +[bug-test workflow](https://github.com/github/spec-kit/blob/main/.github/workflows/bug-test.md) |
| 146 | +uses an agent to select relevant tests, but the test commands themselves |
| 147 | +still run deterministically. |
| 148 | + |
| 149 | +Separately, conventional GitHub Actions run |
| 150 | +[Python tests and Ruff](https://github.com/github/spec-kit/blob/main/.github/workflows/test.yml), |
| 151 | +[Markdown linting for documentation and ShellCheck for shell scripts](https://github.com/github/spec-kit/blob/main/.github/workflows/lint.yml), |
| 152 | +and [CodeQL](https://github.com/github/spec-kit/blob/main/.github/workflows/codeql.yml) |
| 153 | +on PRs and pushes to `main`. Agentic convergence complements those |
| 154 | +independent checks. |
| 155 | + |
| 156 | +👤 Contributors supply tests and reproduction evidence for changes; |
| 157 | +maintainers assess whether the patch and evidence address the stated need, |
| 158 | +not just whether the checks passed. |
| 159 | + |
| 160 | +### 6. Deployment: publish without an agent |
| 161 | + |
| 162 | +The Spec Kit repository uses regular GitHub Actions for delivery. The |
| 163 | +[manually dispatched release trigger](https://github.com/github/spec-kit/blob/main/.github/workflows/release-trigger.yml) |
| 164 | +sets the version, creates a tag, and opens a release PR. The tag triggers a |
| 165 | +conventional |
| 166 | +[GitHub Release](https://github.com/github/spec-kit/blob/main/.github/workflows/release.yml). |
| 167 | +A separately dispatched workflow |
| 168 | +[builds and publishes to PyPI](https://github.com/github/spec-kit/blob/main/.github/workflows/publish-pypi.yml); |
| 169 | +a `docs/` change on `main` triggers |
| 170 | +[DocFX deployment](https://github.com/github/spec-kit/blob/main/.github/workflows/docs.yml). |
| 171 | +These conventional Actions handle deterministic delivery without an agent |
| 172 | +or a Spec Kit command. |
| 173 | + |
| 174 | +👤 Maintainers choose when to start a release and whether to specify |
| 175 | +a version rather than use the automatic patch increment. They later dispatch |
| 176 | +PyPI publishing for that tag and review the release PR. |
| 177 | + |
| 178 | +### 7. Maintenance: investigate, repair, and learn |
| 179 | + |
| 180 | +👤 Reporters supply observed and expected behavior and reproduction |
| 181 | +steps through the |
| 182 | +[bug report form](https://github.com/github/spec-kit/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml). |
| 183 | +Maintainers triage the report, choose when to request each agentic step, |
| 184 | +and review the proposed fix and test evidence before merging. Reports can |
| 185 | +arise before or after release; a newly discovered need can feed the next |
| 186 | +planning cycle instead of being folded into a repair. |
| 187 | + |
| 188 | +★ The repository uses separate |
| 189 | +[bug-assess](https://github.com/github/spec-kit/blob/main/.github/workflows/bug-assess.md), |
| 190 | +[bug-fix](https://github.com/github/spec-kit/blob/main/.github/workflows/bug-fix.md), |
| 191 | +and [bug-test](https://github.com/github/spec-kit/blob/main/.github/workflows/bug-test.md) |
| 192 | +agentic workflows on issues. They separate diagnosis, remediation, and |
| 193 | +verification with human-controlled handoffs; the fix is proposed as a draft |
| 194 | +PR for maintainer review. **Today these project |
| 195 | +workflows do not consume Spec Kit's bundled |
| 196 | +[`bug` extension](bugfix.md)**, even though it offers a corresponding |
| 197 | +assess, fix, test process for users. Having the workflows use that extension |
| 198 | +is a direction for future work, not a current capability or a promised |
| 199 | +release. |
| 200 | + |
| 201 | +Agentic and conventional workflows both run on GitHub Actions. What changes |
| 202 | +is whether an agent interprets evidence or proposes a change. |
| 203 | +[Dependabot](https://github.com/github/spec-kit/blob/main/.github/dependabot.yml) |
| 204 | +also proposes weekly pip and GitHub Actions dependency-update PRs for |
| 205 | +maintainer review; it is conventional automation, not an agentic workflow. |
| 206 | + |
| 207 | +## Extensibility and community practice |
| 208 | + |
| 209 | +Extensibility cuts across this SDLC: the project builds and distributes |
| 210 | +processes as well as using them. The team ships the |
| 211 | +[`assess` bundle](https://github.com/github/spec-kit/tree/main/bundles/assess) |
| 212 | +and [`bugfix` bundle](https://github.com/github/spec-kit/tree/main/bundles/bugfix), |
| 213 | +each combining an extension with a resumable *Spec Kit workflow* and a human |
| 214 | +review gate. It also ships the |
| 215 | +[`lean` preset](https://github.com/github/spec-kit/tree/main/presets/lean) |
| 216 | +to demonstrate an alternative way of shaping core SDD guidance. These are |
| 217 | +Spec Kit's own [extensions, presets, workflows, and bundles](customization.md), |
| 218 | +not the repository's GitHub Actions workflows. |
| 219 | + |
| 220 | +★ Beyond core feature delivery, agentic community-submission workflows for |
| 221 | +[extensions](https://github.com/github/spec-kit/blob/main/.github/workflows/add-community-extension.md), |
| 222 | +[presets](https://github.com/github/spec-kit/blob/main/.github/workflows/add-community-preset.md), |
| 223 | +and [bundles](https://github.com/github/spec-kit/blob/main/.github/workflows/add-community-bundle.md) |
| 224 | +validate submission metadata and propose catalog changes in draft PRs for |
| 225 | +maintainer review. |
| 226 | + |
| 227 | +Catalog discovery does not audit or endorse community code; users must |
| 228 | +review third-party components before use. |
| 229 | + |
| 230 | +## How we went from SDLC to an agentic SDLC |
| 231 | + |
| 232 | +Agentic practices were layered into an existing SDLC, not substituted for |
| 233 | +conventional checks and releases. The commit history shows how that mix |
| 234 | +emerged over time. These are selected milestones, not an exhaustive |
| 235 | +changelog. The same star marks agentic milestones, including use of Spec |
| 236 | +Kit's SDD process; conventional automation and policies are unmarked. |
| 237 | + |
| 238 | +| Month | What changed | |
| 239 | +| --- | --- | |
| 240 | +| August 2025 | <ul><li><a href="https://github.com/github/spec-kit/commit/28fdfaa8">GitHub Release automation</a> was added.</li></ul> | |
| 241 | +| September 2025 | <ul><li><a href="https://github.com/github/spec-kit/commit/4b98c20f">Documentation deployment</a> was added.</li><li><a href="https://github.com/github/spec-kit/commit/6f3e450c">Contribution guidelines</a> began requiring disclosure of AI assistance, including contributor-run agents.</li></ul> | |
| 242 | +| October 2025 | <ul><li><a href="https://github.com/github/spec-kit/commit/33a07969">Markdown linting</a> was added to PR and <code>main</code> checks.</li></ul> | |
| 243 | +| February 2026 | <ul><li><a href="https://github.com/github/spec-kit/pull/1622">Dependabot</a> began proposing weekly pip and GitHub Actions dependency-update PRs.</li><li>A <a href="https://github.com/github/spec-kit/commit/9402ebd0">CodeQL workflow</a> was added for code scanning.</li><li><a href="https://github.com/github/spec-kit/pull/1637">Pytest CI</a> began running tests on PRs and pushes to <code>main</code>.</li><li><a href="https://github.com/github/spec-kit/pull/1637">Ruff linting</a> was added to the Python CI workflow.</li></ul> | |
| 244 | +| May 2026 | <ul><li><a href="https://github.com/github/spec-kit/pull/2655">Extension submissions</a> gained catalog validation and draft PRs. ★</li><li><a href="https://github.com/github/spec-kit/pull/2655">Preset submissions</a> gained catalog validation and draft PRs. ★</li></ul> | |
| 245 | +| June 2026 | <ul><li>An <a href="https://github.com/github/spec-kit/pull/3023">agentic bug-assess workflow</a> was added. ★</li><li>The <a href="https://github.com/github/spec-kit/commit/3fd1e54d4b237af6124bb967e2eae24c93685a89">bundler feature</a> used Spec Kit's SDD process to produce its specification, plan, and tasks. ★</li><li><a href="https://github.com/github/spec-kit/pull/2915">PyPI publishing</a> gained a conventional workflow.</li><li><a href="https://github.com/github/spec-kit/pull/3126">ShellCheck</a> began checking shell scripts in CI.</li></ul> | |
| 246 | +| July 2026 | <ul><li><a href="https://github.com/github/spec-kit/pull/3258">Bug-fix</a> extended the agentic issue workflow with a human handoff. ★</li><li><a href="https://github.com/github/spec-kit/pull/3257">Bug-test</a> added a separate verification stage. ★</li><li><a href="https://github.com/github/spec-kit/pull/3553">Bundle submissions</a> gained catalog automation. ★</li></ul> | |
| 247 | +| August 2026 | <ul><li>The <a href="https://github.com/github/spec-kit/pull/4186">feature-assess workflow</a> began using Spec Kit's <code>assess</code> extension on feature requests. ★</li></ul> | |
| 248 | +| September 2026 | <ul><li><a href="https://github.com/github/spec-kit/pull/4512">AI disclosure</a> began requiring agent, model, settings, and extent.</li><li><a href="https://github.com/github/spec-kit/pull/4752">Contribution guidance</a> added attribution for agent-authored commits and comments.</li></ul> | |
| 249 | + |
| 250 | +This was not a handoff from conventional automation to agents. Tests, lint, |
| 251 | +scanning, and publishing kept repeatable work in GitHub Actions, while |
| 252 | +disclosure made contributor-run agents visible. The project added agentic |
| 253 | +catalog and bug workflows for bounded tasks, used SDD on a substantial |
| 254 | +feature, and later made feature assessment consume Spec Kit's `assess` |
| 255 | +extension. These were separate additions, not steps every issue must follow. |
| 256 | + |
| 257 | +Together they give the project choices. For features, `assess` can inform a |
| 258 | +human decision about a request; substantial implementation work can use SDD |
| 259 | +to specify and plan it, as the bundler did. There is no automatic handoff |
| 260 | +between those processes. A small change can stay in an issue and PR, while |
| 261 | +a bug can move through human-gated assessment, repair, and verification. |
| 262 | +Code changes still face conventional checks and maintainer review; issue |
| 263 | +verdicts and catalog proposals have their own human gates. |
| 264 | + |
| 265 | +## A production practice, not a prescribed recipe |
| 266 | + |
| 267 | +For this public open-source project, a new issue is untrusted input, not |
| 268 | +permission to run an agent. A maintainer activates each repository-owned |
| 269 | +agentic workflow with its label and decides when work advances; contributors |
| 270 | +can also bring their own agents, subject to disclosure and review. These are |
| 271 | +deliberate boundaries for this project, not inherent limits of Spec Kit. |
| 272 | + |
| 273 | +A closed project with a different trust model could automate more handoffs |
| 274 | +between assessment, specification, implementation, and testing, while |
| 275 | +keeping permissions, evidence, and review appropriate to the risk. Spec Kit's |
| 276 | +production mix is not a prescribed recipe: teams can adopt agents in |
| 277 | +different places, with or without Spec Kit's processes. That mix can change |
| 278 | +with the project's needs and practices. |
| 279 | + |
| 280 | +Here, agentic does not mean human-free: contributors still bring problems, |
| 281 | +requirements, and changes; maintainers steer product direction, guide |
| 282 | +delivery, and review evidence. Conventional automation handles repeatable |
| 283 | +checks and publishing, while agents help with bounded work that requires |
| 284 | +interpretation. This division aims to focus human time on judgment, though |
| 285 | +the timeline shows adoption rather than measured time savings. |
0 commit comments