Version 2.0 Changes

Agent OS 2.0 was initially released in October 2025 and it brought several major changes and improvements. This page documents what those are and can serve as your guide to upgrading from version 1.x to 2.x.

On this page:

• New features in 2.0
• Major architecture changes
• What changed from 1.x
• Migration guide

New features in 2.0

Improved alignment (quality)

Multi-agent and single-agent modes improve code quality and alignment with your coding standards.

• Standards injections: Relevant standards are injected into each agent's instructions for their current task, avoiding irrelevant bloat.
• Pattern reuse: Agents are instructed to find and reuse existing code patterns instead of duplicating code.

Improved reliability (process adherence)

Multi-agent and single-agent modes ensure agents follow task instructions exactly and completely.

• Agent-specific instructions: In multi-agent mode, each subagent gets specialized role instructions, staying focused and avoiding confusion from conversation history.
• Prompt generation: In single-agent mode, each spec gets a smart prompt with only the relevant process steps and standards.

Profiles system

Profiles replace "project types" with more powerful features:

• Multiple profiles: Create profiles for different tech stacks
• Profile inheritance: Build on existing profiles
• Easy switching: Change profiles per project

Enhanced planning

The create-spec command in the Agent OS workflow helps you research and scope your feature before writing the specification:

• Agent-assisted research Q&A session
• Analyze existing code patterns
• Gather and analyze visual assets (mockups, wireframes, screenshots)

Visual UI implementation

• Include mockups, wireframes, and screenshots in specs
• Agents use visual references for implementations
• Playwright MCP integration for checking UI in the browser

Verification system

Every step now has dedicated verification, ensuring quality and completeness:

• Spec verification: Ensures specifications are complete
• Implementation verification: Reviews code quality and standards
• Visual verification: Compares implementations against mockups

Major architecture changes

Base installation required

The base installation in Version 2.0 is now required and gets installed into ~/agent-os. Project installations now compile from this base, enabling:

• Centralized management of standards
• Consistent updates across all projects
• Profile inheritance and customization
• Mode-specific compilation (single vs multi-agent)

Compilation process

Unlike 1.x's file copying, version 2.0 uses intelligent compilation:

• Workflows are injected into commands and agents dynamically
• Standards are injected into commands and agents based on profile selection
• Agents are generated from role definitions
• Commands adapt to your chosen mode

Dual-mode support

Version 2.0 officially supports two modes:

• Multi-agent mode: For tools that support subagents (currently Claude Code only)
• Single-agent mode: For all other AI tools with sequential prompting

What changed from 1.x

Migration guide

1

Backup your 1.x installation

Your existing .agent-os folders (with dot) can serve as natural backups since 2.0 uses agent-os (no dot).

2

Install version 2.0 base

curl -sSL https://github.com/buildermethods/agent-os/raw/main/scripts/base-install.sh | bash

This creates ~/agent-os in your home directory.

3

Migrate custom standards

If you've customized files in your version 1.x .agent-os/standards/ folder, you'll want to move or merge them into the new ~/agent-os/profiles/default/standards/ folder.

For easier compatibility with how standards are organized in 2.0, it might help to reorganize your custom standards into the new default subfolders:

• agent-os/profiles/default/standards/global/ for global standards
• agent-os/profiles/default/standards/backend/ for backend standards
• agent-os/profiles/default/standards/frontend/ for frontend standards
• agent-os/profiles/default/standards/testing/ for testing standards

Technically, you can organize the sub-folders inside of the agent-os/profiles/default/standards/ folder as you wish, but deviating from the above would require some updates to the places where standards are injected. It's all documented on this page:

Learn more about standards in 2.0

3

Migrate custom project types to profiles

"Project types" in 1.x are now called "profiles" in 2.0. If you were using custom project types, you'll probably want to create profiles for them in 2.0. There is a script to help you spin up new profiles.

Profiles 2.0 are more powerful and can inherit from the default (or other) profiles, so your project types might be able to be simplified and refactored given the new profile system.

Learn more about profiles in 2.0

If you weren't using custom project types in 1.x, then the "default" profile that comes with your base installation would be your one and only profile in 2.0.

4

Remove old Claude Code files (if applicable)

If you're using Claude Code, version 1.x installed commands and agents directly into your project's .claude/commands/ and .claude/agents/ folders. These should be removed before upgrading to 2.0:

cd /path/to/your/project
rm -rf .claude/commands/*
rm -rf .claude/agents/*

Don't worry - the folders themselves will remain and 2.0 will populate them with new content during installation. Version 2.0 organizes these into .claude/commands/agent-os/ and .claude/agents/agent-os/ subdirectories for better isolation.

5

Update projects

cd /path/to/your/project

~/agent-os/scripts/project-install.sh

Choose your profile and modes during installation. The new agent-os folder will be created alongside your old .agent-os folder.

6

Verify and clean up

After confirming everything works, and after you've migrated and merged your custom standards and project types into your new Agent OS profile(s), you can go ahead and remove old installations:

Remove your 1.x base installation folder:

rm -rf ~/.agent-os

After you've updated a project to 2.0, you can remove the old 1.x project installation folder:

rm -rf /path/to/your/project/.agent-os