saravanakumardb1 c04ee5f054 feat(agent-docs): single-source-of-truth pattern for agent instructions

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

2026-05-23 11:55:19 -07:00

3.3 KiB

Raw Blame History

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

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

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

┌──────────────────────────────────────────────────────────────┐
│  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

3.3 KiB Raw Blame History