OSS Agent Playbook

Preparing different repositories for open-source release involves the same work each time: understanding what the project actually does, checking what can be published safely, making the path to a first successful run clear, and substantiating public claims. OSS Agent Playbook turns this recurring work into a portable workflow for agents with access to project files.

The agent starts with an existing repository and a specific task. The Playbook defines an order of investigation and helps the agent prioritize findings, carry out authorized improvements, verify the observable result, and hand the maintainer a clear outcome with supporting evidence. Shared rules do not have to be copied into every project, while local commands, risks, and decisions remain alongside the code they concern.

One pass through a repository

The work begins with a read-only audit. The agent examines the project’s purpose and audience, the state of the working tree, documentation, configuration, build process, and existing public-facing surfaces. Findings are prioritized by risk: secrets, privacy, licensing, and false claims come first; then a clear path to a first successful run and reproducibility; only after that come additional polish and promotion.

When addressing the selected problems, the Playbook guides the agent through the README and metadata, safe configuration examples, dependencies, a verifiable build, tests, CI, releases, and operational instructions—only to the extent required by the specific project. Material claims must be supported by a test, a reproducible example, or explicitly identified evidence. Manual steps and unverified capabilities are not presented as automation.

After making changes, the agent reviews the complete diff and runs the formatting, tests, build, packaging, link checks, or smoke scenario relevant to the task. The final handoff separates what was changed and verified, what was intentionally left untouched, which risks remain, and which next step would provide the most value. The maintainer receives a concrete result and evidence for evaluating it, not a generic success report.

Shared rules without losing local context

The technology-neutral core consists of Markdown guides covering audits, the repository’s public interface, the README, security, reproducibility, engineering checks, releases, and the agent’s workflow. Checklists collect readiness criteria for publication and ongoing maintenance.

Templates for AGENTS.md, CLAUDE.md, and PROJECT_AGENT_CONTEXT.md connect the core to a specific project. The project context stores verified commands, risks, publication boundaries, and the selected Playbook revision. Optional technology profiles refine the rules for specific technical boundaries; a draft docker-container-images profile is currently available.

OSS Agent Playbook itself follows this model: instructions, verified facts, accepted lessons from the maintainer, and the history of architectural decisions live in separate documents under Git version control. A built-in Python script with no third-party dependencies checks the documentation’s structure, links, and internal consistency.

Use it once or integrate it for the long term

For a one-off pass, it is enough to give the agent local paths to the Playbook and the target repository and request a scoped audit or improvement. Nothing needs to be installed in the project.

For repeated use, the selected revision is pinned to a full SHA and placed in .agent/oss-playbook. The recommended method for a public repository is a squashed Git subtree without the full upstream history; submodules and verified copies of the files are also supported. Short root-level instructions direct the agent to the relevant documents, while Playbook updates are handled like ordinary dependency changes: each new revision is imported, checked, and accepted separately.

The project is evolving as a pre-1.0 reference implementation. It gives an agent a workflow and verifiable criteria while leaving decisions about publication and acceptance of the result to the maintainer. The materials are released under CC0 1.0: they can be copied, adapted, and integrated into other repositories.