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.

---
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: 2025-01-15T10:30:00Z
created_by: claude
---

# 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; a file you add by hand is picked up by flanner sync.

# 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                   # import a file you added by hand

Change per version

Increment version by 1
Update created_at
Change the content

Keep the same

plan_file_id — links all versions
project_id and plan_name
mcp_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

payment-webhooks v2: suspect
  - 24 commits touched cited files since anchor 4c19aef
  anchored_at_commit: 4c19aef8b21d
  referenced_paths: ['src/webhooks.py']
  referenced_symbols: ['verify_signature']
  commits_since_anchor: 24
  churn_scope: paths
  age_days: 12

The four statuses

fresh

Everything the plan cites still exists, and little has changed since it was written.

aging

Some movement: 5 or more commits touched the cited files, or the plan is over 45 days old.

suspect

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).

stale

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. Agents can check the same thing over MCP with get_plan_freshness_tool before trusting a plan.