Docs / Plans
Plans
The plan file format, how versions work, and how freshness is checked.
File format
Every plan managed by Flanner starts with YAML frontmatter. The tools write it; you do not edit it by hand. A version saved with a device signing key also carries artifact_id, the hash of its content; parents, the version it follows; workspace_id, which reads local: and the project id until the repository joins a team; and actor_device_id, the device that wrote it.
---
mcp_plan_file: true
plan_manager_version: '1.0'
project_id: 3d816ecd-489a-4fa0-abe2-15ec93f60d5a
project_name: my-app
plan_file_id: 59c34f9c-8471-47fc-97f2-8dcfefa15434
plan_name: architecture
version: 2
created_at: '2026-01-15T10:30:00.000000Z'
created_by: claude
artifact_id: sha256:6f3e9b1c07a24d58b1e0c9f4a2d7e8b3c5f1a0d9e8c7b6a5f4e3d2c1b0a9f8e7
parents:
- sha256:2c9d4e1f7a0b3c6d8e5f2a1b4c7d0e9f3a6b5c8d1e4f7a0b2c5d8e1f4a7b0c3d
workspace_id: local:3d816ecd-489a-4fa0-abe2-15ec93f60d5a
actor_device_id: dev_7ab74afd93b09861
---
# Architecture Plan
Your plan content here...Versioning
Each version is its own file — architecture_v1.md, architecture_v2.md — and the database records which one is current. Versions are plain revision numbers, not semantic versions. A raw write into the plan directory is refused by the guard hook. flanner sync imports only files that already carry a flanner header, such as plans restored from a backup. To add a new plan, ask your agent to save it, or paste it into the web interface.
# Ask your agent to revise the plan. The MCP tools write
# .plans/architecture_v2.md and record it; nothing to hand-edit.
flanner history architecture # every version, who wrote it, when
flanner sync # re-import files that carry a flanner headerChange per version
versiongoes up by one, or further if a file with that number already exists- Update
created_at - A new
artifact_id, with the old one inparents - Change the content
Keep the same
plan_file_id— links all versionsproject_idandplan_namemcp_plan_file: true
Working through an agent, you never touch the frontmatter yourself — the MCP tools version the file for you. Ask Claude to “show the version history for the architecture plan” to browse it.
Freshness
Freshness tells you whether a plan still matches the code, with the evidence behind the verdict. It is computed on demand from the plan text plus git: nothing is stored, git access is read-only, and every status can show its reasons. It extracts the paths and symbols a plan cites, checks they still exist, anchors the plan version to the commit history, and counts how many commits touched the cited files since.
$ flanner freshness payment-webhooks
● suspect payment-webhooks.md v2 · written 12 days ago
! 24 commits touched cited files since anchor 4c19aef
src/webhooks.py
It names 1 symbol; all still exist.
verify_signature
Re-read it against those commits: git log 4c19aef.. -- src/webhooks.py
Revise it: flanner web opens the editor; flanner history payment-webhooks shows what changed.The four statuses
Everything the plan cites still exists, and little has changed since it was written.
Some movement: 5 or more commits touched the cited files, or the plan is over 45 days old.
Heavy churn: 20 or more commits touched the cited files since the plan was written (60 for the whole repo when the plan cites no files).
The plan cites at least one path or symbol that no longer exists in the repo. The evidence names each one.
flanner why PLAN_NAME prints the reasoning, and --output json gives the raw fields: the anchor commit, the cited paths and symbols, the ones that no longer exist, and the commit count. Agents can check the same thing over MCP with get_plan_freshness_tool before trusting a plan.