Stop prompting AI coding agents like it's 2024

Why use Agent OS?

Stop wrestling with AI that writes the wrong code. Agent OS transforms coding agents from confused assistants into trusted developers who truly understand your codebase.

3 reasons why product teams use Agent OS:

1

Complete context, not just prompts

Unlike basic AI setups, Agent OS provides three layers of context that work together:

• Standards - Your coding style, tech stack, and best practices
• Product - Your mission, architecture, roadmap, and decisions
• Specs - Detailed plans & tasks for each feature implementation

The result: Agents write code that looks like you wrote it—first time, every time.

2

Structured development, not chaos

Agent OS replaces random prompting and circular rewrites with a proven workflow. It automatically:

• Writes comprehensive specs before coding begins
• Breaks features into trackable, TDD-focused tasks
• Documents key decisions as they happen
• Updates your roadmap as features ship

The difference: Ship features faster with clear specs and completed tasks—not endless cycles of (re)explaining requirements and redoing work.

3

Your standards, your way

Agent OS is completely yours to shape. Define your own coding standards, write custom instructions, and adapt every workflow to match how your team operates. No rigid interfaces or prescribed processes—just markdown files you control. Works seamlessly with any AI tool or IDE you choose.

The relief: Your coding agent finally feels like a senior developer on your team—thinking your way, following your patterns, and shipping at your standards.

The Three Layers of Context

Agent OS works by layering context—just like you'd onboard a human developer. Each layer builds on the previous one, creating a complete picture of how you build software.

Layer 1

Your standards

Your standards define how you build software. Your stack. Your opinions. Your style. Your priorities. The standards you expect everyone on your team to follow when building anything. These should include:

• Tech Stack — Your default frameworks, libraries, and tools
• Code Style — Your formatting rules, naming conventions, and preferences
• Best Practices — Your development philosophy (e.g., TDD, commit patterns, etc.)

Your standards documentation lives on your system in ~/.agent-os/standards/... and are referenced from every project, every codebase. Set once, use everywhere, override as needed.

Layer 2

Your product

At the product (codebase) layer, we document what it is we're building, why we're building it, who it's for, and the big-picture product roadmap. This includes:

• Mission — What you're building, for whom, and why it matters
• Roadmap — Features shipped, in progress, and planned
• Decisions — Key architectural and technical choices (with rationale)
• Product-specific stack — The exact versions and configurations for this codebase

Product documentation lives in your codebase (.agent-os/product/) and give agents the full picture of your product.

Layer 3

Your specs

Throughout your product's development, you'll create many specs. Each spec is a single feature or enhancement or fix, which typically represents a few hours or days of work (accellerated with the help of AI). Each spec will have its own requirements, technical specs, and tasks breakdown.

Individual feature specifications include:

• SRD (Spec Requirements Document) — Goals for the feature, user stories, success criteria
• Technical Specs — API design, database changes, UI requirements
• Tasks Breakdown — Trackable step-by-step implementation plan with dependencies

Specs live in dated folders inside your codebase (.agent-os/projects/2025-12-19-user-auth/) and guide agents through each spec's implementations.

With all three layers in place, your agent has everything it needs: how you build (Standards), what you're building (Product), and what to build next (Specs). No more confusion, no more rewrites—just clean, consistent code that looks like you wrote it.

Install Agent OS

Getting started with Agent OS is a two-step process:

1. Base Installation
   Install Agent OS on your system
2. Tool-Specific Setup
   Set up Claude Code, Cursor, or whichever IDE you're using

Installing Agent OS in an existing codebase that's been around a while? Then see Working with Existing Codebases.

See What Gets Installed Where? to understand where all the Agent OS files will live after installation.

curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup.sh | bash

mkdir -p ~/.agent-os/standards
mkdir -p ~/.agent-os/instructions

curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup-claude-code.sh | bash

curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup-cursor.sh | bash

mkdir -p .cursor/rules

@analyze-product

I want to install Agent OS in my existing codebase

~/.agent-os/
├── standards/
│   ├── tech-stack.md         # Your default tech choices
│   ├── code-style.md         # Your formatting preferences
│   └── best-practices.md     # Your development philosophy
└── instructions/
    ├── plan-product.md       # Agent's instructions to initialize a product
    ├── create-spec.md        # Agent's instructions to plan features
    ├── execute-tasks.md      # Agent's instructions to build and ship
    └── analyze-product.md    # Agent's instructions to add to existing code

~/.claude/
├── CLAUDE.md                # Points to your default preferences
└── commands/
    ├── plan-product.md      # → points to ~/.agent-os/instructions/
    ├── create-spec.md       # → points to ~/.agent-os/instructions/
    ├── execute-tasks.md     # → points to ~/.agent-os/instructions/
    └── analyze-product.md   # → points to ~/.agent-os/instructions/

your-product/
├── .claude/
│   └── CLAUDE.md          # Points to project details and instructions
└── .agent-os/
    ├── product/           # Created by plan-product
    └── specs/             # Created by create-spec

your-product/
├── .cursor/
│   └── rules/
│       ├── plan-product.mdc       # → points to ~/.agent-os/instructions/
│       ├── create-spec.mdc        # → points to ~/.agent-os/instructions/
│       ├── execute-tasks.mdc      # → points to ~/.agent-os/instructions/
│       └── analyze-product.mdc    # → points to ~/.agent-os/instructions/
├── .agent-os/
│   ├── product/                   # Created by plan-product
│   └── specs/                     # Created by create-spec
└──CLAUDE.md                       # If also using Claude Code

Using Agent OS

