### Installation Flow Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

Illustrates the step-by-step process when a user runs the project-install.sh script to bootstrap Agent OS in a new project.

```bash
User runs: project-install.sh

1. Validate environment
2. Load config.yml
3. Resolve profile inheritance (if applicable)
   - default
   → rails (inherits from default)
   → rails-api (inherits from rails)
4. Create project structure (agent-os/)
5. For each profile in chain:
   - Copy standards to project
6. Create index.yml
7. Copy command definitions
```

--------------------------------

### Agent OS Profile Sharing Setup

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/workflow-and-integration.md

This example demonstrates a repository structure for sharing Agent OS profiles across teams, enabling base and team-specific standards.

```bash
Main Repository:
  /agent-os-profiles/
    config.yml
    profiles/
      company-default/
        global/
          naming.md
          tech-stack.md
        backend/
          logging.md
      frontend-team/
        inherits_from: company-default
        frontend/
          component-structure.md
      backend-team/
        inherits_from: company-default
        backend/
          authentication.md

Each Project:
  /my-project/
  /my-project/agent-os-base -> ../agent-os-profiles/  
  
  $ ./agent-os-base/scripts/project-install.sh --profile frontend-team
  # Installs: company-default + frontend-team standards
```

--------------------------------

### Initial Project Installation

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

Installs a new Agent OS project. Use options to customize the installation process, such as specifying a profile or only updating commands.

```bash
cd /path/to/my-project
/path/to/agent-os-base/scripts/project-install.sh
```

--------------------------------

### Standard Installation

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Perform a standard installation using the default profile defined in `config.yml`.

```bash
./scripts/project-install.sh
```

--------------------------------

### Verbose Installation for Debugging

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Enable detailed output for troubleshooting by using the `--verbose` flag during installation.

```bash
./scripts/project-install.sh --verbose
```

--------------------------------

### Initialize Agent OS Project

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/workflow-and-integration.md

Clone the Agent OS base installation, navigate to your project directory, and run the installation script to set up the initial project structure.

```bash
# 1. Clone or download Agent OS base installation
git clone https://github.com/buildermethods/agent-os.git agent-os-base

# 2. Navigate to target project
cd my-project/

# 3. Run installation script
/path/to/agent-os-base/scripts/project-install.sh

# 4. Select profile (or accept default)
# System creates agent-os/ directory with initial standards
```

--------------------------------

### Discovery Flow Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

Details the process initiated when a user runs the /discover-standards command, guiding them through pattern discovery and standard creation.

```bash
User runs: /discover-standards

1. Analyze codebase structure
2. Present focus area options to user
3. Read representative files in selected area
4. Extract patterns
5. Present findings to user
6. For each selected pattern:
   a. Ask clarifying questions (why, exceptions, etc.)
   b. Draft standard incorporating answers
   c. Get user approval
   d. Create standard file
7. Update index.yml with new standards
```

--------------------------------

### Help Command Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Displays the help message for the sync-to-profile.sh script, outlining available options and usage.

```bash
./scripts/sync-to-profile.sh -h
```

--------------------------------

### Agent OS Configuration Schema Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/data-structures.md

Example of a YAML configuration file for Agent OS, demonstrating version, default profile, and profile inheritance.

```yaml
version: "3.0"
default_profile: "default"

profiles:
  {profile-name}:
    inherits_from: {parent-profile}
```

```yaml
version: "3.0"
default_profile: "rails"

profiles:
  rails:
    inherits_from: default
  rails-api:
    inherits_from: rails
  nextjs:
    inherits_from: default
```

--------------------------------

### Example User Question Prompt

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

This is an example of a prompt that asks the user a question, provides a header, and lists options for selection. It supports single or multi-select.

```text
Question: Which standard to inject?

Header: Select Standard

Options:
  - api/response-format — Response envelope structure
  - api/error-handling — Error codes and responses
  - global/naming — File and variable naming

MultiSelect: false
```

--------------------------------

