rundown: An Agent Runtime That Turns Markdown into Executable Workflows

rundown is a tool-agnostic agent framework that treats Markdown documents as managed workloads. It enables task execution, verification, and repair through checkbox contracts, bringing determinism and observability to AI agent workflows.

Most current AI agent workflows have a fundamental disruption: work descriptions are in Markdown, agent execution happens elsewhere, verification occurs in human minds, historical records are incomplete, and recovery processes are vague. The result is a familiar problem—things seem done, but actually aren't.

This "handover disruption" leads to a series of pain points:

• Opaque task status, making it hard to judge real progress
• Lack of verification mechanisms for agent outputs, leading to inconsistent quality
• Context loss during multi-agent collaboration, resulting in high repeated communication costs
• Failure recovery relies on manual judgment, unable to be automated

rundown's solution is to elevate checkboxes from "to-do items" to "execution contracts". A task is not considered done because the agent says it's done; instead, it's marked as done only after the work is executed and verified.

This design philosophy draws inspiration from Infrastructure as Code and GitOps concepts: separating intent declarations (task descriptions in Markdown) from actual execution (runtime management) while maintaining a traceable link between the two.

rundown treats Markdown files as first-class workload definitions. Each unchecked checkbox becomes a work unit that includes:

• Context: Descriptive text and code blocks around the task
• Execution Instructions: Run via CLI agents or inline commands
• Verification Standards: Independent verification steps to ensure quality
• Repair Mechanism: Automatic repair loop when verification fails
• Planning Capability: Automatic splitting when tasks are too large

Unlike the random or heuristic task selection in many agent systems, rundown uses a sorted and predictable selection algorithm. This determinism ensures consistency across multiple runs, making debugging and auditing easier.

rundown's execution process strictly separates the two phases of "execution" and "verification":

1. The runtime finds the next ready unchecked task
2. Builds prompts from surrounding context and repository templates
3. Sends to CLI agents for execution (supports OpenCode, Claude, Aider, etc.)
4. Independently verifies the results
5. Enters a repair loop if verification fails
6. Only tasks that pass verification can be checked off

This design prevents "false completion"—cases where the agent claims completion but actually doesn't meet the standards.

rundown is not tied to specific AI tools; instead, it integrates with any agent tool via standard CLI interfaces. This design allows teams to choose the most suitable tool for the scenario without being locked into a single platform.

Each repository defines local workflow templates via the .rundown/ directory:

• execute.md: Execution prompt template
• verify.md: Verification prompt template
• repair.md: Repair prompt template
• plan.md: Planning prompt template
• trace.md: Tracing and auditing template

This templating allows different projects to define workflow specifications suitable for their domains while maintaining a consistent execution framework.