Agent OS

File Structure

What goes where

Overview

Agent OS uses two locations: a base installation in your home directory that holds profiles and scripts, and a project installation in each codebase that holds your standards, specs, and product docs.

Base installation

Located at ~/agent-os/:

Copy
~/agent-os/
├── commands/
│   └── agent-os/           # Slash commands copied to projects
│       ├── discover-standards.md
│       ├── index-standards.md
│       ├── inject-standards.md
│       ├── plan-product.md
│       └── shape-spec.md
├── profiles/
│   ├── default/
│   │   └── standards/      # Standards for this profile
│   └── rails/
│       └── standards/
├── scripts/
│   ├── project-install.sh
│   ├── sync-to-profile.sh
│   └── common-functions.sh
└── config.yml              # Default profile, inheritance

Project installation

Created in your project directory:

Copy
your-project/
├── agent-os/
│   ├── standards/          # Your coding standards
│   │   ├── api/
│   │   │   ├── response-format.md
│   │   │   └── error-handling.md
│   │   ├── database/
│   │   │   └── migrations.md
│   │   └── index.yml           # Index for matching
│   ├── specs/              # Saved specs from /shape-spec
│   │   └── 2026-01-15-1430-user-comments/
│   │       ├── plan.md
│   │       ├── shape.md
│   │       ├── standards.md
│   │       ├── references.md
│   │       └── visuals/
│   └── product/            # Product documentation
│       ├── mission.md
│       ├── roadmap.md
│       └── tech-stack.md
└── .claude/
    └── commands/
        └── agent-os/       # Slash commands
            ├── discover-standards.md
            ├── index-standards.md
            ├── inject-standards.md
            ├── plan-product.md
            └── shape-spec.md

Directory purposes

agent-os/standards/

Your coding standards, organized by domain. Subfolders group related standards. Files at the root level (not in subfolders) are indexed under root.

agent-os/standards/index.yml

Maps standards to descriptions for quick matching. Created and maintained by /discover-standards and /index-standards.

agent-os/specs/

Saved specs from /shape-spec. Each spec gets a timestamped folder with the feature slug.

agent-os/product/

Product documentation created by /plan-product. Used by /shape-spec for context.

.claude/commands/agent-os/

Slash commands for Claude Code. Copied from the base installation during project install.

What to commit

Typically commit:

  • agent-os/standards/ — Share standards with your team
  • agent-os/product/ — Share product context
  • agent-os/specs/ — Preserve project history

The .claude/commands/ folder can be committed or gitignored—team members can regenerate it from their base installation.

Stay updated on Agent OS

Get notified of major new releases and updates to Agent OS.

Builder Methods

Training and community for developers and founders building with AI.

Created by Brian Casel (that's me) — multi-time founder, product designer, teacher, and the creator behind Builder Methods.

© 2026 CasJam Media, LLC / Builder Methods