### Interactive Sync Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Initiates an interactive synchronization process using default settings for the source directory.

```bash
./scripts/sync-to-profile.sh
```

--------------------------------

### Complete Index Schema YAML Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/data-structures.md

A comprehensive example of the index YAML structure, demonstrating nested folders and file descriptions for standards.

```yaml
root:
  ci-cd:
    description: CI/CD configuration and deployment
  coding-style:
    description: Code formatting and style rules

api:
  authentication:
    description: API authentication and token management
  error-handling:
    description: Error codes and error response format
  response-format:
    description: API response envelope structure

backend:
  logging:
    description: Logging levels and structured logging format
  validation:
    description: Input validation and error handling
```

--------------------------------

### Index Matching Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/api-discovery-and-matching.md

Shows an example of matching an index entry's description against user context to calculate a relevance score.

```yaml
Index entry:
  api:
    response-format:
      description: "API response envelope structure and error format"

Context: User wants to create API endpoint

Match score = 1.0 (exact match on "API")
```

--------------------------------

### Typical Agent OS Installation Time

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

Provides a breakdown of the estimated time for each step during a typical Agent OS installation. Factors affecting installation time include the number of standards, file system speed, and inheritance chain depth.

```text
Typical installation:
  - Validate: 100ms
  - Load config: 50ms
  - Create directories: 50ms
  - Copy standards (50 files): 200ms
  - Create index: 100ms
  - Copy commands: 50ms
  Total: ~600ms
```

--------------------------------

### Installation with Specific Profile

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Install Agent OS using a specific profile, such as 'rails', instead of the default.

```bash
./scripts/project-install.sh --profile rails
```

--------------------------------

### Selection Prompt Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/data-structures.md

Example of a user selection prompt, asking which standards to inject with distinct choices.

```text
Which standards to inject?
  - All API standards
  - Just response-format
  - Custom selection
```

--------------------------------

### Share Standards Between Projects (Install)

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

In another project, use the project-install.sh script with the --profile flag to install standards that have been shared from a source project.

```bash
# In other project:
./scripts/project-install.sh --profile {name}
→ Install standards from profile
```

--------------------------------

### Agent OS Installation Structure

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

Illustrates the directory structure and configuration files for an Agent OS installation, including versioning, profiles, scripts, and command definitions.

```text
┌─────────────────────────────────────────────────────────────┐
│                     Agent OS Installation                    │
├─────────────────────────────────────────────────────────────┤
│                                                              
│  config.yml                                                  │
│  ├── version                                                 │
│  ├── default_profile                                         │
│  └── profiles (inheritance definitions)                      │
│                                                              
│  profiles/                   (Template standards)            │
│  ├── default/                                                │
│  │   └── standards/                                          │
│  ├── rails/                                                  │
│  │   └── standards/                                          │
│  └── ...                                                      │
│                                                              
│  scripts/                    (Bootstrap & sync tools)        │
│  ├── project-install.sh                                      │
│  ├── sync-to-profile.sh                                      │
│  └── common-functions.sh                                     │
│                                                              
│  commands/                   (Command definitions)           │
│  └── agent-os/                                               │
│      ├── discover-standards.md                               │
│      ├── shape-spec.md                                       │
│      ├── inject-standards.md                                 │
│      ├── index-standards.md                                  │
│      └── plan-product.md                                     │
│                                                              
└─────────────────────────────────────────────────────────────┘
                              ↓
           (Installation via project-install.sh)
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Project Installation                       │
├─────────────────────────────────────────────────────────────┤
│                                                              
│  my-project/                                                 │
│  ├── agent-os/                                               │
│  │   ├── standards/          (Installed & discovered)        │
│  │   │   ├── index.yml                                       │
│  │   │   ├── api/                                            │
│  │   │   ├── database/                                       │
│  │   │   └── ...                                             │
│  │   ├── specs/              (Feature plans)                 │
│  │   ├── product/            (Mission, roadmap, tech)        │
│  │   └── commands/           (Command copies)                │
│  └── src/                    (Project source code)           │
│                                                              
└─────────────────────────────────────────────────────────────┘
                              ↑
        (Sync back via sync-to-profile.sh)
                              │
                    (Updates base profiles)
```

