From 088a9cabd63e64ccb0b1a2a4ea5bedd09a4e162b Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sat, 23 May 2026 12:06:28 -0700 Subject: [PATCH] fix(agent-docs): update AI.dev guides + script UX after single-source migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- AI.dev/PROMPTS/agents-md-sync.md | 16 +- AI.dev/PROMPTS/ecosystem-audit.md | 5 +- AI.dev/PROMPTS/new-product-scaffold.md | 20 +- AI.dev/SKILLS/README.md | 5 +- AI.dev/SKILLS/index.md | 6 +- AI.dev/SKILLS/scan-repo-context.md | 20 +- AI.dev/SKILLS/update-agent-docs.md | 384 ------------------------- scripts/update-agent-docs.sh | 8 +- 8 files changed, 57 insertions(+), 407 deletions(-) delete mode 100644 AI.dev/SKILLS/update-agent-docs.md diff --git a/AI.dev/PROMPTS/agents-md-sync.md b/AI.dev/PROMPTS/agents-md-sync.md index 0e50bd9c..65e207f0 100644 --- a/AI.dev/PROMPTS/agents-md-sync.md +++ b/AI.dev/PROMPTS/agents-md-sync.md @@ -77,15 +77,25 @@ For each drift found: - Preserve all existing comments and documentation - Keep formatting consistent with other repos -### Step 4: Update CLAUDE.md +### Step 4: Regenerate Derived Files -If AGENTS.md changed significantly, also sync CLAUDE.md (the Claude Code-specific instruction file). +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 -git add AGENTS.md CLAUDE.md +git add AGENTS.md git commit -m "docs(agents): sync AGENTS.md with current repo state - Updated: diff --git a/AI.dev/PROMPTS/ecosystem-audit.md b/AI.dev/PROMPTS/ecosystem-audit.md index ad2b8179..9ff25474 100644 --- a/AI.dev/PROMPTS/ecosystem-audit.md +++ b/AI.dev/PROMPTS/ecosystem-audit.md @@ -77,9 +77,10 @@ pnpm audit ``` ### 7. Documentation Currency -- AGENTS.md matches current layout? +- AGENTS.md exists and matches current layout? +- AGENTS.md contains the canonical-behavior-pointer block? (`bash scripts/check-agent-docs-drift.sh`) - README.md has setup instructions? -- CLAUDE.md exists? +- Legacy agent files removed? (`.cursorrules`, `.windsurfrules`, `.clinerules`, `CLAUDE.md` — replaced by single-source-of-truth pattern) ### 8. Git Hygiene - Any repos with uncommitted changes? diff --git a/AI.dev/PROMPTS/new-product-scaffold.md b/AI.dev/PROMPTS/new-product-scaffold.md index d80804d8..3e4b71fe 100644 --- a/AI.dev/PROMPTS/new-product-scaffold.md +++ b/AI.dev/PROMPTS/new-product-scaffold.md @@ -42,13 +42,14 @@ learning_ai_/ ├── scripts/ │ ├── secret-scan-repo.sh │ └── secret-scan-staged.sh -├── .editorconfig +├── .editorconfig # Generated by update-agent-docs.sh +├── .aider.conf.yml # Generated by update-agent-docs.sh ├── .gitignore +├── .github/ +│ └── copilot-instructions.md # Generated by update-agent-docs.sh (thin pointer) ├── .npmrc # From canonical template (never hand-edit) ├── .nvmrc # "22" -├── .windsurfrules -├── AGENTS.md -├── CLAUDE.md +├── AGENTS.md # Hand-maintained; canonical pointer auto-prepended ├── README.md ├── package.json # Root workspace scripts ├── pnpm-workspace.yaml @@ -56,6 +57,17 @@ learning_ai_/ └── tsconfig.json ``` +> **Deprecated files — do NOT create:** `.cursorrules`, `.windsurfrules`, +> `.clinerules`, `CLAUDE.md`. These were replaced by the single-source-of-truth +> pattern. Agents read `AGENTS.md` plus the canonical behavior file at +> `../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md`. +> +> After adding the new repo to +> `learning_ai_common_plat/.windsurf/workflows/repos.txt`, run +> `bash ../learning_ai_common_plat/scripts/update-agent-docs.sh` +> to populate `.editorconfig`, `.aider.conf.yml`, and +> `.github/copilot-instructions.md`. + ### 2. Create `shared/product.json` ```json diff --git a/AI.dev/SKILLS/README.md b/AI.dev/SKILLS/README.md index c1c0fde5..404af3df 100644 --- a/AI.dev/SKILLS/README.md +++ b/AI.dev/SKILLS/README.md @@ -76,7 +76,7 @@ Each skill follows a consistent format: | Release iOS app | [iOS Release](./ios-release.md) | 🚀 Release & Deployment | | Generate store assets | [Generate Store Assets](./generate-store-assets.md) | 🚀 Release & Deployment | | Ensure mobile code quality | [Mobile Code Quality](./mobile-code-quality.md) | 📱 Mobile Development | -| Update AI docs | [Update Agent Documentation](./update-agent-docs.md) | 📚 Documentation & Communication | +| Update AI docs | `../../.windsurf/workflows/repo_update-agent-docs.md` | 📚 Documentation & Communication | | Write tests | [Test Strategies](./test-strategies.md) | 🧪 Testing & Quality | | Docker full stack | [Docker Compose](./docker-compose.md) | 🔧 Development Workflows | | Security audit | [Security Auditing](./security-auditing.md) | 🧪 Testing & Quality | @@ -95,7 +95,8 @@ Each skill follows a consistent format: - [Desktop Release](./desktop-release.md) - Build and package desktop apps - [iOS Release](./ios-release.md) - TestFlight and App Store deployment - [Generate Store Assets](./generate-store-assets.md) - Create app store artwork -- [Update Agent Documentation](./update-agent-docs.md) - Keep AI docs current +- [Agent Behavior Guidelines](./agent-behavior-guidelines.md) - Canonical agent rules +- Update agent docs across repos — see `../../.windsurf/workflows/repo_update-agent-docs.md` - [Test Strategies](./test-strategies.md) - Comprehensive testing approach - [Test Desktop App](./test-desktop-app.md) - Desktop app testing - [Test iOS App](./test-ios-app.md) - iOS simulator testing diff --git a/AI.dev/SKILLS/index.md b/AI.dev/SKILLS/index.md index d1f8de54..6ba63f70 100644 --- a/AI.dev/SKILLS/index.md +++ b/AI.dev/SKILLS/index.md @@ -39,7 +39,9 @@ ## 📚 Documentation & Communication -- [Update Agent Documentation](./update-agent-docs.md) - AI assistant documentation +- [Agent Behavior Guidelines](./agent-behavior-guidelines.md) - Canonical agent behavior rules (Karpathy + ByteLyst) +- [Agent Onboarding](./agent-onboarding.md) - Read-order index for agents +- Update agent docs across repos — see `../../.windsurf/workflows/repo_update-agent-docs.md` - [Scan Repo Context](./scan-repo-context.md) - Generate comprehensive project context - [API Documentation](./api-documentation.md) - REST API documentation patterns - [Architecture Documentation](./architecture-documentation.md) - System design docs @@ -59,7 +61,7 @@ | Mobile code quality | [Mobile Code Quality](./mobile-code-quality.md) | 📱 Mobile Development | | Test desktop app | [Test Desktop App](./test-desktop-app.md) | 🧪 Testing & Quality | | Test iOS app | [Test iOS App](./test-ios-app.md) | 🧪 Testing & Quality | -| Update AI docs | [Update Agent Documentation](./update-agent-docs.md) | 📚 Documentation & Communication | +| Update AI docs | `../../.windsurf/workflows/repo_update-agent-docs.md` | 📚 Documentation & Communication | | Scan repo for context | [Scan Repo Context](./scan-repo-context.md) | 📚 Documentation & Communication | | Write tests | [Test Strategies](./test-strategies.md) | 🧪 Testing & Quality | | Docker full stack | [Docker Compose](./docker-compose.md) | 🔧 Development Workflows | diff --git a/AI.dev/SKILLS/scan-repo-context.md b/AI.dev/SKILLS/scan-repo-context.md index a78d8e35..09dfa0dc 100644 --- a/AI.dev/SKILLS/scan-repo-context.md +++ b/AI.dev/SKILLS/scan-repo-context.md @@ -36,11 +36,12 @@ Start with high-level understanding: ```bash # Core documentation files -cat AGENTS.md # AI agent guide +cat AGENTS.md # AI agent guide (single per-repo source) cat README.md # Project overview cat ARCHITECTURE.md # Technical architecture cat CONTRIBUTING.md # Contribution guidelines -cat .windsurfrules # Windsurf-specific rules +cat ../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md + # Ecosystem-wide agent behavior rules ``` ### Phase 2: Understand Project Structure @@ -346,13 +347,13 @@ echo "Context documentation generated: $OUTPUT_FILE" The generated `WINDSURF_CONTEXT.md` is automatically picked up by Windsurf. -### Cursor +### Cursor / Windsurf / Claude Code / Codex / Cline -Add to `.cursorrules`: - -``` -Always reference WINDSURF_CONTEXT.md for project understanding -``` +These agents all read `AGENTS.md` at the repo root. Add references to +`WINDSURF_CONTEXT.md` (or equivalent) inside AGENTS.md so every agent sees it. +Do not create per-tool config files (`.cursorrules`, `.windsurfrules`, +`.clinerules`, `CLAUDE.md`) — they are deprecated in favour of the canonical +pointer architecture (see `learning_ai_common_plat/.windsurf/workflows/repo_update-agent-docs.md`). ### GitHub Copilot @@ -391,7 +392,8 @@ git push ## Related Skills -- [Update Agent Documentation](./update-agent-docs.md) - For AI-specific docs +- [Agent Behavior Guidelines](./agent-behavior-guidelines.md) - Canonical agent rules +- [Agent Onboarding](./agent-onboarding.md) - Read-order index for agents - [Architecture Patterns](./architecture-patterns.md) - Understanding architecture - [Local Development Setup](./local-development.md) - Setting up to work - [Documentation Standards](./documentation-standards.md) - Writing good docs diff --git a/AI.dev/SKILLS/update-agent-docs.md b/AI.dev/SKILLS/update-agent-docs.md deleted file mode 100644 index d3af6d54..00000000 --- a/AI.dev/SKILLS/update-agent-docs.md +++ /dev/null @@ -1,384 +0,0 @@ -# Update Agent Documentation Skill - -**Description**: Scan all repos and regenerate AI assistant documentation (AGENTS.md, CLAUDE.md, etc.) across the workspace. - -## When to Use - -- After adding new packages or services -- When changing coding conventions -- After architectural changes -- Periodically to keep docs current -- When onboarding new AI assistants - -## Repositories Covered - -| Repo | Path | Scope | -| ------------------------------------- | --------------------------------------------------- | -------------------------- | -| **learning_voice_ai_agent** | `$HOME/code/mygh/learning_voice_ai_agent` | LysnrAI product code | -| **learning_ai_common_plat** | `$HOME/code/mygh/learning_ai_common_plat` | Shared packages + services | -| **learning_multimodal_memory_agents** | `$HOME/code/mygh/learning_multimodal_memory_agents` | MindLyst native app | - -## Files Updated Per Repo - -| File | Tool | Format | Purpose | -| --------------------------------- | ---------------- | ---------------------------- | -------------------------------- | -| `AGENTS.md` | Universal | Detailed markdown | Full onboarding guide | -| `CLAUDE.md` | Claude Code | Compact markdown (<50 lines) | Quick reference | -| `.cursorrules` | Cursor AI | Plain text | Inline completion + chat rules | -| `.github/copilot-instructions.md` | GitHub Copilot | Markdown | Code generation rules | -| `.windsurfrules` | Windsurf/Codeium | Plain text | Project rules for memory | -| `.clinerules` | Cline/Roo Code | Plain text | Mandatory rules + file locations | -| `.aider.conf.yml` | Aider | YAML | Context files, conventions | -| `.editorconfig` | All editors | INI | Indent, charset, line ending | - -## Phase 1: Gather Current State - -### 1. Scan learning_voice_ai_agent - -```bash -cd $HOME/code/mygh/learning_voice_ai_agent - -# Find all JS projects -find . -maxdepth 2 -type f -name "package.json" -not -path "*/node_modules/*" | head -20 - -# Find Python config -find . -maxdepth 1 -type f -name "*.py" -o -name "*.toml" -o -name "Makefile" | head -20 - -# Read key files -cat AGENTS.md -cat README_MONO_REPO.md -cat docker-compose.yml -cat pyproject.toml - -# Check dashboard dependencies -find admin-dashboard-web user-dashboard-web tracker-dashboard-web -name "package.json" -exec grep "@bytelyst" {} \; - -# List lib files -ls admin-dashboard-web/src/lib/ -ls user-dashboard-web/src/lib/ -ls tracker-dashboard-web/src/lib/ - -# Count tests -find tests/ -name "test_*.py" | wc -l -find admin-dashboard-web/src/app/api -name "route.ts" | wc -l - -# Check CI workflows -ls -la .github/workflows/ - -# Check service topology -head -20 run-local-all-services.sh -``` - -### 2. Scan learning_ai_common_plat - -```bash -cd $HOME/code/mygh/learning_ai_common_plat - -# List all packages -find packages -maxdepth 2 -name "package.json" -not -path "*/node_modules/*" - -# List all services -find services -maxdepth 2 -name "package.json" -not -path "*/node_modules/*" - -# Read key files -cat AGENTS.md -cat README.md -cat pnpm-workspace.yaml -cat tsconfig.base.json - -# Check package exports -find packages -name "src/index.ts" -exec echo "=== {} ===" \; -exec cat {} \; - -# Check service modules -find services -name "src/server.ts" -exec echo "=== {} ===" \; -exec cat {} \; - -# Count tests (quick) -pnpm test 2>&1 | tail -5 - -# Check design tokens -cat packages/design-tokens/tokens/bytelyst.tokens.json -ls packages/design-tokens/generated/ -``` - -### 3. Scan learning_multimodal_memory_agents - -```bash -cd $HOME/code/mygh/learning_multimodal_memory_agents - -# Find source files -find mindlyst-native -maxdepth 3 -name "*.kt" -o -name "*.swift" -o -name "*.tsx" | head -30 - -# Read key files -cat AGENTS.md -cat README.md -cat ARCHITECTURE.md - -# Check dependencies -cat mindlyst-native/gradle/libs.versions.toml -cat mindlyst-native/shared/build.gradle.kts - -# List shared logic -ls mindlyst-native/shared/src/commonMain/kotlin/com/mindlyst/shared/ - -# List platform code -ls mindlyst-native/iosApp/ -ls mindlyst-native/web/src/pages/ - -# Check token sync -head -20 design-system/web/mindlyst.css -``` - -## Phase 2: Identify Changes - -Compare gathered info against existing docs: - -- New packages or services? -- Changed conventions? -- New file ownership patterns? -- Updated environment variables? -- Different test counts? -- New CI workflows? - -Build a change summary before editing. - -## Phase 3: Update Documentation - -### 1. Update AGENTS.md (Most Comprehensive) - -Ensure these sections are current: - -```markdown -## Project Identity - -- Product name, IDs, prefixes -- License format -- Config directory - -## Monorepo Layout - -- Directory tree with descriptions -- Include sibling repo structure -- Service ports and responsibilities - -## Tech Stack Rules - -- Python: version, linter, formatter, tests, logging -- TypeScript services: framework, patterns, database -- TypeScript dashboards: framework, shared packages - -## Coding Conventions - -- MUST follow rules -- MUST NOT do rules -- Commit message format - -## File Ownership Map - -- Table mapping domains → services → key files -- Include all @bytelyst/\* mappings - -## How to Run Things - -- Start services command -- Test commands -- Docker compose -- Seed database - -## Common Patterns - -- Adding Fastify modules -- Adding dashboard pages -- Adding service clients -- Adding backend routes -- Debugging methodology - -## Environment Variables - -- Required vars per service -- Env file locations -- Azure service references - -## Key Documents - -- "When you need to..." → "read this" table -``` - -### 2. Update CLAUDE.md (Compact Summary) - -Keep under 50 lines: - -- Identity (product, tech stack) -- Key commands (start services, run tests) -- Critical rules (MUST follow) -- Current @bytelyst/\* wiring state - -### 3. Update .cursorrules - -```text -Project: LysnrAI - Voice-to-text platform -Stack: Python 3.12 + FastAPI + Next.js 16 + Fastify 5 -Rules: -- Always use req.log, never console.log -- Every Cosmos doc needs productId field -- Use @bytelyst/* packages from common_plat -- Commit: feat(scope): description -- See AGENTS.md for full details -``` - -### 4. Update .github/copilot-instructions.md - -```markdown -# LysnrAI Copilot Instructions - -## Always Do - -- Use structlog for Python logging -- Validate with Zod schemas in TypeScript -- Include productId in all Cosmos documents -- Use @bytelyst/api-client for service calls - -## Never Do - -- Use console.log in production -- Hardcode secrets or API keys -- Modify tests to make them pass -- Use any type in TypeScript - -## Key Patterns - -- Fastify modules: types.ts → repository.ts → routes.ts -- Dashboard pages: src/app/(dashboard)/page-name/page.tsx -- Python routes: backend/src/routes/name.py - -See AGENTS.md for comprehensive guide. -``` - -### 5. Update .windsurfrules - -```text -Project: LysnrAI -Product ID: lysnrrai -Config dir: ~/.lysnrai/ -Key services: backend(8000), billing(4002), growth(4001), platform(4003), tracker(4004) -Dashboards: admin(3001), user(3002), tracker(3003) -Rules: Use @bytelyst/* packages, no console.log, productId required, commit format: type(scope): desc -``` - -### 6. Update .clinerules - -```text -# LysnrAI Project Rules -- All business logic in backend/src/ or services/ -- Dashboards in admin-dashboard-web/, user-dashboard-web/, tracker-dashboard-web/ -- Shared packages in ../learning_ai_common_plat/packages/ -- Use @bytelyst/cosmos for DB, @bytelyst/auth for JWT -- Python: use ruff lint, pytest tests -- TypeScript: use ESLint, Vitest tests -- Never commit .env files or secrets -``` - -### 7. Update .aider.conf.yml - -```yaml -# Aider configuration for LysnrAI -auto-commits: false -lint-cmd: | - python: ruff check --fix - typescript: pnpm lint - shell: shellcheck -f gcc -test-cmd: | - python: pytest tests/ -v - typescript: pnpm test - -# Always include these files in context -context-files: - - AGENTS.md - - README_MONO_REPO.md - - docker-compose.yml - - pyproject.toml - - pnpm-workspace.yaml - - tsconfig.base.json -``` - -### 8. Update .editorconfig - -```ini -# EditorConfig for LysnrAI -root = true - -[*.py] -indent_style = space -indent_size = 4 -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true - -[*.{js,ts,tsx,json}] -indent_style = space -indent_size = 2 -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true - -[*.{kt,swift}] -indent_style = space -indent_size = 4 -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -``` - -## Phase 4: Validate Updates - -```bash -# For each repo: -git add . -git commit -m "docs: update AI agent documentation" -git push - -# Verify files are readable -cat AGENTS.md | head -20 -cat CLAUDE.md -cat .cursorrules -``` - -## Automation Script - -Create `scripts/update-all-agent-docs.sh`: - -```bash -#!/bin/bash -# Update all agent docs across repos - -REPOS=( - "$HOME/code/mygh/learning_voice_ai_agent" - "$HOME/code/mygh/learning_ai_common_plat" - "$HOME/code/mygh/learning_multimodal_memory_agents" -) - -for repo in "${REPOS[@]}"; do - echo "Updating docs in $repo" - cd "$repo" - - # Run the update workflow - # (This would be the full workflow implementation) - - git add . - git commit -m "docs: update AI agent documentation" - git push -done -``` - -## Notes - -- **Be consistent** - Keep the same structure across all repos -- **Be specific** - Include actual file paths and commands -- **Stay current** - Run this workflow regularly -- **Get feedback** - Ask developers if docs are helpful -- **Version control** - Track changes to understand evolution - -## Related Skills - -- [Production Readiness](./production-readiness.md) - Docs are part of readiness -- [Local Development Setup](./local-development.md) - Docs should match local setup -- [Debug Service](./debug-service.md) - Docs should help with debugging diff --git a/scripts/update-agent-docs.sh b/scripts/update-agent-docs.sh index eb784e0f..3b070f83 100755 --- a/scripts/update-agent-docs.sh +++ b/scripts/update-agent-docs.sh @@ -519,5 +519,11 @@ if [[ ${#CHANGED_REPOS[@]} -gt 0 ]]; then echo " git -C ${BASE_DIR}/${r} push" done else - ok "All repos already in sync — no changes." + if $NO_COMMIT; then + ok "Files regenerated. No commits made (--no-commit). Inspect changes with: git -C status" + elif $DRY_RUN; then + ok "Dry run complete. Re-run without --dry-run to apply." + else + ok "All repos already in sync — no changes." + fi fi