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>.mdRecord 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>.mdAll 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:
| Field | Values | Meaning |
|---|---|---|
map | every-pr or on-request | When 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. |
stack | A list of labels | The project's main technologies, such as [Tauri, Rust, React, SQLite], shown on Home. Each label is 1 to 16 characters. Optional. |
skill | A skill name | The 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.
| Field | Type | Meaning |
|---|---|---|
rung | string | Rung ID. |
short | string | Optional compact label for Home Activity, 1 to 16 characters on one line without control characters. Falls back to the title. |
depends_on | list of plan IDs | Plans that must be Done first; [] for none. |
design | list of URLs | Each screen's own design frame or artboard; [] if none, or pending while the screens aren't drawn. |
skills | list of skill names | Optional. 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 withNo design:and its reason. - With
design: pending,rungflo nextleaves 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.