--------------------------------

### Agent OS Minimal Configuration Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

A basic configuration file with only the essential version and default profile settings.

```yaml
version: 3.0
default_profile: default
```

--------------------------------

### Minimal Agent OS Standards Index

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

A basic example of the `index.yml` file containing only essential API response format standards. This serves as a starting point for defining project standards.

```yaml
api:
  response-format:
    description: API response structure

```

--------------------------------

### Agent OS Profile Structure Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

Illustrates the directory structure for profiles, showing nested directories for different configurations within each profile.

```tree
profiles/
├── default/
│   └── global/
│       └── tech-stack.md
├── rails/
│   ├── api/
│   │   └── response-format.md
│   └── global/
│       └── tech-stack.md
└── nextjs/
    ├── frontend/
    │   └── component-structure.md
    └── ...
```

--------------------------------

### Agent OS Installation Failure Recovery Steps

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

Provides a sequence of steps to recover from Agent OS installation failures. This includes checking error messages, verifying integrity, ensuring write permissions, retrying with verbose output, and deleting partial installations.

```text
If installation fails:

1. Check error message for specific issue
2. Verify base installation integrity
3. Ensure target directory is writable
4. Retry with `--verbose` for details
5. Delete partially-created `agent-os/` and retry
```

--------------------------------

### New Standard File Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/api-discovery-and-matching.md

Illustrates the prompt shown to the user when a new standard file is detected, offering options to accept, edit, or skip.

```text
File: api/new-pattern.md

Proposed description: "New pattern for API request validation"

Accept? (yes / edit: [better description] / skip)
```

--------------------------------

### Agent OS Installation Structure

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/workflow-and-integration.md

Illustrates the default directory layout for a base Agent OS installation, including configuration, profiles, scripts, and commands.

```text
agent-os-base/
├── config.yml                  # Global configuration
├── profiles/                   # Profile templates
│   └── default/
│       ├── global/
│       │   └── tech-stack.md
│       └── ...
├── scripts/                    # Installation scripts
│   ├── project-install.sh
│   ├── sync-to-profile.sh
│   └── common-functions.sh
└── commands/
    └── agent-os/
        ├── discover-standards.md
        ├── inject-standards.md
        ├── index-standards.md
        ├── shape-spec.md
        └── plan-product.md
```

--------------------------------

### Dry-Run Sync Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Performs a dry run of the synchronization to preview changes without modifying any files. Useful for testing.

```bash
./scripts/sync-to-profile.sh --dry-run
```

--------------------------------

### Example Prompt: Presenting Findings

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/discover-standards.md

An example of how the system presents API code patterns to the user for documentation. It lists discovered patterns and asks the user which ones they would like to document.

```text
I found these patterns in your API code:
1. **Response Envelope** — All responses use { success, data, error }
2. **Error Codes** — Custom codes like AUTH_001

Which would you like to document?
```

--------------------------------

### Agent OS Installation Script CLI

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

The `project-install.sh` script is used to bootstrap Agent OS into a project directory. It accepts various options to customize the installation process.

```bash
./scripts/project-install.sh [OPTIONS]
```

--------------------------------

### Example Prompt: Asking for Details on a Standard

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/discover-standards.md

Illustrates the process of asking the user for specific details needed to draft a standard. This example focuses on the 'Response Envelope' pattern, inquiring about its purpose and scope.

```text
For the Response Envelope pattern:
- What problem does this solve? Why not return raw data?
- Are there any endpoints that don't use this pattern?
```

--------------------------------

### Verbose Output Sync Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Runs the sync script with verbose output enabled, providing detailed information about the synchronization process.

```bash
./scripts/sync-to-profile.sh --verbose
```

--------------------------------

