saravanakumardb
32c7b1ba7e
- roadmap-execution: phased roadmap execution with checkpoints - new-product-scaffold: scaffold new ByteLyst product repos - prd-to-implementation: convert PRDs to concrete plans - cross-repo-debug: systematic multi-repo debugging - backend-module-crud: Fastify CRUD modules (types/repo/routes/tests) - platform-integration: wire products into common platform - refactor-with-tests: test-first safe refactoring - test-gap-analysis: coverage gap identification and remediation - type-safety-sweep: TypeScript error triage and fix - dependency-health-check: cross-repo dependency audit - pre-release-validation: comprehensive release checklist - docker-production-prep: production Docker images - agents-md-sync: keep AI instruction files accurate - ecosystem-audit: full ecosystem health dashboard
120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
---
|
|
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: Update CLAUDE.md
|
|
|
|
If AGENTS.md changed significantly, also sync CLAUDE.md (the Claude Code-specific instruction file).
|
|
|
|
### Step 5: Commit Per Repo
|
|
|
|
```bash
|
|
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
|
|
|
|
```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
|