Using Augment Cosmos

Augment Cosmos is the AI assistant used on this repo. For what the product can do and how its features work, read the official documentation:

• docs.augmentcode.com — product documentation
• Cosmos — experts, environments, sessions, automations

This page covers only how we use it here. Everything below is a repo convention, not a product feature.

Where to look first

This documentation site is the source of truth for how AI-assisted work is done on this repo. Start at AI Experts:

• Personas (docs/ai-experts/*.md) — domain guidance you reference by name
• Deployed experts (docs/ai-experts/*.yaml) — live in the Cosmos launcher for everyone

If a page here is wrong or out of date, fix it in the same PR as the work that revealed it. Agents are instructed to consult this site first and to propose an update when they find it stale.

Repository rules

Rules in .augment/rules/ load automatically when this repository is part of the session environment. They apply to local daemon and cloud sessions using the repository. User, Space, or organization VFS rules are the portable alternative when a rule must apply without the repository.

The current rules cover documentation-first consultation, issue and pull-request workflow, and secret handling. They are version-controlled with the repository and reviewed like code.

Repository conventions

Branch first. Ask for a branch as part of the request, following Conventions → Branches:

"Create a new feature branch and add a Polars-based ETL pipeline for MX fuels data"

development/main is the universal base branch. orchestration-development and development/mx-fuels-reporting-app are deprecated for new work.

Reference a persona for domain work. “Following the Environment & Security Engineer guidelines, add this new secret.” Personas carry constraints and real file paths that generic prompting won’t.

Review before committing. Run git diff, test locally, and check for accidentally-exposed secrets. Nothing is auto-committed.

Ask for tests explicitly along with new code.

Persistent task tracking

Session-scoped task lists disappear with the session. For work that spans days, use the Personal Assistant — it keeps your task list and memory outside any single session and reads them back at session start.

This matters here: a review of 30 days of our sessions found roughly a fifth existed only to reconstruct context from an earlier session. Tracking the work is cheaper than reconstructing it.

Changing a deployed expert

Edit the bundle in docs/ai-experts/ and open a PR. The Sync AI experts workflow validates and dry-runs it on the PR, then applies on merge to main.

Do not hand-edit an expert in the Cosmos web UI. The next apply overwrites it, and the change leaves no trace in review.