The .obvious Directory

The .obvious directory is where you customize Autobuild agent behavior for your repository. Place it at the root of your repo, and agents read it automatically to understand your workflow policy, code review standards, domain knowledge, and operational procedures.

.obvious complements AGENTS.md. Keep code-local working guidance in AGENTS.md, and keep Autobuild operating guidance in .obvious. All components are optional; add only what your repository needs.

Directory structure

.obvious/
├── obvious.md             # Short Autobuild orientation
├── config.yml             # Repository workflow policy
├── skills/                # Checked-in skills for this repo
│   ├── db-migrations/
│   │   ├── SKILL.md
│   │   └── SKILL_CORE.md  # optional
│   └── login/
│       └── SKILL.md
├── review/                # Code review customization
│   ├── overlay.md
│   ├── scoring-model.md
│   ├── category-overlays.md
│   └── comment-examples.md
└── runbooks/              # Operational procedures for recurring work

config.yml: repository workflow policy

config.yml is the per-repository policy contract. It tells agents how your repository works: default branch, merge method (squash, merge, or rebase), CI behavior, preview environment URLs, and QA process paths. Agents read these values instead of guessing. Most teams start with one or two rules.

skills/: checked-in agent knowledge

The skills/ directory teaches agents repository-specific knowledge they don't have by default. Each skill is a subdirectory containing a SKILL.md file with instructions. Common examples include database migration procedures, login credentials for staging environments, and deployment checklists. Agents discover skills on your repository's default branch and load them on demand when a task matches.

review/: code review customization

The review/ directory customizes how agents review pull requests in your repository. Without it, agents apply a generic review rubric. With it, you can tell the reviewer which rules your linter already handles, flag high-scrutiny paths like authentication middleware or payment processing, and provide examples of the review comment quality you want.

runbooks/: operational procedures

The runbooks/ directory holds plain markdown runbooks for operational tasks: deployment verification, staging checks, and incident response procedures. Agents consult relevant runbooks when the task calls for them. No special format is required; standard markdown files work.

Getting started

The minimum setup is a single file. Create the .obvious directory at your repo root and add obvious.md, a short orientation covering what the repository does, who uses it, and the highest-priority constraints for automated work. Then add the one or two workflow rules in config.yml that would otherwise require manual correction on every pull request:

branches:
  defaultBase: main

pr:
  merge:
    method: squash

Agents pick up the configuration within 15 minutes of it landing on your default branch. From there, add components as you need them: skills when agents need domain knowledge, and review/ when you want to tune code review quality.