AI Experts

This documentation site is the first place to look for how AI-assisted work is done on this repo, and the first place to update when it changes.

Two different things live under docs/ai-experts/:

Kind	Files	How it’s used
Personas	docs/ai-experts/*.md	Guidance profiles you reference by name when prompting. Nothing is deployed.
Deployed experts	docs/ai-experts/*.yaml	Cosmos expert bundles, applied by the Sync AI experts workflow. They appear in the Cosmos launcher for everyone.

The persona files hold the full prompts; the pages here summarize each one’s scope and link back to the source.

For day-to-day Cosmos workflow, see Onboarding → Using Augment Cosmos.

The 9 personas

#	Persona	Domain
1	Monorepo & Workspace Architect	UV workspaces, dependency management, scaffolding
2	Orchestration Specialist	Airflow DAGs, Service Bus triggers, wheel bundling
3	Environment & Security Engineer	Secrets, Dynaconf, Azure Key Vault, vault segregation
4	Workflow & Release Coordinator	Branching, versioning, PR/release workflow
5	UX/UI & Web Interface Specialist	The Next.js dashboard, WorkOS auth, Key Vault loaders
6	Data Science & Analytics Specialist	Prophet forecasting, Plotly/Altair visualization
7	Data Engineering & Architecture Specialist	ETL pipelines, SQLModel schemas, Polars/PySpark
8	Cloud Infrastructure & DevOps Specialist	Azure resources, Docker, Astronomer deployment
9	Issue Management Expert	Triaging findings into GitHub issues, base-branch routing, PR batching

Using a persona

Reference it by name or file when prompting: “Following the Environment & Security Engineer guidelines, add this new secret.” Each persona doc lists its architectural constraints, operational guidelines, and a file-path reference table grounding it in real repo paths.

For complex work, combine personas — adding a DAG that reads a new secret is Orchestration Specialist plus Security Engineer.

docs/ai-experts/system-prompts.md holds ready-to-paste system prompt text for each persona, for configuring an agent outside a normal Cosmos session.

Deployed Cosmos experts

These are live in the Cosmos workspace, defined by YAML bundles in docs/ai-experts/.

Expert	What it does	Bundle
Personal Assistant	Persistent per-user task tracking and memory across sessions; dispatches other experts as workers	docs/ai-experts/personal-assistant.yaml
Issue Management Expert	Turns findings into reviewed GitHub issues and guides them to linked pull requests	docs/ai-experts/issue-management-expert.yaml

Changes go through a PR: the workflow validates and dry-runs the bundle on the PR, then applies it 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.

Cross-cutting rules

Repository-wide rules load from .augment/rules/ when the repository is included in a session environment. The current always-loaded rules cover:

• documentation-first consultation and documentation quality checks
• issue, branch, release, and pull-request workflow
• secret handling and authentication boundaries

Local daemon sessions read these files from the current checkout. Cloud sessions read them when this repository is included in the selected environment. Keep rules that must apply without this repository in user, Space, or organization VFS instead.

Cross-cutting concerns

Dependency management

• Root workspace — UV workspace members (packages/*, projects/*)
• Orchestration — separate workspace, with utils bundled as a pre-built wheel
• Apps — standalone, with direct dependencies

Package versions live in each package’s pyproject.toml. Read them there rather than trusting a number copied into a doc.

Secret management

All secrets flow through Azure Key Vault:

.envrc → export_settings.py → azure_settings hook → Azure CLI → Key Vault → OS keyring cache

Testing

• Unit tests: pytest in each package/project
• DAG validation: orchestration/tests/dags/
• Type checking: pyright (strict mode)
• Linting: ruff

Deployment targets

• Orchestration — Astronomer Cloud, via make build
• Apps — Azure App Services, via Docker Compose
• Local dev — Devbox + direnv

Keeping this current

Update a persona when architecture changes, a new pattern emerges, or an incident teaches something worth writing down.

1. Edit the persona file in docs/ai-experts/.
2. Update the matching page here if the summary or scope changed.
3. Commit as docs(ai-experts): update <expert> for <reason>.

Agents working in this repo are instructed to consult this site first and to propose an update when they find it wrong. Treat a stale page as a bug.