### Example Invocations for Inject Standards

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/commands.md

Provides examples of how to invoke the /inject-standards command for different use cases, including auto-suggestion and explicit file injection.

```bash
/inject-standards
# Analyzes context, suggests relevant standards, presents via AskUserQuestion

/inject-standards api
# Injects all standards in api/ folder

/inject-standards api/response-format
# Injects single api/response-format.md standard
```

--------------------------------

### Custom Source Directory Sync Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Executes the sync script using a custom directory for source standards instead of the default.

```bash
./scripts/sync-to-profile.sh --source custom-standards/
```

--------------------------------

### Example Structure for New Command Documentation

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

This markdown structure outlines the essential sections for documenting a new command, including its purpose, inputs, process, outputs, and an example.

```markdown
# New Command

Purpose and brief description.

## Inputs

What the command needs from user or context.

## Process

Step-by-step workflow with decision points.

## Output

What files/artifacts are created.

## Example

How to invoke and expected flow.
```

--------------------------------

### User Input and Response Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/data-structures.md

Illustrates how commands interact with users using the AskUserQuestion tool, showing a question, options, and a user's response.

```text
Question: Which files to sync?
Options:
  - all-standards
  - api-only
  - select-specific

User responds: select-specific

Command processes response and proceeds to file selection.
```

--------------------------------

### Injection Flow Example (Auto-suggest)

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

Explains the auto-suggest mode of the /inject-standards command, which analyzes context and suggests relevant standards.

```bash
User runs: /inject-standards

Auto-suggest mode:
1. Analyze current context
2. Read index.yml
3. Match context against descriptions
4. Rank and present 2-5 suggestions
5. Get user selection
6. Read selected standard files
7. Format appropriately for scenario
8. Display to user
```

--------------------------------

### Agent OS Configuration with Profile Inheritance

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

An example configuration demonstrating multiple profiles and their inheritance chains, including a default profile and derived profiles.

```yaml
version: 3.0
default_profile: rails

profiles:
  rails:
    inherits_from: default
  rails-api:
    inherits_from: rails
  nextjs:
    inherits_from: default
  full-stack:
    inherits_from: default
```

--------------------------------

### Specific Command Examples in Claude Code

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/workflow-and-integration.md

These are examples of specific Agent OS commands that can be invoked in Claude Code.

```bash
/discover-standards
```

```bash
/shape-spec
```

```bash
/inject-standards api
```

```bash
/index-standards
```

```bash
/plan-product
```

--------------------------------

### Multi-Select Prompt Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/data-structures.md

Demonstrates a multi-select prompt where users can choose multiple options, indicated by checkboxes.

```text
Which areas to discover standards in?
  - [✓] API routes
  - [  ] Database
  - [✓] React components
```

--------------------------------

### Define Product Context with /plan-product

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/workflow-and-integration.md

Use the `/plan-product` command to define your product's mission, roadmap, and tech stack. This command guides you through specifying the problem, target users, solution, features, and technology choices.

```bash
/plan-product
```

--------------------------------

### Spec Creation Flow Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

Outlines the process when a user runs the /shape-spec command in plan mode to create specification documentation.

```bash
User runs: /shape-spec (in plan mode)

1. Clarify feature scope
2. Gather visuals
3. Identify reference implementations
4. Check product context
5. Match and select relevant standards
6. Generate spec folder name (YYYY-MM-DD-HHMM-{slug})
7. Create spec folder structure
8. Create plan.md (from plan mode)
9. Create shape.md (shaping decisions)
10. Create standards.md (relevant standards)
11. Create references.md (code references)
```

--------------------------------

### Standard File Format Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/commands.md

This markdown format outlines the structure for standard files generated by the discover-standards command. It includes a title, description, code examples, and bullet-pointed rules or exceptions.

```markdown
# {Standard Title}

{Brief description of what to do}

{Code example(s)}

- Bullet point rule
- Another rule
- Exception or caveat

```

--------------------------------

