Arca’s Initial Motivation: Keeping Agent Work Inside the Repository

I have been working on a personal project called Arca, an experimental system designed to preserve the work, decisions, discoveries, and handoffs produced by agents like Claude and Codex inside a repository.

In this article, rather than diving into the more advanced ideas I’m currently exploring, I want to reflect on the motivations I had when I first started building Arca. This retrospective is based on comparing logs from that time with my current memory. While some parts are inevitably reinterpreted in hindsight, I have tried to stay close to my original understanding.

Looking back at the Git history, I initialized Arca on April 9. At that point, I saw Arca as a markdown-based harness for autonomous software-development agents. When asking Claude or Codex to work inside a repository, I wanted to make explicit, within the repo itself, which rules the agent should read, what role it should operate under, what artifacts it should leave behind, and how review should be performed.

The initial design intent was documented in arca/docs/design/INITIAL.md.

My Understanding of Agent Design Before Arca

Shortly before starting Arca, I had been thinking about agent design in terms of “state, projection, and representation.” I didn’t view large language models (LLMs) as entities with persistent internal state. Instead, I thought of them more like stateless functions that respond to whatever input they receive at each call.

From this perspective, the essence of agent design boiled down to deciding what state should be preserved, which parts of that state should be selected, and how it should be represented before being passed to the LLM.

I also considered agents not merely as prompts or tools, but as systems operating within a harness. In notes from April 11, I broke down a harness into elements such as instruction, knowledge, execution, observability, validation, constraints, and improvement loops. This was intended as a functional decomposition for running autonomous software-development agents in a stable way.

Looking back now, I realize I was envisioning a fairly broad LLM systems architecture. Within that broader view, Arca began as a repository-local experiment focused specifically on preserving, validating, and handing off agent work.

Initial Motivation: Preventing Agent Work From Disappearing

The original motivation was quite simple. When Claude or Codex performed work, their outputs were often very useful in the moment. However, once the session ended, the agent forgot everything. And I, as a human, would often forget a few days later why the work had been done, how far things had progressed, and what discoveries had been made.

So the first thing I needed was a way to preserve agent work beyond the session itself. I wanted to record agent activity, keep work artifacts inside the repository, and allow future agents — or future versions of myself — to resume the work.

At this stage, I wasn’t trying to build a sophisticated system. I simply needed to preserve what the agent did, which files were added or modified, how validation was performed, and what work remained unfinished — all inside the repository.

The first document that captured this design intent was arca/docs/design/INITIAL.md.

Building a Scaffold From INITIAL.md

The first task in Arca wasn’t to implement application features. Instead, it was about aligning the repository scaffold with the design notes I had written in arca/docs/design/INITIAL.md.

An action log from that time recorded work like this:

Task:

Align the repository scaffold with the updated arca/docs/design/INITIAL.md.

Actions Taken:

• replaced env.yaml with env.md

• added templates

• added logs

• added procedures

• added task lifecycle procedure

• added GitHub pull request template

Outcome:

The repository scaffold now matches the current initial design document

and includes the new artifact loop from logs to procedures.

In other words, I was consciously treating the process as transforming design notes into repository structure. The initial design document was gradually realized as a scaffold composed of templates, logs, procedures, and a pull request template.

The original vision of Arca was to make autonomous development safer by placing design intent inside the repository, transforming that intent into machine-readable work contracts, and preserving the resulting work as action logs.

At that stage, however, the logs were still primitive. They preserved what had been done, what had been validated, and what follow-up work remained. But the logs alone did not fully explain why a particular structure was necessary or which design decisions motivated it.

That reasoning existed inside INITIAL.md, the work records existed in the action logs, and the implementation history was visible in repository diffs. In hindsight, the overall flow could be reconstructed by reading these sources together. But at the time, the logs were closer to simple execution records.

How Arca Was Positioned Inside INITIAL.md

Inside INITIAL.md, Arca was defined as a scaffold-based agent environment for software delivery with a strict pull-request-first workflow. The center of gravity was software delivery, focusing on protecting the main branch, developing changes on topic branches, and reviewing work through pull requests.

In other words, Arca was designed as a safe operational scaffold for delegating development work to agents.

The design goals emphasized starting with a minimal agent system, making the execution model explicit inside the repository, separating shared rules from role-specific behavior, enforcing a pull-request-first workflow, and keeping the repository portable across environments.

At this stage, I primarily saw Arca as a harness or scaffold for controlling agent execution.

The Emergence of the Scaffold

The central concept inside INITIAL.md was the scaffold itself — a stable contract that agents should read before performing work.

