Skip to content

docs: document high-assurance spec workflow #2518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
officialasishkumar wants to merge 2 commits into
base: main
Choose a base branch
from
+24 −7
Open

docs: document high-assurance spec workflow #2518

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
55b9fe3
docs: document high-assurance workflow
officialasishkumar May 14, 2026
8288897
docs: clarify analyze workflow gate
officialasishkumar May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,19 @@ This guide will help you get started with Spec-Driven Development using Spec Kit
> [!NOTE]
> All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`.

## The 6-Step Process
## Recommended Workflow

> [!TIP]
> **Context Awareness**: Spec Kit commands automatically detect the active feature based on your current Git branch (e.g., `001-feature-name`). To switch between different specifications, simply switch Git branches.

After installing Spec Kit and defining your project constitution, quick experiments can use the lean feature path: `/speckit.specify` -> `/speckit.plan` -> `/speckit.tasks` -> `/speckit.implement`. For production features or any work with meaningful ambiguity, treat `/speckit.clarify`, `/speckit.checklist`, and `/speckit.analyze` as regular quality gates:

```text
/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.checklist -> /speckit.plan -> /speckit.tasks -> /speckit.analyze -> /speckit.implement
```
Comment on lines +15 to +17
Copy link
Copy Markdown
Contributor Author

@officialasishkumar officialasishkumar May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the quickstart to clarify that /speckit.analyze remains the pre-implementation consistency gate, with an optional post-implementation repeat only as an extra review.


Use `/speckit.clarify` to reduce requirement ambiguity before planning, `/speckit.checklist` to validate requirements quality before planning, and `/speckit.analyze` to check spec/plan/task consistency before implementation starts. You can repeat `/speckit.analyze` after implementation as an extra review, but keep the first analysis before `/speckit.implement` so gaps are caught while the plan and tasks can still be adjusted.

### Step 1: Install Specify

**In your terminal**, run the `specify` CLI command to initialize your project:
Expand All @@ -24,10 +32,13 @@ uvx --from git+https://github.com/github/spec-kit.git specify init .

> [!NOTE]
> You can also install the CLI persistently with `pipx`:
>
> ```bash
> pipx install git+https://github.com/github/spec-kit.git
> ```
>
> After installing with `pipx`, run `specify` directly instead of `uvx --from ... specify`, for example:
>
> ```bash
> specify init <PROJECT_NAME>
> specify init .
Expand Down Expand Up @@ -56,14 +67,20 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
```

### Step 4: Refine the Spec
### Step 4: Refine and Validate the Spec

**In the chat**, use the `/speckit.clarify` slash command to identify and resolve ambiguities in your specification. You can provide specific focus areas as arguments.

```bash
/speckit.clarify Focus on security and performance requirements.
```

Then validate the requirements with `/speckit.checklist` before creating the technical plan:

```bash
/speckit.checklist
```

### Step 5: Create a Technical Implementation Plan

**In the chat**, use the `/speckit.plan` slash command to provide your tech stack and architecture choices.
Expand All @@ -72,21 +89,21 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
```

### Step 6: Break Down and Implement
### Step 6: Break Down, Analyze, and Implement

**In the chat**, use the `/speckit.tasks` slash command to create an actionable task list.

```markdown
/speckit.tasks
```

Optionally, validate the plan with `/speckit.analyze`:
Validate cross-artifact consistency with `/speckit.analyze` before implementation:

```markdown
/speckit.analyze
```

Then, use the `/speckit.implement` slash command to execute the plan.
Use the `/speckit.implement` slash command to execute the plan.

```markdown
/speckit.implement
Expand Down Expand Up @@ -159,7 +176,7 @@ Generate an actionable task list using the `/speckit.tasks` command:

### Step 7: Validate and Implement

Have your coding agent audit the implementation plan using `/speckit.analyze`:
Have your coding agent audit the spec, plan, and tasks with `/speckit.analyze` before implementation:

```bash
/speckit.analyze
Expand All @@ -179,7 +196,7 @@ Finally, implement the solution:
- **Be explicit** about what you're building and why
- **Don't focus on tech stack** during specification phase
- **Iterate and refine** your specifications before implementation
- **Validate** the plan before coding begins
- **Validate** requirements and plans before coding begins
- **Let the coding agent handle** the implementation details

## Next Steps
Expand Down
Loading