Organizing an AI agent's work on a repository

An AI agent’s work is easier to organize around a result that can be shown and checked. For example: fix empty-input handling, preserve the response format, and confirm the behavior with an existing scenario. This gives the task a completion point and helps determine an appropriate scope.

OSS Agent Playbook applies this approach to preparing existing repositories for open-source publication and subsequent maintenance. It is a public collection of Markdown guidance, templates, and documentation checks. The following is a general workflow for a file-aware agent; the project supplies the actual commands and authorized actions.

Describe the task through observable behavior

Start with what happens now, what should change, and what would demonstrate the result. A bug report benefits from input data and a reproduction; a new capability needs a primary user scenario and compatibility constraints.

A short task brief could look like this:

• Result: empty input produces a clear error.
• Context: the problem reproduces in the existing parser.
• Scope: input handling and its relevant verification scenario.
• Compatibility: successful responses keep their current format.
• Handoff: patch, observed result, and remaining limitations.

This is a task-framing example, not a ready-made command for a particular tool. A real brief should identify the relevant component and behavior. Invented paths, test commands, or support promises do not make a detailed brief useful.

Provide verified repository context

The agent needs the project’s purpose, the main scenario’s path, applicable instructions, working-tree state, and commands that actually exist. Another person’s changes are part of the initial state: first understand how they relate to the task.

Keep reusable guidance separate from local facts. Playbook provides integration templates for AGENTS.md, CLAUDE.md, and PROJECT_AGENT_CONTEXT.md. The last can record verified commands, risks, and the selected Playbook revision. Adapt these files to the repository while preserving its existing instructions.

There is no need to read every directory and every possible technology profile upfront. For the chosen task, find the entry point, affected boundary, and its consumers. Connecting additional tools is a separate job; the Codex MCP configuration guide covers that workflow.

Choose a small, complete stage

First establish the cause and dependencies of the change. A file-format change affects both writing and reading. A handler fix needs a check that observes its new behavior. A simple plan describes these relationships and ends with a verifiable result.

Keep one understandable objective within a patch. Unrelated dependency updates, rewriting a neighboring module, and polishing the README may require separate decisions and make the fix harder to assess.

Before a long stage, save a short checkpoint: the starting revision, identified cause, decisions, changed files, completed checks, and next step. This is a practical way to resume after an interruption. The text alone does not restore a lost process or prove that the system remains in the described state: recheck facts that may have changed.

Verify what actually changed

Verification should match the promise. A parser needs appropriate input cases; an archive needs its contents inspected; startup instructions need a reproducible first successful scenario. A build command and a working published deployment establish different states.

Begin with a check relevant to the change, then expand it when affected relationships or failures justify doing so. If the required environment is unavailable, record the limitation and prepare a clear continuation path. An unexecuted test cannot be reported as passed.

Inspect the final diff and new files separately. This can reveal accidentally changed settings, forgotten examples, and differences between the stated scope and the resulting patch. Public projects also require attention to secrets, licensing, and truthful capability descriptions: presentation cannot compensate for a false promise.

Hand off a concrete candidate

A useful handoff lets the next person assess the result quickly:

• what behavior changed and where it can be observed;
• which revision or patch contains the change;
• what was checked and what result was observed;
• which limitations remain and what still needs to happen.

Publication, releases, and changes to a running service need a defined acceptance process. Playbook describes these boundaries; actual permissions and technical restrictions remain with the project and runtime environment. With an established process, the agent completes the prescribed steps and reports their observed outcome.

Frequently asked questions

Do I need a large AGENTS.md file?

File size does not determine context quality. Short routing to current rules and verified project facts is more useful. Repeated, contradictory instructions complicate decisions; task-specific information belongs somewhere it can be updated along with the task.

Does Playbook automatically check the entire project?

It provides guidance and a deterministic check of its own documentation. From the Playbook root, that check uses python3 scripts/check_docs.py. Application tests, builds, packaging, and checks for the selected technology boundary run separately. Markdown rules do not replace a sandbox or permission system.

When is a checkpoint useful?

Before a long stage, a change of owner, or handing over a completed candidate. It should contain the decisions and facts needed for the next action. Frequently repeating a report without a state change adds no information; a significant finding may require updating an earlier account.

Do green tests mean the task can be closed?

They confirm the checks that were observed. Readiness also requires comparing the result with the original task, usage conditions, and publication boundary. Deciding which risks are acceptable remains engineering work; the note on engineering judgment discusses this further.