Feature/58eaf20d ai markdown guidance

[jpicklyk]

---

Add Markdown Transformation Tools for Entity Export

Overview

Adds three new MCP tools for transforming tasks, features, and projects into markdown documents with YAML frontmatter. This enables AI agents to export entities to human-readable,
documentation-friendly formats suitable for file export, wikis, and version control.

Problem Statement

Users need to export task orchestrator entities (tasks, features, projects) to markdown format for:

• Documentation generation and maintenance
• File export to wikis, static site generators, or documentation systems
• Version control and diff-friendly storage
• Human-readable archives and reports
• Display in markdown-capable systems

Initial exploration considered adding an includeMarkdownView parameter to existing Get* tools, but this approach would:

• Double response size when combined with includeSections=true
• Create unclear use cases (when to use vs not use the parameter)
• Display poorly in terminal environments (escaped strings instead of rendered markdown)
• Mix inspection concerns with transformation concerns

Solution

Added 3 dedicated markdown transformation tools:

• task_to_markdown - Transform tasks to markdown format
• feature_to_markdown - Transform features to markdown format
• project_to_markdown - Transform projects to markdown format

Key Design Principles:

• Separation of Concerns: Inspection tools (get_) return JSON for terminal/API use; transformation tools (_to_markdown) return markdown for export/rendering
• No Content Duplication: Avoids doubling response size by having separate tools
• Clear Use Cases: Tool names explicitly indicate transformation intent
• AI-Friendly: Easier for AI agents to understand when to use each tool

What's Included

Core Implementation:

• MarkdownRenderer - Domain-layer renderer supporting multiple content formats (markdown, JSON, code, plain text)
• MarkdownOptions - Configurable rendering options (line endings, code language, heading offsets, etc.)
• MarkdownRendererTest - Comprehensive test suite (23 tests, 100% passing)

MCP Tools:

• TaskToMarkdownTool - Retrieves task + sections, renders to markdown
• FeatureToMarkdownTool - Retrieves feature + sections, renders to markdown
• ProjectToMarkdownTool - Retrieves project + sections, renders to markdown

MCP Resources:

• MarkdownResourceProvider - Provides documentation resource explaining markdown capabilities

Documentation:

• Updated API reference (37 → 40 tools)
• Updated tool category counts
• Added "Markdown Transformation" section with usage patterns
• Updated CHANGELOG with unreleased changes

Markdown Output Format

Each transformation tool produces a markdown document with:

YAML Frontmatter:

id: 550e8400-e29b-41d4-a716-446655440000
type: task
title: Task Title
status: in-progress
priority: high
complexity: 7
tags:
- tag1
- tag2
created: 2025-05-10T14:30:00Z
modified: 2025-05-10T14:30:00Z

Markdown Content:

Task Title

Task summary describing what needs to be done.

Section Title

Section content rendered according to format (markdown, JSON, code, or plain text).

Another Section

More section content...

Testing

• ✅ All 23 MarkdownRenderer tests passing
• ✅ Build successful with no errors
• ✅ No changes to existing Get* tools (verified against main)
• ✅ All existing functionality preserved

Breaking Changes

None. This is a purely additive change:

• No modifications to existing tools
• No schema changes
• No behavior changes to existing functionality

Tool Count

• Before: 37 MCP tools
• After: 40 MCP tools
  • Task Management: 6 → 7 tools
  • Feature Management: 5 → 6 tools
  • Project Management: 5 → 6 tools

Future Considerations

The current implementation renders entities as standalone documents without cross-linking to related entities (e.g., projects don't link to features, features don't link to tasks).
This keeps the output format-agnostic and doesn't assume:

• File naming conventions
• Directory structures
• Link formats (relative/absolute/URI schemes)
• Whether files will exist on disk

Cross-linking could be added in a future enhancement if specific use cases emerge.

---

Generated with https://claude.com/claude-code

Co-Authored-By: Claude noreply@anthropic.com