my current @activegraphai inspired approach to a modular repo-centric agent operating system https://t.co/dRba7xv6ZE

Building a Repo-Centric Modular Agent Stack

I have been converging on a modular architecture for agentic work in which the durable unit is the project, rather than the model, conversation, IDE session, or individual agent.

A project is represented as a governed repository containing enough operational state for a human or agent to enter with minimal prior context, determine the current state, assume a bounded role, perform work, verify the result, and leave a legible state transition for whoever enters next.

The conventional interaction model is approximately:

human → prompt → agent → output → human

Most of the working context remains inside the session. The human carries continuity between tools, models, and conversations.

My current architecture is closer to:

human ↔ Chief of Staff ↔ project managers ↔ workers / reviewers ↔ shared project state

The central separation is between persistent project state and replaceable execution components. Models, agents, tools, interfaces, and sessions can change. The repository retains the project’s state, rules, evidence, decisions, history, and verification mechanisms.

The architecture is ActiveGraph-inspired in a specific sense: the underlying record is primary, while the current view is a projection over that record. Applied to agent work, this means that useful output does not remain only as conversational text. It becomes a structured event, artifact, decision, claim, experiment, test result, or state transition with enough lineage to be inspected later.

The Repository as the Project Substrate

GitHub functions as more than a code host in this setup. The repository is the shared operating environment through which humans and multiple agents interact with the same project.

Depending on the project, the repository may contain source code, specifications, schemas, issues, research claims, source pointers, experimental runs, decision records, acceptance criteria, queues, tests, generated projections, approval state, tool policies, and machine-readable metadata.

The relevant question is not whether every piece of context has been preserved. It is whether a capable fresh agent can reconstruct the project’s operational state:

‣ the project’s objective and current phase; ‣ the accepted state and its evidentiary basis; ‣ the source hierarchy and canonical records; ‣ prior attempts and material failures; ‣ decisions and unresolved implications; ‣ open questions, blockers, and dependencies; ‣ invariants, permissions, and approval boundaries; ‣ available roles and tools; ‣ the next bounded areas of useful work; ‣ the mechanisms by which a proposed change can be evaluated.

Chat remains useful as temporary working memory. It is not the authoritative project record.

I do not attempt to persist every token generated by every model. Most conversational content is scaffolding. The durable information is concentrated in state transitions such as:

These records function as structured clues. They compress the material trajectory of the work without requiring future agents to replay the full conversation. The optimization target is not exhaustive memory; it is low-cost, reliable continuation.

decision → evidence → resulting state → unresolved implications hypothesis → experiment → observation → result → confidence task → implementation → verification → artifact failure → diagnosis → newly discovered constraint

Canonical State and Derived Projections

The repository distinguishes between the underlying record and the views generated from it.

The canonical layer may contain Git history, append-only events, accepted records, decision objects, source references, immutable run artifacts, experiment outputs, verified claims, or other durable state transitions.

The projection layer contains convenient representations of that state: README summaries, current-status pages, dashboards, queues, indexes, task lists, reports, briefs, and context packages prepared for agents.

A projection may become stale or incomplete. Its value comes from remaining traceable to a more durable substrate from which it can be regenerated, compared, or challenged.

This is the architectural pattern I originally developed through ActiveGraph:

event history → projection logic → current state

Treating the underlying history as primary provides replay, provenance, lineage, forks, trajectory comparison, and reconstruction of why a particular state exists. It also makes it possible to separate a current interpretation from the evidence and events that produced it.

Not every repository literally runs on ActiveGraph. Smaller projects can implement the same state model through Git, structured files, deterministic scripts, tests, and disciplined commit history. In richer projects, the repository can itself become an ActiveGraph containing explicit relationships among:

people → agents → tasks → events → claims → experiments → artifacts → decisions → sources → results → open questions

Once those relationships are explicit, the system can answer more useful operational questions: which conclusions depend on a disputed assumption, which experiments support a claim, which decision changed a trajectory, which open questions block the most downstream work, which results have been independently reproduced, or what would differ under a fork from an earlier state.

A Layered Instruction Architecture

Agent behavior is composed from several distinct instruction layers rather than encoded in one large prompt.

The effective instruction stack is approximately:

global operating rules + role skill + project contract + current task

The global operating layer contains a small set of invariants that remain relatively stable across projects. These include preserving provenance, distinguishing evidence from inference, keeping secrets outside prompts and repositories, representing uncertainty explicitly, requiring appropriate authority for consequential actions, and preferring durable project state over hidden conversational memory.

The role layer contains reusable operating procedures. A reviewer has a review protocol. A researcher has methods for source handling, experiment design, claim formation, and uncertainty. A project manager has a state-reconciliation and delegation loop. A verifier has defined falsification or acceptance procedures. A Chief of Staff has a portfolio-level attention-routing procedure.

