Why a folder of specs cannot refuse: the objection to file-based planning, taken seriously and answered.
Graphban · · 3 min read
The absence this makes loud: a plan that cannot disagree with you.
The most reasonable objection to all of this is that you already have a docs folder. It deserves a real answer rather than a dismissal.
Most people reach the same conclusion and reach for the same tool: write it down. A vault of markdown — Obsidian, or just a docs/ folder — with your specs, your task list, your notes, and a CLAUDE.md holding the rules. Point the agent at it and let it read and write.
It is a genuinely good way to think, and it is the right first thing to build. Graphban started as exactly that. The problem shows up the moment you ask it to be an authority rather than a record — because a vault is a document store doing the job of a control plane, and a document store has exactly one answer to every request: yes.
A file cannot refuse
An agent writes status: done into your task file and
the write succeeds, because writes succeed. There is no call to gate, so approval isn't
earned — it's typed. Every rule in your CLAUDE.md
is a suggestion with good manners.
A folder cannot arbitrate
Two agents open the same list and one of them loses. There are no leases, no atomic
claims, no reservations — a filesystem has no concurrency model for work, only
for bytes, and git will surface the conflict long after both of them wasted the effort.
Nothing distinguishes empty from finished
A section nobody wrote looks exactly like a section that's complete. And because you
edit the spec in place, there is no frozen version to measure against — so drift is
definitionally zero, and the thing that changed to match what got built is your spec.
Every note is equally true
Nothing was vetted, so nothing can corroborate anything. A wrong lesson written twice
by one confused session outranks a right one written once — and the next agent reads it as
established fact, because a vault has no notion of who vouched for what.
And the agent is editing the rules
The file that tells the agent how to behave is a file the agent can write to. When that
works it is invisible; the one time it doesn't, you lose trust in the whole vault and you
don't get it back. That's why Graphban will draft a change to your
AGENTS.md and hand it to you — and why approving it
writes zero bytes.
None of which means throw the markdown away. Specs in Graphban are markdown, and they sync two-way with a folder — point it at a Drive or Obsidian directory and your PRDs are still files you can read, diff and edit in the editor you like. You keep the writing. What you add is something that can say no. What a spec is, and why approval is not a status anyone sets, is specs.