The Project Graph

The problem: agentic projects forget the why

A multi-agent development setup produces a mountain of artifacts — PRDs, change requests, tasks, architecture docs, changelogs, commits. Most tooling captures what exists. Almost none captures why each step was taken — and that is exactly the memory a team of agents needs to stay coherent.

Three failure modes fall out of that gap, and every one of them is a lost-context problem:

Actor, not index

Context Graph's whole thesis is the fourth element: every edge carries a RelationContext — who decided, why, via which channel, under which policy, valid until when. So the thing you called most important — the reason behind each step — isn't a feature to bolt on. It's the native unit of storage.

That flips the ambition. Not "an index of progress and code" but a decision-and-state substrate your agents read from and write to — one that can also act: define the methodology, hold current state, surface precedent, and refuse illegal moves.

What CG is not — and what it sits on

A crowded adjacent category is the structural code graph — tools like CodeGraph that index symbols, calls, and imports with tree-sitter to make an agent's reading of a codebase cheaper (real, measurable token savings). CG is not that, and shouldn't try to be. The distinction is sharp — it's recoverable vs irrecoverable information:

Two more axes: CG is active (it gates, flags, records) where a code graph is descriptive (a map you read); and CG is generic (sales, compliance, agentic dev — code is one config) where a code graph is code-only. So the two stack: a structural index is the ideal feeder for CG's API/Module objects — giving the "don't rebuild that API" check a complete, exact inventory to govern against.

Grounding: an existing AI dev team

This isn't hypothetical. The analysis maps onto a working methodology — dsivov/ai_development_team — so every proposal below has something real to answer to. (The setup evolves; treat it as the reference for principles, not a frozen spec.)

The project ontology

The ontology layer already lets us declare a typed schema per workspace. A project graph is just the right object and link types for software delivery:

Typed properties matter here too: a Decision has status (enum: proposed · accepted · superseded), an API has a signature and stability, a Task has state. Those typed values are what the rules gate and precedent search reason over.

What's worth remembering

You leaned toward "decisions worth remembering," not every keystroke — but weren't sure where the line falls. Here's a proposal for a principled line, and it comes straight out of CG's own design.

A RelationContext has content only if it can name a rationale and (usually) an actor — CG even has an is_empty() check for exactly this. So use that as the filter:

Roles as first-class identities

The roles are distinct, each with its own skills and sessions. The exact set is preset data, not core code — the current setup has six (manager, architect, developer, integrator, devop, production-engineer), and it will keep changing. Whatever the list, being distinct has three clean consequences in the graph:

Methodology as data

You chose the actor / enforcement model — CG shapes agent behaviour, not just records it. The way that becomes real: encode the methodology in the three layers we already have, so the process is data, not prose in a system prompt.

Together those three are a state machine over the project graph: agents advance the project only through governed actions, and the pre-emit gate refuses illegal moves — surfacing the reason. That is the "actor" in concrete terms.

# methodology rule: a new API that looks like an existing one gets flagged, not built
rule "reuse before you build"  priority 20
when
    sim(relation_type, "CREATE_API") > 0.4
    and similar(decision_trace, "EXISTING_CAPABILITY", 0.55)
then
    flag("A similar capability already exists — cite it or justify the new API")
end

Worked example: "don't rebuild that API"

The single use case that ties every layer together — a developer agent about to build something that already exists:

1. Developer agent, before coding, invokes ProposeAPI(name, description, module).
2. The gate runs sim() over the descriptions of existing API objects and does a precedent search over past decisions.
3. Duplicate? → FLAG with the match cited. The agent reads the reason and reuses instead.
4. Novel? → PASS; an audit edge records the new API, attributed to the role and session.
5. Either way the reasoning is now in the graph — the next agent inherits it for free.

This is ontology (API objects) + rules (the duplicate check) + actions (governed ProposeAPI) + precedent search, composed.

The sync bus: CG replaces shared files

Today the four roles coordinate through shared files — changelogs, task lists, architecture docs — which go stale the moment they're written. Replace the file hand-off with a live query against CG over the MCP server: each agent reads current state on demand and writes decisions back.

Onboarding & the playbook

How does an agent know how to use CG — the config, the flow, its own permissions? A setup wizard tailors and initialises the project; each agent then gets an operating manual. But "manual" splits into two things that must be handled differently.

