Discover Standards

What it does

The /discover-standards command walks you through extracting tribal knowledge from your codebase into documented standards.

It produces:

• Standards files — Markdown files in agent-os/standards/ organized by domain
• Index file — agent-os/standards/index.yml with descriptions. These help the agent identify and suggest standards to inject into the current context—without reading them in full (and taking up valuable context space).

The process

1. Determine focus area

If you don't specify an area, the command analyzes your codebase and presents 3-5 major areas:

• API routes, database, components, authentication, etc.

Or specify an area upfront: /discover-standards api

2. Analyze the area

The command reads 5-10 representative files looking for patterns that are:

• Unusual or unconventional — Not standard framework patterns
• Opinionated — Specific choices that could have gone differently
• Tribal — Things a new developer wouldn't know without being told
• Consistent — Repeated across multiple files

3. Deep dive

For each pattern worth documenting, you're asked 1-2 targeted questions to understand the "why" behind it.

4. Write the standards

The command drafts concise standards and asks you to confirm, edit, or skip each one.

5. Update the index

New standards are added to index.yml with descriptions for matching.

6. Continue or done

The command offers to discover standards in another area, or you can stop.

When to run it

• When setting up Agent OS on an existing project
• After a major refactor that introduced new patterns
• When onboarding new team members
• Periodically to capture patterns that have emerged organically

Writing good standards

Standards are injected into AI context windows. Keep them concise:

• Lead with the rule — State what to do first, explain why second
• Use code examples — Show, don't tell
• Skip the obvious — Don't document what the code already makes clear
• Bullet points over paragraphs — Scannable beats readable

Manual standards

You can create standards manually. After creating files, update the index:

• Run /index-standards to detect new files and prompt for descriptions
• Or edit index.yml directly

/index-standards

The /index-standards command rebuilds and maintains the index:

• Scans for all standards files
• Adds missing entries (prompts for descriptions)
• Removes entries for deleted files
• Alphabetizes and cleans up

Run it after manually creating or deleting standards, or if /inject-standards suggestions seem out of sync.

Note: /discover-standards runs index-standards automatically as its final step.