088a9cabd6
Followup audit of the single-source-of-truth agent-docs rollout. Several AI.dev prompts and skills still taught agents the old 8-file pattern (which would re-introduce drift) and the generator script emitted a misleading summary in --no-commit mode. AI.dev guides: - Delete AI.dev/SKILLS/update-agent-docs.md — entire doc taught the old 8-file pattern. Canonical reference is now .windsurf/workflows/repo_update-agent-docs.md. - AI.dev/SKILLS/index.md + README.md: replace dangling 'Update Agent Documentation' link with pointers to agent-behavior-guidelines.md, agent-onboarding.md, and the workflow doc. - AI.dev/SKILLS/scan-repo-context.md: remove instructions to read .windsurfrules / write .cursorrules. Point at the canonical behavior file. - AI.dev/PROMPTS/new-product-scaffold.md: remove .windsurfrules and CLAUDE.md from the scaffold tree. Add deprecated-files callout + regeneration hint. - AI.dev/PROMPTS/agents-md-sync.md: drop 'Step 4 update CLAUDE.md', point at the generator instead. Remove CLAUDE.md from `git add`. - AI.dev/PROMPTS/ecosystem-audit.md: replace 'CLAUDE.md exists?' with 'canonical-behavior-pointer block present? legacy files absent?'. Script UX: - scripts/update-agent-docs.sh: stop printing 'All repos already in sync' when --no-commit suppressed commits or --dry-run was used. Emit accurate per-mode summaries instead.
130 lines
4.2 KiB
Markdown
130 lines
4.2 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: 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
|