Project Story
About the Project
Our project addresses an increasingly common but often overlooked problem:
How can an AI agent project remain continuous, controllable, and verifiable when it lasts for days, is interrupted multiple times, and is handed over between different humans and agents?
Most agent tools today are good at completing local tasks: reading code, modifying files, running commands, or finishing a clearly defined objective within a single conversation. Real software engineering, machine learning research, and scientific computing projects, however, rarely end in one session.
Projects go through changing requirements, failed experiments, rejected plans, team handoffs, runtime changes, and sometimes multiple agents working on different tasks at the same time.
In these situations, chat history is not a reliable project state system. It can become too long, difficult to audit, impossible to version properly, and hard for a fresh agent to interpret. A new agent may struggle to determine:
- What is the current project goal?
- Which plans are approved, and which are no longer valid?
- What did the previous agent complete?
- Which experiments and results can still be trusted?
- Who owns the next action?
- Which artifacts and evidence support the final conclusions?
We therefore started building a repo-native agent harness: a system in which the Git repository stores not only code, but also serves as a persistent project control plane for humans and agents working together.
Our vision can be summarized as:
Make a Wish. Ship the Proof.
A user defines an objective. Humans and agents then plan, implement, experiment, recover, and review their work through the repository. The final delivery is not just an answer or an artifact, but a chain of evidence that can be independently verified.
Inspiration
The project was inspired by several problems we repeatedly encountered while using AI agents for complex work.
The first problem was memory loss after a session interruption.
An agent may have already read a large amount of code, tested multiple approaches, and learned many implicit constraints. Once the session ends, however, a new agent often has to inspect the project again or depend on a temporary summary.
This repeats token usage and human explanation. More importantly, the new agent may reconstruct the project state incorrectly.
The second problem was continuing to execute an outdated intention after the plan has changed.
For example, a human may have rejected an approach or changed the project's goals and constraints, while an old TODO item, checkpoint, or conversation summary still remains. Without a reliable way to identify invalidated state, a fresh agent may continue following a plan that appears reasonable but is no longer valid.
The third problem was having results without trustworthy evidence.
A metric, model checkpoint, or experiment report may be outdated or may have been produced by a different version of the code. A project may claim that performance improved, but still be unable to answer:
- Which commit produced this result?
- Which dataset and configuration were used?
- Was the referenced artifact replaced?
- Can an external evaluator independently reproduce or verify the result?
These problems led us to an important realization: long-running agent projects need more than stronger models or more sophisticated runtime harnesses. They also need a project control plane that persists across sessions, humans, agents, and execution environments.
What We Built
We designed the entire Git repository as a versioned, auditable, and recoverable workspace for agent-driven projects.
The project focuses on several categories of state.
1. Goals and Plans
Project goals and plans should not exist only inside chat history. They should become explicit project objects with clear versions and lifecycle states.
When a human changes a goal, rejects a plan, or approves a revised approach, the previous state should be explicitly invalidated rather than silently remaining in the project context.
2. Decisions and Human Gates
Important decisions, approvals, rejections, and invalidations are recorded so that an agent can distinguish between:
- The currently valid plan;
- A proposal that has not yet been approved;
- An approach that has already been rejected;
- A historical decision that became invalid after a goal change.
This preserves final human control while reducing repeated explanations and incorrect restatements.
3. Checkpoints, Handoffs, and Recovery
Before an interruption, the project can record current ownership, completed work, unresolved questions, and the next action.
A fresh agent does not need access to the previous chat. It can recover the project by reading the repository and then revalidate whether the checkpoint is still fresh, complete, and consistent with the current goal.
4. Artifacts, Evidence, and Claims
We aim to create a traceable relationship between project outputs:
[ \text{Artifact} \rightarrow \text{Evidence} \rightarrow \text{Claim} \rightarrow \text{Deliverable} ]
Every important claim in the final deliverable should be traceable to specific evidence. That evidence should, in turn, point to a concrete run, log, model, dataset, or other artifact.
5. Safety and Drift-Prevention Mechanisms
The project can use hooks, permissions, validators, and continuous integration checks to detect problems such as:
- An agent adopting an invalidated plan;
- A checkpoint being created from an outdated version;
- An evidence reference being replaced;
- A claim in the final deliverable lacking supporting evidence;
- Multiple agents creating conflicting ownership records.
Our goal is not to maximize the number of files in the repository. The goal is to determine which states should be externalized, versioned, and audited, which states belong in a durable operational layer, and which states should remain ephemeral inside the runtime.
How We Built It
Rather than immediately adding every possible agent-infrastructure feature to the template, we first defined the project lifecycle and the boundaries between different types of state.
The complete lifecycle includes:
Create or migrate a project → understand the repository → converge on goals and plans → divide the work → select agents, models, and budgets → execute in isolated environments → monitor and recover → organize artifacts and evidence → deliver a verifiable result.
During the design process, we divided project state into three layers.
1. Versioned Project Control Plane
This layer stores goals, plans, decisions, approvals, handoffs, and evidence indexes that need to be reviewed, traced, and potentially rolled back.
2. Durable Operational State
This layer stores frequently changing information such as execution queues, leases, temporary caches, and environment state. It may persist across sessions without necessarily being committed to version control.
3. Ephemeral Runtime State
This layer contains context that is only valid during one agent invocation or one execution process.
This separation is important. Writing every piece of information into Git would create excessive versioning, noise, and maintenance overhead. Keeping critical state only inside the runtime or chat history, however, would make reliable recovery impossible.
The central design question is therefore not simply how to preserve more state. It is:
Which state must persist, which state must be versioned, and which state should be allowed to disappear?
What We Learned
Our biggest lesson was that agent capability and project reliability are not the same problem.
A stronger model may improve performance on local tasks, but it does not automatically solve invalid state, conflicting plans, incorrect handoffs, or compromised evidence. Long-running projects need to externalize critical state from model memory and give that state a clear lifecycle.
We also learned that more complex mechanisms are not always better.
For simple, single-session, low-state tasks, a complete project control plane may only increase token usage, execution time, and cognitive burden. Its value is more likely to emerge under conditions such as:
- Frequent project interruptions;
- Multiple humans or agents contributing to the same project;
- Goals and plans being revised repeatedly;
- Results requiring verification by an external evaluator;
- Work needing to be resumed after a long delay;
- Incorrect conclusions or artifacts carrying a high cost.
We therefore treat the value of the system as a net-benefit problem:
[
\text{Net Benefit}
\text{Reliability Gain} + \text{Recovery Savings} +
\text{Evidence Value}
\text{Token Cost}
\text{Human Burden}
\text{Maintenance Cost} ]
A mechanism should become part of the core harness only when its benefits are supported by evidence from real tasks and controlled experiments.
Challenges We Faced
Defining the State Boundary
One of the hardest problems was deciding which information should enter version control.
Saving too little makes recovery unreliable. Saving too much fills the repository with duplicated, temporary, and outdated state. We need to balance recoverability against system complexity.
Preventing Silent Adoption of Stale State
Saving plans and checkpoints is not enough. The system also needs to represent freshness, provenance, invalidation, and dependency relationships.
Otherwise, a structured but outdated file may be more dangerous than having no file at all, because it can give an agent greater confidence in an incorrect state.
Separating Mechanism Benefits from Additional Resources
If a treatment condition uses more tokens, more agent calls, or more human intervention, it may achieve better results without proving that the project control plane itself is effective.
Experiments therefore need to hold the model, budget, permissions, network policy, human policy, and evaluator as constant as possible.
Designing Strong Baselines
A complex system should be compared against genuinely competitive simple alternatives.
The baseline should not be limited to a repository with no persistent project state. It should also include an ordinary repository with a structured TODO.md file or handoff summary.
If a simple handoff document explains most of the benefit, we should narrow our claims rather than overstate the value of the complete system.
Keeping the Evaluator Independent
The harness must not modify task answers, hidden tests, or evaluation criteria. Interruptions, plan revisions, evidence replacements, and collaboration conflicts should be injected by a controller outside the execution sandbox.
This separation prevents the system from appearing successful merely because it changed the evaluation process itself.
What's Next
The next stage of the project is to evaluate the following questions through controlled experiments:
- Can a fresh agent correctly recover a project without access to the previous conversation?
- Do versioned goals, plans, and decisions reduce stale-state violations?
- Does an evidence chain reduce unsupported claims?
- Is a simple handoff document already sufficient?
- Does selective versioning outperform over-versioning?
- Do the benefits appear primarily under disruption?
- Are the reliability gains worth the additional token, time, and human burden?
We do not assume that a complete harness will always outperform an ordinary repository.
The project ultimately asks:
When AI agents evolve from one-time assistants into long-term project participants, how should project state be organized so that their work remains reliable through interruptions, revisions, handoffs, and verification?
Our goal is not only to create another agent template. We want to establish a practical way for humans and agents to collaborate over time, preserve human control, and deliver results that can be trusted.
Log in or sign up for Devpost to join the conversation.