Skip to Content
rungFlo

Record formats

The Markdown formats the CLI reads and writes.

rungflo export and rungflo pull write records in these formats, and rungflo import reads them.

Layout

Repo files:

.rungflo/
  README.md
  project.md
  architecture/
    map.md
    decisions/<decision>.md

Record export layout (relative to the export directory, or .rungflo-records/ for pull):

rungs.md
features/<feature>/feature.md
features/<feature>/plans/<plan>.md
features/<feature>/plans/<plan>/reports/<timestamp>.md

All files are Markdown, optionally with YAML frontmatter. Feature and plan IDs use lowercase kebab-case, such as pr-guide/model-runner.

project.md

Free-form Markdown that describes the product, its audience, and its tech stack. It may start with YAML frontmatter that holds these fields:

FieldValuesMeaning
mapevery-pr or on-requestWhen agents update architecture/map.md. every-pr, the default, updates it in every PR that changes what it shows. on-request updates it only when the user asks.
stackA list of labelsThe project's main technologies, such as [Tauri, Rust, React, SQLite], shown on Home. Each label is 1 to 16 characters. Optional.
skillA skill nameThe skill every T3 Code thread rungflo starts uses, such as full-stop. rungflo reads it from the chosen clone and starts the prompt with $<skill>. Optional.

Home also reads the body: the # title, the first sentence of the paragraph under it, the first sentence under ## Who it is for and under ## How it works, and the links under ## Designs.

rungs.md

Each rung is a level-2 heading ## <id>: <title>, followed by its outcome paragraph starting with "When this rung is done, you can". Export order is rung order; rungs have no dates. Create or update one with rungflo rung.

## guides: Plans and PR guides

When this rung is done, you can see every plan's stage and read a guide for every PR.

feature.md

No frontmatter. The level-1 heading is the feature title; the body says what it is, why it exists, and which screens it touches. Save it with rungflo feature <id> --file <path>; its plans can serve different rungs.

Plan files

A plan is one agent-sized task, built in one PR or several slices. Its ID is <feature>/<plan>; the export path features/pr-guide/plans/model-runner.md represents pr-guide/model-runner. Pick the rung whose outcome it serves, adding one with rungflo rung if needed.

FieldTypeMeaning
rungstringRung ID.
shortstringOptional compact label for Home Activity, 1 to 16 characters on one line without control characters. Falls back to the title.
depends_onlist of plan IDsPlans that must be Done first; [] for none.
designlist of URLsEach screen's own design frame or artboard; [] if none, or pending while the screens aren't drawn.
skillslist of skill namesOptional. The kit skills the plan's build should load.

The level-1 heading is the title. Three level-2 headings follow in order: Goal, Approach, Acceptance criteria. Criteria use - [ ]; rungflo tick records met criteria and their PR without revising the plan. Exported checkboxes reflect those records.

Create with rungflo plan <id> --create --file <path>. Revise only when the user asks, using --file <path> --base <rev>; record implementation differences in a checkpoint's drift.

Every plan names its designs or explains their absence:

  • With designs, end the criteria with a side-by-side of each screen and its design, in each drawn theme, attached to the PR.
  • With design: [], include an Approach line starting with No design: and its reason.
  • With design: pending, rungflo next leaves the plan out until its design links are set.
---
rung: guides
depends_on:
  - pr-guide/model-runner
design: []
---

# Generate PR guides

## Goal

Read a guide for every ready PR.

## Approach

- No design: this slice changes the generator only.

## Acceptance criteria

- [ ] A ready PR gets a guide.

Checkpoint reports

Write checkpoints on the server with rungflo checkpoint <session> --status in-progress|blocked|complete, repeating --done, --decision, --drift, and --next as needed. Ask questions with rungflo ask; they stay open until answered or withdrawn. The server owns identity, ordering, and history; exported report filenames are a projection.

The Markdown format has status frontmatter and optional agent (up to 40 characters) and thread (up to 200), each one line without control or bidi characters. These five level-2 sections always appear in order, each as a bullet list or None.. Repeat every drift that still holds; every decision states its reason.

---
status: in-progress
agent: T3 Code
thread: 0a1b2c3d
---

## Done

- What this session finished.

## Decisions

- The choice you made. Reason: why you made it.

## Drift

- Where the work departed from the plan or the design, and why.

## Questions for you

- One question for the user.

## Next

- What the next session does first.

Linking a PR to a plan

Use one line by itself in the PR body: Plan: <feature>/<plan>. Branch names do not link plans. A PR from a fork links no plan, and a merged PR's links don't change when its body is edited. Keep the PR a draft until its slice meets its criteria or a checkpoint explains the drift.

Derived state

Never write a stage into a record. The server derives progress from linked PRs, ticks, member acceptance, sessions, and questions; rungflo next reads the first ready, unclaimed plan. Folder-backed projects retain their GitHub-derived stages. Open the next slice's PR before the current slice merges.

Architecture

Each file in architecture/decisions/ records how the project handles one concern and why. It has no frontmatter and four level-2 headings in this order: Context, Decision, Why, and Consequences.

On this page