saravanakumardb1 088a9cabd6 fix(agent-docs): update AI.dev guides + script UX after single-source migration

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.

2026-05-23 12:06:28 -07:00

4.2 KiB

Raw Blame History

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:

Project Identity — product name, ID, bundle IDs, ports, ecosystem
Repo Layout — file tree (keep up to date!)
Tech Stack — frameworks, languages, tools per layer
Coding Conventions — MUST follow / MUST NOT do
.npmrc rules — never edit directly
Cosmos Containers (if backend) — container, partition key, purpose
Build & Test Commands — exact pnpm commands
API Endpoints (if backend) — method, path, description
Environment Variables — var, default, description
Current State (optional) — phases, commits, test counts
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: Regenerate Derived Files

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

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

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

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

4.2 KiB Raw Blame History