Standards: Your Code, Your Way

Standards are markdown files containing your coding conventions, patterns, and best practices. They ensure AI agents write code that looks like you wrote it.

Standards define how code should be written in your projects—variable naming, error handling, API design, component architecture. Not generic guidelines, but your specific rules.

This page covers:

• Where standards live
• Creating effective standards
• How standards are applied

Where standards live

Standards should be managed and stored in your Agent OS base installation. They are then compiled into your project installation based on which profile you're using in that project.

Your base installation's default profile comes with this folder structure for standards:

~/agent-os/profiles/default/standards/
├── backend/
├── frontend/
├── global/
└── testing/

You can store as many individual standards files inside of these folders, create additional subfolders as needed, or reorganize them as you see fit.

Note: For the easiest "out of the box" experience, it's best to keep your standards folder organized by those four sub-folders: backend, frontend, global, testing, since the injection points are already set up for these. But if you wish to customize this structure, read below for details on how to customize the standards injection points to match your structure.

Creating effective standards

Start small

1. Get started with Agent OS using minimal standards
2. Notice what you're frequently fixing
3. Add a standard for that pattern
4. Watch the corrections disappear

Keep standards modular

Use specific, focused files rather than monolithic documents:

Be specific and actionable

Good standards are clear and implementable:

Best practices

• Keep actionable: Focus on concrete patterns with clear examples
• Include examples: Always provide examples of how to follow the standard
• Keep modular: Use specific, focused files rather than monolithic documents
• Start minimal: Begin with very few standards, add as needed
• Document your why: Include brief explanations of patterns
• Avoid over-specification: Focus on patterns that matter to you and your team for consistency

How standards are applied

Note: This section explains how Agent OS works "under the hood." You don't necessarily need to customize how and where standards get injected. For the simplest use case, it's best to keep your standards folder organized by the four sub-folders: backend, frontend, global, and testing, since the injection points are already set up for these.

However, if you choose to reorganize or add additional subfolders and want to dial in exactly which standards are injected into which workflows and agents, read on to understand how that works and how you can customize things.

Agent OS intelligently injects relevant standards into agent instructions and workflows. For example:

• Database agents get database standards
• UI agents get frontend standards
• API agents get backend and API standards
• All agents get global standards

Injection syntax

You'll find instances of the following injection tags sprinkled throughout your profile's workflows and commands files. During your project installation process, Agent OS will compile your profile's agents and workflows and replace these injection tags with references that point to the specified standards files.

When you see something like this:

{{standards/global/*}}

That will be replaced with a list of references to all files and sub-folders inside the global folder, which ends up looking like this:

@agent-os/standards/global/naming.md
@agent-os/standards/global/code-style.md
@agent-os/standards/global/best-practices.md
@agent-os/standards/global/testing.md

If a tag points to the name of a specific file (not a folder), like this:

{{standards/backend/database}}

That will be replaced with a reference to the database.md file which ends up looking like this:

@agent-os/standards/backend/database.md

In many cases, multiple sets of standards will be injected to form a complete set of standards for an agent or workflow. For example:

{{standards/global/*}}
{{standards/frontend/components}}
{{standards/frontend/css}}

To find all injection points, search your profile folder for {{standards.

Standards injected into implementers and verifiers

Your profile defines a set of implementers and verifiers roles which are used during the implementation phase of the spec-driven development workflow.

These roles are defined in .yml files inside your profile's roles folder. The section of each role's definition that specifies which standards should be injected into the instructions for that role looks like this:

...
standards:
  - global/*
  - backend/database.md
  - backend/queries.md