Harnesses > Memory and context
Agent OS
Draft. This entry has not been checked against its sources yet.
Five slash commands that write your codebase's conventions into short standards files, load the relevant ones into a conversation or plan on request, and save each plan-mode spec to the repository.
| Maintainer | Brian Casel (Builder Methods) |
|---|---|
| Category | Memory and context |
| Hosts | Claude Code |
| Components | 5 commands |
| License | MIT |
| Version | 3.0 |
| Source code | https://github.com/buildermethods/agent-os |
| Website | https://buildermethods.com/agent-os |
| Docs | none |
| DeepWiki | https://deepwiki.com/buildermethods/agent-os |
| Last researched | 2026-09-28, at commit 475b0ca |
Features
Definitions are on the compare page.
| Feature | Supported | Notes |
|---|---|---|
| Stages of work it covers | ||
| Brainstorming | partial | /shape-spec asks what you are building and '1-2 clarifying questions if the scope is unclear', then about visuals, reference code, and standards. No step to compare approaches. |
| Written plans | yes | /shape-spec runs inside the host's plan mode, and task 1 of every plan saves it to agent-os/specs/ before any code. |
| Test first | no | No test guidance. The test-first task loop from version 1 was retired with the implementation phases in 3.0. |
| Debugging process | no | |
| Code review | no | No review step. Version 2 had verifier subagents; 3.0 removed them. |
| Verification | no | |
| Learning capture | partial | /discover-standards writes conventions it finds in the code to agent-os/standards/, which later commands read. It records patterns on request, not lessons from finished work. |
| Branch to PR | no | |
| How it runs | ||
| Single entry point | no | Five separate commands with no dispatcher. |
| Automatic activation | no | Slash commands only. Standards reach the agent only when you run /inject-standards or /shape-spec. |
| Session-start hook | no | |
| Blocking hooks | no | No hooks. |
| Subagents | no | 3.0 stopped installing subagents. /inject-standards can format standards for subagents you write yourself. |
| Parallel agents | no | |
| Git worktrees | no | |
| Adopting it | ||
| Multiple hosts | partial | The README says it 'Works alongside Claude Code, Cursor, Antigravity', but the installer writes only to .claude/commands/ and the commands call Claude Code's AskUserQuestion tool. |
| Per-project setup | yes | project-install.sh copies commands and standards into the repository; commit them to share. |
| Team extensions | partial | Your own standards and profiles, with inheritance in config.yml, are the extension point. No documented way to add or override commands. |
| No extra services | yes | Bash scripts and Markdown. No network calls, keys, or accounts. |
How it works
The workflow
Agent OS 3.0 keeps two jobs, standards and spec shaping, and hands the rest to the host. The changelog says it "refocuses the framework on what it does best—establishing and injecting standards", and that spec writing is "Now best handled using Plan mode", while the host's own todo lists and the model take over task breakdown and implementation. The implementation and orchestration phases of versions 1 and 2 are gone.
The five commands have no fixed order. The installer suggests starting with the first two below.
- Discover standards (
/discover-standards). The agent proposes three to five areas of the codebase, reads "5-10 representative files" in the one you pick, and lists patterns that are unusual, opinionated, "tribal", or repeated. For each pattern you choose, it asks one or two questions about why the pattern exists, shows a draft, and writes the file only after you approve. Standards go toagent-os/standards/<folder>/<name>.mdand are kept short: "Every word costs tokens." - Inject standards (
/inject-standards). With no arguments, it readsagent-os/standards/index.yml, matches the one-line descriptions against the conversation, and suggests two to five standards. With arguments (/inject-standards api/response-format) it loads those directly. It formats the result for one of three situations: implementation work (read the full text into the chat), writing a skill, or writing a plan (add@agent-os/standards/...references or paste the full text). - Plan the product (
/plan-product), optional. One question at a time about the problem, users, what makes it different, launch features, later features, and tech stack. Writesmission.md,roadmap.md, andtech-stack.mdtoagent-os/product/. - Shape a spec (
/shape-spec), which "must be run in plan mode". It asks what you are building, for visuals, for similar code to study, whether the work fits the product docs, and which indexed standards apply. It then builds a plan in which task 1 is always "Save spec documentation", and asks you to approve. The host carries out the rest of the plan. - Index standards (
/index-standards). Rebuildsindex.ymlafter you add or delete standards by hand. It asks you to confirm a description for each new file and removes entries for deleted files without asking.
Components
- 5 commands:
discover-standards,inject-standards,index-standards,plan-product, andshape-spec, 1,147 lines of Markdown in all. None has frontmatter. - No skills, subagent definitions, hooks, or MCP servers. The 3.0 announcement: "While Agent OS no longer installs subagents, you can create your own."
- 3 shell scripts:
project-install.shsets up a project,sync-to-profile.shcopies a project's standards back into a profile for reuse, andcommon-functions.shholds shared code, including profile inheritance. - Profiles: named sets of standards in the base install, selected with
--profile. A profile can inherit from another throughinherits_frominconfig.yml. The default profile ships one example file,global/tech-stack.md. .agents/setupand.agents/resumeset up the maintainer's own Rails application on a development machine. They are not part of Agent OS and are not installed.
How it steers the agent
Everything is wording in the commands. There are no hooks, reviewer gates, or scripts that check the agent's output.
- Commands ask before they write.
AskUserQuestionappears 27 times across the five files, and drafts of standards, index descriptions, and plans are shown for approval first. - A few hard rules:
/shape-spectells the agent to "stop immediately" outside plan mode, and/discover-standardssays "you MUST complete this full loop" for one standard before starting the next, and "Do NOT batch all questions upfront." - The spec is saved before the code: the save is always task 1 of the plan.
- Standards are kept small and indexed, so
/inject-standardscan pick a few by description without reading every file. - The commands treat standards as advice: "Standards guide, not dictate — They inform the plan but aren't always mandatory."
Files it writes
- Standards:
agent-os/standards/<folder>/<name>.md, plusagent-os/standards/index.yml. Read by/inject-standardsand/shape-spec. - Product docs:
agent-os/product/mission.md,roadmap.md, andtech-stack.md. Read by/shape-spec. - Specs:
agent-os/specs/YYYY-MM-DD-HHMM-<slug>/withplan.md,shape.md(scope and decisions),standards.md(the full text of the standards that apply),references.md, andvisuals/. No command reads earlier specs back; the command says "Months later, someone can find this spec and understand what was built and why." - Commands:
.claude/commands/agent-os/*.md, copied by the installer. - In the base install only:
profiles/<name>/standards/, and a.backups/<timestamp>/folder whensync-to-profile.shoverwrites files.
Nothing is added to CLAUDE.md or AGENTS.md, so a new session knows nothing about the standards until a command loads them.
Install
Installation has two stages, and neither uses a plugin marketplace.
- Base install: a copy of the repository in your home folder, which holds your profiles. The documentation gives a clone command along the lines of
git clone https://github.com/buildermethods/agent-os.git ~/agent-os; the docs site was not reachable from the research environment, so check the exact command at buildermethods.com/agent-os. - Project install: from the project root, run
~/agent-os/scripts/project-install.sh. Use--profile <name>to pick a profile, or--commands-onlyto update the commands without touching standards. Ifagent-os/standards/already exists, it asks before overwriting. Commitagent-os/and.claude/commands/agent-os/so the team gets the same setup.
The installer targets Claude Code only. The README says Agent OS "Works alongside Claude Code, Cursor, Antigravity, and other AI tools", but version 3 ships no install path or files for other hosts, and the commands name Claude Code's AskUserQuestion tool. Versions 1.4 to 2.x had a --cursor install flag.
At the researched commit, the default profile's example file sits at profiles/default/global/, while the installer copies only from profiles/<name>/standards/. A test install into an empty project copied the five commands and wrote an empty index.yml, but no standards. This does not matter if you build your standards with /discover-standards.
Needs bash and git. Version 3.0 had an install bug that made the script exit silently (discussion #311); the fix is in the unreleased changes included in the researched commit.
When to choose it
- Your codebase has conventions that the agent keeps getting wrong, and you want them written down as short files the team can review and commit.
- You already use Claude Code's plan mode and want it to ask about scope, reference code, and your standards, then save the result to the repository.
- You want a small, readable addition: five commands and three shell scripts, with no hooks or background behavior.
- You maintain several similar projects and want to reuse one set of standards through profiles.
When not to
- You want a full process from idea to merged code. Agent OS 3.0 has no testing, debugging, review, verification, or git steps; the host does the implementation on its own.
- You want standards applied without anyone remembering to ask. Nothing loads them automatically.
- Your team does not use Claude Code. Other hosts get no installer.
- You want lessons from finished work captured. Standards come from reading existing code on request, and there is no step after a task.
Version 3 replaced the commands of version 2 entirely; content from earlier versions (standards, specs, product docs) carries over, but tutorials for 1.x and 2.x describe commands that no longer exist.
Sources
- buildermethods/agent-os at 475b0ca:
README.md,CHANGELOG.md,config.yml,commands/agent-os/*.md,scripts/*.sh,profiles/default/,.github/CONTRIBUTING.md. The install was also run in a scratch project to see what it writes. - Agent OS v3 announcement, discussion #310 and install bug, discussion #311
- Agent OS documentation (linked from the README, not read: blocked from the research environment; the base-install command comes from a search-result summary of its installation page)
- DeepWiki was not used: it was unreachable from the research environment.