Summary: Traditional documents — reports, slide decks, spreadsheets — are artifacts shaped by human biology: linear, single-file, snapshot-oriented. AI agents need something different: stable references, change tracking, decomposability, etc. Source repositories provide all of these natively. This post argues that the repository is emerging as a primary interaction medium between humans and agents — a workspace where humans declare intent, agents elaborate it into artifacts, and both iterate toward quality. Documents don’t disappear; they become output artifacts, like compiled binaries. The repository is the source code; a document is one rendering. This pattern generalizes beyond software to any productivity process that involves intent, elaboration, and validation.

Motivation

For five hundred years, the document has been the fundamental unit of knowledge work. Reports, memoranda, slide decks, spreadsheets, manuscripts — these are the containers in which humans create, share, and refine ideas. But documents are artifacts designed for human biology. A report is 10–50 pages because that’s what a person can read in a sitting. Every document format is shaped by the constraints of human attention, memory, and screen real estate. These constraints produced deep design assumptions such as single-file packaging, linear structure, and formatting that fuses content and presentation.

But AI agents do not have the same constraints. An agent can process thousands of files in seconds. It doesn’t need linear structure — it navigates by reference, search, or schema. What agents do need is exactly what documents lack: stable references, change tracking, decomposability, etc.  Fortunately, platforms like GitHub, which are Git repository hosting frameworks, provide all of these requirements and more.  Throughout this document, when we mention “repository” we are broadly referring to the version control system, hosting platform, and associated tools and workflows that such platforms provide.  While these systems were originally created to support collaboration between humans, our experiences with agent-driven development lead us to a stronger claim:

The repository is emerging as a primary interaction medium between humans and agents, and between agents themselves. This pattern will generalize beyond software development to any complex productivity process. The repository (including files, tools, workflows, etc.) is the source of truth.  Document are artifacts rendered from that source.

Insights from Building a Software Project Using Agents

This post is informed by our work on AVA (Agent Verification Architecture), a framework for verifying AI agent behavior.  AVA is a tool that generates deterministic checkers for input trajectories from a given agent execution (tool calls, model reasoning, etc.). The checks are specified in natural language and AVA uses a software engineering agent (swe-agent) to convert the natural language into Python code checks (which we call invariant packs).  For example, the natural language might say “The agent should not make redundant file reads” and the Python code in the invariant pack checks if the agent tool calls in the trajectory actually read the same file twice.  AVA is a direct successor of the open-source AgentPex tool. Once AVA has generated an invariant pack, running it is deterministic.  The creation of the AVA invariant packs is agent-driven and involves a collaboration between the developers (us) and the swe-agent.

The AVA repository contains code, documentation, specification, tests, presentation slides, etc. and most were created through human/agent conversations. The repository isn’t just read by agents; it is written to by agents, interpreted by agents, and maintained by agents. It is the shared workspace, communication bus, and institutional memory for a human-agent team.

While we use our swe-agent for other activities in the AVA repository, a central important activity is the creation of a new invariant pack. Invariant packs are agent-specific and when we want to create an invariant pack for a new input agent, we follow this process:

Human writes a policy document describing intended agent behavior (natural language intent)
↓
Our swe-agent compiles policy → invariant pack (executable checks in Python)
↓
swe-agent validates invariant pack with regression testing, agent-driven data analytics, etc.
↓
Human reviews results, consults with swe-agent on the results, and refines policy
↓
swe-agent recompiles (and the loop continues)

Every step in this loop is mediated by files in the repository.  The repository is the runtime environment on which this collaboration runs.

The Intent-Elaboration-Validation Loop

Our daily conversations with our swe-agent gives us experience and perspective about how to have an effective partnership. This is the recurring pattern we observe:

Intent Declaration  →  Elaboration  →  Validation  →  Iteration
(human)               (agent)         (agent/human)    (both)

In our verification framework, this manifests as:

