learning_ai_common_plat/AI.dev/PROMPTS/agents-md-sync.md

name	description	argument-hint	agent
agents-md-sync	Audit and update AGENTS.md files across all ByteLyst repos to match current codebase reality — layout, test counts, API endpoints, packages.	Scope, e.g. "all repos", "learning_ai_efforise only", "test counts only"	agent

AGENTS.md Sync Prompt

Ensure all AGENTS.md files across the ByteLyst ecosystem accurately reflect the current state of each repository.

Context — What AGENTS.md Does

AGENTS.md is the primary instruction file for AI coding assistants (Claude Code, Copilot, Cursor, Windsurf, Gemini). It must be accurate because:

• AI agents read it before making changes
• Incorrect docs lead to incorrect code
• Stale test counts erode agent trust
• Wrong layout trees cause file-not-found errors

Standard AGENTS.md Sections

Every ByteLyst repo should have these sections:

1. Project Identity — product name, ID, bundle IDs, ports, ecosystem
2. Repo Layout — file tree (keep up to date!)
3. Tech Stack — frameworks, languages, tools per layer
4. Coding Conventions — MUST follow / MUST NOT do
5. .npmrc rules — never edit directly
6. Cosmos Containers (if backend) — container, partition key, purpose
7. Build & Test Commands — exact pnpm commands
8. API Endpoints (if backend) — method, path, description
9. Environment Variables — var, default, description
10. Current State (optional) — phases, commits, test counts
11. Cross-Repo Automation — link to CODING_AGENT_AUTOMATION_PLAYBOOK.md

Sync Protocol

Step 1: Scan Each Repo

For each repo, programmatically verify:

# File tree matches layout section
find . -type f -name "*.ts" -o -name "*.tsx" -o -name "*.swift" -o -name "*.kt" | head -50

# Test count matches
pnpm test --reporter=verbose 2>&1 | tail -5

# API endpoints match (backend)
grep -r "app\.\(get\|post\|patch\|put\|delete\)" backend/src/modules/*/routes.ts

# Package count matches
ls node_modules/@bytelyst/ 2>/dev/null | wc -l

# Cosmos containers match
grep -r "getCollection\|getContainer" backend/src/modules/*/repository.ts

Step 2: Identify Drift

Compare AGENTS.md content against reality:

Section	Check	Drift Signal
Repo Layout	find vs documented tree	New dirs/files not listed
Tech Stack	package.json deps	New framework not mentioned
Test Counts	pnpm test output	Count differs by >5
API Endpoints	route file scan	Missing endpoints
Cosmos Containers	repository scan	New containers
Packages Used	node_modules scan	New @bytelyst/* packages
Ports	shared/product.json	Port mismatch

Step 3: Update AGENTS.md

For each drift found:

• Update the specific section
• Preserve all existing comments and documentation
• Keep formatting consistent with other repos

Step 4: Update CLAUDE.md

If AGENTS.md changed significantly, also sync CLAUDE.md (the Claude Code-specific instruction file).

Step 5: Commit Per Repo

cd <repo>
git add AGENTS.md CLAUDE.md
git commit -m "docs(agents): sync AGENTS.md with current repo state

- Updated: <sections that changed>
- Test count: X → Y
- <other changes>"
git push

Report Format

## AGENTS.md Sync Report

| Repo | Status | Sections Updated | Commit |
|------|--------|-----------------|--------|
| learning_ai_common_plat | ✅ Up to date | — | — |
| learning_ai_efforise | 🔄 Updated | Layout, Tests | abc123 |
| learning_ai_flowmonk | 🔄 Updated | API Endpoints | def456 |
| learning_ai_dev_intelli | ❌ Skipped | — | Needs manual review |

### Key Findings
- <finding 1>
- <finding 2>

Guardrails

• Never delete documentation — only add or update
• Preserve comments — keep existing notes and explanations
• Verify before commit — run pnpm typecheck to ensure no doc references break
• One repo per commit — keep history clean