The project contract contains the information specific to one repository: mission, ontology, source hierarchy, canonical state boundaries, invariants, schemas, role definitions, tool permissions, mutation boundaries, approval policies, acceptance criteria, escalation rules, and definition of completion.

The task context supplies the narrowest and most transient layer: current objective, relevant files, recent changes, dependencies, constraints, requested output, and any deadline or approval state.

This separation allows the same reviewer or researcher skill to operate across multiple repositories without forcing those repositories into the same schema. Project-specific truth remains local to the project, while general operating methods remain reusable.

When a project becomes durable, an initial bootstrap phase establishes the minimum viable operating environment: the project brief, canonical source boundaries, major invariants, acceptance criteria, permissions, phase structure, and routing instructions.

The root agent instruction file remains relatively compact. It functions as an index into more specific contracts:

work type X → load contract A state class Y → load policy B generated artifact Z → apply validation procedure C

Codex, Claude, Cursor, ChatGPT, and other tool-specific instruction files contain adapter information and routing logic rather than independent copies of the project’s rules. Canonical policy remains in one place, reducing semantic drift between interfaces.

Changes to important rules are also represented as project changes. They are attributable, reviewable, and preserved in history rather than silently introduced through an updated prompt.

Models Enter Through Thin Adapters

I use different models and interfaces for different kinds of work: ChatGPT, Codex, Claude, Replit, local agents, GitHub-native automation, and specialized connectors. I do not treat each interface as a separate institutional memory.

Each model enters the same project through a thin adapter. The adapter establishes:

‣ agent identity and assigned role; ‣ available tools and credentials; ‣ read and mutation permissions; ‣ canonical instruction entry points; ‣ relevant project or task context; ‣ the mechanism for recording results.

Where direct filesystem access is available, the agent reads the repository. Where only remote access exists, it uses GitHub or another structured connector. External systems are accessed through official APIs, CLIs, or connectors where possible, with browser interaction serving as a less structured fallback.

The adapter does not maintain its own version of project truth. Its function is to connect a model to the project’s existing state and contracts.

This makes model substitution substantially less disruptive. A Claude session does not need to retain knowledge that is unavailable to Codex, and a particular Codex conversation does not become the sole holder of an architectural decision. Durable knowledge is externalized into the project environment.

Roles as Executable Contracts

The system uses roles such as builder, researcher, reviewer, verifier, auditor, project manager, and Chief of Staff. These are not primarily personalities. They are executable operating contracts.

A role contract defines:

‣ which state the agent reads; ‣ which questions it is responsible for answering; ‣ which decisions it may make; ‣ which tools it may invoke; ‣ which state it may modify; ‣ which artifacts it must produce; ‣ what evidence it must record; ‣ when it must escalate; ‣ what constitutes completion.

A builder may implement a bounded change but lack authority to alter acceptance criteria. A reviewer may inspect and challenge an artifact without mutating it. A verifier may evaluate a proposed state transition against a deterministic contract. A project manager may create and sequence tasks while delegating implementation. An auditor may inspect provenance, policy compliance, and source-of-truth integrity without participating in ordinary execution.

Interchangeability comes from externalizing both project memory and role behavior. The model supplies reasoning and execution capability; the repository and role contract supply institutional context, authority, and procedure.

Heartbeats as Bounded Control Loops

Persistent state provides continuity but does not create movement. The execution layer uses bounded heartbeats: short control loops in which an agent wakes, reconciles state, performs a limited amount of work, records the result, and exits.

A typical heartbeat follows a structure such as:

identify role and authority → inspect assignments, approvals, and changed state → reconcile current state against project objectives → select or claim one bounded unit of work → execute or delegate → verify and record the resulting state transition → exit

The bounded execution window reduces dependence on long-lived context and limits the accumulation of unrecorded assumptions. The project state carries continuity between heartbeats.

Different roles operate at different levels of resolution. Narrow agents can execute deeper work within a specific implementation or research task. Wider agents use shallower loops because their responsibility is coordination rather than direct execution.

The resulting hierarchy is approximately:

Chief of Staff heartbeat → determine which projects require attention

Project Manager heartbeat → determine the next useful project-level action

Worker / Researcher heartbeat → execute bounded work

Reviewer / Verifier → evaluate the resulting artifact or claim

Repository → record the accepted state transition

Heartbeats can be scheduled, event-triggered, or manually invoked. The common element is repeated state reconciliation within a bounded execution scope.

Project Management and Chief of Staff Orchestration

Each durable repository can contain a project manager role responsible for interpreting local state, sequencing work, identifying blockers, delegating to specialized agents, and reconciling completed outputs.

The project manager has access to deeper project context than the Chief of Staff. Its operating knowledge remains inside the repository through the project contract, status records, decisions, issues, and task graph.

