You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: enhance README structure and add workflow improvements (#16)
* docs: refocus workflow guidance and tooling notes
- reframe the README around the SDD prompt lifecycle and artifacts
- document MCP prompt support behaviors across popular IDE and CLI setups
* feat: add health check for mcp
* build(linter): centralize markdownlint configuration
Move markdownlint rule configuration from inline pre-commit hook
arguments to a dedicated .markdownlint.yaml file for better
maintainability and adherence to standard practices.
This also allows other tooling to pick up on the markdown config.
Changes:
- Create .markdownlint.yaml with disabled rules (MD013, MD024,
MD033, MD034, MD041)
- Remove --disable arguments from markdownlint-fix hook in
.pre-commit-config.yaml
- Maintain existing exclusions for CHANGELOG.md and LICENSE
This improves configuration management without changing linting
behavior.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
* docs: enhance README header with badges and improved formatting
Add centered header layout with tagline and multiple badges including
CI status, GitHub stars, and documentation links. Improve visual
presentation and project discoverability.
* docs: enhance README structure with highlights and workflow guidance
Add comprehensive overview sections to improve first-time user experience
and clarify the relationship between prompts and optional MCP tooling.
Changes:
- Add "Highlights" section summarizing key value propositions
- Insert "Prompt Workflow" section with numbered workflow steps
- Add "How does it work?" explanation of the prompt-driven approach
- Include "Workflow Essentials" with practical getting-started steps
- Clarify that MCP is an optional integration layer
- Improve link formatting consistency throughout document
These additions provide better information architecture and help users
understand the workflow before diving into detailed implementation
stages.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
* docs: minor tweak
---------
Co-authored-by: Claude <[email protected]>
This project provides a ubiquitous framework for spec driven development (SDD) that can be used anywhere an AI agent is used as a collaborator.
20
+
-**Prompt-first workflow:** Use curated prompts to go from idea → spec → task list → implementation-ready backlog.
21
+
-**Predictable delivery:** Every step emphasizes demoable slices, proof artifacts, and collaboration with junior developers in mind.
22
+
-**Bonus MCP tooling:** Optionally pair the workflow with an MCP server for automation inside modern AI clients.
10
23
11
-
MCP technology provides a standard way to represent and exchange information between AI agents, and this framework provides a way to use that information to guide the process of refining and implementing specifications of all kinds. Using MCP allows users to take advantage of the framework with whatever AI tool and AI model they choose, in whatever workflow they prefer.
24
+
## Why Spec-Driven Development?
12
25
13
-
## Goals
26
+
Spec-Driven Development (SDD) keeps AI collaborators and human developers aligned around a shared source of truth. This repository packages a lightweight, prompt-centric workflow that turns an idea into a reviewed specification, an actionable plan, and a disciplined execution loop. By centering on markdown artifacts instead of tooling, the workflow travels with you—across projects, models, and collaboration environments.
14
27
15
-
-**Simple:** Easy to use and understand with transparent access to the underlying tools and processes.
16
-
-**Ubiquitous:** Can be used anywhere an AI agent is used as a collaborator.
17
-
-**Reliable:** Reliable and can be trusted to deliver consistent results.
18
-
-**Flexible:** Can be used with any AI tool and AI model inside any workflow.
19
-
-**Scalable:** Can be used with any size of project.
28
+
MCP technology remains available as an optional integration, but the heart of the project is the trio of prompts that guide teams from idea to demoable outcomes with consistent artifacts.
- Ability to customize the prompts used to drive the SDD workflow
25
-
- TBD
32
+
-**Clarify intent before delivery:** The spec prompt enforces clarifying questions so requirements are explicit and junior-friendly.
33
+
-**Ship demoable slices:** Every stage pushes toward thin, end-to-end increments with clear demo criteria and proof artifacts.
34
+
-**Make work transparent:** Tasks live in versioned markdown files so stakeholders can review, comment, and adjust scope anytime.
35
+
-**Progress one slice at a time:** The management prompt enforces single-threaded execution to reduce churn and unfinished work-in-progress.
36
+
-**Stay automation ready:** While SDD works with plain Markdown, the prompts are structured for MCP, IDE agents, or other AI integrations.
37
+
38
+
## Prompt Workflow
39
+
40
+
All prompts live in `prompts/` and are designed for use inside your preferred AI assistant.
41
+
42
+
1.**`generate-spec`** (`prompts/generate-spec.md`): Ask clarifying questions, then author a junior-friendly spec with demoable slices.
43
+
2.**`generate-task-list-from-spec`** (`prompts/generate-task-list-from-spec.md`): Transform the approved spec into actionable parent tasks and sub-tasks with proof artifacts.
44
+
3.**`manage-tasks`** (`prompts/manage-tasks.md`): Coordinate execution, update task status, and record outcomes as you deliver value.
45
+
46
+
Each prompt writes Markdown outputs into `tasks/`, giving you a lightweight backlog that is easy to review, share, and implement.
26
47
27
48
## How does it work?
28
49
29
-
The MCP is driven by basic Markdown files that function as prompts for the AI agent. Users can reference the specific MCP tools in their prompts to use specific flows within the SDD workflow. Users can manage the context of the AI by using the tools of their existing workflows (GitHub CLI, Atlassian MCP, etc.). The AI agent can use the tools of the user's existing workflows to perform actions (e.g., create a new issue, update an existing issue, etc.)
50
+
The workflow is driven by Markdown prompts that function as reusable playbooks for the AI agent. Reference the prompts directly, or invoke them via supported tooling, to keep the AI focused on structured outcomes. Users can manage context with their existing workflows (GitHub CLI, Atlassian MCP, etc.), and optionally let the MCP server automate portions of the process.
51
+
52
+
## Workflow Overview
53
+
54
+
Three prompts in `/prompts` define the full lifecycle. Use them sequentially to move from concept to completed work.
55
+
56
+
### Stage 1 — Generate the Spec ([prompts/generate-spec.md](./prompts/generate-spec.md))
57
+
58
+
- Directs the AI assistant to use clarifying questions with the user before writing a Markdown spec.
59
+
- Produces `/tasks/000X-spec-<feature>.md` with goals, demoable units of work, functional/non-goals, metrics, and open questions.
60
+
61
+
### Stage 2 — Generate the Task List ([prompts/generate-task-list-from-spec.md](./prompts/generate-task-list-from-spec.md))
62
+
63
+
- Reads the approved spec, inspects the repo for context, and drafts parent tasks first.
64
+
- On confirmation from the user, expands each parent task into sequenced subtasks with demo criteria, proof artifacts, and relevant files.
65
+
- Outputs `/tasks/tasks-000X-spec-<feature>.md` ready for implementation.
- Enforces disciplined execution: mark in-progress immediately, finish one subtask before starting the next, and log artifacts as you go.
70
+
- Bakes in commit hygiene, validation steps, and communication rituals so handoffs stay tight.
32
71
33
-
Here is a detailed diagram of the SDD workflow:
72
+
### Detailed SDD Workflow Diagram
34
73
35
74
```mermaid
36
75
sequenceDiagram
@@ -69,24 +108,34 @@ sequenceDiagram
69
108
MT->>CODE: Iterate changes
70
109
```
71
110
72
-
### Available Prompts
111
+
##Core Artifacts
73
112
74
-
The server provides three core prompts for spec-driven development:
113
+
-**Specs:**`000X-spec-<feature>.md` — canonical requirements, demo slices, and success metrics.
114
+
-**Task Lists:**`tasks-000X-spec-<feature>.md` — parent/subtask checklist with relevant files and proof artifacts.
115
+
-**Status Keys:**`[ ]` not started, `[~]` in progress, `[x]` complete, mirroring the manage-tasks guidance.
116
+
-**Proof Artifacts:** URLs, CLI commands, screenshots, or tests captured per task to demonstrate working software.
75
117
76
-
-`generate-spec`: Create a detailed specification from a feature description
77
-
-`generate-task-list-from-spec`: Generate an actionable task list from a spec
78
-
-`manage-tasks`: Manage and track progress on task lists
118
+
## Hands-On Usage (No MCP Required)
79
119
80
-
## Technologies Used
120
+
1.**Kick off a spec:** Copy or reference `prompts/generate-spec.md` inside your preferred AI chat. Provide the feature idea, answer the clarifying questions, and review the generated spec before saving it under `/tasks`.
121
+
2.**Plan the work:** Point the assistant to the new spec and walk through `prompts/generate-task-list-from-spec.md`. Approve parent tasks first, then request the detailed subtasks and relevant files. Commit the result to `/tasks`.
122
+
3.**Execute with discipline:** Follow `prompts/manage-tasks.md` while implementing. Update statuses as you work, attach proof artifacts, and pause for reviews at each demoable slice.
81
123
82
-
| Technology | Description | Link |
83
-
| --- | --- | --- |
84
-
|`uv`| Modern Python package and project manager |<https://docs.astral.sh/uv/>|
85
-
| FastMCP | Tool for building MCP servers and clients |<https://github.com/jlowin/fastmcp>|
86
-
|`pre-commit`| Git hooks for code quality and formatting |<https://pre-commit.com/>|
Guides are coming for wiring these prompts as first-class slash commands in popular IDEs and AI tools (Windsurf, VS Code, Cursor, Claude Code, Codex, and more).
127
+
128
+
## Optional: Automate with the MCP Server
129
+
130
+
Prefer tighter tooling? This repository also ships an MCP server that exposes the same prompts programmatically. Treat it as an accelerator—everything above works without it.
131
+
132
+
> Note: MCP prompt support is not uniformly supported across AI tools. See [docs/mcp-prompt-support.md](./docs/mcp-prompt-support.md) for details.
88
133
89
-
## Quick Start
134
+
### Workflow Essentials
135
+
136
+
1. Open `prompts/generate-spec.md` inside your AI assistant and follow the instructions to produce a new spec in `tasks/`.
137
+
2. Point the assistant at the generated spec and run `prompts/generate-task-list-from-spec.md` to create the implementation backlog.
138
+
3. Use `prompts/manage-tasks.md` while executing work to keep status, demo criteria, and proof artifacts up to date.
90
139
91
140
### Installation
92
141
@@ -97,41 +146,38 @@ cd spec-driven-workflow-mcp
97
146
98
147
# Install dependencies
99
148
uv sync
100
-
101
-
# Run tests
102
-
uv run pytest
103
149
```
104
150
105
-
### Running the Server
151
+
### Run the MCP Server
106
152
107
-
**STDIO Transport (for local development):**
153
+
**STDIO (local development):**
108
154
109
155
```bash
110
156
uvx fastmcp run server.py
157
+
```
111
158
112
-
# Or start an MCP Inspector instance for local testing along with the app:
159
+
**With MCP Inspector:**
160
+
161
+
```bash
113
162
uvx fastmcp dev server.py
114
163
```
115
164
116
-
**HTTP Transport (for remote access):**
165
+
**HTTP Transport:**
117
166
118
167
```bash
119
168
uvx fastmcp run server.py --transport http --port 8000
120
169
```
121
170
122
-
See [docs/operations.md](docs/operations.md) and [CONTRIBUTING.md](CONTRIBUTING.md) for detailed configuration, contribution workflow, and deployment options.
171
+
See [docs/operations.md](docs/operations.md) and [CONTRIBUTING.md](CONTRIBUTING.md) for advanced configuration, deployment, and contribution guidelines.
123
172
124
173
## References
125
174
126
175
| Reference | Description | Link |
127
176
| --- | --- | --- |
128
-
| MCP | MCP is a standard way to represent and exchange information between AI agents |<https://modelcontextprotocol.io/docs/getting-started/intro>|
129
-
| FastMCP | The fast, Pythonic way to build MCP servers and clients. |<https://gofastmcp.com/getting-started/welcome>|
130
-
| AI Dev Tasks | Example of a basic SDD workflow using only markdown files. |<https://github.com/snarktank/ai-dev-tasks>|
131
-
| AI Dev Tasks (customized) | A customized version of AI Dev Tasks |<https://github.com/liatrio/read-me/tree/main/damien-storm/ai-stuff#feature-development-flow>|
132
-
| Spec Driven Workflow | Liatrio app that provides a unified development workflow system |<https://github.com/liatrio-labs/spec-driven-workflow>|
177
+
| AI Dev Tasks | Foundational example of an SDD workflow expressed entirely in Markdown. |<https://github.com/snarktank/ai-dev-tasks>|
178
+
| MCP | Standard protocol for AI agent interoperability, used here as an optional integration layer. |<https://modelcontextprotocol.io/docs/getting-started/intro>|
179
+
| FastMCP | Python tooling for building MCP servers and clients that power this repo's automation. |<https://github.com/jlowin/fastmcp>|
133
180
134
181
## License
135
182
136
-
This project is licensed under the Apache License, Version 2.0. See the
137
-
[LICENSE](LICENSE) file for details.
183
+
This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.
This guide tracks how well popular IDEs, CLIs, and agent shells load the Spec Driven Development (SDD) prompts exposed by the MCP server. Use it to choose the smoothest environment, understand current limitations, and contribute new findings.
| OpenCode | TBD | Yes | Implicit trigger (no slash commands) | Ideal | Prompts are invoked through natural language requests. |
15
+
| Windsurf | TBD | Yes | No | Not good | MCP loads but returns `Error: no tools returned.` Adding a dummy tool unblocks basic use. |
16
+
| VS Code | TBD | Yes | Slash commands generated, but not executed | Not good | Prompts appear as commands but are inserted verbatim into chat; AI ignores them. |
17
+
| Codex CLI | TBD | Yes | No | Non-existent | Prompts not recognized; manual copy/paste required. |
18
+
| Codex IDE Plugin | TBD | Yes | No | Non-existent | Same as CLI—no prompt awareness. |
19
+
| Goose | TBD | Yes | TBD | TBD | Loads successfully; behavior still being evaluated. |
-**Ideal** environments either supply native slash commands or automatically invoke the correct prompt flows from natural language requests.
27
+
-**Not good** means the MCP connection succeeds but prompt usage is clumsy or broken without manual intervention.
28
+
-**Non-existent** indicates the tool ignores MCP prompts entirely today.
29
+
-**TBD** rows invite contributors to validate behavior and update this document.
30
+
31
+
## Field Notes & Tips
32
+
33
+
- Tools that surface the prompts as first-class slash commands (Claude Code CLI/Desktop, Gemini CLI) provide the fastest path to running the SDD workflow without touching raw Markdown.
34
+
- When slash commands are absent but the tool still uses the MCP (Cursor, OpenCode), instruct the assistant with the stage name ("generate spec", "generate task list", etc.) to trigger the correct prompt.
35
+
- Windsurf currently requires registering a simple placeholder tool to prevent the `no tools returned` error. After that, prompts still are not recognized.
36
+
- VS Code recognizes the prompts but pastes the entire template back into chat. Until native execution improves, reference the relevant prompt file and run it manually in the chat window.
37
+
38
+
## How to Contribute Updates
39
+
40
+
1. Launch the MCP server with the environment you are testing.
41
+
2. Note whether prompts load automatically and how the assistant responds to each stage of the SDD workflow.
42
+
3. Capture any error messages or required workarounds.
43
+
4. Update the support matrix and notes above with your findings.
44
+
5. Open a pull request summarizing the change so the community keeps an accurate inventory.
45
+
46
+
Have results for a tool marked **TBD**? Please add them—this table is only as useful as the data we collectively maintain.
0 commit comments