The "Superpowers" Engine for AI Engineering.

Note: This repository integrates the "Superpowers" methodology (Brainstorming, TDD, SDD) onto a decentralized mdflow architecture. See Konzept.md for the architectural vision.

mdflow is a CLI tool that treats Markdown files as executable AI agents. It follows the Unix philosophy of "everything is a file" and pipeable streams.

We have integrated the core "Superpowers" skills and workflows into mdflow:

1. Brainstorming: Interactive design sessions.
2. Planning: Automated implementation planning.
3. Subagent Driven Development (SDD): "Fan-out" execution of plans using parallel workers.
4. Rigorous Engineering: Skills for TDD, Systematic Debugging, and Code Review.

See AGENTS.md for the full Skills Library.

• reference.md: Definitions of Agent, Skill, Workflow, Tool, and Configuration Schema.
• architecture.md: Architectural vision and migration strategy.
• technical.md: Technical documentation of the source code.

Instead of monolithic "Agent Platforms", we believe in:

• Executable Markdown: Files named task.model.md are commands.
• Composable Skills: Imports (@file) allow reusing prompt logic.
• Pipeline Architecture: cat task.md | mdflow | grep "result"

• src/: The mdflow runtime (TypeScript).
• skills/: Passive instruction sets (The "Superpowers").
• agents/: Executable agent definitions.
• commands/: Executable commands for workflows.
• ontology.md & Schema.md: System definition.

Markdown files become first-class CLI commands. Write a prompt in markdown, run it like a script. The command is inferred from the filename.

# review.claude.md
---
model: opus
---
Review this code for bugs and suggest improvements.

mdflow treats Markdown files as Executable Agents. It provides the runtime environment to implement the "Superpowers" methodology—a decentralized, file-centric approach to AI software development.

# The Superpowers Workflow
md commands/brainstorm.md   # Interactive design session
md commands/write-plan.md   # Generate execution plan
md commands/execute-plan.md # Execute the plan

We follow a structured Agentic Workflow:

1. Skills (skills/): Reusable knowledge modules (e.g., tdd.md, security.md).
2. Agents (agents/): Executable personas that combine Skills + Prompts.
3. Workflow: Brainstorm $\to$ Plan $\to$ Implement $\to$ Review.

Recommended structure for your repository:

my-project/
├── .mdflow/
├── skills/                  # Your Knowledge Base
│   ├── tdd.md
│   └── code-style.md
├── agents/                  # Your Executable Agents
│   ├── architect.claude.md
│   └── developer.codex.md
├── commands/                # Workflow Commands
│   ├── brainstorm.md
│   ├── write-plan.md
│   └── execute-plan.md
├── DESIGN.md                # Generated Context
└── PLAN.md                  # Generated Context

npm install -g mdflow
# or
bun install && bun link

Create agents/coder.claude.md:

---
model: claude-3-5-sonnet
_inputs:
  _task:
    type: text
    description: "What should I build?"
---
You are an Expert Developer.
@../skills/tdd.md

Task: {{ _task }}

md agents/coder.claude.md

Name your file task.COMMAND.md and run it.

• task.claude.md $\to$ Runs Claude
• task.gemini.md $\to$ Runs Gemini
• task.codex.md $\to$ Runs OpenAI (Codex)

Build context dynamically from your codebase.

Review these files:
@./src/**/*.ts

Turn prompts into forms.

---
_inputs:
  _env:
    type: select
    options: [dev, prod]
---
Deploy to {{ _env }}.

• AGENTS.md: The "Superpowers" Knowledge Base & Spec.
• Guide: 10+ Examples of mdflow in action.
• Architecture: The architectural vision behind the framework.
• Reference: Ontology and Schema.
• Technical: Source code documentation.

Global defaults in ~/.mdflow/config.yaml. Project specific environment variables in .env.

Note: This tool powers the "Superpowers" methodology but is agnostic—you can use it for any LLM automation task.