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

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

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

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:

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

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

# 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

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

# 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

# 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

# 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

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

#!/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 - Docs are part of readiness
• Local Development Setup - Docs should match local setup
• Debug Service - Docs should help with debugging