### Confirmation Prompt Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/data-structures.md

A common pattern for user confirmation, offering options to proceed, edit, or skip.

```text
Create this file? 
  - Yes
  - Edit [describe changes]
  - Skip
```

--------------------------------

### Example User Input: Error Codes Details

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/discover-standards.md

Example user response providing details about the error codes pattern, including the naming convention (AREA_NUMBER) and documentation location (wiki).

```text
Format is AREA_NUMBER like AUTH_001. We keep a list in the wiki.
```

--------------------------------

### List Standards Files

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/index-standards.md

This example shows the expected output format when listing all .md files in the agent-os/standards/ directory and its subfolders, organized by folder.

```text
root/coding-style.md        # Files in standards/ root use "root" as the folder name
root/naming.md
api/response-format.md
api/error-handling.md
database/migrations.md
```

--------------------------------

### Claude Skill Scenario - References

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/api-discovery-and-matching.md

Example output for the 'Creating a Skill' scenario when choosing to include standard references, which allows for auto-updates.

```text
Detected scenario: Creating a Skill

How should standards be included?
1. References (points to @agent-os/standards/...
2. Copy content (embeds full standards)
```

```text
Include these standard references in your skill:

@agent-os/standards/api/response-format.md
@agent-os/standards/api/error-handling.md
```

--------------------------------

### Project Installation Structure

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/workflow-and-integration.md

Details the file system organization for a project that includes Agent OS components, such as standards, specifications, and product documentation.

```text
my-project/
├── agent-os/                   # Agent OS for this project
│   ├── standards/              # Project standards
│   │   ├── index.yml           # Standards index
│   │   ├── api/
│   │   │   ├── response-format.md
│   │   │   └── error-handling.md
│   │   ├── database/
│   │   │   └── migrations.md
│   │   └── ...
│   ├── specs/                  # Feature specifications
│   │   ├── 2026-01-15-1430-user-auth/
│   │   │   ├── plan.md
│   │   │   ├── shape.md
│   │   │   ├── standards.md
│   │   │   ├── references.md
│   │   │   └── visuals/
│   │   └── ...
│   ├── product/                # Product documentation
│   │   ├── mission.md
│   │   ├── roadmap.md
│   │   └── tech-stack.md
│   └── commands/               # Command definitions
│       └── agent-os/
│           ├── discover-standards.md
│           ├── inject-standards.md
│           ├── index-standards.md
│           ├── shape-spec.md
│           └── plan-product.md
├── src/                        # Project source code
├── package.json
└── ...
```

--------------------------------

### Plan a Feature with Standards

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

This command initiates a planning mode for features. It guides you through shaping questions, selecting relevant standards, creating a spec folder, and implementing with context.

```bash
# In plan mode:
/shape-spec
→ Answer shaping questions
→ Select relevant standards
→ Create spec folder
→ Implement with standards context
```

--------------------------------

### Example Standards Index YAML Structure

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/index-standards.md

This YAML structure demonstrates the expected format for the index.yml file, including alphabetized folders and files with one-line descriptions.

```yaml
root:
  coding-style:
    description: General coding style, formatting, linting rules
  naming:
    description: File naming, variable naming, class naming conventions

api:
  error-handling:
    description: Error codes, exception handling, error response format
  response-format:
    description: API response envelope structure, status codes, pagination

database:
  migrations:
    description: Migration file structure, naming conventions, rollback patterns
```

--------------------------------

### Agent OS Configuration for Multiple Teams

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

Shows a configuration setup for multiple teams, each inheriting from a common company-wide default profile.

```yaml
version: 3.0
default_profile: company-default

profiles:
  company-default:
    # No parent
  frontend-team:
    inherits_from: company-default
  backend-team:
    inherits_from: company-default
  mobile-team:
    inherits_from: company-default
  ml-team:
    inherits_from: company-default
```

--------------------------------

### Index Schema Root Folder YAML Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/data-structures.md

Illustrates the YAML structure for the 'root' folder in the index, representing standards files at the top level.

