Skip to content

💫 Toolkit to help you get started with SDD or any other process!

fix(plan): clarify quickstart validation guide scope (#2805)

WOLIKIMCHENG6d511acfb9df
diff --git a/templates/commands/plan.md b/templates/commands/plan.md
index b44854f45..44ab8403a 100644
--- a/templates/commands/plan.md
+++ b/templates/commands/plan.md
@@ -147,7 +147,14 @@ Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generate
- Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
- Skip if project is purely internal (build scripts, one-off tools, etc.)
-3. **Agent context update**:
+3. **Create quickstart validation guide** → `quickstart.md`:
+ - Document runnable validation scenarios that prove the feature works end-to-end
+ - Include prerequisites, setup commands, test/run commands, and expected outcomes
+ - Use links or references to contracts and data model details instead of duplicating them
+ - Do not include full implementation code, model/service/controller bodies, migrations, or complete test suites
+ - Keep this artifact as a validation/run guide; implementation details belong in `tasks.md` and the implementation phase
+
+4. **Agent context update**:
- Update the plan reference between the `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` markers in `__CONTEXT_FILE__` to point to the plan file created in step 1 (the IMPL_PLAN path)
**Output**: data-model.md, /contracts/*, quickstart.md, updated agent context file
diff --git a/tests/integrations/test_integration_generic.py b/tests/integrations/test_integration_generic.py
index 856b34e0f..84f0f277d 100644
--- a/tests/integrations/test_integration_generic.py
+++ b/tests/integrations/test_integration_generic.py
@@ -185,6 +185,20 @@ class TestGenericIntegration:
)
assert "__CONTEXT_FILE__" not in content
+ def test_plan_defines_quickstart_as_validation_guide(self, tmp_path):
+ """The generated plan command should keep quickstart.md out of implementation scope."""
+ i = get_integration("generic")
+ m = IntegrationManifest("generic", tmp_path)
+ i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+ plan_file = tmp_path / ".custom" / "cmds" / "speckit.plan.md"
+ assert plan_file.exists()
+ content = plan_file.read_text(encoding="utf-8")
+
+ assert "Create quickstart validation guide" in content
+ assert "runnable validation scenarios" in content
+ assert "Do not include full implementation code" in content
+ assert "implementation details belong in `tasks.md` and the implementation phase" in content
+
def test_implement_loads_constitution_context(self, tmp_path):
"""The generated implement command should load constitution governance context."""
i = get_integration("generic")