VISION.md as the External Contract for Scheduled Agents

·https://github.com/badass-courses/aihero-support/blob/main/VISION.md
repopatternaiagentsagent-loopssupportfrontgovernance

VISION.md gives scheduled agent loops an external operating contract before they touch Front-managed support spaces.

Joel’s useful distinction here is dead simple: AGENTS.md is for inside the repo, while VISION.md is for agents approaching the repo from the outside. Not “how to compile this package” or “where the tests live.” More like: what is this space for, what are you allowed to do automatically, and what should you leave the fuck alone.

That matters for scheduled agent loops. External agents can read the vision first, then choose the right mode: observe, draft, route, archive, escalate, or stop. That’s a cleaner contract than asking every autonomous process to infer intent from repo internals and vibes.

The source is the badass-courses/aihero-support VISION.md, tied to work generalizing AI Hero support for Front. The repo content wasn’t available from this capture, so the durable thing to remember is the contract shape, not the specific rules in that file.

This fits joelclaw because it separates permission from implementation. VISION.md says what outside agents may do. AGENTS.md says how internal agents should work. Different files for different blast radiuses. Good boundary. 🐀

Key Ideas

  • VISION.md is an external-facing agent contract: goals, permissions, boundaries, and autonomy rules for scheduled work.
  • AGENTS.md stays internal-facing: repo commands, architecture, tests, deploy steps, and implementation rules.
  • For Front-based support, the pattern creates a safer layer before agents touch customer conversations: read the vision, choose allowed actions, stop when outside scope.
  • The pattern scales better than stuffing every policy into one file because “what may I do here?” and “how do I work here?” are different questions.
  • A future joelclaw loop runner could require a VISION.md preflight receipt before scheduled jobs act on external systems.

Links

← All discoveries