From cc007c9d555e0aadc7ece86bfcaf8d97c1bd928d Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Tue, 21 Oct 2025 13:10:28 -0400 Subject: [PATCH 1/6] 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 --- README.md | 103 ++++++++++++++++++++----------------- docs/mcp-prompt-support.md | 46 +++++++++++++++++ 2 files changed, 101 insertions(+), 48 deletions(-) create mode 100644 docs/mcp-prompt-support.md diff --git a/README.md b/README.md index 27500d9..49da876 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,42 @@ -# Spec Driven Development (SDD) MCP +# Spec Driven Development Workflow [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) -Spec Driven Development MCP header +Spec Driven Development header -## Why does this exist? +## Why Spec Driven Development? -This project provides a ubiquitous framework for spec driven development (SDD) that can be used anywhere an AI agent is used as a collaborator. +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. -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. +## Guiding Principles -## Goals +- **Clarify intent before delivery:** The spec prompt enforces clarifying questions so requirements are explicit and junior-friendly. +- **Ship demoable slices:** Every stage pushes toward thin, end-to-end increments with clear demo criteria and proof artifacts. +- **Make work transparent:** Tasks live in versioned markdown files so stakeholders can review, comment, and adjust scope anytime. +- **Progress one slice at a time:** The management prompt enforces single-threaded execution to reduce churn and unfinished work-in-progress. +- **Stay automation ready:** While SDD works with plain Markdown, the prompts are structured for MCP, IDE agents, or other AI integrations. -- **Simple:** Easy to use and understand with transparent access to the underlying tools and processes. -- **Ubiquitous:** Can be used anywhere an AI agent is used as a collaborator. -- **Reliable:** Reliable and can be trusted to deliver consistent results. -- **Flexible:** Can be used with any AI tool and AI model inside any workflow. -- **Scalable:** Can be used with any size of project. +## Workflow Overview -Future functionality will include: +Three prompts in `/prompts` define the full lifecycle. Use them sequentially to move from concept to completed work. -- User-defined output formats (Markdown task list, Jira objects via Atlassian MCP, GitHub issues, etc.) -- Ability to customize the prompts used to drive the SDD workflow -- TBD +### Stage 1 — Generate the Spec ([prompts/generate-spec.md](./prompts/generate-spec.md)) -## How does it work? +- Directs the AI assistant to use clarifying questions with the user before writing a Markdown spec. +- Produces `/tasks/000X-spec-.md` with goals, demoable units of work, functional/non-goals, metrics, and open questions. -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.) +### Stage 2 — Generate the Task List ([prompts/generate-task-list-from-spec.md](./prompts/generate-task-list-from-spec.md)) -### SDD Workflow Overview +- Reads the approved spec, inspects the repo for context, and drafts parent tasks first. +- On confirmation from the user, expands each parent task into sequenced subtasks with demo criteria, proof artifacts, and relevant files. +- Outputs `/tasks/tasks-000X-spec-.md` ready for implementation. -Here is a detailed diagram of the SDD workflow: +### Stage 3 — Manage Tasks ([prompts/manage-tasks.md](./prompts/manage-tasks.md)) + +- Enforces disciplined execution: mark in-progress immediately, finish one subtask before starting the next, and log artifacts as you go. +- Bakes in commit hygiene, validation steps, and communication rituals so handoffs stay tight. + +### Detailed SDD Workflow Diagram ```mermaid sequenceDiagram @@ -69,24 +75,28 @@ sequenceDiagram MT->>CODE: Iterate changes ``` -### Available Prompts +## Core Artifacts -The server provides three core prompts for spec-driven development: +- **Specs:** `000X-spec-.md` — canonical requirements, demo slices, and success metrics. +- **Task Lists:** `tasks-000X-spec-.md` — parent/subtask checklist with relevant files and proof artifacts. +- **Status Keys:** `[ ]` not started, `[~]` in progress, `[x]` complete, mirroring the manage-tasks guidance. +- **Proof Artifacts:** URLs, CLI commands, screenshots, or tests captured per task to demonstrate working software. -- `generate-spec`: Create a detailed specification from a feature description -- `generate-task-list-from-spec`: Generate an actionable task list from a spec -- `manage-tasks`: Manage and track progress on task lists +## Hands-On Usage (No MCP Required) -## Technologies Used +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`. +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`. +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. -| Technology | Description | Link | -| --- | --- | --- | -| `uv` | Modern Python package and project manager | | -| FastMCP | Tool for building MCP servers and clients | | -| `pre-commit` | Git hooks for code quality and formatting | | -| Semantic Release | Automated release process (via GitHub Actions) | | +### Slash Command Integration (TBD) + +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). + +## Optional: Automate with the MCP Server -## Quick Start +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. + +> Note: MCP prompt support is not uniformly supported across AI tools. See [docs/mcp-prompt-support.md](./docs/mcp-prompt-support.md) for details. ### Installation @@ -97,41 +107,38 @@ cd spec-driven-workflow-mcp # Install dependencies uv sync - -# Run tests -uv run pytest ``` -### Running the Server +### Run the MCP Server -**STDIO Transport (for local development):** +**STDIO (local development):** ```bash uvx fastmcp run server.py +``` -# Or start an MCP Inspector instance for local testing along with the app: +**With MCP Inspector:** + +```bash uvx fastmcp dev server.py ``` -**HTTP Transport (for remote access):** +**HTTP Transport:** ```bash uvx fastmcp run server.py --transport http --port 8000 ``` -See [docs/operations.md](docs/operations.md) and [CONTRIBUTING.md](CONTRIBUTING.md) for detailed configuration, contribution workflow, and deployment options. +See `docs/operations.md` and `CONTRIBUTING.md` for advanced configuration, deployment, and contribution guidelines. -## References +## References & Further Reading | Reference | Description | Link | | --- | --- | --- | -| MCP | MCP is a standard way to represent and exchange information between AI agents | | -| FastMCP | The fast, Pythonic way to build MCP servers and clients. | | -| AI Dev Tasks | Example of a basic SDD workflow using only markdown files. | | -| AI Dev Tasks (customized) | A customized version of AI Dev Tasks | | -| Spec Driven Workflow | Liatrio app that provides a unified development workflow system | | +| AI Dev Tasks | Foundational example of an SDD workflow expressed entirely in Markdown. | | +| MCP | Standard protocol for AI agent interoperability, used here as an optional integration layer. | | +| FastMCP | Python tooling for building MCP servers and clients that power this repo's automation. | | ## License -This project is licensed under the Apache License, Version 2.0. See the -[LICENSE](LICENSE) file for details. +This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details. diff --git a/docs/mcp-prompt-support.md b/docs/mcp-prompt-support.md new file mode 100644 index 0000000..5ed1b0b --- /dev/null +++ b/docs/mcp-prompt-support.md @@ -0,0 +1,46 @@ +# MCP Prompt Support + +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. + +## Support Matrix + +| Tool | Version
Tested | Loads MCP? | Prompt Actions | Experience | Workarounds / Notes | +| --- | --- | --- | --- | --- | --- | +| Claude Code CLI | TBD | Yes | Slash commands generated automatically | Ideal | Prompts appear as native slash commands. | +| Claude Code Desktop | TBD | Yes | TBD | Ideal | Loads successfully; verifying how quickly prompts become slash commands. | +| Claude Code IDE (JetBrains) | TBD | Yes | TBD | Ideal | Successful load; documenting slash-command behavior. | +| Cursor | TBD | Yes | Implicit trigger (no slash commands) | Ideal | Natural-language requests ("generate a spec") invoke the prompts. | +| Gemini CLI | TBD | Yes | Slash commands generated automatically | Ideal | Prompts appear as native slash commands. | +| OpenCode | TBD | Yes | Implicit trigger (no slash commands) | Ideal | Prompts are invoked through natural language requests. | +| Windsurf | TBD | Yes | No | Not good | MCP loads but returns `Error: no tools returned.` Adding a dummy tool unblocks basic use. | +| 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. | +| Codex CLI | TBD | Yes | No | Non-existent | Prompts not recognized; manual copy/paste required. | +| Codex IDE Plugin | TBD | Yes | No | Non-existent | Same as CLI—no prompt awareness. | +| Goose | TBD | Yes | TBD | TBD | Loads successfully; behavior still being evaluated. | +| Crush | TBD | TBD | TBD | TBD | Awaiting confirmation. | +| Q Developer CLI | TBD | TBD | TBD | TBD | Awaiting confirmation. | +| Q Developer IDE Plugin | TBD | TBD | TBD | TBD | Awaiting confirmation. | + +## Interpretation + +- **Ideal** environments either supply native slash commands or automatically invoke the correct prompt flows from natural language requests. +- **Not good** means the MCP connection succeeds but prompt usage is clumsy or broken without manual intervention. +- **Non-existent** indicates the tool ignores MCP prompts entirely today. +- **TBD** rows invite contributors to validate behavior and update this document. + +## Field Notes & Tips + +- 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. +- 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. +- Windsurf currently requires registering a simple placeholder tool to prevent the `no tools returned` error. After that, prompts still are not recognized. +- 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. + +## How to Contribute Updates + +1. Launch the MCP server with the environment you are testing. +2. Note whether prompts load automatically and how the assistant responds to each stage of the SDD workflow. +3. Capture any error messages or required workarounds. +4. Update the support matrix and notes above with your findings. +5. Open a pull request summarizing the change so the community keeps an accurate inventory. + +Have results for a tool marked **TBD**? Please add them—this table is only as useful as the data we collectively maintain. From d63ff1cd4745ba3e346ca314efed17df94f27a2d Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Thu, 16 Oct 2025 10:22:12 -0400 Subject: [PATCH 2/6] feat: add health check for mcp --- mcp_server/__init__.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/mcp_server/__init__.py b/mcp_server/__init__.py index f226e9d..042c89c 100644 --- a/mcp_server/__init__.py +++ b/mcp_server/__init__.py @@ -5,6 +5,8 @@ """ from fastmcp import FastMCP +from starlette.requests import Request +from starlette.responses import PlainTextResponse from .config import config from .prompts_loader import register_prompts @@ -21,6 +23,10 @@ def create_app() -> FastMCP: # Initialize FastMCP server mcp = FastMCP(name="spec-driven-development-mcp") + @mcp.custom_route("/health", methods=["GET"]) + async def health_check(request: Request) -> PlainTextResponse: + return PlainTextResponse("OK") + # Load prompts from the prompts directory and register them register_prompts(mcp, config.prompts_dir) From 315a543d1d56656d5619133148e31e39485e29e8 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Fri, 17 Oct 2025 17:33:02 -0400 Subject: [PATCH 3/6] build(linter): centralize markdownlint configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .markdownlint.yaml | 20 ++++++++++++++++++++ .pre-commit-config.yaml | 8 -------- 2 files changed, 20 insertions(+), 8 deletions(-) create mode 100644 .markdownlint.yaml diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..7b90f78 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,20 @@ +# Default state for all rules +default: true + +# Path to configuration file to extend +extends: null + +# Line length +MD013: false + +# Duplicate headings +MD024: false + +# Inline HTML +MD033: false + +# Bare URLs +MD034: false + +# First line in file must be a top-level heading +MD041: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c9b6300..6569b19 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -20,14 +20,6 @@ repos: rev: v0.45.0 hooks: - id: markdownlint-fix - args: - - "--disable" - - "MD013" # Line length - - "MD024" # Duplicate headings - - "MD033" # Inline HTML - - "MD034" # Bare URLs - - "MD041" # First line in file must be a top-level heading - - "--" exclude: "CHANGELOG.md|LICENSE" - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook From c4cde9cf1eb86a41db76cf54ff6ff59fbd4bc7ec Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Fri, 17 Oct 2025 17:51:48 -0400 Subject: [PATCH 4/6] 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. --- README.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 49da876..035acb9 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,19 @@ -# Spec Driven Development Workflow - -[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) - -Spec Driven Development header +
+ Spec Driven Development header +

