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

```bash
# 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: Regenerate Derived Files

If AGENTS.md changed significantly, regenerate the derived agent files
(`.github/copilot-instructions.md`, `.aider.conf.yml`, `.editorconfig`) via:

```bash
cd ../learning_ai_common_plat
bash scripts/update-agent-docs.sh
```

The canonical-behavior-pointer block at the top of AGENTS.md is auto-managed —
do not edit it by hand. Legacy files (`CLAUDE.md`, `.cursorrules`,
`.windsurfrules`, `.clinerules`) are deprecated and should not exist.

### Step 5: Commit Per Repo

```bash
cd <repo>
git add AGENTS.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

```markdown
## 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