The Chief of Staff operates across projects through a smaller portfolio projection. That projection may contain:

‣ active projects and objectives; ‣ current phase and owner; ‣ latest material state change; ‣ blockers and stale work; ‣ pending approvals; ‣ unresolved decisions; ‣ recommended next action; ‣ project-level health or confidence indicators.

The Chief of Staff does not ingest every project’s internal context into one central prompt. It routes attention. When a project requires deeper analysis, it delegates to that repository’s project manager, which operates against the project’s local state and contracts.

Its control loop is approximately:

observe portfolio → detect attention requirement → dispatch → reconcile outcome → escalate judgment

This avoids turning the top-level coordinator into a second system of record or an increasingly fragile global context window.

Verification as a Separate System Layer

Multi-agent execution becomes unreliable when each agent inherits the previous agent’s conclusions without independent checks.

In this architecture, verification is part of the state-transition mechanism. Depending on the project, verification may be implemented through schemas, type systems, tests, CI, deterministic validators, allowed-path rules, state-transition constraints, checksums, preregistered experimental predicates, independent reproduction, or structured review.

The relevant execution pattern is:

agent proposes change → verifier evaluates contract → accepted state changes

Generation and acceptance are separate operations when the cost of an incorrect state transition justifies that separation.

This distinction becomes especially important when agents can modify their own workflows, instructions, evaluators, or orchestration logic. A self-modification is not accepted merely because the modifying agent reports success. The resulting state is evaluated against invariants that are outside the scope of the proposed modification, or by an independently authorized verifier.

Verification also applies to research and reasoning artifacts. A claim may be linked to:

claim ← evidence ← source or experiment ← method and version ← run or artifact ← assumptions ← producing agent or action ← confidence and epistemic status

The claim is therefore not just a sentence. It is a stateful object with traceable lineage.

Explicit Epistemic State

The repositories distinguish among different classes of knowledge rather than collapsing all agent-generated material into a single category of “known.”

Depending on the project, records may carry states such as:

proposed / observed / reproduced / accepted /disputed / superseded / unresolved / inferred / source-backed / speculative

Confidence, authority, sensitivity, and evidentiary basis can also remain explicit.

This matters because an incoming agent needs to distinguish between a verified invariant, a provisional interpretation, an unresolved conflict, and an unsupported hypothesis. It also prevents a polished synthesis from silently replacing the weaker evidence on which it was based.

At scale, unstructured AI output accumulates into an unreliable text archive. Structured provenance and epistemic state allow the same material to function as inspectable institutional memory.

Human Input as Durable Control State

My role moves away from manually carrying context between agents and toward the parts of the system that remain difficult to formalize: objectives, priorities, taste, constraints, ambiguity resolution, consequential approvals, and changes of direction.

The Chief of Staff and project managers expose the points where that input has the highest leverage. At the portfolio level, the interface can remain compact:

‣ what requires attention ‣ which projects are blocked ‣ which decisions require judgment ‣ which priorities have changed ‣ which work can proceed autonomously

When a human decision has implications beyond the current conversation, it becomes a durable project record. The decision can then affect future tasks, approvals, acceptance criteria, and agent behavior without being restated in each session.

The human remains part of the control architecture, but not the transport layer for project memory.

Session Output as a State Delta

A completed agent session produces more than the immediate requested artifact. It also produces a legible state delta.

Depending on the work, that delta may include implementation, tests, experimental evidence, updated claims, decision records, newly discovered constraints, failed approaches, source pointers, unresolved questions, changed confidence, or bounded next actions.

The compounding loop is:

execute → record clues → update state → verify → continue from the new state

This changes the economics of repeated agent use. Context loading becomes progressively cheaper because prior work is represented in the environment rather than repeatedly reconstructed through human briefing.

The architecture can be summarized as:

project substrate

canonical state

• derived projections
• layered instructions
• role contracts
• model adapters
• bounded heartbeats
• verification
• provenance
• human governance

The ActiveGraph influence is not that every repository requires the ActiveGraph runtime. It is that projects are treated as evolving, replayable systems whose present state is derived from durable records of work.

The models provide variable reasoning and execution capacity. The repository provides continuity. Skills and contracts provide operating behavior. Heartbeats provide movement. Verification and provenance provide trust. Project managers coordinate locally. The Chief of Staff allocates attention across projects. Human judgment changes the objectives and constraints under which the rest of the stack operates.

Yohei@yoheinakajima·Aug 7work-from-anywhereQuoteYohei@yoheinakajima·Aug 7upgraded my stack, and i can now work on almost anything from anywhere hands free:

• talk to chief of staff (via remote codex voice or text)
• chief assigns tasks to managers of various projects
• manager assigns tasks to the builder/doer
• CoS & each project has it’s own repo111718343K