Two kinds of "knowing CG"

The tailored wizard flow

The manifest — an agent's operating context

One generic, role-scoped call returns everything an agent needs to act; it re-fetches it when the config version bumps.

GET /workspace/manifest?role=developer  →
{
  "workspace": "acme_app", "role": "developer",
  "skills": ["clean-code", "debugging", "impl-patterns"],
  "object_types": ["Feature", "Task", "Module", "API", "Commit"],
  "actions": [ {"name":"ProposeAPI", "params":[…], "effect":"…"}, {"name":"AdvanceTask", …} ],
  "guardrails": [ "new API — confirm reuse (FLAG)", "deprecation needs a linked decision" ],
  "lifecycle": { "Task": "proposed → active → done | blocked" },
  "mcp": { "url": "…", "tools": ["query", "emit", "invoke"] }
}

The endpoints stay generic — POST /presets/{name}/install, GET /workspace/manifest?role=, and a POST /onboard that runs install and returns {workspace, per-role manifests, mcp, installed}. The wizard is orchestration on top; core never learns "manager" or "Task".

Ready vs missing

What this use case can stand on today, and what it's waiting on — mapped to the real state of the codebase.

Closing the gaps

A running analysis of the missing pieces this use case needs, settled one at a time. Each is a design sketch and a recommendation, not a committed build.

Gap 1 — Object-level RBAC shipped ✓

Your two firm choices — distinct roles and enforcement — both point straight at role-gated actions: "the architect may ApproveArchitecture; the developer may not." That is the sharpest gap, because the tempting shortcut is actively unsafe.

What's missing today. Access control stops at the workspace boundary (authenticate in auth.py, then you get the whole tenant). Inside a workspace there is no principal who can do some things and not others. Three pieces are absent:

• a principal within the workspace — the four roles as distinct, authenticated identities;
• permissions bound to objects/actions — role → which verbs, on which object types or actions;
• an enforcement point that runs before a state change.

Two layers, not one — CG complements the harness

Crucially, the current setup already enforces roles — in the agent harness (role_enforcer.py PreToolUse hooks + git branch rules). CG must not try to replace that. The clean division of labour:

So CG doesn't introduce access control from scratch — it moves the state-changing slice of it out of each agent's scattered hook config into one shared, auditable place. The reframing: not "close a security hole" but "centralize and audit what's already enforced per-agent." (The trap below still applies to that CG-side layer.)

The minimal design — a fourth policy layer

The shape is already familiar: a per-workspace policy next to rules / ontology / actions, enforced at the chokepoint the action layer already gives us.

Opt-in by default — it scales to zero

The requirement that CG stay simple for single-agent projects (including CG's own development) is met by the same pattern every other layer uses: absent means permissive. No rules → no gate; no ontology → no validation; and now no RBAC policy → allow everything. RBAC exists only where a workspace installs a policy.

Deployment stays identical — no external authorization service, no Zanzibar to stand up. RBAC is one more per-workspace JSON policy on the existing store; ReBAC reuses the graph. Single binary, same as today.

The CG-native upgrade — permissions from the graph (ReBAC)

Static role → actions works, but the project graph already encodes ownership: Role —owns→ Module —exposes→ API. So a grant can be relationship-derived — "a role may modify the APIs of modules it owns" — resolved by a graph query at check time. That is ReBAC (relationship-based, à la Google Zanzibar), and CG is unusually well-placed for it because the relationships are already first-class. Permissions then evolve with the project instead of living in a separate static table.

Gap 2 — Workflow orchestration shipped ✓

"Workflow orchestration" is really two gaps, and conflating them is how a project builds the wrong, enormous thing:

What the lifecycle layer is

Mostly composable from what exists, plus one new declarative primitive:

A transition becomes one guarded action: AdvanceTask(to:"done") → RBAC (may this role?) → lifecycle check (is active→done legal?) → rules gate (policy: passing commit + integrator sign-off?) → apply + audit edge (who moved it, why, evidence). The richer part is cross-object entry conditions — "a Feature can't enter in_progress until an accepted Decision motivates it" — a guard expressed as a graph query. That is what makes CG's version beat a standalone FSM library.

Open questions & decision log

Decided (this session)

Still open — for the next round