Markdown Files as State Machines for AI Development Workflows

Summary

A structured markdown file can function as a reliable state machine for orchestrating multi-step AI development workflows. The key insight: prose instructions fail because LLMs treat them as suggestions. Numbered steps with explicit branching logic, checkpoint markers, and disk-persisted session state produce repeatable, context-resilient automation.

Source: Brad Feld, “Exploring /start: How a Markdown File Runs My Development Workflow” (2026-03-10).

The Problem

Early attempts at workflow automation via CLAUDE.md used descriptive prose (“fetch the ticket, then create a branch”). Claude treated these as loose guidance, not executable steps. The result was inconsistent behavior, especially after context compaction wiped in-memory state.

The Pattern: Structured Markdown as Execution Engine

Replace narrative prose with explicit decision trees and numbered steps. The markdown structure itself does what an interpreter would do in a traditional programming language.

Core Components

1. Numbered Steps with Preconditions

Each step has a defined trigger, action, and exit condition. Claude executes them sequentially rather than interpreting intent from paragraphs.

2. Decision Trees with Explicit Branching

Rather than “handle reopened tickets appropriately,” the markdown encodes branching logic: scan comments for signals like “bug,” “doesn’t work,” or “sent back,” then route to a Plan subagent with structured context highlighting the specific issues.

3. Checkpoint Markers Persisted to Disk

Dual persistence survives context compaction:

• .claude-session/TICKET-XXX.json tracks workflow state, current step, and session metadata
• .claude-session/TICKET-XXX-plan.md stores implementation tasks as checkboxes (the canonical progress tracker)

When context compacts, Claude re-reads these files and resumes from the exact step and task.

4. Workflow Profiles

Project-specific behavior declared in CLAUDE.md removes hardcoded conditionals:

workflow:
  base_branch: preview
  quality_gates:
    - pnpm run type-check
    - pnpm run lint
  user_testing: required
  ship:
    method: pr

The /start command reads profiles at runtime and adapts accordingly.

Multi-Repository Routing

A YAML-based Team Registry maps ticket prefixes to repositories:

• Standard routing: prefix maps to fixed directory
• Heterogeneous routing: prompt user to select among options
• Post-switch preflight: stash uncommitted changes before switching

Why This Works

The markdown structure constrains the LLM’s execution path the same way types constrain a compiler. Instead of hoping the model interprets prose correctly, you encode the workflow as a finite state machine where each state has defined transitions.

This connects to Making Invalid States Impossible: the numbered steps make it structurally difficult for the agent to skip or reorder operations.

Integration with Quality Gates

The workflow composes with the Superpowers methodology at specific checkpoints:

Key Tradeoff

The markdown becomes less readable to humans and more reliable for Claude. This is the correct tradeoff for automation-first workflows. Human readability matters for authoring and debugging the state machine, not for runtime execution.

Connections

• Declarative Constraints Over Imperative Instructions: constraints outperform instructions for LLM reliability
• Making Invalid States Impossible: same principle applied to workflow steps instead of code generation
• Stateless Verification Loops: checkpoint files enable clean resumption after context loss
• Writing a Good CLAUDE.md: the CLAUDE.md is the delivery mechanism for these state machines
• Checkpoint Commit Patterns: disk persistence as insurance against context window limits

Actionable Takeaway

If you want an AI agent to do something complex and do it reliably, the answer is not better prose instructions. It is more structured ones. Encode workflows as numbered steps with explicit branching, persist state to disk at checkpoints, and design for context compaction as a guaranteed event, not an edge case.