With Agent OS installed, you're ready to supercharge your AI coding workflow. Here's how to use each part:

Setting Your Standards

Before starting any project, customize your global standards to match how you like to build. Your agent will reference these standards constantly when planning projects and writing code, so make them reflect your actual preferences:

💡 Pro tip: Be opinionated! The more specific your standards, the more consistent your agent's output.

Starting a New Product

When beginning a fresh codebase, you can provide as much or as little detail as you want—though more detail leads to better results by using the @plan-product command.

@plan-product

I want to build a SaaS tool for tracking customer feedback
Key features: feedback collection, sentiment analysis, reporting dashboard
Target users: Product managers at B2B SaaS companies
Tech stack: Use my defaults

Note: When starting a new product, feel free to provide as much or as little detail in your initial prompt. You can even invoke the @plan-product command with no other details and your agent will then prompt you for the specific details it needs to get started on your product's plan and roadmap.

Once your agent has collected the basic details it needs, it will:

• ✅ Create .agent-os/product/ structure
• ✅ Generate mission.md with product vision
• ✅ Create a 5-phase roadmap
• ✅ Document all technical decisions
• ✅ Set up your preferred tech stack

Important: Review and edit the generated documentation to ensure it accurately reflects your vision and goals.

Adding Agent OS to Existing Products

Have an existing codebase? No problem. Use the @analyze-product command to install Agent OS into your existing codebase.

@analyze-product

I want to install Agent OS in my existing codebase

Your agent will:

• 🔍 Analyze your current code structure
• 📊 Detect your tech stack and patterns
• 📝 Create documentation reflecting what's already built
• ✅ Add completed features to "Phase 0" in the roadmap

Important: Review the generated documentation carefully—your agent's analysis might miss nuances or business context that only you know.

Planning a Feature

Ready to build something new? You have two options:

Option 1: Ask "what's next?"

Your agent should automatically trigger the @create-spec command, check your product's roadmap.md file, and suggest the next uncompleted feature. You can confirm or adjust the feature before proceeding.

Option 2: Request a specific feature

Use the @create-spec command along with your instructions or request for a new feature or task.

@create-spec

Let's add user authentication with email/password and OAuth

Either way, your agent will:

• 📋 Create a Spec Requirements Document (SRD)
• 🔧 Write technical specifications
• 💾 Design database schemas (if needed)
• 🔌 Document API endpoints (if needed)
• ✅ Break down work into ordered tasks

Important: This is the most critical review point! Carefully examine the SRD, specs, and especially the task breakdown. Adjust anything that doesn't match your expectations before proceeding.

Specs live in: .agent-os/specs/2025-07-16-user-authentication/

Executing Tasks

Time to code! Start building:

@execute-task

Work on the next task in the user authentication project

By default, your agent will complete one parent task and all its sub-tasks. You can adjust this:

• More work: "Complete tasks 1 and 2 with all sub-tasks"
• Less work: "Just do task 1.1 and 1.2"
• Specific task: "Work on task 3: API endpoints"

Your agent will:

• 📝 Follow your coding standards exactly
• 🧪 Write tests first (if that's your style)
• 💾 Commit with clear messages
• ✅ Update task progress as it goes
• 🔊 Play a sound when done

Important: While agents are great at following patterns, always review the code for business logic accuracy and edge cases before merging.

Workflow Examples

Example 1: Monday Morning

What's next on the roadmap?

Your agent checks .agent-os/product/roadmap.md and suggests the next uncompleted feature.

Example 2: Quick Bug Fix

@create-spec

Users report the dashboard is slow when filtering by date

Even for bug fixes, your agent creates a mini-spec with clear tasks.

Example 3: Continuing Work

@execute-task

Continue where we left off yesterday

Your agent reads the task list and picks up exactly where it stopped.

Refining Your Agent OS

Agent OS gets better with use. Each spec teaches you something about your process, your preferences, and how to better guide your AI agents. Here's how to continuously improve your setup.

The Refinement Loop

After each feature or spec, ask yourself:

1. What worked well?
   Patterns to document and repeat
2. What needed correction?
   Gaps in your standards or instructions
3. What surprised you?
   Unexpected approaches that might be worth adopting

Common Refinements

Where to Make Updates

Making Refinements Stick

Team Refinement

If working with a team:

1. Schedule Regular Reviews
   Monthly or after major features
2. Collect Patterns
   What is everyone correcting in code reviews?
3. Reach Consensus
   Agree on patterns before adding to standards
4. Share Updates
   Ensure everyone updates their local Agent OS files

Signs You Need Refinement

• You're making the same corrections repeatedly
• Agents consistently miss certain patterns
• Code reviews reveal style inconsistencies
• New team members point out unclear conventions
• You discover better patterns worth standardizing

The Long Game

Remember: Agent OS is a living system. The goal isn't perfection on day one—it's continuous improvement. Each refinement makes your agents more effective and your codebase more consistent.

Your Agent OS a year from now will be dramatically better than today's, shaped by real experience and tailored to exactly how you and your team work best.

Best Practices

While Agent OS's task execution process automatically updates your roadmap and prompts for decision updates, it's good practice to regularly:

1. Review and refine your standards
   As you see patterns in code reviews, update your standards files
2. Regularly review roadmap.md
   Ensure it reflects actual progress and priorities
3. Update decisions.md
   Document important choices that affect future development
4. Refine best-practices.md
   Add patterns that help your agent think like you think

Regular maintenance keeps your Agent OS aligned with your evolving project and team needs.

Tips for Success

Troubleshooting

Remember: The best time to fix issues is during planning, not after code is written!

FAQ