From b08ae10ff8c590d54db7619b3d4570eae7b5b24c Mon Sep 17 00:00:00 2001 From: meow2149 Date: Tue, 2 Jun 2026 11:15:44 +0800 Subject: [PATCH 1/4] docs: add hands-off orchestration example Signed-off-by: meow2149 Co-authored-by: Cursor --- docs/community/hands-off-orchestration.md | 67 +++++++++++++++++++++++ docs/community/walkthroughs.md | 2 + docs/toc.yml | 2 + 3 files changed, 71 insertions(+) create mode 100644 docs/community/hands-off-orchestration.md diff --git a/docs/community/hands-off-orchestration.md b/docs/community/hands-off-orchestration.md new file mode 100644 index 0000000000..0ea45df9ab --- /dev/null +++ b/docs/community/hands-off-orchestration.md @@ -0,0 +1,67 @@ +# Hands-Off Orchestration Example + +This example shows how to ask an AI coding agent to run a hands-off, artifact-first Spec Kit flow without moving into issue creation or implementation by default. + +Use this pattern when you want a repeatable planning pass that produces reviewed artifacts first: + +```text +/speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze +``` + +The key rule is that the agent stops after analysis unless the user explicitly asks it to continue. + +## Guardrails + +- Generate and review artifacts before creating issues or writing code. +- Ask the user when a product decision is required. +- Loop back to the earlier stage when a later stage finds stale, incomplete, or inconsistent artifacts. +- Do not run `/speckit.taskstoissues` unless the user explicitly requests issue creation. +- Do not run `/speckit.implement` unless the user explicitly requests implementation. + +## Example Agent Prompt + +Copy this prompt into your agent after initializing a Spec Kit project: + +```text +Run an artifact-first Spec Kit orchestration flow for the following feature: + + + +Follow this sequence: + +1. Run /speckit.specify for the requested feature. +2. Run /speckit.clarify to identify ambiguity. If a real product decision is required, stop and ask me before continuing. +3. Run /speckit.plan after the specification is clear enough to plan. +4. Run /speckit.checklist and fix requirement-quality gaps by looping back to /speckit.clarify or /speckit.specify as needed. +5. Run /speckit.tasks after the plan and checklist are consistent. +6. Run /speckit.analyze to check cross-artifact consistency. +7. Stop after analysis and report the generated artifacts, open questions, and recommended next step. + +Do not create GitHub issues unless I explicitly ask for issue creation. +Do not implement tasks unless I explicitly ask for implementation. +``` + +## Optional Follow-Up Prompts + +After reviewing the generated artifacts, continue with one of these explicit prompts: + +```text +Create GitHub issues from the generated tasks, but do not implement them. +``` + +```text +Implement the generated tasks now. +``` + +Keeping issue creation and implementation as separate follow-up prompts makes the default flow safe for planning, design review, and handoff scenarios. + +## When To Use This Pattern + +Use this pattern when: + +- A team lead wants implementation-ready artifacts before assigning work. +- A project wants consistent specs, plans, and tasks for every feature request. +- The feature has enough ambiguity that clarification and checklist passes are useful. +- You want automation to prepare work, but not silently create issues or write code. + +For smaller experiments, the shorter workflow in the [Quick Start Guide](../quickstart.md) may be enough. diff --git a/docs/community/walkthroughs.md b/docs/community/walkthroughs.md index b32c025803..20ebda0721 100644 --- a/docs/community/walkthroughs.md +++ b/docs/community/walkthroughs.md @@ -5,6 +5,8 @@ See Spec-Driven Development in action across different scenarios with these community-contributed walkthroughs: +- **[Hands-off orchestration example](hands-off-orchestration.md)** — Shows an artifact-first flow that runs specify, clarify, plan, checklist, tasks, and analyze, then stops before issue creation or implementation unless the user explicitly opts in. + - **[Greenfield .NET CLI tool](https://github.com/mnriem/spec-kit-dotnet-cli-demo)** — Builds a Timezone Utility as a .NET single-binary CLI tool from a blank directory, covering the full spec-kit workflow: constitution, specify, plan, tasks, and multi-pass implement using GitHub Copilot agents. - **[Greenfield Spring Boot + React platform](https://github.com/mnriem/spec-kit-spring-react-demo)** — Builds an LLM performance analytics platform (REST API, graphs, iteration tracking) from scratch using Spring Boot, embedded React, PostgreSQL, and Docker Compose, with a clarify step and a cross-artifact consistency analysis pass included. diff --git a/docs/toc.yml b/docs/toc.yml index ce91339a1b..56bab3f9b4 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -60,5 +60,7 @@ href: community/presets.md - name: Walkthroughs href: community/walkthroughs.md + - name: Hands-Off Orchestration + href: community/hands-off-orchestration.md - name: Friends href: community/friends.md From 0ccb82126f0c2772dca8943a9d4d4a65fe3f0e5f Mon Sep 17 00:00:00 2001 From: meow2149 Date: Wed, 3 Jun 2026 01:20:11 +0800 Subject: [PATCH 2/4] docs: clarify orchestration example guidance Signed-off-by: meow2149 Co-authored-by: Cursor --- docs/community/hands-off-orchestration.md | 6 +++--- docs/community/walkthroughs.md | 12 +++++++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/community/hands-off-orchestration.md b/docs/community/hands-off-orchestration.md index 0ea45df9ab..32615e14c4 100644 --- a/docs/community/hands-off-orchestration.md +++ b/docs/community/hands-off-orchestration.md @@ -14,7 +14,7 @@ The key rule is that the agent stops after analysis unless the user explicitly a - Generate and review artifacts before creating issues or writing code. - Ask the user when a product decision is required. -- Loop back to the earlier stage when a later stage finds stale, incomplete, or inconsistent artifacts. +- Loop back to an earlier stage when a later stage finds stale, incomplete, or inconsistent artifacts. - Do not run `/speckit.taskstoissues` unless the user explicitly requests issue creation. - Do not run `/speckit.implement` unless the user explicitly requests implementation. @@ -46,11 +46,11 @@ Do not implement tasks unless I explicitly ask for implementation. After reviewing the generated artifacts, continue with one of these explicit prompts: ```text -Create GitHub issues from the generated tasks, but do not implement them. +Run /speckit.taskstoissues to create GitHub issues from the generated tasks, but do not implement them. ``` ```text -Implement the generated tasks now. +Run /speckit.implement to implement the generated tasks now. ``` Keeping issue creation and implementation as separate follow-up prompts makes the default flow safe for planning, design review, and handoff scenarios. diff --git a/docs/community/walkthroughs.md b/docs/community/walkthroughs.md index 20ebda0721..ea01a9faef 100644 --- a/docs/community/walkthroughs.md +++ b/docs/community/walkthroughs.md @@ -1,12 +1,18 @@ # Community Walkthroughs -> [!NOTE] -> Community walkthroughs are independently created and maintained by their respective authors. They are **not reviewed, nor endorsed, nor supported by GitHub**. Review their content before following along and use at your own discretion. +## Spec Kit Examples -See Spec-Driven Development in action across different scenarios with these community-contributed walkthroughs: +These examples are maintained in the Spec Kit documentation: - **[Hands-off orchestration example](hands-off-orchestration.md)** — Shows an artifact-first flow that runs specify, clarify, plan, checklist, tasks, and analyze, then stops before issue creation or implementation unless the user explicitly opts in. +## Community Walkthroughs + +> [!NOTE] +> External community walkthroughs are independently created and maintained by their respective authors. They are **not reviewed, nor endorsed, nor supported by GitHub**. Review their content before following along and use at your own discretion. + +See Spec-Driven Development in action across different scenarios with these community-contributed walkthroughs: + - **[Greenfield .NET CLI tool](https://github.com/mnriem/spec-kit-dotnet-cli-demo)** — Builds a Timezone Utility as a .NET single-binary CLI tool from a blank directory, covering the full spec-kit workflow: constitution, specify, plan, tasks, and multi-pass implement using GitHub Copilot agents. - **[Greenfield Spring Boot + React platform](https://github.com/mnriem/spec-kit-spring-react-demo)** — Builds an LLM performance analytics platform (REST API, graphs, iteration tracking) from scratch using Spring Boot, embedded React, PostgreSQL, and Docker Compose, with a clarify step and a cross-artifact consistency analysis pass included. From 5154d17dd1732b0b514799a4d26c780ed28a3d1c Mon Sep 17 00:00:00 2001 From: meow2149 Date: Wed, 3 Jun 2026 21:30:16 +0800 Subject: [PATCH 3/4] docs: align orchestration example workflow Co-authored-by: Cursor --- docs/community/hands-off-orchestration.md | 11 ++++++++--- docs/community/walkthroughs.md | 2 +- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/community/hands-off-orchestration.md b/docs/community/hands-off-orchestration.md index 32615e14c4..835055a702 100644 --- a/docs/community/hands-off-orchestration.md +++ b/docs/community/hands-off-orchestration.md @@ -5,16 +5,20 @@ This example shows how to ask an AI coding agent to run a hands-off, artifact-fi Use this pattern when you want a repeatable planning pass that produces reviewed artifacts first: ```text -/speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze +/speckit.specify -> /speckit.clarify -> /speckit.checklist -> /speckit.plan -> /speckit.tasks -> /speckit.analyze ``` The key rule is that the agent stops after analysis unless the user explicitly asks it to continue. +> [!NOTE] +> This conservative example uses only `README.md` and `DESIGN.md` as in-repo guidance sources unless the user explicitly provides more context. + ## Guardrails - Generate and review artifacts before creating issues or writing code. - Ask the user when a product decision is required. - Loop back to an earlier stage when a later stage finds stale, incomplete, or inconsistent artifacts. +- Use only `README.md` and `DESIGN.md` as in-repo guidance sources unless the user explicitly provides more context. - Do not run `/speckit.taskstoissues` unless the user explicitly requests issue creation. - Do not run `/speckit.implement` unless the user explicitly requests implementation. @@ -31,12 +35,13 @@ Follow this sequence: 1. Run /speckit.specify for the requested feature. 2. Run /speckit.clarify to identify ambiguity. If a real product decision is required, stop and ask me before continuing. -3. Run /speckit.plan after the specification is clear enough to plan. -4. Run /speckit.checklist and fix requirement-quality gaps by looping back to /speckit.clarify or /speckit.specify as needed. +3. Run /speckit.checklist and fix requirement-quality gaps by looping back to /speckit.clarify or /speckit.specify as needed. +4. Run /speckit.plan after the specification passes the requirements checklist. 5. Run /speckit.tasks after the plan and checklist are consistent. 6. Run /speckit.analyze to check cross-artifact consistency. 7. Stop after analysis and report the generated artifacts, open questions, and recommended next step. +Use only README.md and DESIGN.md as in-repo guidance sources unless I explicitly provide more context. Do not create GitHub issues unless I explicitly ask for issue creation. Do not implement tasks unless I explicitly ask for implementation. ``` diff --git a/docs/community/walkthroughs.md b/docs/community/walkthroughs.md index ea01a9faef..940a555c7f 100644 --- a/docs/community/walkthroughs.md +++ b/docs/community/walkthroughs.md @@ -4,7 +4,7 @@ These examples are maintained in the Spec Kit documentation: -- **[Hands-off orchestration example](hands-off-orchestration.md)** — Shows an artifact-first flow that runs specify, clarify, plan, checklist, tasks, and analyze, then stops before issue creation or implementation unless the user explicitly opts in. +- **[Hands-off orchestration example](hands-off-orchestration.md)** — Shows an artifact-first flow that runs specify, clarify, checklist, plan, tasks, and analyze, then stops before issue creation or implementation unless the user explicitly opts in. ## Community Walkthroughs From 0dbf86bea65c76427421e4356c0395d8ecd3e70c Mon Sep 17 00:00:00 2001 From: meow2149 Date: Thu, 4 Jun 2026 10:30:49 +0800 Subject: [PATCH 4/4] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/community/hands-off-orchestration.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/community/hands-off-orchestration.md b/docs/community/hands-off-orchestration.md index 835055a702..fb2e7e76dd 100644 --- a/docs/community/hands-off-orchestration.md +++ b/docs/community/hands-off-orchestration.md @@ -8,6 +8,8 @@ Use this pattern when you want a repeatable planning pass that produces reviewed /speckit.specify -> /speckit.clarify -> /speckit.checklist -> /speckit.plan -> /speckit.tasks -> /speckit.analyze ``` +This ordering matches the [Quick Start Guide](../quickstart.md) workflow, where `/speckit.checklist` is a requirements-quality gate before `/speckit.plan`. + The key rule is that the agent stops after analysis unless the user explicitly asks it to continue. > [!NOTE]