johnlindquist/mdflow

Multi-backend CLI for executable markdown prompts. Run .md files against Claude, Codex, Gemini, or Copilot.

What it solves

mdflow is a Git-native control plane for agentic workflows. It solves the problem of inconsistent, non-repeatable AI agent tasks by allowing users to define specific jobs (like code reviews or release notes) as version-controlled Markdown files. This transforms prompts into first-class CLI commands that can be piped, chained, and guarded by behavioral evaluations.

How it works

  • Markdown as Commands: Files named with a specific pattern (e.g., task.claude.md) are automatically mapped to a CLI engine (like Claude, Codex, or Gemini). The Markdown body serves as the prompt, and YAML frontmatter is converted into CLI flags.
  • Engine Resolution: It uses a resolution ladder to determine which AI engine to run, prioritizing explicit CLI flags, environment variables, and filenames over defaults.
  • Context Isolation: By default, it strips ambient context (like user config or session persistence) to ensure runs are isolated and repeatable, though this can be opted out of via _isolated: false.
  • Lifecycle Hooks: Users can attach TypeScript files (hooks) to flows to inject context or block actions during specific events (e.g., userPromptSubmit).
  • Behavioral Evals: It includes an md eval command to run behavioral test cases in isolated workspaces, ensuring prompt revisions don't introduce regressions.
  • Evolution Protocol: The md evolve command allows users to propose and verify prompt improvements based on feedback without immediately overwriting the source file.

Who it’s for

Developers and teams who want to treat their AI agent prompts as code, incorporating version control, regression testing, and a standardized way to execute AI tasks across different CLI-based LLM engines.

Highlights

  • Git-native: Flows are stored in the ./flows directory and are diffable in pull requests.
  • Unix Philosophy: Supports stdin/stdout, allowing agents to be piped (e.g., git diff | md review.md).
  • Flow Workbench: An interactive CLI surface for searching and running project, global, and installed flows.
  • Engine Agnostic: Supports a wide range of engines including pi, claude, codex, copilot, gemini, and agy.
  • Template Variables: Supports dynamic inputs via frontmatter variables, CLI flags, and interactive form prompts.

Related

  • Project
    MrLesk/Backlog.md

    A Markdown-native task manager and Kanban visualizer designed to help humans review AI agent work through spec-driven development and small, verifiable tasks.

  • Project
    coleam00/skills

    A collection of modular Markdown-based skills for AI coding agents that replace bloated system prompts with task-specific procedures for planning, implementing, and validating software.

  • Project
    github/gh-aw

    GitHub Agentic Workflows (`gh-aw`) is a GitHub CLI extension that lets you write AI‑powered automation as Markdown files with YAML front‑matter. The tool compiles these *agentic* workflows into standard GitHub Actions workflows, running LLMs (Copilot, Claude, OpenAI, Gemini, Pi) in a sandboxed, read‑only mode. Writes are gated through a separate safe‑outputs job with scoped permissions. It’s designed for tasks like issue triage, PR review, CI failure analysis, docs updates, and repo reporting, integrating securely with existing CI/CD pipelines.

  • Project
    zhu1090093659/spec_driven_develop

    An architecture-first workflow plugin for AI coding agents that turns large software changes into a spec-driven loop of analysis, decomposition, and adaptive execution.

  • Project
    HangYu8123/HarnessFlow

    A portable Markdown instruction pack that transforms AI coding assistants into disciplined multi-agent pipelines with planning, self-review, and persistent memory.