Project Management Inside the Repository

The Problem

On most projects, project management happens at one remove from the work. The plan lives in a tracker, decisions are buried in meeting minutes, the status update is whatever someone wrote by hand last Friday, and the developers work somewhere else entirely. The project manager sees the project through summaries of it, and influences it by asking other people to make changes.

AI changes what’s possible here, but only if the project’s information has a home an agent can reach and a shape it can follow. So I moved project management into the repository itself, beside the code and content, and I keep refining how that works on every project I run.

Working Where the Developers Work

Being in the repository changes what a project manager can do:

• See what is actually happening. I can read the branches, the pull requests and the code itself, and ask an agent to compare them with the plan. Status comes from the work itself.
• Influence the work directly. Requirements, specs and decisions live where developers read them. When a ruling changes a requirement, the change lands in the document the developer opens, the same day.
• Contribute directly. I make changes in the developers’ own workspace through pull requests: specs, page content, test plans, structured data, fixes to documentation. They review my work the same way they review each other’s.

A Project Laid Out as Files

Every project gets the same skeleton. Here is the shape of one, simplified from a live client repository:

• pm/the program itself
  • README.mdwhat lives where, across the whole repository
  • CHARTER.mdwhy the project exists and who decides
  • PROCESS.mdhow we work; changes more often than the charter
  • STATUS.mdwhere things stand, kept current by an agent
  • STATUSLOG.mddated decisions, newest first
  • ROADMAP.md · BACKLOG.mdwhat's coming, planned ahead
  • meetings/one confirmed, dated record per meeting
  • status-reports/reports generated from the records
• workstreams/<area>/open items and next steps, beside the work they track
• docs/source material the project collects, organized
• .agents/skills/the rules each agent follows

Two rules hold it together. If a document’s subject is the project, it lives in pm/; if its subject is the work, it lives with the work, and pm/README.md records where. And every document is either a source, where a fact is written down once, or a view built from sources, like a status page or a report. If a view were deleted, it could be rebuilt from the sources, which is what lets an agent maintain it.

Anything Can Come In

Meetings are one input among many. Whatever the project produces or depends on can be brought into the repository and organized so an agent can work with it:

• Meeting transcriptsdrafted into records, confirmed by a person
• Client websites and PDFscrawled, archived and read
• Emails and documentsfiled beside what they affect
• Spreadsheets and exportsconverted to structured data
• The code and its historybranches, pull requests, commits

the repositorypm/ · docs/ · workstreams/ · skills · code

• A weekly HTML reportshown in the team meeting
• A one-page brieffor an executive or a single decision
• Specs and requirementsupdated the day a ruling is made
• Data and modelsready for the developers to build on
• Pull requestsin the developers' own workspace

A meeting shows how the loop runs. The call is transcribed, an agent drafts a record, I confirm it, and every change the meeting implied is carried into the document it affects in the same pass. The transcript itself stays out of the repository, since it carries personal detail and half-formed positions.

From a Client’s Website to an Order Model

On a website rebuild for a metal building-products manufacturer, the new site had to replace how customers order. Each product had a PDF order sheet that customers printed, filled in by hand and sent back. Before any of that could be designed, the project needed to know what was actually being ordered, across 93 products.

1. Crawl the live catalogueA script in the repository walked the client's product pages and downloaded every order sheet and model drawing, date-stamped, with a manifest recording where each file came from.docs/products/catalog.json
2. One folder per productEach product got its own folder holding its PDFs and a page of everything that could be read out of them.docs/products/<category>/<family>/<product>/
3. Structured dataThe form fields on every sheet were read out into structured data. Laid side by side, the sheets turned out to share one vocabulary and nearly all offered the same choice between a quote and an order.docs/products/ProductCatalog.md
4. A unified order modelOne model for every order and quote request across the catalogue, drafted beside it, with the decisions it still needs from the client listed at the end.docs/products/OrderModel.md
5. A data model for engineeringThe order model was then written out as tables and fields, one document per table, in the engineering workstream where the developers pick it up.pm/workstreams/ws-engineering/data-model/

The pipeline is committed with the catalogue, so when the client’s site changes it can be run again. The order model is a working draft, not yet confirmed by the client.

Presenting It However It’s Needed

Because the whole project’s information sits in one place in a form an agent can read, it can be presented in whatever shape a particular audience needs, when they need it.

Each week an agent builds a paged HTML report from the current records for the team meeting: where every workstream stands, what was decided, who is carrying what, and what’s blocked. It replaced a slide deck that used to be put together by hand. The same records can produce a one-page brief for an executive, a decision paper laying out the options on one open question, or a walkthrough for someone joining the project. Each is built from the records, so none of them can drift from what was actually decided. A client stakeholder put it well when they built one of their own: if it’s derivative or duplicative of the maintained documents, that means it’s correct.

Writing Skills as Problems Come Up

The agents work through skills: written instructions that hold the rules for one job. I write them on the spot, when a problem shows up, so the fix applies to every later run. These are some of the problems that produced one:

• A first-pass meeting note read well but had dropped the whole question-and-answer section and added two details nobody said. The meeting skill gained a second pass that checks the draft against the transcript, and a rule that no specific may appear that isn’t in the source.
• Status counts drawn from the repository aged quietly. The status skill now requires every such section to say when it was last checked.
• A generated report over-credited the two people who wrote the most documents. Owner fields now get a human review each week.
• A client’s catalogue existed only as PDFs on their website. The crawl and extraction became a script in the repository, rerunnable when the site changes.

Some skills carry from project to project, such as meeting triage, status upkeep and report layout. Others exist for one project’s problem and stay there.

Current Status

This is how I run every project now. Each new one starts from the same skeleton of documents and skills, takes on whatever that project needs, and feeds what it teaches back into the method. The framework is written down as a portable document and keeps changing as I use it.