Agent OS 3.0

Agent OS v3 is a major release that refocuses the framework on what it does best—establishing and injecting standards—while deferring to modern AI tools for the parts they now handle better.

Full documentation → | Migration guide →

Why the change?

AI coding tools have evolved significantly since Agent OS's original release in mid-2025. Claude Code's plan mode, extended thinking, and improved models now handle much of the scaffolding that earlier versions of Agent OS provided.

It doesn't make sense to reinvent these core functions, which are much better handled by the core tools than 3rd-party frameworks like Agent OS:

• Spec writing — Now best handled using Plan mode.
• Task breakdown — Claude Code and other tools automatically create and track todo lists.
• Implementation orchestration — Frontier models manage and delegate tasks on their own now (but you can still direct them to use subagents as you like).

Agent OS v3 focuses more squarely on the original problems it set out to solve:

• Establishes standards — A system to align your agents to how you build products and your product's mission.
• Injects standards smartly — Deploys the right standards at the right time, without reinventing your workflow.
• Enhances spec-driven development — Helps you create stronger, more aligned specs.

What's different in v3?

Standards

The concept and structure of standards is unchanged. But v3 introduces new tools for creating and maintaining them:

• /discover-standards — Lets the agent surface, suggest, and create standards from your codebase.
• /inject-standards — Injects standards into any context: conversations, plans, Claude Skills, or anywhere your agent needs them. It automatically detects which standards are relevant via the new index.yml file.
• Sync script — Syncs your project's standards back to your base profiles.

Specs

The structure of specs is unchanged—your agent-os/specs/ folders remain intact.

What's new is how specs are created. Instead of Agent OS commands handling spec writing, we defer to Plan Mode in Claude Code (or Cursor, or any agent with plan mode). This is the industry-standard approach to spec-driven development in 2026+.

Agent OS enhances plan mode with /shape-spec, which prompts targeted questions that consider your standards and product mission—resulting in better, more aligned specs (which get written via Plan mode). It also saves your plan into your Agent OS spec folder automatically.

Product planning

The product planning phase from v2 is still here, producing the same files:

• agent-os/product/mission.md
• agent-os/product/roadmap.md
• agent-os/product/tech-stack.md

It's simpler, smarter, and uses the AskUserQuestion tool for a smoother experience.

Profiles

Profiles are still here for managing different standards sets across project types.

Inheritance is simpler in v3—now defined in your main config.yml instead of separate profile-config.yml files. V3 also adds a sync script to push new standards from a project back to your base profiles.

Subagents & orchestration

The implementation and orchestration phases from v2 have been retired. Today's frontier models handle spec implementation well on their own—this is the recommended approach in 2026+.

While Agent OS no longer installs subagents, you can create your own. Use /inject-standards to bake your standards into subagents, Claude Skills, custom commands, or any prompt.

Is it backward compatible?

Yes and no.

Your content stays the same. Your standards, specs, and product docs use the same format. They transfer directly to v3 without modification.

Commands and scripts are new. The installation and updating process is much simpler in v3, but the commands themselves are different.

If you prefer to remain on v2, the v2 documentation is still available. However, we recommend using v3 on all new projects and consider updating existing projects to v3.

v2.1.1

• Replaced references to 'spec-researcher' (depreciated agent name) with 'spec-shaper'.
• Clarified --dry-run output to user to reassure we're in dry-run mode
• Tightened up template and istructions for writing spec.md, aiming to keep it shorter, easier to scan, and covering only the essentials.
• Tweaked create-task-list workflow for consistency.
• When planning product roadmap, removed instruction to limit it to 12 items.

v2.1.0 - Claude Code Skills, Improved Configs & more...

Version 2.1 implemented a round of significant changes to how things work in Agent OS. Here is a summary of what's new in version 2.1.0:

TL;DR

Here's the brief overview. It's all detailed below and the docs are updated to reflect all of this.