Phase	Artifact	Author	Lives In
Intent	Policy documents	Human	Repository
Elaboration	Invariant packs (Python code)	Agent	Repository
Elaboration	NL Explanation of Invariants	Agent	Repository
Validation	Benchmark results, regression tests	Agent (script)	Repository
Validation	Human/swe-agent discussion	Human + Agent	Repository

The intent-elaboration-validation loop mediated by repositories is an instance of what Syme calls an “Intent/Actualization Toolchain” — a framework where user intent flows through elaboration stages to produce actualized artifacts, with the “burden of actualization” distributed across the chain.   But here’s the critical insight: this loop is not specific to software. Anywhere a human has intent that requires elaboration by a capable agent, followed by validation against quality criteria, this pattern applies. Here’s how our experiences might generalize beyond writing software.

Business Document Production – A corporate team producing a quarterly business review could use:

• Intent: A template with sections, data requirements, and style guidelines
• Elaboration: An agent populates sections from data sources, creates charts, writes narrative
• Validation: A compliance agent checks for policy adherence, an editor agent checks tone and style, a human reviews the results and decides when the process is complete

The repository provides version control, change tracking, and a structured space for intent declaration.

Policy and Compliance Workflows – A compliance team could maintain:

• Intent: Regulatory requirements as structured documents
• Elaboration: An agent maps requirements to organizational controls, identifies gaps
• Validation: An audit agent checks that every requirement is addressed

This is exactly the pattern we implemented for validation policies. Our policy document expresses human intent about what constitutes safe agent behavior. The swe-agent elaborates these into executable checks. Replace “safe agent behavior” with “SOX compliance” or “GDPR data handling” and the structure is identical.

While our experience involves creating a software repository to build a software project and embedding support for agent collaboration into that framework, we don’t expect users unfamiliar with repositories or software development to start using them for their business workflows.   We must think deeply about how to support such users.  What programming language concepts and software engineering techniques can they benefit from when they collaborate with agents in their experiences?  One crazy example: Is it possible that documents should come with test cases so that when agents modify them, they can be regression tested?  It’s an enormous opportunity for our community as many of our research discoveries now have even greater significance.  However these mechanisms are exposed to users, we are confident that many of the existing mechanisms available in repositories will be present in some form.

Repositories: A Governance Substrate, Not Just a Storage Layer

Repositories, particularly those hosted on platforms like GitHub, come with decades of battle-tested governance infrastructure that maps directly onto the guardrails agents need. The problems that version control and code review were designed to solve — untrusted contributors, destructive changes, coordination failures — are precisely the problems that arise when AI agents become contributors.

Leveraging Revision Control: Every change an agent makes is a commit. Every commit can be reverted. If an agent produces a bad invariant pack, introduces a regression, or misinterprets a policy document, the fix is git revert — instantaneous and complete. This property is even more valuable for agents than for humans, because agents make changes faster and with less deliberation. An agent can touch dozens of files in a single session. Without revision control, recovering from a bad session would require painstaking manual reconstruction.

Leveraging Branches: Branches give agents sandboxed workspaces where they can elaborate freely without affecting the mainline. This is particularly powerful for multi-agent workflows. One swe-agent can be refining a policy document on one branch while another agent is regenerating invariant packs on a different branch. The branches provide natural isolation — agents don’t interfere with each other’s work — and the merge operation provides a natural synchronization point where conflicts are surfaced and resolved.

Pull Requests are Human in the Loop (HITL): The pull request is perhaps the most important governance mechanism for agent-driven work. An agent can produce any artifact it wants, but nothing reaches the mainline without human review. The PR provides:

• Diff visibility: The human sees exactly what changed, not just the final state.
• Discussion threads: Reviewers can ask the swe-agent questions about specific changes.
• CI integration: Automated tests, linters, and benchmarks run on every PR via continuous integration (CI) — a pipeline that automatically builds and checks every proposed change.

The PR workflow converts agent contributions from “trust me” to “verify then trust” — the same standard applied to human contributors, but with infrastructure already in place.

Process Automation through Repo Actions: Repository-native automation (GitHub Actions, GitHub Agentic Workflows) provides scheduled and event-driven agent orchestration. Agents run on a periodic basis and generate new issues that other agents and/or humans can review. In our framework:

• A nightly workflow runs regression tests against the current invariant pack and files an issue if the tests fail
• A weekly workflow generates a platform feedback report consolidating findings for agent framework teams
• A dependency-sync workflow audits the file-dependency manifest and flags stale artifacts

Leveraging Repository Access Control: Platform-level access control mechanisms provide principled boundaries for what agents can do:

• Repository permissions determine which agents can read or write which repositories. A documentation agent doesn’t need write access to the production code repository.
• Branch protection rules prevent agents from pushing directly to main, requiring the PR review workflow.
• Environment secrets control which agents can access which credentials. The compile-checkers agent needs LLM API keys; the validation agent does not.
• Safe-outputs configuration in GitHub Agentic Workflows constrains what a workflow can write — restricting mentions, labels, and content length in issues and PRs to prevent prompt injection attacks from propagating through agent-created artifacts.

These same access control primitives that organizations have used for years to manage human contributors, CI bots, and third-party integrations. The Open Source Security Foundation (OpenSSF) has published guidance specifically advocating for such structured, security-focused instructions in repository files to minimize insecure AI-generated code.

Leveraging History for Accountability: Git history provides something no other collaboration medium offers: a complete, immutable, attributable record of every change. When a swe-agent commits with a co-authored-by trailer, the commit record permanently captures:

• What changed (the diff)
• Which agent produced it (the co-author trailer)
• Why it was made (the commit message)

This audit trail is essential for trust, debugging, and compliance. In our repository, when an invariant pack produces unexpected results, the history shows exactly why the change occurred.

Call to Action

We argue that the repository is a powerful mechanism in supporting human/agent collaboration and that it supports that interaction in ways that current documents do not. We base our observations on using agents for software development, but we believe the approach is more general. Any productivity process that involves intent, elaboration, and validation can be structured as repository-mediated collaboration.

The implications for the software research community are dramatic.  While existing repositories support many important capabilities, how can they be best extended with agents as first-class collaborators?  Are the current interfaces to repositories appropriate for agent-first collaboration or does the user experience need to evolve?  What additional privacy, security, and reliability mechanisms should be in place when agents have greater responsibilities?

The practical implications are of our observations are significant. Organizations that want to leverage AI agents for complex tasks should think about how they leverage repositories for their uses.  As Karpathy’s “Software 3.0” vision suggests, the agents will get smarter on their own. The framework for hosting the human/agent interaction, such as the repository, is the part you control.

In the process of using swe-agents to build our AVA tool, we achieved a limited understanding of the repository as a universal collaboration medium.  Ours is one of many new experiences that individuals working with agents are having.  By sharing these perspectives, we hope that best practices will emerge. We feel that the software engineering and programming languages communities have a great deal to offer in shaping the transition to human/agent collaboration.

The patterns described in this post were developed while building AVA, an agent verification framework where ~90% of code, documentation, specs, and tests were authored by AI software engineering agents (GitHub Copilot CLI) under human direction.

Peli de Halleux is a Principal Research Software Developer Engineer in Redmond, Washington working in the Research in Software Engineering (RiSE) group. His research interests include empowering individuals to build LLM-powered applications more efficiently.

Don Syme is a Principal Researcher with GitHub Next and Visiting Professor at Kings College London working on AI-assisted software development. He’s the creator of the F# language, is the co-inventor of language integrated async/await programming and played a key role in the design of generics in C# and the .NET platform. His current work focuses on Continuous AI and repository automation.

Ben Zorn is a Partner Researcher at Microsoft Research in Redmond, Washington working in (and previously having co-managed) the Research in Software Engineering (RiSE) group. His research interests include programming language design and implementation, end-user programing, and empowering individuals with responsible uses of artificial intelligence.

Disclaimer: These posts are written by individual contributors to share their thoughts on the SIGPLAN blog for the benefit of the community. Any views or opinions represented in this blog are personal, belong solely to the blog author and do not represent those of ACM SIGPLAN or its parent organization, ACM.