Version 2.x Changes

Agent OS 2.x 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.x
• Major architecture changes
• What changed from 1.x
• Migration guide

New features in 2.x

Improved alignment (quality)

Agent OS 2.x introduced flexible configuration options to improve code quality and alignment with your coding standards.

• Standards injections: Relevant standards are injected into each command's instructions for the 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)

Agent OS 2.x's structured workflow ensures agents follow task instructions exactly and completely.

• Specialized instructions: Each command and workflow provides focused, specialized instructions for the current phase of development.
• Flexible execution: Use slash commands with Claude Code or @ reference commands with any AI coding tool.

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

Claude Code Skills integration (Added in 2.1)

Agent OS 2.1 introduced seamless Claude Code Skills integration, providing a more intelligent and context-efficient way to apply coding standards:

• Automatic standards application: Your standards are converted to Skills that Claude applies intelligently when relevant
• Context efficiency: Significantly reduced token usage compared to explicit standards injection
• Skill optimization: The /improve-skills command enhances Skill descriptions for better recognition
• Enabled by default: Works automatically when using Claude Code commands

Major architecture changes

Base installation required

The base installation in Version 2.x 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
• Configuration-specific compilation based on your selected options

Compilation process

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

• Workflows are injected into commands dynamically
• Standards are injected based on profile selection and configuration
• Commands adapt to your configuration options

Flexible configuration system

Version 2.x introduced flexible configuration options that let you adapt Agent OS to any AI coding tool:

• Claude Code integration: Full support for slash commands, subagents, and Skills (Skills added in 2.1)
• Universal compatibility: Works with Cursor, Codex, Gemini, Windsurf, and any AI coding tool through @ references
• Mix and match: Enable the features your tool supports through boolean configuration options

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.x uses agent-os (no dot).

2

Install version 2.x 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.x, 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.x

4

Migrate custom project types to profiles

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

Profiles 2.x 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.x

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.x.

5

Remove old Claude Code files (if applicable)

If you're using Claude Code, version 1.x installed Agent OS commands and agents directly into your project's .claude/commands/ and .claude/agents/ folders. Only the Agent OS-specific files from version 1.x need to be removed before upgrading to 2.x. If you have other custom agents or commands in these folders, keep them.

Version 2.x organizes Agent OS files into dedicated subdirectories for better isolation:

• .claude/commands/agent-os/ - Agent OS 2.x commands
• .claude/agents/agent-os/ - Agent OS 2.x agents

If your project includes a claude.md file, any old references to Agent OS files can and should be removed from this file (Agent OS 2.x doesn't use this file anymore). If you have no other content in your claude.md, then it's safe to remove this file altogether.

6

Update projects

cd /path/to/your/project

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

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

7

Migrate product and specs folders

If you have existing /product and /specs folders from your 1.x installation, you can simply move them into your new 2.x agent-os installation and continue building:

cd /path/to/your/project
mv .agent-os/product agent-os/product
mv .agent-os/specs agent-os/specs

The structure and format of product/ and specs/ folders are mostly the same in 2.x, so this should be a smooth transition. Your existing product documentation and specifications will work with the new version.

8

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.x, you can remove the old 1.x project installation folder:

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