Agent OS: a shell-based framework for injecting your standards into AI coding agents

Four capabilities, and three of them are about standards

The README lists four core capabilities, and the naming is worth pausing on. Discover Standards extracts patterns and conventions from your codebase into documented standards. Deploy Standards injects the relevant standards based on what you are building. Index Standards keeps those standards organized and discoverable. Shape Spec creates better plans that lead to better builds.

Three of the four are about the same loop: work out how your codebase already does things, write it down, then feed the relevant parts back to the agent at the moment it needs them. That is the whole thesis, and it is a narrower thesis than the framework's earlier versions had.

The target audience is stated plainly. Agent OS works alongside Claude Code, Cursor, Antigravity and other AI tools, in any language and any framework. The README's framing is that it keeps agents aligned in a lightweight system that fits how you already build.

The repository is small in a way that is worth noticing, because it constrains what you are installing. The tree holds `.agents/`, `commands/`, `profiles/`, `scripts/`, `config.yml`, a `CHANGELOG.md`, a `LICENSE` and a `README.md`. There is no source code to compile and no service to run.

Version 3 deleted most of the framework on purpose

The v3.0.0 release notes, published on 2026-01-20, are the most informative document in this repository, and they are a retraction as much as a release. The stated reasoning is that AI coding tools have evolved significantly since Agent OS's original release in mid-2025, and that Claude Code's plan mode, extended thinking and improved models now handle much of the scaffolding earlier versions provided.

Three capabilities are named as handed over to the tools: spec writing is now best handled using Plan mode, task breakdown is done by tools that automatically create and track todo lists, and implementation orchestration is managed by frontier models delegating tasks on their own, with the note that you can still direct them to use subagents. The sentence about not reinventing functions that are much better handled by the core tools is the clearest statement of the project's position, and it is aimed at frameworks like Agent OS rather than at the tools.

What survives is the standards system, described as refocusing the framework on what it does best. Both a full documentation link and a separate migration guide are published alongside the release, which tells you there was enough to migrate that it needed its own document.

Version 2 shows what the framework used to be

The v2.1.0 release notes from 2025-10-21 describe the shape the project had before the retraction, and reading them explains what teams used to install. There was an option to use Claude Code's Skills feature for reading standards, and an option to enable or disable delegating to Claude Code subagents. The single and multi-agent modes were replaced by more flexible configuration options, and the short-lived roles system was retired as too complex and better handled by standard tooling. The notes also mention removing documentation and verification bloat.

The most concrete part is the phase list, which went from four to six named development phases:

cd commands
cat config.yml

The six were plan-product for planning a product's mission and roadmap, shape-spec for shaping and planning a feature before writing it up, write-spec for writing the spec file, create-tasks for creating the tasks file, implement-tasks for single-agent implementation of that task list, and orchestrate-tasks for finer-grained control and multi-agent work. The note about using them all or picking and choosing is a hint about how loosely they were meant to fit together.

The v2.1.1 notes a week later show the iteration: references to the deprecated agent name spec-researcher were replaced with spec-shaper, the dry-run output was clarified to reassure you are in dry-run mode, the templates for writing a spec were tightened to be shorter and easier to scan, and an instruction limiting a product roadmap to twelve items was removed.

Getting the framework onto your machine

The README does not carry installation steps. Documentation, installation, usage and best practices are all on buildermethods.com, and the repository's own contribution is the command and profile files.

The shape of a checkout is the shape of the thing:

git clone
cd agent-os

After that you are looking at directories rather than a build output. `.agents/` holds the agent definitions, `commands/` holds the slash commands and workflow definitions, `profiles/` holds the saved configurations, `scripts/` holds the shell helpers that make the system run, and `config.yml` is the file that decides which of those are active.

Since the repository's primary language is Shell and there is no package manifest, there is no `npm install` step to wait on. The cost of adopting this framework is measured in files read and conventions agreed, not in dependencies resolved.

One maintenance signal is visible in the tree: the repository contains a `CHANGELOG.md`, and the README links it directly under a heading about following updates and releases, alongside a link to subscribe to notifications for major new releases. It is not archived and the last push was on 2026-08-29.

Who this is for, and the dependency it quietly creates

There is a fair reading in which Agent OS is infrastructure for a habit you should have anyway: writing down how your codebase works so that both people and tools can follow it. Discovery means running the tool against a real repository and reading what it concludes. If the extracted standards match the conventions you actually enforce, the tool has done something useful in one pass. If it describes a pattern the team abandoned last year, the standards are wrong and no amount of injection will fix that.

The dependency worth naming is the one on the host tool. Everything here is configuration, commands and shell that assume an AI coding assistant is present and willing to be directed. The README's list, Claude Code, Cursor and Antigravity, is a compatibility statement, and version 3 makes it more than that: plan mode, extended thinking, subagents and Skills are the mechanisms the framework now defers to. If your tool of choice lacks plan mode and subagents, the parts Agent OS gave up are not coming back somewhere else.

It is also worth being clear about what this is not. It does not generate code, it does not review code, and it does not replace a linter or a formatter. The claims it makes are about plans and conventions, not about correctness.

The project is by Brian Casel, who created Builder Methods, and the README directs readers there for a newsletter and a YouTube channel as well as a paid community. That is the shape of a project with a person attached to it, which matters for how quickly it responds to a change in how the underlying tools work.

How to judge it in one afternoon

There is a practical test that settles this framework faster than reading the documentation. Point the standards discovery at a repository you know well, let it extract conventions, then read the output against the code.

If the result captures the things your team argues about in review, such as where validation lives, how errors are shaped, which library does HTTP, and what a module boundary looks like, then the mechanism works and the remaining question is whether you want it injected automatically. If the result is a list of generic best practices, you have learned that the framework needs a seeded input rather than a cold start, and you should write two or three standards by hand first to see whether injection helps at all.

The second test is about your tool. Since version 3, the framework is a thin layer over plan mode and subagents. If your assistant already handles spec writing and task breakdown well, Agent OS may be solving a problem you no longer have, and the standards half might be better as a file your tool reads directly.

The README's own claim is that it fits how you already build, which is the right standard to hold it to and a poor one to accept at face value. Version 3 removed the parts that did not meet that bar once, and the changelog is linked from the README if you want to see whether the standard has held since January 2026.

Editorial conclusion

Agent OS is worth trying if your recurring frustration with AI coding tools is that they keep proposing patterns your team already rejected six months ago, because that is precisely the problem the standards system addresses. It is not worth installing if you want planning, task breakdown or multi-agent orchestration, since version 3 deliberately removed all three in favour of letting the underlying tools handle them. Start by running the standards discovery against an existing repository and reading what it extracts, since a framework that writes your conventions down for you is either obviously right or obviously wrong within one run. Documentation, installation and the migration guide all live on buildermethods.com rather than in the repository, and the last push was on 2026-08-29 with version 3.0 published on 2026-01-20.

Frequently asked questions

Official sources

1. buildermethods/agent-os on GitHub
2. License: MIT
3. Project website
4. README
5. Releases