💫 Toolkit to help you get started with SDD or any other process!
docs: explain how Spec Kit uses an agentic SDLC (#4774)
Manfred Riem8d3f64cdccc8
diff --git a/docs/README.md b/docs/README.mdindex d787a4b6f..49936c014 100644--- a/docs/README.md+++ b/docs/README.md@@ -28,6 +28,7 @@ To build the documentation locally:- `toc.yml` - Table of contents configuration- `installation.md` - Installation guide- `quickstart.md` - Spec-Driven Development walkthrough+- `guides/agentic-sdlc.md` - How Spec Kit applies agentic and conventional SDLC practices to itself- `guides/bugfix.md` - Bug-fixing walkthrough- `guides/assessment.md` - Idea assessment walkthrough- `guides/customization.md` - Choosing and combining customization building blocksdiff --git a/docs/guides/agentic-sdlc.md b/docs/guides/agentic-sdlc.mdnew file mode 100644index 000000000..eafa14da6--- /dev/null+++ b/docs/guides/agentic-sdlc.md@@ -0,0 +1,285 @@+# How Spec Kit Develops Spec Kit: An Agentic SDLC++Spec Kit's own development combines agentic work with conventional software+delivery. Agents assess feature requests, help develop substantial changes,+and investigate reported bugs. The project also uses Spec Kit itself where+its processes fit, while deterministic tests and releases remain ordinary+GitHub Actions and maintainers make the decisions to proceed or merge.++Public workflows and a historical feature provide the evidence for this case+study. They show different paths through the project's SDLC, including where+the project uses Spec Kit itself.++## The project's software development life cycle++The traditional stages locate the project's practices across its SDLC.++```mermaid+flowchart LR+ P["Planning"] --> Q["Requirements"] --> D["Design"] --> I["Development"]+ I --> T["Testing"] --> R["Deployment"] --> M["Maintenance"]+```++These stages are a map, not a required sequence. Work can begin wherever+its starting material and goal call for it: a feature request in planning,+an existing change in testing, or a bug report in maintenance. Stages can+overlap, repeat, or be skipped; one feature issue can feed an assessment,+record requirements, and carry design discussion. The arrows show one+familiar path, not mandatory transitions between SDLC stages.+Feedback from maintenance can inform the next planning cycle.++## Who does the work++These modes illustrate how work gets done here; they are not an exhaustive+taxonomy or inventory of activities. A stage can combine them.++**Regular automation.** Scripts and bots follow predefined rules to run+checks, propose dependency updates, and publish releases. They do not+interpret feature requests or choose designs.++**Agent automation.** A coding agent interprets context and produces an+assessment, SDD artifacts, a proposed change, or a test report. It may run+through a contributor-invoked Spec Kit command, a contributor's own agent,+or a label-triggered repository workflow. Running an agent on GitHub+Actions does not make its reasoning a deterministic script.++A star (★) marks agentic work: before prose paragraphs and after+timeline items. A person (👤) highlights human contributions in the+stage narratives, including work done with an agent's help.++**Human work.** People can frame issues, discuss approaches, write or revise+changes, and review evidence, with or without an agent's help. Maintainers+apply labels to start repository workflows and decide whether to proceed+or merge. Those handoffs are human decisions, not evidence that people+authored every assessment, specification, fix, or test report.++## How the project works at each stage++### 1. Planning: assess feature requests++A feature can enter planning through the+[feature request form](https://github.com/github/spec-kit/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml).+It asks for the problem, proposed solution, alternatives, component, and use+cases. The resulting issue starts with `needs-triage`; filing it does not+automatically launch an agent.++★ When a feature request is labeled for assessment, the+[feature-assess agentic workflow](https://github.com/github/spec-kit/blob/main/.github/workflows/feature-assess.md)+provisions the Specify CLI from the checkout, installs Spec Kit's bundled+[`assess` extension](assessment.md), and follows its intake, research, define,+shape, and decide stages. The agent posts its evidence and a `go`,+`needs-clarification`, or `kill` verdict to the issue. **This is an agentic+workflow using Spec Kit itself.**++👤 Contributors frame the request; maintainers decide whether to+initiate assessment and how to act on its verdict. A `go` finding informs+that planning decision; it does not automatically open a feature PR or+start SDD.++### 2. Requirements: record the intent in issues or specs++👤 Contributors can record early requirements in the same feature issue+through its problem statement, use cases, and acceptance criteria, then+clarify or revise the intent during discussion. For a bounded change, that+may be enough; it does not have to become an SDD `spec.md`.++★ For substantial changes, contributors can instead expand the requirements+with Spec Kit's core SDD commands against the project's constitution. Spec Kit+used this process on itself in the+[historical bundler work](https://github.com/github/spec-kit/commit/3fd1e54d4b237af6124bb967e2eae24c93685a89):+the commit contains a constitution and feature specification for the+`specify bundle` command. This is evidence of **SDD dogfooding for that+feature**; the bundler work is distinct from the current `feature-assess`+workflow. The+[contribution guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#does-spec-kit-use-spec-kit)+asks contributors to test relevant changes with SDD while allowing small fixes+to use the normal issue and PR process. Generated `specs/` artifacts are+normally gitignored; the linked commit preserves a historical snapshot.++### 3. Design: choose an approach at the right scale++👤 The feature form's proposed solution and alternatives can seed a+design discussion; contributors and maintainers can refine the approach+during PR review. A separate SDD plan is not required for every issue.+Larger changes need prior discussion and agreement with maintainers, as the+[contribution guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#submitting-a-pull-request)+explains. When decisions should remain useful across changes, the repository+keeps [CLI](https://github.com/github/spec-kit/blob/main/design/cli.md),+[integration](https://github.com/github/spec-kit/blob/main/design/integration.md),+and [workflow-step](https://github.com/github/spec-kit/blob/main/design/workflow-step.md)+design documents.++★ The [bundler SDD snapshot](https://github.com/github/spec-kit/commit/3fd1e54d4b237af6124bb967e2eae24c93685a89)+illustrates the deeper path: its plan, research, data model, contracts, and+tasks made the design actionable through `/speckit.plan` and+`/speckit.tasks`. This shows where Spec Kit itself was used without+presenting that level of detail as the default for every change.++### 4. Development: make reviewable changes++The [bundler implementation](https://github.com/github/spec-kit/pull/3070)+added `specify bundle` after the recorded SDD work. This is a concrete+specification-led feature in the project. Other bounded changes use the+ordinary issue, PR, review, and test process.++👤 Contributors can implement and revise changes directly or with an+agent's help. Maintainers review the resulting PR and its evidence, even+when an agent produced the proposed change.++★ Contributors can use their own agents, independently of the repository's+workflows. Because that work may not be visible in a diff, the+[contribution policy](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit)+requires disclosure of the tool, model, settings or mode, and extent of AI+assistance. Agent-authored commits and comments need their own attribution;+the known bug-fix and community-catalog workflows are exempt because their+agent identity is inherent. Disclosure provides provenance, not a lower+evidence or review bar.++### 5. Testing: verify both intent and behavior++★ The bundler work includes a+[convergence pass](https://github.com/github/spec-kit/commit/de1c8ce6765f07cd1c4728a251b95adbfa3a8d07)+that appended a missing task. This is one example of Spec Kit's SDD process+checking implementation against intent rather than treating the first pass+as complete. The+[bug-test workflow](https://github.com/github/spec-kit/blob/main/.github/workflows/bug-test.md)+uses an agent to select relevant tests, but the test commands themselves+still run deterministically.++Separately, conventional GitHub Actions run+[Python tests and Ruff](https://github.com/github/spec-kit/blob/main/.github/workflows/test.yml),+[Markdown linting for documentation and ShellCheck for shell scripts](https://github.com/github/spec-kit/blob/main/.github/workflows/lint.yml),+and [CodeQL](https://github.com/github/spec-kit/blob/main/.github/workflows/codeql.yml)+on PRs and pushes to `main`. Agentic convergence complements those+independent checks.++👤 Contributors supply tests and reproduction evidence for changes;+maintainers assess whether the patch and evidence address the stated need,+not just whether the checks passed.++### 6. Deployment: publish without an agent++The Spec Kit repository uses regular GitHub Actions for delivery. The+[manually dispatched release trigger](https://github.com/github/spec-kit/blob/main/.github/workflows/release-trigger.yml)+sets the version, creates a tag, and opens a release PR. The tag triggers a+conventional+[GitHub Release](https://github.com/github/spec-kit/blob/main/.github/workflows/release.yml).+A separately dispatched workflow+[builds and publishes to PyPI](https://github.com/github/spec-kit/blob/main/.github/workflows/publish-pypi.yml);+a `docs/` change on `main` triggers+[DocFX deployment](https://github.com/github/spec-kit/blob/main/.github/workflows/docs.yml).+These conventional Actions handle deterministic delivery without an agent+or a Spec Kit command.++👤 Maintainers choose when to start a release and whether to specify+a version rather than use the automatic patch increment. They later dispatch+PyPI publishing for that tag and review the release PR.++### 7. Maintenance: investigate, repair, and learn++👤 Reporters supply observed and expected behavior and reproduction+steps through the+[bug report form](https://github.com/github/spec-kit/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml).+Maintainers triage the report, choose when to request each agentic step,+and review the proposed fix and test evidence before merging. Reports can+arise before or after release; a newly discovered need can feed the next+planning cycle instead of being folded into a repair.++★ The repository uses separate+[bug-assess](https://github.com/github/spec-kit/blob/main/.github/workflows/bug-assess.md),+[bug-fix](https://github.com/github/spec-kit/blob/main/.github/workflows/bug-fix.md),+and [bug-test](https://github.com/github/spec-kit/blob/main/.github/workflows/bug-test.md)+agentic workflows on issues. They separate diagnosis, remediation, and+verification with human-controlled handoffs; the fix is proposed as a draft+PR for maintainer review. **Today these project+workflows do not consume Spec Kit's bundled+[`bug` extension](bugfix.md)**, even though it offers a corresponding+assess, fix, test process for users. Having the workflows use that extension+is a direction for future work, not a current capability or a promised+release.++Agentic and conventional workflows both run on GitHub Actions. What changes+is whether an agent interprets evidence or proposes a change.+[Dependabot](https://github.com/github/spec-kit/blob/main/.github/dependabot.yml)+also proposes weekly pip and GitHub Actions dependency-update PRs for+maintainer review; it is conventional automation, not an agentic workflow.++## Extensibility and community practice++Extensibility cuts across this SDLC: the project builds and distributes+processes as well as using them. The team ships the+[`assess` bundle](https://github.com/github/spec-kit/tree/main/bundles/assess)+and [`bugfix` bundle](https://github.com/github/spec-kit/tree/main/bundles/bugfix),+each combining an extension with a resumable *Spec Kit workflow* and a human+review gate. It also ships the+[`lean` preset](https://github.com/github/spec-kit/tree/main/presets/lean)+to demonstrate an alternative way of shaping core SDD guidance. These are+Spec Kit's own [extensions, presets, workflows, and bundles](customization.md),+not the repository's GitHub Actions workflows.++★ Beyond core feature delivery, agentic community-submission workflows for+[extensions](https://github.com/github/spec-kit/blob/main/.github/workflows/add-community-extension.md),+[presets](https://github.com/github/spec-kit/blob/main/.github/workflows/add-community-preset.md),+and [bundles](https://github.com/github/spec-kit/blob/main/.github/workflows/add-community-bundle.md)+validate submission metadata and propose catalog changes in draft PRs for+maintainer review.++Catalog discovery does not audit or endorse community code; users must+review third-party components before use.++## How we went from SDLC to an agentic SDLC++Agentic practices were layered into an existing SDLC, not substituted for+conventional checks and releases. The commit history shows how that mix+emerged over time. These are selected milestones, not an exhaustive+changelog. The same star marks agentic milestones, including use of Spec+Kit's SDD process; conventional automation and policies are unmarked.++| Month | What changed |+| --- | --- |+| August 2025 | <ul><li><a href="https://github.com/github/spec-kit/commit/28fdfaa8">GitHub Release automation</a> was added.</li></ul> |+| 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> |+| 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> |+| 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> |+| 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> |+| 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> |+| 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> |+| 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> |+| 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> |++This was not a handoff from conventional automation to agents. Tests, lint,+scanning, and publishing kept repeatable work in GitHub Actions, while+disclosure made contributor-run agents visible. The project added agentic+catalog and bug workflows for bounded tasks, used SDD on a substantial+feature, and later made feature assessment consume Spec Kit's `assess`+extension. These were separate additions, not steps every issue must follow.++Together they give the project choices. For features, `assess` can inform a+human decision about a request; substantial implementation work can use SDD+to specify and plan it, as the bundler did. There is no automatic handoff+between those processes. A small change can stay in an issue and PR, while+a bug can move through human-gated assessment, repair, and verification.+Code changes still face conventional checks and maintainer review; issue+verdicts and catalog proposals have their own human gates.++## A production practice, not a prescribed recipe++For this public open-source project, a new issue is untrusted input, not+permission to run an agent. A maintainer activates each repository-owned+agentic workflow with its label and decides when work advances; contributors+can also bring their own agents, subject to disclosure and review. These are+deliberate boundaries for this project, not inherent limits of Spec Kit.++A closed project with a different trust model could automate more handoffs+between assessment, specification, implementation, and testing, while+keeping permissions, evidence, and review appropriate to the risk. Spec Kit's+production mix is not a prescribed recipe: teams can adopt agents in+different places, with or without Spec Kit's processes. That mix can change+with the project's needs and practices.++Here, agentic does not mean human-free: contributors still bring problems,+requirements, and changes; maintainers steer product direction, guide+delivery, and review evidence. Conventional automation handles repeatable+checks and publishing, while agents help with bounded work that requires+interpretation. This division aims to focus human time on judgment, though+the timeline shows adoption rather than measured time savings.diff --git a/docs/index.md b/docs/index.mdindex d7f4ca97e..15dd7f9e3 100644--- a/docs/index.md+++ b/docs/index.md@@ -27,6 +27,9 @@ These are independent entry points, not mandatory phases. SDD ships in core.Bug fixing and assessment are bundled, opt-in extensions. Assessment can standalone; a decision to proceed does not automatically start implementation.+See [how the Spec Kit project runs its agentic SDLC](guides/agentic-sdlc.md)+and where it uses Spec Kit itself.+Adding Spec Kit to an established codebase? Start with the[existing-project guide](guides/existing-projects.md).@@ -139,6 +142,10 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a## Explore the docs<div class="nav-cards">+ <a href="guides/agentic-sdlc.md" class="nav-card">+ <strong>Spec Kit's Agentic SDLC</strong>+ <span>How this project assesses, builds, tests, ships, and repairs changes</span>+ </a><a href="quickstart.md" class="nav-card"><strong>Spec-Driven Development</strong><span>Define, plan, implement, and converge on a feature</span>@@ -198,4 +205,4 @@ Ready to start? [Choose your process](#choose-your-process).</div>-<p class="text-end small text-body-secondary">Last updated: September 14, 2026</p>+<p class="text-end small text-body-secondary">Last updated: September 28, 2026</p>diff --git a/docs/toc.yml b/docs/toc.ymlindex c1811f197..063aaff62 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -11,6 +11,8 @@items:- name: Installationhref: installation.md+ - name: Spec Kit's Agentic SDLC+ href: guides/agentic-sdlc.md- name: Spec-Driven Developmenthref: quickstart.md- name: Bug Fixing