learning_ai_common_plat/AI.dev/SKILLS/update-agent-docs.md

# 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