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.
19
+
## Highlights
10
20
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.
21
+
-**Prompt-first workflow:** Use curated prompts to go from idea → spec → task list → implementation-ready backlog.
22
+
-**Predictable delivery:** Every step emphasizes demoable slices, proof artifacts, and collaboration with junior developers in mind.
23
+
-**Bonus MCP tooling:** Optionally pair the workflow with an MCP server for automation inside modern AI clients.
12
24
13
-
## Goals
25
+
## Why Spec-Driven Development?
14
26
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.
27
+
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.
20
28
21
-
Future functionality will include:
29
+
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
31
+
## Guiding Principles
32
+
33
+
-**Clarify intent before delivery:** The spec prompt enforces clarifying questions so requirements are explicit and junior-friendly.
34
+
-**Ship demoable slices:** Every stage pushes toward thin, end-to-end increments with clear demo criteria and proof artifacts.
35
+
-**Make work transparent:** Tasks live in versioned markdown files so stakeholders can review, comment, and adjust scope anytime.
36
+
-**Progress one slice at a time:** The management prompt enforces single-threaded execution to reduce churn and unfinished work-in-progress.
37
+
-**Stay automation ready:** While SDD works with plain Markdown, the prompts are structured for MCP, IDE agents, or other AI integrations.
38
+
39
+
## Prompt Workflow
40
+
41
+
All prompts live in `prompts/` and are designed for use inside your preferred AI assistant.
42
+
43
+
1.**`generate-spec`** (`prompts/generate-spec.md`): Ask clarifying questions, then author a junior-friendly spec with demoable slices.
44
+
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.
45
+
3.**`manage-tasks`** (`prompts/manage-tasks.md`): Coordinate execution, update task status, and record outcomes as you deliver value.
46
+
47
+
Each prompt writes Markdown outputs into `tasks/`, giving you a lightweight backlog that is easy to review, share, and implement.
26
48
27
49
## How does it work?
28
50
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.)
51
+
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.
52
+
53
+
## Workflow Overview
54
+
55
+
Three prompts in `/prompts` define the full lifecycle. Use them sequentially to move from concept to completed work.
56
+
57
+
### Stage 1 — Generate the Spec ([prompts/generate-spec.md](./prompts/generate-spec.md))
58
+
59
+
- Directs the AI assistant to use clarifying questions with the user before writing a Markdown spec.
60
+
- Produces `/tasks/000X-spec-<feature>.md` with goals, demoable units of work, functional/non-goals, metrics, and open questions.
61
+
62
+
### Stage 2 — Generate the Task List ([prompts/generate-task-list-from-spec.md](./prompts/generate-task-list-from-spec.md))
63
+
64
+
- Reads the approved spec, inspects the repo for context, and drafts parent tasks first.
65
+
- On confirmation from the user, expands each parent task into sequenced subtasks with demo criteria, proof artifacts, and relevant files.
66
+
- 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.
71
+
- Bakes in commit hygiene, validation steps, and communication rituals so handoffs stay tight.
72
+
73
+
### Detailed SDD Workflow Diagram
34
74
35
75
```mermaid
36
76
sequenceDiagram
@@ -69,24 +109,34 @@ sequenceDiagram
69
109
MT->>CODE: Iterate changes
70
110
```
71
111
72
-
### Available Prompts
112
+
##Core Artifacts
73
113
74
-
The server provides three core prompts for spec-driven development:
114
+
-**Specs:**`000X-spec-<feature>.md` — canonical requirements, demo slices, and success metrics.
115
+
-**Task Lists:**`tasks-000X-spec-<feature>.md` — parent/subtask checklist with relevant files and proof artifacts.
116
+
-**Status Keys:**`[ ]` not started, `[~]` in progress, `[x]` complete, mirroring the manage-tasks guidance.
117
+
-**Proof Artifacts:** URLs, CLI commands, screenshots, or tests captured per task to demonstrate working software.
75
118
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
119
+
## Hands-On Usage (No MCP Required)
79
120
80
-
## Technologies Used
121
+
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`.
122
+
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`.
123
+
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
124
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).
128
+
129
+
## Optional: Automate with the MCP Server
130
+
131
+
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.
132
+
133
+
> 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
134
89
-
## Quick Start
135
+
### Workflow Essentials
136
+
137
+
1. Open `prompts/generate-spec.md` inside your AI assistant and follow the instructions to produce a new spec in `tasks/`.
138
+
2. Point the assistant at the generated spec and run `prompts/generate-task-list-from-spec.md` to create the implementation backlog.
139
+
3. Use `prompts/manage-tasks.md` while executing work to keep status, demo criteria, and proof artifacts up to date.
90
140
91
141
### Installation
92
142
@@ -97,41 +147,38 @@ cd spec-driven-workflow-mcp
97
147
98
148
# Install dependencies
99
149
uv sync
100
-
101
-
# Run tests
102
-
uv run pytest
103
150
```
104
151
105
-
### Running the Server
152
+
### Run the MCP Server
106
153
107
-
**STDIO Transport (for local development):**
154
+
**STDIO (local development):**
108
155
109
156
```bash
110
157
uvx fastmcp run server.py
158
+
```
111
159
112
-
# Or start an MCP Inspector instance for local testing along with the app:
160
+
**With MCP Inspector:**
161
+
162
+
```bash
113
163
uvx fastmcp dev server.py
114
164
```
115
165
116
-
**HTTP Transport (for remote access):**
166
+
**HTTP Transport:**
117
167
118
168
```bash
119
169
uvx fastmcp run server.py --transport http --port 8000
120
170
```
121
171
122
-
See [docs/operations.md](docs/operations.md) and [CONTRIBUTING.md](CONTRIBUTING.md) for detailed configuration, contribution workflow, and deployment options.
172
+
See [docs/operations.md](docs/operations.md) and [CONTRIBUTING.md](CONTRIBUTING.md) for advanced configuration, deployment, and contribution guidelines.
123
173
124
174
## References
125
175
126
176
| Reference | Description | Link |
127
177
| --- | --- | --- |
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>|
178
+
| AI Dev Tasks | Foundational example of an SDD workflow expressed entirely in Markdown. |<https://github.com/snarktank/ai-dev-tasks>|
179
+
| MCP | Standard protocol for AI agent interoperability, used here as an optional integration layer. |<https://modelcontextprotocol.io/docs/getting-started/intro>|
180
+
| FastMCP | Python tooling for building MCP servers and clients that power this repo's automation. |<https://github.com/jlowin/fastmcp>|
133
181
134
182
## License
135
183
136
-
This project is licensed under the Apache License, Version 2.0. See the
137
-
[LICENSE](LICENSE) file for details.
184
+
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