Running Agility Work from an Ops Repo

When every developer manages a team of agents, the agents need shared memory across projects. An ops repo is that memory: one Git repo, mostly Markdown, that people and agents read and update as the source of truth for all your Agility work.

Each project repo holds that project's detail. The ops repo holds the portfolio: what's in flight, what stage each project is at, what you've learned, and how you do things. Any agent session opens it, reads the rules in CLAUDE.md (or AGENTS.md), and updates the dashboard or starts a new project the same way everyone else does.

This article is part of the Vibe Coding with Agility section.

Rules for the repo

• Markdown first, no code, no secrets. Markdown is readable by people and agents, and diffable. Documents and data are fine alongside it: rendered PDFs, CSV exports, JSON snapshots.
• Link, don't copy. Summarize a project here and link to its repo for detail.
• Absolute dates (2026-10-29), never "last week". Agents read these files months later.
• People by name and role only. No contact details, credentials or customer personal data.
• "Unknown" beats a guess. Open questions go in an inbox file.
• Sensitive documents live somewhere locked down. Contracts and internal client documents go in a restricted store; the ops repo links to them.

Layout

ops/
├── CLAUDE.md             the routines every agent session follows
├── README.md             "if you want to… go to…"
├── DASHBOARD.md          one row per project: status, owner, next action
├── INBOX.md              quick capture, triaged later
├── projects/<slug>.md    one page per project, with front matter
├── playbooks/            how-to by stage: new project, demo, handoff
├── knowledge/            gotchas, MCP rules, integrations, decisions
├── starter/              your reference implementation: capabilities, drift, backlog
├── templates/            project page, intake, demo script, debrief
└── log/                  append-only logs

Each project page starts with front matter an agent can read and update:

---

slug: acme-site
status: building        # intake | discovery | building | demo-ready | live | handed-off | archived
owner: Jane Smith (Lead Developer)
repo: https://github.com/<org>/acme-site
instance_guid: 1234abcd-u
last_activity: 2026-10-29
---

Routines agents can run

CLAUDE.md turns the repo into something agents can run. Write each recurring job as a numbered routine:

**When a project changes stage:**
1. Update projects/<slug>.md (front matter, snapshot, a dated log line).
2. Update its row in DASHBOARD.md.
3. Post a short note to the CRM or ticket, if you use one.
4. New traps go in knowledge/gotchas.md; reusable code goes in starter/backlog.md.
5. Commit and push.

**"Sweep the projects"** (weekly):
1. `gh repo list <org>`; any repo without a page gets one.
2. For each repo: last commit, uncommitted work, new docs since last_activity.
3. Check the reference implementation's history; update the drift table.
4. Summarize what changed and list questions only a person can answer. Commit.

Also write down what agents must never do on their own, such as changing a deal's stage or posting anything customer-facing without a person reviewing it first.

Habits that keep it useful

• Same-day updates. An out-of-date dashboard is worse than none.
• Every call gets a transcript, and the transcript goes into the docs. Have an agent pull decisions, follow-ups and requirements into the project page the same day.
• Record decisions as you make them. A few lines on why, written at the time. It's what you'll want most in three months.
• Mine your history. Point an agent at every project repo and its Git history and ask what keeps going wrong. Turn the answers into gotchas, skills and starter fixes.
• Every lesson lands somewhere. One project's trap becomes every agent's rule.

Set one up in an afternoon

1. Create a private repo and clone it.
2. Ask your agent to scaffold the layout above and write README.md and CLAUDE.md from these rules, adapted to your stages.
3. Run the first sweep: list your org's repos and draft a page for each, marking unknowns as unknown. Review and correct.
4. Seed knowledge/gotchas.md from MCP and Agility Gotchas and your own history.
5. Schedule the sweep weekly.

Related

• Managing a Team of Coding Agents
• Training Your Team to Build with Agents
• Writing an AGENTS.md for Agility Projects