[Project.md: Structured Context Files as a First-Class Input for Project Agents]

I manage projects at Enji using the PM Agent our team builds. That combination, being both the user and part of the team, means I notice problems differently. This is about one problem that took me longer than it should have to name.

PM Agent had access to everything it should have needed: Jira tickets, GitHub commits, worklogs, and sprint history. When I asked about project status, it gave me answers that were technically accurate but oddly generic, the kind of response that correctly summarizes what's in the data without understanding what the data means for this specific project, with this specific client, running under these specific constraints.

The agent knew what was happening, but it didn't know what it meant.

I asked it once whether we were at risk of missing the Q2 milestone. The answer referenced ticket completion rates and sprint velocity: all correct. What it didn't know: our client had a contractual clause that made a two-week slip significantly more expensive than the numbers suggested, and our team lead had flagged that two of the open tickets were harder than their estimates reflected. The agent had no way to factor in either of those things, because neither lived in Jira.

That's the problem I was trying to solve.

Jira is good at tracking what the team has committed to and what's been completed, but not designed to capture why decisions were made, what constraints the team is operating under, or what "good" looks like for a particular client.

That knowledge lives everywhere and nowhere. In sprint planning notes. In the onboarding document, the team lead wrote six months ago that nobody has touched it since. In the heads of the three people who were on the original scoping call. In a Confluence page that was accurate once and hasn't been touched in a quarter.

When an AI agent works without this context, it operates like a very capable analyst who just joined the team yesterday: technically fluent, but missing the institutional knowledge that shapes every real decision.

This is what the AI community calls a context window problem, but in practice, it's less a technical constraint and more an organizational one. The information exists; it's just not in a form the agent can access.

Deciding what the agent should know has a name now: context engineering. It's less about prompting and more about deciding, deliberately, what counts as context for this project and this team. Project.md is the simplest form of that decision we've found.

Project.md is a plain-text file that lives in the project's settings in Enji. The idea is simple: you write down, once, the things that a new team member would need to understand to do their job on this project, and the agent reads it every time it responds.

I think of it as a context contract: a formal agreement between the team and the agent about what constitutes the source of truth. Not what happened in the last sprint (Jira handles that), but what the project is, who it's for, what the constraints are, and how we define good outcomes here.

What this file covers:

• Project description and current phase: what we're building, who the client is, and where we are in the delivery lifecycle.
• Key milestones and their business significance: not just dates, but what each milestone means contractually or strategically.
• Team structure and ownership: who is responsible for what, including how we handle handoffs.
• Risk thresholds and escalation rules: what triggers a client notification, what we handle internally, and what constitutes a blocker versus a flag.
• Client conventions and sensitivities: terminology the client uses, topics that require careful framing, and communication preferences.
• Our definition of "at risk": because "three tickets open with four days to the milestone" means something very different depending on the project.

Writing it took about an hour. That context now informs every response the agent gives, without me having to repeat it in every query.

Project.md handles project-specific context well. But we also have institutional knowledge that lives at the organizational level: architecture decisions, API documentation, process guides, and retrospective notes from past projects with the same client. That knowledge lives in Confluence, and once we connected it to PM Agent, it became queryable too.

The practical impact showed up in two ways: first, the agent stopped giving generic answers to process questions. When someone asked how we handle security review handoffs, it could reference the actual process document rather than offering a general answer. Second, onboarding got faster in a concrete way: a developer joining mid-sprint understood the client's compliance constraints from a single query, instead of needing a separate handover conversation with whoever happened to hold that context.

We're careful about which spaces are included. Not everything in our Confluence is relevant to every project, and an agent pointed at everything returns noisier results than one pointed at the right sources. The integration settings let us control this per project, which matters more in practice than it sounds.

The clearest way to show what both layers changed is to look at real questions — some draw on project-specific context from Project.md, one draws on organisational context from Confluence.

"Are we at risk of missing the Q2 milestone?"

Before: "Current sprint completion is at 71%. With 12 open tickets and an average cycle time of 2.3 days, delivery by Q2 is feasible but tight. Consider reviewing the backlog for scope reduction opportunities."

After: "Based on current velocity and the two tickets flagged as higher-effort than estimated, the Q2 milestone is at moderate risk. Given the contractual implications of delays beyond two weeks for this client, this warrants a conversation with the client before the end of the week rather than a backlog review."

The data was identical, but the interpretation changed because the agent now understood what Q2 meant for this specific client.

"Is anything on this project drifting that I should look at?"

Before: "Three tickets are open with four days remaining in the sprint. Cycle time is within the normal range. No immediate blockers detected."

After: "Three tickets are open with four days left, which is within normal range for most projects, but this project's definition of 'at risk' flags any client-facing ticket still open inside the final five days. Two of these three are client-facing, so by this project's own threshold, they're worth a look now rather than at sprint end."

The "before" answer applies a generic notion of "normal." The "after" answer applies this project's definition of risk (the one written into Project.md), so the same ticket counts that looked fine become a flag because the agent is measuring against the team's actual standard instead of a default.

"What's the status of the authentication module?"

Before: A summary of ticket statuses and recent commits, accurate but context-free. It tells you what changed without knowing why it matters.

After: The same summary, with a note that the authentication module is marked as a dependency for the client's compliance review and that any delays here have downstream implications for the sign-off timeline we committed to in the last steering call.

Here, the agent pulled organisational context from the Confluence docs, not from the .md file.

As the responses show, in each case, the agent moved from a technically correct output to an actually useful one.

Project.md doesn't update itself. When something meaningful changes — a new milestone, an adjusted escalation rule, a client reversing a convention — someone has to update the file.

That's by design. The point of a context contract is that it's deliberate. Writing it forces the team to articulate things that are often left implicit: what "at risk" actually means here, what the client cares about most, and where the boundaries of the agent's autonomy should be.

We've found that the act of writing surfaces alignment gaps. When two team members disagree about what goes in the escalation rules section, that disagreement shows up immediately, not after something has already gone wrong.

The initial file takes about an hour to write; updates can take fifteen minutes or more. In return, every subsequent agent interaction is informed by that context. It's one of the better time investments I've made in the last year of working with AI in a PM role, and it's why context engineering has become a discipline in its own right for how we manage projects.