```yaml
root:
  coding-style:
    description: Code formatting and linting
  naming:
    description: Naming conventions
```

--------------------------------

### Injection Flow Example (Explicit)

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/architecture-and-design.md

Details the explicit mode of the /inject-standards command, where users directly specify standards to be delivered.

```bash
User runs: /inject-standards

Explicit mode:
1. Parse arguments (folder/file specifications)
2. Validate files exist
3. Read specified standard files
4. Format appropriately for scenario
5. Display to user
```

--------------------------------

### Inject Standards - Explicit Mode Examples

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/inject-standards.md

In explicit mode, provide specific standards or directories to inject directly. Use this for precise control over which standards are included.

```bash
/inject-standards api                           # All standards in api/

```

```bash
/inject-standards api/response-format           # Single file

```

```bash
/inject-standards api/response-format api/auth  # Multiple files

```

```bash
/inject-standards root                          # All standards in the root folder

```

```bash
/inject-standards root/naming                   # Single file from root folder

```

--------------------------------

### Updating Index File with New Standard

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/discover-standards.md

Example of updating the index file (index.yml) with a newly created standard, including its file path and a suggested description.

```yaml
api:
  response-format:
    description: API response envelope structure and error format
```

--------------------------------

### File Entry Example in Index

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

Illustrates how a file entry within the index maps to a specific standard file. The key corresponds to the file name without the extension, and the description provides a brief summary.

```yaml
api:
  response-format:  # Corresponds to agent-os/standards/api/response-format.md
    description: API response envelope structure

```

--------------------------------

### Example Index Update Report

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/index-standards.md

This report summarizes the changes made to the index.yml file, including the number of new, removed, and unchanged entries.

```text
Index updated:
  ✓ 2 new entries added
  ✓ 1 stale entry removed
  ✓ 8 entries unchanged

Total: 9 standards indexed
```

--------------------------------

### Profile Inheritance Configuration

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

Example of how to configure profile inheritance in Agent OS. This allows a profile to inherit settings from a base profile.

```yaml
profiles:
  rails:
    inherits_from: default
```

--------------------------------

### Keyword Extraction Example

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/api-discovery-and-matching.md

Demonstrates the process of extracting keywords from a sample conversation and matching them against predefined standards. This helps in identifying relevant API and backend development concepts.

```text
Example conversation:
"I need to build an API endpoint in Node.js that validates 
input and returns a consistent response format."

Extracted keywords:
- API
- Node.js
- validation
- response format

Matched standards:
- api/response-format ✓ (API + response format)
- backend/validation ✓ (validation)
- global/naming (maybe helpful)
```

--------------------------------

### Example Invocation of index-standards

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/commands.md

This command automatically scans for standards files, identifies changes, and updates the index. It is typically run as the final step of the /discover-standards command.

```bash
/index-standards

```

--------------------------------

### Example Prompt: Asking for Details on Error Codes

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/discover-standards.md

Follow-up prompt to gather information for the 'Error Codes' standard. It asks about the naming convention and documentation location for error codes.

```text
For the Error Codes pattern:
- What's the naming convention for codes?
- Where should new error codes be documented?
```

--------------------------------

### Standard Markdown File Format

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

Illustrates the recommended markdown format for defining standards in Agent OS. This format includes a title, description, code example, rules, and exceptions.

```markdown
# Standard Title

Brief description of what to do.

## Code Example

```language
// Show how to apply the standard
```

## Rules

- Lead with the rule
- Use bullet points for scanability
- Keep it concise

## Exceptions

- Note any exceptions or edge cases
```

--------------------------------

### Example Invocation of shape-spec

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/commands.md

This is how to invoke the shape-spec command. It must be run while in plan mode and guides the user through the shaping workflow before implementation tasks begin.

```bash
/shape-spec
```

--------------------------------

### Share Standards Across Projects

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

Use these scripts to synchronize project standards to a shared profile and then install that profile into new projects. This ensures consistency across your development environment.

