learning_ai_common_plat/.windsurf/workflows/repo_update-agent-docs.md

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:

   # 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:

   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 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:

   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):

   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.