---
description: Regenerate AI agent docs across all repos (single source of truth pattern)
---

# Update Agent Docs Across Workspace

Maintains AI agent docs across the ByteLyst workspace using a
**single source of truth** pattern with **zero duplication**.

## Architecture

```
learning_ai_common_plat/AI.dev/SKILLS/
├── agent-behavior-guidelines.md   ← SINGLE source of truth for behavior rules
└── agent-onboarding.md            ← Read-order index for agents

<each repo>/
├── AGENTS.md                       ← Repo-specific only. Auto-prepended with
│                                     "Read first" pointer to canonical file.
├── .github/copilot-instructions.md ← Thin pointer (no rules). Auto-generated.
├── .aider.conf.yml                 ← Aider config pointing to AGENTS.md. Auto-generated.
└── .editorconfig                   ← Editor config. Auto-generated.

DELETED across all repos (content was duplicated AGENTS.md):
├── CLAUDE.md
├── .cursorrules
├── .windsurfrules
└── .clinerules
```

## Steps

1. **Edit the canonical sources** when behavior rules change:

   ```bash
   # ecosystem-wide agent behavior (Karpathy + ByteLyst)
   open learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md

   # read-order index
   open learning_ai_common_plat/AI.dev/SKILLS/agent-onboarding.md
   ```

   These are referenced (not copied) by every repo's AGENTS.md, so changes
   take effect immediately — no regeneration needed when only behavior rules change.

2. **Run the generator** to delete legacy files / refresh pointers / sync configs:

   ```bash
   cd /Users/sd9235/code/mygh/learning_ai_common_plat
   ./scripts/update-agent-docs.sh --dry-run    # preview
   ./scripts/update-agent-docs.sh              # apply + commit per repo
   ./scripts/update-agent-docs.sh --no-commit  # apply without committing
   ```

   Reads `learning_ai_common_plat/.windsurf/workflows/repos.txt` as the
   canonical list of managed repos.

3. **Verify no drift**:

   ```bash
   bash scripts/check-agent-docs-drift.sh
   ```

   Exits 1 if any repo has drifted from the canonical generator output.
   Suitable for CI.

4. **Review changes per repo**:

   ```bash
   while IFS= read -r repo; do
     [[ -z "$repo" || "$repo" =~ ^# ]] && continue
     echo "── $repo ──"
     git -C /Users/sd9235/code/mygh/"$repo" log -1 --oneline
   done < /Users/sd9235/code/mygh/learning_ai_common_plat/.windsurf/workflows/repos.txt
   ```

5. **Push (when ready)**:

   ```bash
   while IFS= read -r repo; do
     [[ -z "$repo" || "$repo" =~ ^# ]] && continue
     git -C /Users/sd9235/code/mygh/"$repo" push
   done < /Users/sd9235/code/mygh/learning_ai_common_plat/.windsurf/workflows/repos.txt
   ```

## Files generated per repo

| File                              | Type    | Tool(s)                                |
| --------------------------------- | ------- | -------------------------------------- |
| `AGENTS.md`                       | Hybrid  | Codex, Claude, Cursor, Windsurf, Cline |
| `.github/copilot-instructions.md` | Pointer | GitHub Copilot                         |
| `.aider.conf.yml`                 | Config  | Aider                                  |
| `.editorconfig`                   | Config  | All editors                            |

`AGENTS.md` is hybrid: the body is hand-maintained (repo-specific content),
but the generator idempotently prepends a `<!-- BEGIN: canonical-behavior-pointer -->`
block at the top. The block is the only auto-managed region; everything else
is left alone.

## Files deleted by the generator

| File             | Reason                                                        |
| ---------------- | ------------------------------------------------------------- |
| `CLAUDE.md`      | Duplicated AGENTS.md. Claude Code reads AGENTS.md by default. |
| `.cursorrules`   | Duplicated AGENTS.md. Cursor reads AGENTS.md.                 |
| `.windsurfrules` | Duplicated AGENTS.md. Windsurf reads AGENTS.md.               |
| `.clinerules`    | Duplicated AGENTS.md. Cline reads AGENTS.md.                  |

## Notes

- Safe to run repeatedly (idempotent).
- Only commits when actual changes exist in the repo.
- The script never touches the body of AGENTS.md outside the marker block.
- For workspaces that include `learning_ai_common_plat` as a sibling
  (default for Windsurf/Cascade), the canonical guidelines file resolves
  via the relative path written into each AGENTS.md pointer.