docs: enhance README structure and add workflow improvements

[ryderstorm]

Why?

Improve README discoverability, readability, and user onboarding by enhancing the documentation structure and visual presentation. This PR consolidates recent documentation improvements and workflow clarifications to better communicate the value proposition and usage patterns of the Spec Driven Development workflow.

What Changed?

Documentation Enhancements

• Enhanced README header (c4cde9c): Added centered layout with tagline, CI status badge, GitHub stars, and documentation links for improved visual presentation
• Added comprehensive overview sections (840adda):
  • New "Highlights" section summarizing key value propositions
  • "Prompt Workflow" section with numbered workflow steps
  • "How does it work?" explanation of the prompt-driven approach
  • "Workflow Essentials" with practical getting-started steps
  • Clarified that MCP is an optional integration layer
  • Improved link formatting consistency

Build & Configuration

• Centralized markdownlint configuration (315a543): Moved linter rules from inline pre-commit arguments to dedicated .markdownlint.yaml file for better maintainability

Feature Additions

• Added health check endpoint (d63ff1c): New /health endpoint for MCP server monitoring and deployment readiness checks
• Refocused workflow guidance (cc007c9): Reframed README around SDD prompt lifecycle and artifacts, added MCP prompt support documentation

Additional Notes

This PR brings together several improvements that enhance both the user experience and operational capabilities:

• Better information architecture helps first-time users understand the workflow before diving into implementation details
• Health check endpoint enables better deployment monitoring and load balancer integration
• Centralized linter configuration follows standard practices and allows other tooling to pick up markdown config
• All changes maintain backward compatibility

Checklist:

• Linked relevant spec/task IDs: Part of ongoing documentation improvements
• Ran tests: All passing
• Ran linters/hooks: Pre-commit checks pass with new markdownlint config
• Updated docs: This PR is primarily documentation-focused

[coderabbitai]

Walkthrough

Configuration and documentation updates restructure the project around a Markdown-prompt-centric workflow. Changes include a new linting configuration file, simplification of pre-commit hooks, substantial README reorganization emphasizing prompt workflows and artifacts, new MCP tool support documentation, and a basic HTTP health endpoint in the server code.

Changes

Cohort / File(s)	Summary
Linting Configuration .markdownlint.yaml, .pre-commit-config.yaml	Added .markdownlint.yaml with default state enabled and specific rules disabled (MD013, MD024, MD033, MD034, MD041). Removed explicit arguments block from markdownlint-fix hook in pre-commit config to use default settings.
Documentation Overhaul README.md	Restructured README from MCP-centric to Markdown-prompt-driven workflow focus. Added rich HTML header with badges, introduced "Highlights" and "Prompt Workflow" sections, detailed three-prompt lifecycle, added sequence diagram, updated installation and usage instructions, and reorganized reference links.
New Documentation docs/mcp-prompt-support.md	New file documenting MCP prompt support matrix across tools, including invocation mechanisms, status tracking, interpretation guide, and contribution workflow.
Server Enhancements mcp_server/__init__.py	Added HTTP health endpoint (GET /health returning "OK" response), imported Starlette dependencies, and registered a basic example tool in app creation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A README reimagined, prompts now shine,
Three-step workflows in perfect design,
Health checks hop and linting rules bend,
Markdown workflows—a tale without end! ✨

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The pull request description is provided as a template skeleton with no actual content filled in. All three required sections—"Why?", "What Changed?", and "Additional Notes"—contain only placeholder comments with no substantive information. The checklist items are all unchecked and no supporting details are included. This represents a largely incomplete description that fails to communicate the motivation, scope, or context of the changes to reviewers.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "Feat/readme improvements" accurately describes a real and substantial aspect of the changeset. The raw summary confirms that README.md underwent extensive restructuring with new HTML headers, reorganized sections, new diagrams, and updated instructions—representing high code review effort. However, the changeset also includes server code modifications (health endpoint, tool registration in mcp_server/init.py), new linting configuration (.markdownlint.yaml), and a new documentation file (docs/mcp-prompt-support.md). The title refers to one significant component but does not capture the full scope of the PR's changes.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/readme-improvements

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

mcp_server/__init__.py (1)

26-28: Health endpoint works but is minimal.

The implementation is correct and follows standard health check patterns. For a prompt-serving MCP server, a simple "OK" response may be sufficient.