```bash
./scripts/sync-to-profile.sh          # Sync project to profile
./scripts/project-install.sh           # Install profile in new project
```

--------------------------------

### Get Profile Inheritance Chain

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Use get_profile_inheritance_chain to construct the full inheritance chain for a profile, starting from the base. It detects circular dependencies and missing profile directories, returning specific error prefixes.

```bash
chain=$(get_profile_inheritance_chain "config.yml" "rails" "profiles/")
if [[ "$chain" == CIRCULAR:* ]]; then
    echo "Circular dependency detected: $chain"
    exit 1
fi
```

--------------------------------

### Prompt for Existing Product Docs Check

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/plan-product.md

Use this prompt when checking for existing product documentation files. It lists potential files and asks the user how to proceed.

```text
I found existing product documentation:
- mission.md: [exists/missing]
- roadmap.md: [exists/missing]
- tech-stack.md: [exists/missing]

Would you like to:
1. Start fresh (replace all)
2. Update specific files
3. Cancel

(Choose 1, 2, or 3)
```

--------------------------------

### Deleted Standard Files Report

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/api-discovery-and-matching.md

Example of the report generated when stale index entries for deleted files are automatically removed.

```text
Removed stale entries:
  - api/deprecated-pattern
  - backend/old-logging
```

--------------------------------

### Create a Standard Workflow

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

This sequence outlines the steps to create a new standard using the discover-standards command. It involves selection, answering questions, and approval.

```bash
/discover-standards
→ Select area
→ Select pattern to document
→ Answer questions
→ Approve file
```

--------------------------------

### Handle Missing Standards Index

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/inject-standards.md

This message is displayed if the `agent-os/standards/index.yml` file is not found or is empty, guiding the user to create or index standards.

```text
No standards index found. Run /discover-standards first to create standards,
or /index-standards if you have standards files without an index.

```

--------------------------------

### Report Removed Stale Index Entries

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/index-standards.md

This is an example report message indicating that stale index entries for non-existent files have been automatically removed.

```text
Removed 2 stale index entries: api/old-pattern.md, testing/deprecated.md
```

--------------------------------

### Plan a Feature with Standards

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

Enter plan mode using this command to associate standards with a feature specification. This helps in clarifying the scope and context before implementation.

```bash
# In plan mode:
/shape-spec
```

--------------------------------

### Troubleshoot Agent OS Suggestions

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

Use these commands for troubleshooting. Rebuild the index to ensure it's up-to-date, or use explicit mode with `/inject-standards api` for more direct control.

```bash
/index-standards        # Rebuild index
/inject-standards api   # Use explicit mode
```

--------------------------------

### Share Standards Between Projects (Source)

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

From the source project, use the sync-to-profile.sh script to select and sync standards to a profile. This makes them available for sharing.

```bash
# In source project:
./scripts/sync-to-profile.sh
→ Select profile
→ Select standards to sync
→ Sync to profile
```

--------------------------------

### Inject a Standard into Project

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

Use the inject-standards command to bring a specific standard into your project. The standard will be displayed in context for reference during implementation.

```bash
/inject-standards {api/response-format}
→ Standard displayed in context
→ Reference during implementation
```

--------------------------------

### Inject Standards into Context with /inject-standards

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/workflow-and-integration.md

Use the `/inject-standards` command to make relevant project standards available in your current context, whether in a conversation, plan, or Claude Skill. This ensures AI agents adhere to established patterns.

```bash
# Usage in conversation:
I'm implementing the API error handling. Let me inject the relevant standards:

/inject-standards api
```

```bash
# Usage building a Claude Skill:
/inject-standards api/error-handling
```

--------------------------------

### Claude Skill Scenario - Copy Content

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/api-discovery-and-matching.md

Example output for the 'Creating a Skill' scenario when choosing to copy full standard content, resulting in self-contained skills.

```text
Include this standards content in your skill:

--- Standard: api/response-format ---

[Full content]
```