This contract was composed of several markdown files: AGENTS.md served as the repo-wide operating contract; arca/env.md specified execution and tool expectations; arca/rules.md contained shared behavior and workflow rules; and arca/agents/*.md defined narrowly scoped agent roles.

The purpose was to avoid hidden prompts or external services. The idea was that agent behavior should be understandable simply by reading the repository itself.

At the time, my main interest was exploring how far agent behavior could be stabilized through markdown-based contracts stored inside the repo.

The Introduction of Procedures

The “near-term next steps” section of INITIAL.md included introducing an action log as a markdown-based artifact under arca/logs/, capturing agent actions per task. It also proposed defining initial procedure storage in arca/procedures/ and establishing a loop from action logs to procedures.

Looking back, this already contained an idea that would later become central to Arca: preserving agent work as raw logs and gradually growing reusable procedures from them.

At the time, I called these reusable workflows “procedures,” but today I think “skills” is a better term. A procedure is a record of a repeatable workflow, whereas a skill is an operational capability that an agent can reuse.

Initially, I simply wanted to preserve useful procedures. But over time, I began to see them as a form of operational knowledge inherited by future agents. The flow I envisioned was from raw action logs to reusable procedures, then to skills, and finally to future behavior.

At this stage, Arca had already begun forming a feedback loop where work records influenced future agent behavior.

The Evolution of Role Separation

The initial set of agent roles was intentionally small: orchestrator, implementer, and reviewer.

The orchestrator organized work and determined what should happen next. The implementer modified the repository directly. The reviewer checked changes, validation, workflow violations, and regression risks.

Since the original target was autonomous software-development workflows, these three roles initially seemed sufficient.

However, as I continued using Arca, role separation became increasingly granular. Part of this came from observing that more non-implementation work was appearing. It was also influenced by Codex recommendations and other agent harnesses I studied at the time, many of which separated roles into planner, researcher, executor, reviewer, and similar categories.

As a result, Arca temporarily moved toward much finer role separation. Roles expanded to include:

• researcher, who gathered external information and sources
• spec-planner, who organized plans and specifications before implementation
• implementer, performing approved changes
• reviewer, inspecting results and identifying workflow violations or missing validation
• procedure-curator or skill-curator, extracting reusable skills from logs and repeated work
• and scaffold-curator, maintaining AGENTS.md, rules, environment, roles, templates, and scaffold structure.

This separation had practical value. Research, specification work, implementation, review, scaffold maintenance, and skill extraction all tended to blur together when assigned to the same agent.

However, more recently I have been moving back toward reintegration. Over-separating roles increases the operational overhead of understanding roles and managing handoffs, especially in a personal project.

Currently, the structure has become closer to three roles: builder, reviewer, and curator. The builder handles research, design, and implementation work. The reviewer inspects outputs and identifies problems or missing elements. The curator organizes logs, skills, and scaffolds into reusable forms.

So role separation did not evolve in only one direction. I first explored increasingly fine-grained roles, observed the differences in responsibility, and later reintegrated them into a smaller operational structure.

The Design of Handoffs

The design of handoffs was strongly influenced by Codex suggestions.

Initially, it seemed sufficient for humans to assign tasks to agents and receive results back. But as tasks became longer-running, several problems emerged: the next agent did not know where to start reading, it became unclear what was completed or incomplete, validation status became difficult to track, and pending decisions became hard to identify.

This led to the introduction of handoffs — not merely memos, but state transfer mechanisms that allowed the next agent — or a future version of myself — to safely resume work.

A handoff preserved the current state, completed work, remaining work, validation status, known risks, and recommended next action.

Through handoffs, agent outputs stopped being temporary chat responses and instead became resumable work states preserved inside the repository.

At the Time, I Thought of Arca as a Markdown-Based Harness

At that stage, I thought of Arca primarily as a markdown-based harness. Rules, roles, environments, templates, logs, and procedures were all written in Markdown and read by agents. Instead of implementing my own runtime, I relied on existing agent harnesses such as Codex or Claude. Arca itself was the repository-side contract.

I still think that understanding was half correct.

Arca truly was markdown-based. In the sense that agents read natural-language contracts stored inside the repository, it functioned as a harness or scaffold.

However, even then, I had started feeling that the real value was not the execution itself, but the fact that agent work remained readable afterward. What was done, why it was done, what was validated, what remained unfinished, and what should be handed to the next worker — these were the key pieces of knowledge preserved.

That realization later influenced how Arca continued to evolve.

Conclusion

The original motivation behind Arca was to build a markdown-based harness for safely operating autonomous software-development agents. But from the very beginning, an equally important concern was preserving agent work in a way that allowed both humans and agents to continue the work later.

Arca’s evolution can be seen as a progression from a markdown-based harness to a repository scaffold, then to an action log, evolving into procedures or skills, and finally to handoffs that enable resumable work.

At that stage, I had not yet reached the broader understanding I have today. By writing INITIAL.md, building scaffolds, operating agents, managing logs and procedures, and separating roles and handoffs, the meaning of Arca gradually became clearer over time.