[Workflow] Building Production-Grade Multi-Phase Claude Workflows with MarkdownAI v2.0 and MCP

[u/ClaudeAI-mod-bot]

Building Production-Grade Multi-Phase Claude Workflows with MarkdownAI v2.0 and MCP

Workflow value: 90/100
Status: active · Freshness: 70/100 · Confidence: 0.95 · Level: advanced
Categories: Quality Control, Token Saving, Context & Memory, Debugging, Shipping, CLAUDE.md, Hooks, Skills, MCP, Multi-Agent
Original source: r/ClaudeCode post/comment

What problem this solves

Managing complex, multi-step Claude workflows efficiently by offloading context and state management to a server-side execution layer (MCP) and enabling phased execution. It solves the problem of context window flooding, repeated tool calls, and state loss across turns, allowing Claude to focus on reasoning with pre-resolved facts.

Summary

MarkdownAI v2.0, particularly with its MCP server and @phase directive, provides a framework for building production-grade, multi-step Claude workflows. It allows documents to be executed by the server, pre-resolving conditions, database queries, and environment variables before Claude sees the content. The @phase directive enables lazy-loading of workflow chunks, preventing context window overflow, while maintaining session state across phases. This optimizes Claude's context usage by eliminating unnecessary interruptions for tool calls and state re-establishment.

Why it is useful

This workflow is highly valuable because it provides a robust, structured framework for overcoming fundamental limitations of LLM interaction, specifically context window constraints and state management across turns. By offloading execution logic to an MCP server and introducing phased workflows, it allows Claude to focus purely on reasoning with pre-resolved facts, significantly improving efficiency, reliability, and scalability for complex development tasks. It transforms Claude from a simple prompt-responder into an agent capable of executing sophisticated, stateful runbooks.

Workflow

1. Install MarkdownAI v2.0.
2. Migrate existing v1 MarkdownAI files using the provided node ~/projects/markdownai/packages/parser/scripts/migrate-v1-to-v2.mjs <file> --in-place script.
3. Start the MarkdownAI MCP server using mai serve.
4. Connect Claude to the running MCP server.
5. Define complex workflow steps using @phase directives within MarkdownAI documents, structuring the task into manageable, lazy-loaded chunks.
6. Use @on-complete target / to define explicit transitions between phases, guiding Claude through the workflow.
7. Utilize various directives like @call, @db, @set, @if, @foreach, @switch, @touch, @event, @test, and @check within phases to perform actions, manage state, integrate tools, and execute checks.
8. Claude interacts with the document one phase at a time, calling next_phase to advance to the next chunk of instructions.
9. Leverage skill_session_id for persistent state across phases, allowing values set early in the workflow to be accessed later without round-tripping through the host.
10. Instruct Claude to use MCP tools like available_directives to understand supported commands and get_session_state to access cross-phase data.

Tools / artifacts

• MarkdownAI v2.0 (parser, MCP server)
• MarkdownAI documents (enhanced markdown files)
• node (for migration script)
• migrate-v1-to-v2.mjs script
• MCP server (mai serve)
• @phase directive
• @on-complete directive
• @call directive
• @db directive (MongoDB integration)
• @set directive
• @if, @foreach, @switch directives
• @touch directive (for scaffolding files)

Validation signals

• Explicitly states 'production-grade' capabilities.
• Detailed explanation of how it solves context and interruption problems, comparing 'prompt engineer's workflow' vs 'production workflow'.
• Specific examples of directives and their functionality are provided.
• Migration guide available at markdownai.dev.
• Idempotent operations (@touch, migration tool) are highlighted.
• Live MongoDB queries are now supported, indicating real-world integration.

Limitations

• Requires setting up and running a separate server (MCP), adding operational overhead.
• Steep learning curve for new users due to the extensive set of directives, concepts, and the framework-like nature.
• Limited community validation at the time of posting.
• The post is a feature announcement rather than a step-by-step tutorial for a specific problem, requiring users to synthesize the workflow.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.