🧭 Spec Driven Development Workflow

+

Build predictable software with a repeatable AI-guided workflow.

+
+ +

+ Spec-driven development tools for collaborating with AI agents to deliver reliable outcomes. +

+ +

+ CI Status + License + GitHub stars + Documentation +

## Why Spec Driven Development? From 840adda310931c2c30dab752bdf62da39c7595a3 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 22 Oct 2025 11:20:14 -0400 Subject: [PATCH 5/6] docs: enhance README structure with highlights and workflow guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 035acb9..751630e 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,18 @@ Documentation

+## Highlights + +- **Prompt-first workflow:** Use curated prompts to go from idea → spec → task list → implementation-ready backlog. +- **Predictable delivery:** Every step emphasizes demoable slices, proof artifacts, and collaboration with junior developers in mind. +- **Bonus MCP tooling:** Optionally pair the workflow with an MCP server for automation inside modern AI clients. + ## Why Spec Driven Development? 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. +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. + ## Guiding Principles - **Clarify intent before delivery:** The spec prompt enforces clarifying questions so requirements are explicit and junior-friendly. @@ -27,6 +35,20 @@ Spec Driven Development (SDD) keeps AI collaborators and human developers aligne - **Progress one slice at a time:** The management prompt enforces single-threaded execution to reduce churn and unfinished work-in-progress. - **Stay automation ready:** While SDD works with plain Markdown, the prompts are structured for MCP, IDE agents, or other AI integrations. +## Prompt Workflow + +All prompts live in `prompts/` and are designed for use inside your preferred AI assistant. + +1. **`generate-spec`** (`prompts/generate-spec.md`): Ask clarifying questions, then author a junior-friendly spec with demoable slices. +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. +3. **`manage-tasks`** (`prompts/manage-tasks.md`): Coordinate execution, update task status, and record outcomes as you deliver value. + +Each prompt writes Markdown outputs into `tasks/`, giving you a lightweight backlog that is easy to review, share, and implement. + +## How does it work? + +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. + ## Workflow Overview Three prompts in `/prompts` define the full lifecycle. Use them sequentially to move from concept to completed work. @@ -109,6 +131,12 @@ Prefer tighter tooling? This repository also ships an MCP server that exposes th > Note: MCP prompt support is not uniformly supported across AI tools. See [docs/mcp-prompt-support.md](./docs/mcp-prompt-support.md) for details. +### Workflow Essentials + +1. Open `prompts/generate-spec.md` inside your AI assistant and follow the instructions to produce a new spec in `tasks/`. +2. Point the assistant at the generated spec and run `prompts/generate-task-list-from-spec.md` to create the implementation backlog. +3. Use `prompts/manage-tasks.md` while executing work to keep status, demo criteria, and proof artifacts up to date. + ### Installation ```bash @@ -140,9 +168,9 @@ uvx fastmcp dev server.py uvx fastmcp run server.py --transport http --port 8000 ``` -See `docs/operations.md` and `CONTRIBUTING.md` for advanced configuration, deployment, and contribution guidelines. +See [docs/operations.md](docs/operations.md) and [CONTRIBUTING.md](CONTRIBUTING.md) for advanced configuration, deployment, and contribution guidelines. -## References & Further Reading +## References | Reference | Description | Link | | --- | --- | --- | From 1824faf20dabc4ca08a8324392a5c45e01f02804 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 22 Oct 2025 11:32:39 -0400 Subject: [PATCH 6/6] docs: minor tweak --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 751630e..7026ba6 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@
Spec Driven Development header -

🧭 Spec Driven Development Workflow

+

🧭 Spec-Driven Development Workflow

Build predictable software with a repeatable AI-guided workflow.

+

Spec-driven development tools for collaborating with AI agents to deliver reliable outcomes.

@@ -21,9 +22,9 @@ - **Predictable delivery:** Every step emphasizes demoable slices, proof artifacts, and collaboration with junior developers in mind. - **Bonus MCP tooling:** Optionally pair the workflow with an MCP server for automation inside modern AI clients. -## Why Spec Driven Development? +## Why Spec-Driven Development? -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. +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. 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.