Consider whether future enhancements should verify:

• Prompt directory accessibility
• Configuration validity
• Any external dependencies

README.md (1)

24-24: Consider hyphenating compound adjective.

Static analysis suggests "Spec-Driven Development" (with hyphen) when used as a compound adjective modifying "Development." This applies to the heading and similar uses throughout the document.

While the current usage is understood, consider this change for grammatical precision:

-## Why Spec Driven Development?
+## Why Spec-Driven Development?

Apply similar changes to other occurrences where "Spec Driven" modifies a noun (e.g., line 26). Note that "Spec Driven Development" as a proper name (e.g., in the title) can remain unhyphenated.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9a6d6d6 and 840adda.

📒 Files selected for processing (5)

• .markdownlint.yaml (1 hunks)
• .pre-commit-config.yaml (0 hunks)
• README.md (3 hunks)
• docs/mcp-prompt-support.md (1 hunks)
• mcp_server/__init__.py (2 hunks)

💤 Files with no reviewable changes (1)

• .pre-commit-config.yaml

🧰 Additional context used

🪛 LanguageTool

README.md

[grammar] ~24-~24: Use a hyphen to join words.
Context: ...n inside modern AI clients. ## Why Spec Driven Development? Spec Driven Develop...

(QB_NEW_EN_HYPHEN)

🔇 Additional comments (13)

.markdownlint.yaml (1)

1-20: LGTM! Configuration aligns well with documentation needs.

The disabled rules are appropriate for this project:

• MD033 (inline HTML) and MD041 (first line heading) accommodate the HTML header in README.md
• MD013 (line length) provides flexibility for long URLs and code blocks
• MD024 (duplicate headings) and MD034 (bare URLs) offer practical flexibility for documentation

mcp_server/__init__.py (2)

8-9: LGTM! Correct imports for the health endpoint.

The starlette imports are appropriate for implementing a custom HTTP route within the FastMCP framework.

---

33-37: LGTM! Test tool registration is appropriate.

The basic example tool serves its stated purpose of verifying MCP tool registration. The static return value is suitable for a verification tool.

docs/mcp-prompt-support.md (3)

1-23: LGTM! Well-structured support matrix with clear contribution path.

The table provides valuable guidance for users selecting tools, and the TBD entries appropriately signal areas awaiting community validation. The categorization (Ideal/Not good/Non-existent/TBD) gives users quick insight into tool readiness.

---

31-36: Field notes align with codebase changes.

The Windsurf note about requiring a placeholder tool aligns with the basic_example_tool registration added in mcp_server/__init__.py, demonstrating consistency between documentation and implementation.

---

38-46: LGTM! Clear contribution workflow.

The five-step contribution process is straightforward and encourages community participation in validating tool support.

README.md (7)

18-36: LGTM! Clear highlights and principles establish the workflow's value.

The highlights section effectively communicates the prompt-first approach, and the guiding principles provide actionable constraints that align with the documented workflow stages.

---

38-71: LGTM! Workflow sections provide clear, actionable guidance.

The progression from prompt workflow overview through detailed stage descriptions gives users a complete mental model. The explicit artifact locations (tasks/, filename patterns) make outcomes tangible.

---

74-109: LGTM! Mermaid diagram effectively visualizes the three-stage workflow.

The sequence diagram clearly shows participant interactions and the bidirectional feedback loops (analyze → clarify → refine). The participant naming aligns with the documented prompt filenames.

---

111-139: LGTM! Core artifacts and hands-on usage deliver practical next steps.

The artifact definitions establish clear conventions (status markers, file patterns), and the hands-on usage section provides a concrete entry point for users who want to start without MCP tooling. The cross-reference to docs/mcp-prompt-support.md (added in this PR) maintains consistency.

---

140-171: LGTM! Installation and run instructions are clear and complete.

The instructions cover multiple transport modes (STDIO, inspector, HTTP) and reference the appropriate documentation files for advanced scenarios.

---

173-183: LGTM! References and license are properly documented.

The reference table provides context for foundational concepts (AI Dev Tasks, MCP, FastMCP), and the license reference is correctly formatted.

---

1-16: LGTM! Professional header with proper badge configuration.

The HTML-based header provides visual polish, and the disabled MD033/MD041 linting rules appropriately accommodate this structure. Badge URLs correctly reference the repository. The header image at ./misc/header.png exists and is accessible.