A plan that lives in your git repo, not a cloud database

You are a staff engineer, and your plan lives somewhere you can't reach with the tools you trust. Jira and Linear keep it in a closed cloud database you only touch through an API; Notion's markdown export is lossy and one-way. You can't diff a plan, branch it, or review a scope change in a pull request — and you can't hand the raw truth to an agent without an export step in between.

My Architect inverts that. The filesystem is the source of truth. The UI is a view and an editor over the files, not the other way around.

The files are the plan

A project is a directory of plain, human-readable text:

• hierarchy.yaml — the tree of nodes (initiatives → epics → features → tasks).
• requirements.yaml — the orthogonal requirements layer (FR / NFR / SAR / CON / OQ).
• Docs as .md — one source-of-truth document per node.
• Diagrams as .dsl — WBS, User Story Maps, Event Storming, box/C4.

No proprietary blob, no vendor round-trip. You can open the whole plan in your editor, grep it, and commit it next to the code it plans. The UI reads these files and edits them back; nothing lives in a place the filesystem doesn't.

Why the diffs stay clean

Making files the store is easy. Making them diff well is the part that took discipline, so a scope review reads like a code review instead of a wall of noise.

Stable paths across renames. hierarchy.yaml holds a stable id per node; on disk, each node is a directory in a slug chain that mirrors the tree (register/email-login/…), so the layout is browsable, not a flat pile. The slug is frozen at creation — rename a node and only its title changes in hierarchy.yaml; the directory keeps its original slug and never moves. So git log --follow on a feature's doc stays intact across a year of renames, and a rename shows up as a one-line title change, not a phantom file move.

Layout is recomputed, not stored. A diagram's .dsl holds structure, not pixels. For WBS, User Story Maps, and box/C4, layout is recomputed from the DSL every time you open the canvas (ELK auto-layout, six presets), so there is no coordinate drift between clients and nothing to diff but the DSL. A diff on such a diagram shows a box added or an edge rerouted — a structural change — never that someone nudged a node three pixels while reading. The one place coordinates enter the file is a deliberate manual pin in an Event Storming board (@x,y on a card you dragged), and that too is a visible, one-line DSL change — an intent you chose, not incidental drift.

Roundtrip is byte-stable. parse(serialize(x)) == x. What the UI writes back is what you'd have written by hand, so an edit through the app and an edit through your editor produce the same bytes. The diff carries the change and nothing else.

The loop is live, not a sync job

Because the files are canonical, editing them from either side just works. Change requirements.yaml in your editor and chokidar — watching the project directory — pushes it to every open browser within a 100ms debounce window. Move a node on the canvas and the .dsl is rewritten on disk. There is no import, no export, no "sync now" button, because there is only ever one copy of the truth.

The same property is what makes the plan agent-native. An agent doesn't scrape an API and rebuild a shadow model — it reads the actual files through the MCP tools, or works the task loop directly (get_next_task → start_task → complete_task, with a blocker gate for anything it can't finish). The raw truth is already in the format the agent wants. No export step stands between the plan and the thing that acts on it.

The aha

Next quarter's scope changes. Someone re-parents an epic, drops two features, adds a requirement, redraws the release map. In a cloud tool that's an audit-log entry you take on faith. Here it's a branch and a pull request: the reviewer sees hierarchy.yaml gain three nodes and lose two, requirements.yaml add one FR, a .dsl reroute an edge — and approves, requests changes, or reverts, with the same muscle they use on code.

You review next quarter's scope as a diff, because the plan is just files, and the file is the truth. Branch it, blame it, revert it, put it behind CI. It's out of the vendor's database and inside your repo, where the rest of your source of truth already lives.

How to try it

1. Create a project — see getting started. Pick a preset and complexity; it scaffolds a hierarchy, a WBS and baseline docs as files.
2. Point your version control at the project directory and commit it. Rename a node, edit a doc, redraw a diagram — then read the diff.
3. To let an agent read and edit the same files, connect an AI agent over MCP.

The plan belongs in the same place as the code that fulfills it: under version control, in a format you can read, owned by you.