We Replaced Our Project Management Stack With Flat Files and AI Agents

"The conventions file IS the schema." — Diego Oppenheimer

Last week, Diego Oppenheimer (founder of Algorithmia, partner at Factory) published a piece that hit Hacker News and went viral in the AI builder community: "I Replaced Our CRM With a Git Repo and an AI Agent."

His thesis was brilliant in its simplicity: the best interface between a human and an AI agent isn't a GUI or an API. It's a plain text file. By replacing Salesforce with markdown files, git, and a conventions file, he got transactions, audit logs, access control, and atomic commits for free.

We read it and immediately nodded. We've been doing a version of this at Monkey Run for months without calling it that.

We run a multi-agent venture studio. We have specialized AI agents (founders, PMs, marketing, security, COO) operating across multiple concurrent projects. Early on, we tried to hook them up to traditional project management tools—Jira, Linear, Notion.

It was a disaster.

Traditional PM tools aren't agent-readable. Agents struggle to authenticate, paginate through API results, or reason over deeply nested JSON responses efficiently. They lose context. They get stuck in pagination loops.

We needed something agents could read with cat and update with a text edit. Here is the architecture we built, what broke along the way, and the rules that keep the whole system from collapsing.

The Architecture: HWW-1.5 Layout

Every Monkey Run project follows a standardized flat-file layout we call HWW-1.5 ("How We Work"). There is no database. There is no API. The file system is the source of truth.

project-root/
  .agents/                    # Agent definitions (prompt-as-code)
    agent-name/
      agent.yaml              # Identity, model, tools
      directives/             # .md instruction files
  .cursor/rules/              # Cursor orchestrator rules (.mdc)
  src/                        # Application source code
  FEATURES.yaml               # Feature contract (source of truth)
  COO_STATUS.md               # Cross-project status (COO reads this)
  PATTERNS.md                 # Lessons learned, reusable patterns
  CONVENTIONS.md              # The schema

The core of this system is file-based handoffs.

For example, our AI COO (Jared) doesn't query an API to see how a project is doing. He reads the COO_STATUS.md file. The project's founder agent updates that file at the end of every session. It's a one-way flow: agents write it, the COO reads it.

Similarly, FEATURES.yaml acts as the definitive contract for what is being built.

# Example FEATURES.yaml excerpt
- slug: portfolio-dashboard
  name: Portfolio Dashboard
  status: in-progress
  priority: p0
  owner: atlas-founder
  acceptance_criteria:
    - Shows real-time valuations
    - Syncs with ESPN API

Agents read FEATURES.yaml at session start to understand their scope, priorities, and constraints. If a feature isn't in the YAML, it doesn't exist.

CONVENTIONS.md: The Soul of the System

As Diego pointed out in his CRM build: "The conventions file IS the schema."

Agents are processes. They read files, do work, and write files. Without clear rules, they invent their own conventions—and those conventions conflict across agents and sessions.

Our CONVENTIONS.md file is a 600-line document that acts as the database schema. It defines naming rules, commit formats, access control, entity resolution, and validation constraints. Every agent reads this at session start.

The key innovation for a multi-agent system: agents have autonomy within their lane, but need PRs to change lanes.

The file evolves through failure. Every time an agent makes a mistake that a convention should have prevented, we add a rule. When a rule is too restrictive and blocks legitimate work, we relax it. It's a living schema.

The PR Decision Tree (Access Control Without IAM)

If you have multiple AI agents touching the same codebase, how do you prevent them from destroying each other's work?

You don't need complex IAM roles. You use git branch protection—a system battle-tested for 20 years. We codified this into a PR Decision Tree in our conventions:

graph TD
    A[Was this explicitly instructed by a human?] -->|YES| B{Was it destructive?}
    A -->|NO - Agent Inferred| C[Open PR for review, always]
    B -->|YES| D[Open PR, always]
    B -->|NO| E[Commit directly to main]

Destructive actions (Always PR):

Deleting any file that's been in main for >1 commit
Changing a feature status to cut
Modifying FEATURES.yaml priorities
Bulk updates (touching >5 files in one commit)
Changing CONVENTIONS.md itself

Safe actions (Direct Commit):

Adding new files
Updating code within an assigned feature
Adding tests
Updating documentation
Writing to COO_STATUS.md

The goal is speed with guardrails: agents move fast within their assigned feature, but need human approval to change the architecture or delete history.

What We Have That Single-Agent Systems Don't

Diego runs one agent for one fund. We run specialized agents across an entire portfolio of startups. That requires a few extra layers:

Cross-project coordination: Our COO agent sweeps across all project repos, reading their COO_STATUS.md files, and aggregates them into a single dashboard.
Materialized views: We use AI to generate daily summaries with auto-flagging. These are treated like materialized views in a database—agents are forbidden from hand-editing them; they must regenerate them from the source data.
The orchestrator pattern: We have agents that manage other agents, making judgment calls about when to delegate a task to a specialist vs. when to keep the context and build it themselves.

What Broke (The Honest Section)

It wasn't a smooth path to get here. We broke a lot of things.

Agent Conflicts: Before we implemented WIP.md (Work In Progress), we had two agents undoing each other's work in the same files simultaneously. One agent would refactor a component while another agent was trying to add a prop to it.

Context Rot: Agents would lose track of architectural decisions mid-session. They'd start building a feature, hit a token limit, summarize their state poorly, and resume the next session with a completely different architectural approach.

The Human Bottleneck: Agents would block on design decisions we hadn't made yet. They'd open a PR, wait 12 hours for the CEO to wake up and review it, and do nothing in the meantime.

Duplicate Entities: Before we had an entity resolution protocol, agents would create duplicate records across projects. We had three different files for the same external API integration because agents didn't know how to check if it already existed.

Every single one of these failures became a rule in CONVENTIONS.md.

What's Next

We're currently building pre-commit hooks that enforce CONVENTIONS.md automatically. If an agent tries to commit a status transition from shipped back to in-progress, the hook rejects it. The schema enforces itself.

We're also integrating Open Brain (a vector DB + MCP architecture pioneered by Nate B. Jones) as the memory layer underneath the flat files.

The convergence is happening right now: Diego's git-as-CRM, Nate's Open Brain, and our multi-agent orchestration. The future of project management isn't a better SaaS app. It's a folder full of markdown files, a git repository, and a really good conventions file.