--------------------------------

### Get Profile Inherits From

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/installation-and-scripts.md

Use get_profile_inherits_from to retrieve the 'inherits_from' value for a specific profile in a YAML configuration file. It returns an empty string if no inheritance is defined.

```bash
parent=$(get_profile_inherits_from "config.yml" "child")
```

--------------------------------

### Skill Creation Output Format (References) for Inject Standards

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/commands.md

When creating a skill, this format is used to reference standards by their file paths, ensuring they stay in sync with the source.

```text
Be sure to include references to the following standards files:

@agent-os/standards/api/response-format.md
@agent-os/standards/api/error-handling.md
@agent-os/standards/global/naming.md
```

--------------------------------

### Presenting Codebase Areas to User

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/discover-standards.md

Use the AskUserQuestion tool to present identified codebase areas to the user for focus. This is part of Step 1 when no specific area is initially provided.

```text
I've identified these areas in your codebase:

1. **API Routes** (src/api/) — Request handling, response formats
2. **Database** (src/models/, src/db/) — Models, queries, migrations
3. **React Components** (src/components/) — UI patterns, props, state
4. **Authentication** (src/auth/) — Login, sessions, permissions

Which area should we focus on for discovering standards? (Pick one, or suggest a different area)
```

--------------------------------

### Shape Spec in Plan Mode

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/workflow-and-integration.md

Execute /shape-spec in plan mode to initiate a guided process for shaping specifications, creating a spec folder, and saving initial documentation.

```bash
Entering plan mode in Claude Code...

/shape-spec

# Command detects plan mode
# Guides through shaping process
# Creates spec folder
# Task 1 saves shaping documentation
```

--------------------------------

### Inject Standards - Auto-Suggest Mode

Source: https://github.com/buildermethods/agent-os/blob/main/commands/agent-os/inject-standards.md

Use this command without arguments to analyze the current context and receive suggestions for relevant standards.

```bash
/inject-standards
```

--------------------------------

### Example Standard: API Response Envelope

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/data-structures.md

Illustrates a standard for API response envelopes, ensuring consistent client handling by defining a predictable structure for both successful and error responses.

```json
{ "success": true, "data": { /* actual data */ } }
{ "success": false, "error": { "code": "ERROR_CODE", "message": "Human message" } }
```

```markdown
# API Response Envelope

All API responses use a consistent envelope structure for predictable client handling.

## Pattern

Every response wraps data or errors in this envelope:

```json
{ "success": true, "data": { /* actual data */ } }
{ "success": false, "error": { "code": "ERROR_CODE", "message": "Human message" } }
```

## Rules

- Always include `success` boolean as first field
- On success: include `data` field, omit `error`
- On error: include `error` object with `code` and `message`, omit `data`
- Status codes (200, 404, 500) are set in HTTP headers, not the envelope

## Exception

Streaming endpoints (WebSocket, Server-Sent Events) may use different formats.

```

--------------------------------

### Agent OS Plan File Template

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

Template for a full implementation plan, typically generated from plan mode. Use this to detail project implementation steps.

```markdown
# plan.md
Full implementation plan (from plan mode).
```

--------------------------------

### Fix: Profile Not Found

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/quick-reference.md

Troubleshoot 'Profile not found' errors by verifying the profiles directory and configuration.

```bash
Error: Profile 'rails' not found

Fix: Check profiles/ directory exists
Fix: Check config.yml default_profile is correct
Fix: Use --profile {name} with valid profile
```

--------------------------------

### Agent OS config.yml File Format

Source: https://github.com/buildermethods/agent-os/blob/main/_autodocs/configuration.md

Defines the basic structure of the Agent OS configuration file, including version and default profile settings, with an example of profile inheritance.

```yaml
version: 3.0
default_profile: default

# Optional: define inheritance relationships for profiles
profiles:
  profile-a:
    inherits_from: default
  profile-b:
    inherits_from: profile-a
```