• Option to leverage Claude Code's new "Skills" feature for reading standards
• Option to enable or disable delegating to Claude Code subagents
• Replaced "single/multi-agent modes" with more flexible configuration options
• Retired the short-lived "roles" system. Too complex, and better handled with standard tooling (more below).
• Removed documentation & verification bloat
• Went from 4 to 6 more specific development phases (use 'em all or pick and choose!):
  1. plan-product -- (no change) Plan your product's mission & roadmap
  2. shape-spec -- For shaping and planning a feature before writing it up
  3. write-spec -- For writing your spec.md
  4. create-tasks -- For creating your tasks.md
  5. implement-tasks -- Simple single-agent implementation of tasks.md
  6. orchestrate-tasks -- For more advanced, fine-grain control and multi-agent orchestration of tasks.md.
• Simplified & improved project upgrade script

Let's unpack these updates in detail:

Claude Code Skills support

2.1 adds official support for Claude Code Skills.

When the config option standards_as_claude_code_skills is true, this will convert all of your standards into Claude Code Skills and not inject references to those Standards like Agent OS normally would.

2.1 also provides a Claude Code command, improve-skills which you definitely should run after installing Agent OS in your project with the skills option turned on. This command is designed to improve and rewrite each of your Claude Code Skills descriptions to make them more useable and discoverable by Claude Code.

Enable/Disable delegation to Claude Code subagents

2.1 introduces an config option to enable or disable delegating tasks to Claude Code subagents. You can disable subagents by setting use_claude_code_subagents to false.

When set to false, and when using Claude Code, you can still run Agent OS commands in Claude Code, and instead of delegating most tasks to subagents, Claude Code's main agent will execute everything.

While you lose some context efficiency of using subagents, you can token efficiency and some speed gains without the use of subagents.

Replaced "single-agent & multi-agent modes" with new config options

2.0.x had introduced the concepts of multi-agent and single-agent modes, where multi-agent mode was designed for using Claude Code with subagents. This naming and configuration design proved suboptimal and inflexible, so 2.1.0 does away with the terms "single-agent mode" and "multi-agent mode".

Now we configure Agent OS using these boolean options in your base ~/agent-os/config.yml:

claude_code_commands: true/false
use_claude_code_subagents: true/false
agent_os_commands: true/false

The benefits of this new configuration approach are:

• Now you can use Agent OS with Claude Code with or without delegating to subagents. (subagents bring many benefits like context efficiency, but also come with some tradeoffs—higher token usage, less transparency, slower to finish tasks).

• Before, when you had both single-agent and multi-agent modes enabled, your project's agent-os/commands/ folder ended up with "multi-agent/" and "single-agent/" subfolders for each command, which is confusing and clumsy to use. Now in 2.1.0, your project's agent-os/commands/ folder will not have these additional "modes" subfolders.

• Easier to integrate additional feature configurations as they become available, so that you can mix and match the exact set of features that fit your preferred coding tools and workflow style. For example, we're also introducing an option to make use of the new Claude Code Skills feature (or you can opt out). More on this below.

Retired (short-lived) "Roles" system

2.0.x had introduced a concept of "Roles", where your roles/implementers.yml and roles/verifiers.yml contained convoluted lists of agents that could be assigned to implement tasks. It also had a script for adding additional "roles".

All of that is removed in 2.1.0. That system added no real benefit over simply using available tooling (like Claude Code's own subagent generator) for spinning up your subagents.

2.1.0 introduces an 'orchestrate-tasks' phase, which achieves the same thing that the old "Roles" system intended: Advanced orchestration of multiple specialized subagents to carry out a complex implementation. More on this below.

Removed documentation & verification bloat

2.0.x had introduced a bunch of "bloat" that quickly proved unnecessary and inefficient. These bits have been removed in 2.1.0:

• Verification of your spec (although the spec-verifier Claude Code subagent is still available for you to call on, if/when you want)
• Documentation of every task's implementation
• Specialized verifiers (backend-verifier, frontend-verifier)

The final overall verification step for a spec's implementation remains intact.

From 4 to 6 more specific development phases

While some users use all of Agent OS' workflow for everything, many have been picking the parts they find useful and discarding those that don't fit their workflow—AS THEY SHOULD!

2.1.0 establishes this as a core principle of Agent OS: You can use as much or as little of it as you want!

With that in mind, we've moved from 4 to 6 different phases of development that can potentially be powered by Agent OS:

1. plan-product -- No changes here. This is for establishing your product's mission, roadmap and tech-stack.

2. shape-spec -- Use this when you need to take your rough idea for a feature and shape it into a well-scoped and strategized plan, before officially writing it up. This is where the agent asks you clarifying questions and ends up producing your requirements.md.

• Already got your requirements shaped? Skip this and drop those right into your spec's requirements.md 👍

3. write-spec -- Takes your requirements.md and formalizes it into a clear and concise spec.md.

4. create-tasks -- Takes your spec.md and breaks it down into a tasks list, grouped, prioritized and ready for implementation.

5. implement-tasks -- Just want to build right now(!), then use this to implement your tasks.md with your main agent.

6. orchestrate-tasks -- Got a big complex feature and want to orchestrate multiple agents, with more fine-grain control over their contexts? Use this. It provides a structure to delegate your task groups to any Claude Code subagents you've created. Or if you're not using Claude Code, it generates targeted prompt files (as was established in 2.0.x).

Simplified & improved project upgrade script

Now whenever you need to upgrade your Agent OS project installation (to a new version or to push configuration changes or standards changes to a project), now when you run project-install.sh or project-update.sh, the system will:

• Check and compare your incoming version & configs to your current project's
• Show you what will stay intact or be removed & re-installed
• Ask you to confirm to proceed.

v2.0.5

• Updated base installation update options to include a "Full update" option, which is the easiest way to pull and update the latest Agent OS stuff (default profile, scripts) without losing your base installation's custom profiles.
• The "Full update" option also dynamically updates your base install config.yml version number without changing your configurations.

v2.0.4

• Fixed multi-agent-mode not installing the roles/ files in the project agent-os folder.
• Clarified spec-research instructions.

v2.0.3

• Updated instructions and default standards to reduce excessive tests writing and test running during feature development to improve speed and token useage.
• For Claude Code users:
  • Replaced hard-coding of 'opus' model setting on agents with 'inherit' so that it inherits whichever model your Claude Code is currently using.
  • Updated create-role script to add the "Inherit" option when creating new agents.
• Clarified next command to run when in single-agent mode.

Agent OS 2.0 🚀

Agent OS 2.0 is a major new release that brings several core architectural changes and improvements.

The big headline here is the dual mode architecture for supporting both multi-agent tools (Claude Code) and single-agent tools (every other tool).

this page documents:

• The new features in Agent OS 2.0
• Architectural changes in 2.0
• What changed from 1.x
• Updating guide

The Agent OS docs also received a complete overhaul and expansion. It's now broken out into multiple pages that document every detail of how to install, use and customize Agent OS.

v1.4.1: Recaps, Project Manager subagent & task execution improvements

Several more improvements in version 1.4.1 after yesterday's release of 1.4.0.

Replaced Decisions with Recaps

Earlier versions added a decisions.md inside a project's .agent-os/product/. In practice, this was rarely used and didn't help future development.

It's been replaced with a new system for creating "Recaps"—short summaries of what was built—after every feature spec's implementation has been completed. Similar to a changelog, but more descriptive and context-focused. These recaps are easy to reference by both humans and AI agents.

Recaps are automatically generated via the new complete-tasks.md process.

Added Project-Manager Subagent

A goal of this update was to tighten up the processes for creating specs and executing tasks, ensuring these processes are executed reliably. Sounds like the job for a "project manager".

This update introduces a new subagent (for Claude Code) called project-manager which handles all task completion, status updates, and reporting progress back to you.

Spec Creation & Task Execution Reliability Improvements

Several changes to the instructions, processes, and executions, all aimed at helping agents follow the process steps consistently.

• Consolidated task execution instructions with clear step-by-step processes
• Added post-flight verification rules to ensure instruction compliance
• Improved subagent delegation tracking and reporting
• Standardized test suite verification and git workflow integration
• Enhanced task completion criteria validation and status management

v1.4.0: new project-centric installation process, project types, config.yml

BIG updates in this one! Thanks for all the feedback, requests and support 🙏

All New Installation Process

The way Agent OS gets installed is structured differently from prior versions. The new system works as follows:

There are 2 installation processes:

• Your "Base installation" (now optional, but still recommended!)
• Your "Project installation"

"Base installation"

• Installs all of the Agent OS files to a location of your choosing on your system where they can be customized (especially your standards) and maintained.
• Project installations copy files from your base installation, so they can be customized and self-contained within each individual project.
• Your base installation now has a config.yml

To install the Agent OS base installation,

1. cd to a location of your choice (your system's home folder is a good choice).

2. Run one of these commands:

• Agent OS with Claude Code support:
  curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --claude-code
• Agent OS with Cursor support:
  curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --cursor
• Agent OS with Claude Code & Cursor support:
  curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --claude-code --cursor

3. Customize your /standards (just like earlier versions)

Project installation

• Now each project codebase gets it's own self-contained installation of Agent OS. It no longer references instructions or standards that reside elsewhere on your system. These all get installed directly into your project's .agent-os folder, which brings several benefits:
  • No external references = more reliable Agent OS commands & workflows.
  • You can commit your instructions, standards, Claude Code commands and agents to your project's github repo for team access.
  • You can customize standards differently per project than what's in your base installation.

Your project installation command will be based on where you installed the Agent OS base installation.

• If you've installed it to your system's home folder, then your project installation command will be ~/.agent-os/setup/project.sh.
• If you've installed it elsewhere, your command will be /path/to/agent-os/setup/project.sh
  (after your base installation, it will show you your project installation command. It's a good idea to save it or make an alias if you work on many projects.)

If (for whatever reason) you didn't install the base installation, you can still install Agent OS directly into a project, by pulling it directly off of the public github repo using the following command.

• Note: This means your standards folder won't inherit your defaults from a base installation. You'd need to customize the files in the standards folder for this project.
  curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/project.sh | bash -s -- --no-base --claude-code --cursor

Agent OS config.yml

When you install the Agent OS base installation, that now includes a config.yml file. Currently this file is used for:

• Tracking the Agent OS version you have installed
• Which coding agents (Claude Code, Cursor) you're using
• Project Types (new! read on...)

Project Types

If you work on different types of projects, you can define different sets of standards, code style, and instructions for each!

• By default, a new installation of Agent OS into a project will copy its instructions and standards from your base installation's /instructions and /standards.
• You can define additional project types by doing the following:
  • Setup a folder (typically inside your base installation's .agent-os folder, but it can be anywhere on your system) which contains /instructions and /standards folders (copy these from your base install, then customize).
  • Define the project type's folder location on your system in your base install's config.yml
• Using project types:
  • If you've named a project type, 'ruby-on-rails', when running your project install command, add the flag --project-type=ruby-on-rails.
  • To make a project type your default for new projects, set it's name as the value for default_project_type in config.yml

Removed or changed in version 1.4.0:

This update does away with the old installation script files:

• setup.sh (replaced by /setup/base.sh and /setup/project.sh)
• setup-claude-code.sh (now you add --claude-code flag to the install commands or enable it in your Agent OS config.yml)
• setup-cursor.sh (now you add --cursor flag to the install commands or enable it in your Agent OS config.yml)

Claude Code Agent OS commands now should not be installed in the ~/.agent-os/.claude/commands folder. Now, these are copied from ~/.agent-os/commands into each project's ~/.claude/commands folder (this prevents duplicate commands showing in in Claude Code's commands list). The same approach applies to Claude Code subagents files.

Upgrading to version 1.4.0

Follow these steps to update a previous version to 1.4.0:

1. If you've customized any files in /instructions, back those up now. They will be overwritten.

2. Navigate to your home directory (or whichever location you want to have your Agent OS base installation)

3. Run the following to command, which includes flags to overwrite your /instructions (remove the --cursor flag if not using Cursor):
   curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --overwrite-instructions --claude-code --cursor

4. If your ~/.claude/commands contain Agent OS commands, remove those and copy the versions that are now in your base installation's commands folder into your project's .claude/commands folder.

5. Navigate to your project. Run your project installation command to install Agent OS instructions and standards into your project's installation. If your Agent OS base installation is in your system's home folder (like previous versions), then your project installation will be: ~/.agent-os/setup/project.sh

Subagents, Simplifications & Efficiency

Added

• Pre-flight Check System - New meta/pre-flight.md instruction for centralized agent detection and initialization
• Proactive Agent Usage - Updated agent descriptions to encourage proactive use when appropriate
• Structured Instruction Organization - New folder structure with core/ and meta/ subdirectories

Changed

• Instruction File Structure - Reorganized all instruction files into subdirectories:
  • Core instructions moved to instructions/core/ (plan-product, create-spec, execute-tasks, execute-task, analyze-product)
  • Meta instructions in instructions/meta/ (pre-flight, more to come)
• Simplified XML Metadata - Removed verbose <ai_meta> and <step_metadata> blocks for cleaner, more readable instructions
• Subagent Integration - Replaced manual agent detection with centralized pre-flight check across all instruction files to enforce delegation and preserve main agent's context.
• Step Definitions - Added subagent attribute to steps for clearer delegation of work to help enforce delegation and preserve main agent's context.
• Setup Script - Updated to create subdirectories and download files to new locations

Improved

• Code Clarity - Removed redundant XML instructions in favor of descriptive step purposes
• Agent Efficiency - Centralized agent detection reduces repeated checks throughout workflows
• Maintainability - Cleaner instruction format with less XML boilerplate
• User Experience - Clearer indication of when specialized agents will be used proactively

Removed

• CLAUDE.md - Removed deprecated Claude Code configuration file (functionality moved to pre-flight system, preventing over-reading instructions into context)
• Redundant Instructions - Eliminated verbose ACTION/MODIFY/VERIFY instruction blocks