File Structure

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/:

~/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:

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.