# Agent Onboarding — Read Order

> Quick index for AI coding agents joining any ByteLyst repo.
> Read these documents in the order shown before making changes.

## 1. Universal behavior (ecosystem-wide, identical across every repo)

[`agent-behavior-guidelines.md`](agent-behavior-guidelines.md)

The canonical agent behavior contract — Karpathy's 4 rules (Think, Simplicity,
Surgical, Goal-Driven) plus 7 ByteLyst-specific rules (tests, verification,
shared infra, logging, Cosmos, commits, style).

## 2. Per-repo context

`<repo-root>/AGENTS.md`

Each repo has its own `AGENTS.md` with:

- Project identity (product name, ID, ports, domain)
- Repo layout
- Tech stack rules
- Coding conventions specific to that repo
- File ownership map
- Build & test commands

## 3. Per-repo product manifest

`<repo-root>/shared/product.json`

Canonical product identity (product ID, display name, bundle IDs, etc.).
Loaded at runtime via `@bytelyst/config` or read directly by build tooling.

## 4. Cross-repo automation playbook

[`../../docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md`](../../docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md)

Periodic maintenance tasks that span all repos (test audits, coverage,
dependency health, secret scans, typecheck sweeps).

## 5. Skill libraries (this directory)

Other files in [`AI.dev/SKILLS/`](.) are topic-specific playbooks
(architecture patterns, debugging, releases, testing, etc.). Read on demand,
not upfront.

---

## How agent files compose

```text
┌──────────────────────────────────────────────────────────────┐
│  Single source of truth (this directory)                     │
│                                                              │
│    agent-behavior-guidelines.md  ← THE behavior contract     │
│    agent-onboarding.md           ← this file                 │
└──────────────────────────────────────────────────────────────┘
                          ▲
                          │ referenced (never copied)
                          │
┌──────────────────────────────────────────────────────────────┐
│  Per-repo files (one per repo)                               │
│                                                              │
│    AGENTS.md                       ← repo-specific only      │
│    .github/copilot-instructions.md ← thin pointer            │
│    .aider.conf.yml                 ← Aider config            │
│    .editorconfig                   ← editor config           │
└──────────────────────────────────────────────────────────────┘
```

No behavior rule lives in two files. Drift is impossible by construction.

## Maintenance

- Generator: `learning_ai_common_plat/scripts/update-agent-docs.sh`
- Drift check: `learning_ai_common_plat/scripts/check-agent-docs-drift.sh`
- Workflow: `learning_ai_common_plat/.windsurf/workflows/repo_update-agent-docs.md`