---
description: Scan all repos and regenerate AI agent docs (AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions) across the workspace
---

# Update Agent Documentation

Scans all three workspace repos, builds a comprehensive understanding of the current state, and regenerates all AI agent communication files. Run this periodically — especially after adding packages, services, modules, or changing conventions.

## Repos Covered

| Repo | Path | Scope |
|------|------|-------|
| **learning_voice_ai_agent** | `$HOME/code/mygh/learning_voice_ai_agent` | LysnrAI product code (desktop, backend, dashboards) |
| **learning_ai_common_plat** | `$HOME/code/mygh/learning_ai_common_plat` | Shared @bytelyst/* packages + @lysnrai/* microservices |
| **learning_multimodal_memory_agents** | `$HOME/code/mygh/learning_multimodal_memory_agents` | MindLyst native app (KMP + SwiftUI + Compose + Next.js) |

## Files Updated Per Repo

| File | Tool | Format |
|------|------|--------|
| `AGENTS.md` | Universal (OpenAI Codex, all agents) | Detailed markdown — full onboarding, structure, conventions, patterns, ownership |
| `CLAUDE.md` | Claude Code (Anthropic) | Short markdown (<50 lines) — compact quick-reference summary |
| `.cursorrules` | Cursor AI | Plain text — inline completion + chat rules |
| `.github/copilot-instructions.md` | GitHub Copilot | Markdown — code generation always/never lists |
| `.windsurfrules` | Windsurf / Codeium Cascade | Plain text — project rules for Windsurf memory system |
| `.clinerules` | Cline / Roo Code (VS Code) | Plain text — mandatory rules + key file locations |
| `.aider.conf.yml` | Aider | YAML — context files, conventions pointer, lint commands |
| `.editorconfig` | All editors / JetBrains AI | INI — indent, charset, line ending, trim rules |

---

## Steps

### Phase 1: Gather Current State

1. **Scan learning_voice_ai_agent structure:**
   // turbo
   - Run `find $HOME/code/mygh/learning_voice_ai_agent -maxdepth 2 -type f -name "package.json" -not -path "*/node_modules/*" | head -20` to find all JS projects
   // turbo
   - Run `find $HOME/code/mygh/learning_voice_ai_agent -maxdepth 1 -type f -name "*.py" -o -name "*.toml" -o -name "Makefile" | head -20` to find Python config
   - Read `AGENTS.md`, `README_MONO_REPO.md`, `docker-compose.yml`, `pyproject.toml`
   - Read each dashboard's `package.json` to check current `@bytelyst/*` dependencies
   - List `user-dashboard-web/src/lib/` to see which lib files exist
   - NOTE: admin-dashboard-web and tracker-dashboard-web moved to `../learning_ai_common_plat/dashboards/`
   - Read `user-dashboard-web/src/lib/cosmos.ts` and `auth-server.ts` to verify which @bytelyst/* packages are wired
   - Count Python tests: `find tests/ -name "test_*.py" | wc -l`
   - Count API routes: `find user-dashboard-web/src/app/api -name "route.ts" | wc -l`
   - Read `.github/workflows/` to count CI workflows
   - Read `run-local-all-services.sh` header to understand service topology

2. **Scan learning_ai_common_plat structure:**
   // turbo
   - Run `find $HOME/code/mygh/learning_ai_common_plat/packages -maxdepth 2 -name "package.json" -not -path "*/node_modules/*"` to list all packages
   // turbo
   - Run `find $HOME/code/mygh/learning_ai_common_plat/services -maxdepth 2 -name "package.json" -not -path "*/node_modules/*"` to list all services
   - Read `AGENTS.md`, `README.md`, `pnpm-workspace.yaml`, `tsconfig.base.json`
   - Read each package's `src/index.ts` to catalog exports
   - Read each service's `src/server.ts` to catalog registered modules
   - Count tests: run `cd $HOME/code/mygh/learning_ai_common_plat && pnpm test 2>&1 | tail -5` (if quick) or count test files
   - Read `packages/design-tokens/tokens/bytelyst.tokens.json` for current token state
   - Check `packages/design-tokens/generated/` for what output formats exist

3. **Scan learning_multimodal_memory_agents structure:**
   // turbo
   - Run `find $HOME/code/mygh/learning_multimodal_memory_agents/mindlyst-native -maxdepth 3 -name "*.kt" -o -name "*.swift" -o -name "*.tsx" | head -30`
   - Read `AGENTS.md`, `README.md`, `ARCHITECTURE.md`
   - Read `mindlyst-native/gradle/libs.versions.toml` for dependency versions
   - Read `mindlyst-native/shared/build.gradle.kts` for KMP targets
   - List `mindlyst-native/shared/src/commonMain/kotlin/com/mindlyst/shared/` for shared logic files
   - List `mindlyst-native/iosApp/`, `mindlyst-native/web/src/pages/`
   - Read `design-system/web/mindlyst.css` header for token sync state

### Phase 2: Identify Changes

4. **Compare current state against existing agent docs:**
   - For each repo, diff the gathered info against what's already in AGENTS.md
   - Identify: new packages, new services, new modules, changed conventions, new file ownership, new env vars, updated test counts, new CI workflows
   - Note any stale or incorrect information in existing docs

5. **Build a change summary** — list what needs updating in each file before editing

### Phase 3: Update learning_voice_ai_agent Agent Docs

6. **Update `AGENTS.md`** — the most comprehensive file. Ensure these sections are current:
   - **Project Identity** — product name, IDs, prefixes
   - **Monorepo Layout** — directory tree with descriptions, including sibling repo structure
   - **Tech Stack Rules** — Python, TypeScript services, TypeScript dashboards (with @bytelyst/* wiring)
   - **Coding Conventions** — MUST/MUST NOT rules
   - **File Ownership Map** — table mapping domains → services → key files (include all @bytelyst/* mappings)
   - **How to Run Things** — start services, run tests, docker compose, seed
   - **Common Patterns** — adding modules, pages, service clients, backend routes, debugging
   - **Environment Variables** — required vars per service, env file locations
   - **Key Documents** — table of "when you need to..." → "read this"

7. **Update `CLAUDE.md`** — compact summary (<50 lines):
   - Identity, key commands, critical rules, current @bytelyst/* wiring state

8. **Update `.cursorrules`** — Cursor inline completion + chat rules:
   - Project context, code generation patterns, naming conventions, import patterns
   - Reference AGENTS.md for full details

9. **Update `.github/copilot-instructions.md`** — GitHub Copilot code generation guidance:
   - Always/never lists, commit format, import patterns, type patterns

10. **Update `.windsurfrules`** — Windsurf/Cascade project rules:
    - Architecture, key paths, conventions, @bytelyst/* wiring, build verification commands

11. **Update `.clinerules`** — Cline/Roo Code mandatory rules:
    - Numbered mandatory rules, key file locations, verify command

12. **Update `.aider.conf.yml`** — Aider configuration:
    - Context files to read (AGENTS.md, README), conventions pointer, lint commands

13. **Update `.editorconfig`** — Editor/formatting rules:
    - Indent style/size per language, charset, line endings, trim rules

### Phase 4: Update learning_ai_common_plat Agent Docs

14. **Update all 8 agent doc files** in common platform, ensuring:
    - `AGENTS.md`: Package exports, service modules, file ownership (27+ domains), dependency graph, consumer info, test count
    - `CLAUDE.md`: Compact summary
    - `.cursorrules`: Completion rules for @bytelyst/* and @lysnrai/*
    - `.github/copilot-instructions.md`: Generation rules
    - `.windsurfrules`: pnpm workspace rules, ESM conventions
    - `.clinerules`: Mandatory rules for package/service development
    - `.aider.conf.yml`: Context files, pnpm lint commands
    - `.editorconfig`: Already exists — verify still correct

### Phase 5: Update learning_multimodal_memory_agents Agent Docs

15. **Update all 8 agent doc files** in MindLyst repo, ensuring:
    - `AGENTS.md`: KMP shared module, platform UI state, design tokens, build commands, progress
    - `CLAUDE.md`: Compact summary
    - `.cursorrules`: Already exists — verify current
    - `.github/copilot-instructions.md`: Already exists — verify current
    - `.windsurfrules`: Already exists — verify current
    - `.clinerules`: Already exists — verify current
    - `.aider.conf.yml`: Already exists — verify current
    - `.editorconfig`: Already exists — verify current

### Phase 6: Verify & Commit

16. **Verify consistency across repos:**
    - Shared conventions (commit format, productId rule, etc.) should match across all 3 AGENTS.md files
    - @bytelyst/* package descriptions should be consistent between common platform and voice agent docs
    - Design token flow should be consistent between common platform and MindLyst docs

17. **Commit and push each repo** (stage all 8 files):
    - `cd $HOME/code/mygh/learning_voice_ai_agent && git add AGENTS.md CLAUDE.md .cursorrules .github/copilot-instructions.md .windsurfrules .clinerules .aider.conf.yml .editorconfig && git commit -m "docs: update agent docs via /update-agent-docs" && git push`
    - `cd $HOME/code/mygh/learning_ai_common_plat && git add AGENTS.md CLAUDE.md .cursorrules .github/copilot-instructions.md .windsurfrules .clinerules .aider.conf.yml .editorconfig && git commit -m "docs: update agent docs via /update-agent-docs" && git push`
    - `cd $HOME/code/mygh/learning_multimodal_memory_agents && git add AGENTS.md CLAUDE.md .cursorrules .github/copilot-instructions.md .windsurfrules .clinerules .aider.conf.yml .editorconfig && git commit -m "docs: update agent docs via /update-agent-docs" && git push`

18. **Print summary** of all changes made across all repos.

---

## Notes

- Run this workflow after: adding/removing packages, services, or modules; changing conventions; major refactors; adding new CI workflows; updating environment variables
- The workflow is idempotent — safe to run multiple times
- It reads current state fresh each time rather than relying on cached knowledge
- If a file doesn't exist yet (e.g., CLAUDE.md in MindLyst), create it
- Never hardcode stale counts — always count dynamically (tests, routes, workflows, etc.)
- Preserve any repo-specific conventions that differ between repos (e.g., MindLyst uses Pages Router, dashboards use App Router)
