c04ee5f054
Establish a single canonical source for ecosystem-wide AI agent behavior
rules, eliminating duplication across the 8 agent-config files that each
repo used to maintain.
New canonical sources (this repo only):
- AI.dev/SKILLS/agent-behavior-guidelines.md (Karpathy + ByteLyst rules)
- AI.dev/SKILLS/agent-onboarding.md (read-order index)
Generator rewrite (scripts/update-agent-docs.sh):
- Deletes legacy files that duplicated AGENTS.md:
.cursorrules, .windsurfrules, .clinerules, CLAUDE.md
- Regenerates .github/copilot-instructions.md as a thin pointer (no rules).
- Regenerates .aider.conf.yml and .editorconfig.
- Idempotently prepends a canonical-behavior-pointer block to AGENTS.md.
- Supports --dry-run and --no-commit flags.
Drift check (scripts/check-agent-docs-drift.sh):
- Fast marker-based check across all repos.
- Verifies legacy files absent, AGENTS.md pointer present, copilot/aider/
editorconfig markers intact.
Workflow doc updated: .windsurf/workflows/repo_update-agent-docs.md
Repos.txt: added learning_ai_talk2obsidian (was missing from canonical list).
This repo's own agent files are migrated by the same generator:
- Removed: .cursorrules, .windsurfrules, .clinerules, CLAUDE.md
- Updated: AGENTS.md (pointer block prepended)
- Updated: .github/copilot-instructions.md (rewritten as pointer)
- Updated: .aider.conf.yml (canonical format)
Karpathy attribution: behavior rules adapted from
https://github.com/multica-ai/andrej-karpathy-skills
78 lines
3.3 KiB
Markdown
78 lines
3.3 KiB
Markdown
# 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`
|