Keep product direction durable without freezing implementation, and promote recurring reviews only when their signal earns it.
Separate product direction from operating instructions
VISION.md describes the user, intended outcome, product qualities, durable constraints, and open decisions. Code remains implementation truth. AGENTS.md can instead describe how an agent operates. Do not silently merge those roles or treat an old architectural diagram as a permanent restriction.
For a concrete task, make adherence explicit: Preserve / May change / Must ask / Verification. Strict refactoring constraints and open-ended improvement are different contracts. An agent can improve the architecture without abandoning the product’s end ideal.
Keep automation at the lowest justified stage
The promotion ladder is manual run → deterministic script → bounded agent → non-blocking CI report → blocking gate, with schedules and human approval as deliberate choices rather than inevitable destinations.
Every promotion needs an owner, evidence threshold, false-positive tolerance, latency and cost boundary, stop condition, and recovery path. Collect repeated manual receipts before making a result blocking. General curation and review schedules can become noise; useful on-demand execution is better than automated interruption without a decision to change.
Operating practice
Let vision guide automation
What to notice
Keep code as implementation truth while giving agents durable product direction and an explicit adherence dial.
Try this
Draft VISION.md from product evidence, then mark Preserve, May change, Must ask, and Verification for one task.
“Code is a source of truth.”
John Lindquist · 05:35:33
Concept
Vision describes the user, outcome, qualities, durable constraints, and open decisions. It should guide improvement without freezing a stale architecture into permanent context.
Reflection
VISION.md and AGENTS.md can serve different roles. Do not silently collapse product direction and operating instructions.
Recording evidence: listen at 05:25:50.
“This defines the end ideal of this product. And no matter what the state of the product is in, it can always push more towards that vision.”
John Lindquist · 05:37:00
Links shared for this topic
- Workshop NotebookLM notebook — The research notebook and generated artifacts shown near the close.
- Handy — A dictation tool shared during the VISION.md discussion.