Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs(assess): clarify README invocation guidance (#5068)

WOLIKIMCHENG80f5935f045d
diff --git a/bundles/assess/bundle.yml b/bundles/assess/bundle.yml
index f704b632c..5466b2ce6 100644
--- a/bundles/assess/bundle.yml
+++ b/bundles/assess/bundle.yml
@@ -17,7 +17,7 @@ requires:
provides:
extensions:
- id: "assess"
- version: "1.0.1"
+ version: "1.0.2"
workflows:
- id: "assess"
version: "1.0.0"
diff --git a/extensions/assess/README.md b/extensions/assess/README.md
index 857bb4221..655c5ae45 100644
--- a/extensions/assess/README.md
+++ b/extensions/assess/README.md
@@ -2,7 +2,7 @@
A five-stage assessment pipeline for Spec Kit that turns **any idea** into a defensible **go / needs-clarification / kill** decision *before* it enters Spec-Driven Development. It is the missing **discovery track** that sits in front of the SDD **delivery track** (`specify β†’ clarify β†’ plan β†’ tasks β†’ analyze β†’ implement`).
-Discovery answers *"is this worth building?"* Delivery answers *"how do we build it?"* Only ideas that survive assessment hand off to `/speckit.specify`.
+Discovery answers *"is this worth building?"* Delivery answers *"how do we build it?"* Only ideas that survive assessment hand off to `/speckit-specify`.
## Overview
@@ -12,11 +12,11 @@ Each idea lives in its own directory under `.specify/assessments/<slug>/`, with
```
.specify/assessments/<slug>/
-β”œβ”€β”€ intake.md # speckit.assess.intake β€” capture the raw idea
-β”œβ”€β”€ research.md # speckit.assess.research β€” gather (and challenge with) evidence
-β”œβ”€β”€ problem.md # speckit.assess.define β€” define the problem, goals, metrics
-β”œβ”€β”€ concept.md # speckit.assess.shape β€” shape solution options + appetite
-└── decision.md # speckit.assess.decide β€” go / needs-clarification / kill β†’ handoff
+β”œβ”€β”€ intake.md # /speckit-assess-intake β€” capture the raw idea
+β”œβ”€β”€ research.md # /speckit-assess-research β€” gather (and challenge with) evidence
+β”œβ”€β”€ problem.md # /speckit-assess-define β€” define the problem, goals, metrics
+β”œβ”€β”€ concept.md # /speckit-assess-shape β€” shape solution options + appetite
+└── decision.md # /speckit-assess-decide β€” go / needs-clarification / kill β†’ handoff
```
The pipeline is a **funnel**: most ideas should be killed or parked before `shape`. Killing an idea with a documented reason is a successful outcome, not a failure.
@@ -24,7 +24,7 @@ The pipeline is a **funnel**: most ideas should be killed or parked before `shap
```mermaid
flowchart LR
A[intake] --> R[research] --> D[define] --> S[shape] --> C{decide}
- C -->|go| SPEC[/speckit.specify/]
+ C -->|go| SPEC[/"/speckit-specify"/]
C -->|kill| X[closed, recorded]
C -.->|needs-clarification| F[refine named artifact in place]
F -.->|then revise decision.md| C
@@ -32,13 +32,17 @@ flowchart LR
## Commands
+Slash commands in this README use GitHub Copilot's default skills syntax.
+For another agent, use its
+[equivalent invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation).
+
| Command | Stage | Output |
|---------|-------|--------|
-| `speckit.assess.intake` | Capture & normalize a raw idea (text, URL, ticket, or codebase pointer). | `intake.md` |
-| `speckit.assess.research` | Gather users/market/prior-art/data evidence β€” and evidence *against* the idea. | `research.md` |
-| `speckit.assess.define` | Define the problem: users, goals, non-goals, success metrics, cost of inaction. | `problem.md` |
-| `speckit.assess.shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |
-| `speckit.assess.decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit.specify`. | `decision.md` |
+| `/speckit-assess-intake` | Capture & normalize a raw idea (text, URL, ticket, or codebase pointer). | `intake.md` |
+| `/speckit-assess-research` | Gather users/market/prior-art/data evidence β€” and evidence *against* the idea. | `research.md` |
+| `/speckit-assess-define` | Define the problem: users, goals, non-goals, success metrics, cost of inaction. | `problem.md` |
+| `/speckit-assess-shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |
+| `/speckit-assess-decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit-specify`. | `decision.md` |
Stages are meant to run in order but are not rigidly gated:
@@ -65,14 +69,14 @@ Then ask whether the new information clears the blocker and to update any downst
When you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.
-Rerunning an earlier `speckit.assess.*` command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.
+Rerunning an earlier assessment command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.
## Slug Conventions
A *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.
- **User-provided**: normalized to lowercase kebab-case (e.g. `offline-mode`, `cut-onboarding-friction`). Preserved verbatim after normalization β€” no timestamps or numbers appended.
-- **Asked for**: in interactive use, `speckit.assess.intake` asks for a slug when none is supplied, suggesting a kebab-case default derived from the idea.
+- **Asked for**: in interactive use, `/speckit-assess-intake` asks for a slug when none is supplied, suggesting a kebab-case default derived from the idea.
- **Automated**: when no human is available, the agent generates a unique slug and never overwrites an existing assessment directory (appending `-2`, `-3`, … or a short date as needed).
- **Reuse from context**: later stages reuse the slug reported earlier in the same session, confirmed by the presence of the assessment directory.
@@ -91,31 +95,37 @@ specify extension enable assess
## Typical Flow
-```bash
+Run these skills in your agent's chat, not your terminal, one at a time,
+reviewing each result before continuing.
+
+This example uses GitHub Copilot's default skills syntax. For another agent,
+use its [equivalent invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation).
+
+```text
# 1. Capture an idea (pasted text, a URL, or "assess this repo")
-/speckit.assess.intake "Let users work offline and sync when they reconnect" slug=offline-mode
+/speckit-assess-intake "Let users work offline and sync when they reconnect" slug=offline-mode
# 2. Gather evidence β€” and reasons it might not be worth it
-/speckit.assess.research slug=offline-mode
+/speckit-assess-research slug=offline-mode
# 3. Define the actual problem
-/speckit.assess.define slug=offline-mode
+/speckit-assess-define slug=offline-mode
# 4. Shape 2–3 concept options with appetites
-/speckit.assess.shape slug=offline-mode
+/speckit-assess-shape slug=offline-mode
# 5. Decide β€” go, clarify, or kill
-/speckit.assess.decide slug=offline-mode
-# β†’ on "go", hand the decision.md handoff summary to /speckit.specify
+/speckit-assess-decide slug=offline-mode
+# β†’ on "go", optionally pass the decision.md handoff summary to /speckit-specify
```
## Handoff
-`assess` is a **standalone pipeline you enter deliberately** β€” it registers no lifecycle hooks and never inserts itself into `/speckit.specify`. The only coupling runs forward and by choice: a `go` verdict from `/speckit.assess.decide` hands its `decision.md` summary to `/speckit.specify`. Discovery and specification stay separate processes.
+`assess` is a **standalone pipeline you enter deliberately** β€” it registers no lifecycle hooks and never inserts itself into `/speckit-specify`. The only coupling runs forward and by choice: a `go` verdict from `/speckit-assess-decide` hands its `decision.md` summary to `/speckit-specify`. Discovery and specification stay separate processes.
## Guardrails
-- Only `speckit.assess.*` commands write, and only inside `.specify/assessments/<slug>/`. **None of them modify source code** β€” solution design and implementation belong to the SDD lifecycle (`/speckit.specify` onward).
+- Only the five assessment commands write, and only inside `.specify/assessments/<slug>/`. **None of them modify source code** β€” solution design and implementation belong to the SDD lifecycle (`/speckit-specify` onward).
- Web content fetched during `intake`/`research` is treated as untrusted data, governed by an explicit URL Trust Policy (allowlisted public sources fetched freely; unknown hosts prompted or skipped; loopback/RFC1918/metadata endpoints refused).
- Evidence is never over-claimed: unsourced statements are tagged `ASSUMPTION`, and `research.md` always includes an *Evidence Against the Idea* section.
- Verdicts are never over-claimed: a `go` requires a valid problem, `adequate`+ evidence (never weak/unknown), and a shaped concept; otherwise the honest verdict is `needs-clarification`.
@@ -124,4 +134,4 @@ specify extension enable assess
## Relationship to Other Extensions
-`assess` is deliberately the **generic, role-neutral** discovery track β€” usable by a founder, PM, BA, engineer, or designer. Richer or more specialized pre-SDD flows in the community catalog (e.g. product-lifecycle orchestrators, technical-discovery, intake-normalization, brownfield onboarding) can layer on top of or feed into it; `assess` aims to be the minimal, opinionated funnel that ends cleanly at the `/speckit.specify` handoff.
+`assess` is deliberately the **generic, role-neutral** discovery track β€” usable by a founder, PM, BA, engineer, or designer. Richer or more specialized pre-SDD flows in the community catalog (e.g. product-lifecycle orchestrators, technical-discovery, intake-normalization, brownfield onboarding) can layer on top of or feed into it; `assess` aims to be the minimal, opinionated funnel that ends cleanly at the `/speckit-specify` handoff.
diff --git a/extensions/assess/extension.yml b/extensions/assess/extension.yml
index 42b281b8e..1b6341e34 100644
--- a/extensions/assess/extension.yml
+++ b/extensions/assess/extension.yml
@@ -3,7 +3,7 @@ schema_version: "1.0"
extension:
id: assess
name: "Idea Assessment Pipeline"
- version: "1.0.1"
+ version: "1.0.2"
description: "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments/<slug>/"
category: "process"
effect: "read-write"
diff --git a/extensions/catalog.json b/extensions/catalog.json
index c20cec03e..5bd7235b8 100644
--- a/extensions/catalog.json
+++ b/extensions/catalog.json
@@ -20,7 +20,7 @@
"assess": {
"name": "Idea Assessment Pipeline",
"id": "assess",
- "version": "1.0.1",
+ "version": "1.0.2",
"description": "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments/<slug>/",
"author": "spec-kit-core",
"repository": "https://github.com/github/spec-kit",