From 2e35334e134fa4bfde1b6c8c58e0da8519300727 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sat, 21 Mar 2026 09:04:35 -0700 Subject: [PATCH] docs(devops): add coding agent automation playbook - 11 cross-repo automation tasks for AI coding agents - Workspace hygiene, test suites, coverage gaps, typecheck, deps, secrets - Baseline test counts: 1,457 backend + 864 web = 2,321 total - Priority matrix, quick-start commands, existing workflow references --- .../CODING_AGENT_AUTOMATION_PLAYBOOK.md | 494 ++++++++++++++++++ 1 file changed, 494 insertions(+) create mode 100644 docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md diff --git a/docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md b/docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md new file mode 100644 index 00000000..e4ac59ca --- /dev/null +++ b/docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md @@ -0,0 +1,494 @@ +# ByteLyst — Coding Agent Automation Playbook + +> **Purpose:** Define repeatable, cross-repo tasks that AI coding agents (Windsurf Cascade, Claude Code, Cursor, Codex) should run periodically to maintain code health, test quality, and consistency across the ByteLyst workspace. +> +> **Scope:** All 14 repos in the ByteLyst workspace. Tasks are designed to be run by any coding agent in a single session. +> +> **Last updated:** 2026-03-21 + +--- + +## Workspace Inventory + +| # | Repo | Product | Backend | Web | Mobile | Port | +| --- | ----------------------------------- | --------------------- | ---------------------------- | -------------------- | ------------- | ---------- | +| 1 | `learning_ai_common_plat` | @bytelyst/\* platform | services/ | dashboards/ | — | 4003, 4005 | +| 2 | `learning_voice_ai_agent` | LysnrAI | ✅ | user-dashboard-web/ | ios + android | 4015 | +| 3 | `learning_multimodal_memory_agents` | MindLyst | ✅ | mindlyst-native/web/ | KMP + web | 4014 | +| 4 | `learning_ai_clock` | ChronoMind | ✅ | web/ | ios + android | — | +| 5 | `learning_ai_jarvis_jr` | JarvisJr | ✅ | web/ | ios + android | 4012 | +| 6 | `learning_ai_fastgap` | NomGap | ✅ | web/ | Expo | 4013 | +| 7 | `learning_ai_peakpulse` | PeakPulse | ✅ | — | ios | 4010 | +| 8 | `learning_ai_flowmonk` | FlowMonk | ✅ | web/ | Expo | 4017 | +| 9 | `learning_ai_notes` | NoteLett | ✅ | web/ | Expo | 4016 | +| 10 | `learning_ai_trails` | ActionTrail | ✅ | web/ | — | 4018 | +| 11 | `learning_ai_local_memory_gpt` | LocalMemGPT | ✅ | web/ | — | 4019 | +| 12 | `learning_ai_auth_app` | ByteLyst Auth | — | — | ios + android | — | +| 13 | `learning_ai_smart_auth` | SmartAuth | — (extends platform-service) | — | — | — | +| 14 | `learning_ai_productivity_web` | Productivity Tools | — | src/ | — | — | + +--- + +## 1. Workspace Hygiene Sweep + +**Frequency:** Every session start, or weekly +**Trigger phrase:** "Run workspace hygiene sweep" + +### 1a. Dirty / Uncommitted Changes Check + +Scan all 14 repos for uncommitted or untracked changes. Flag anything that should be committed or stashed. + +```bash +for repo in learning_ai_common_plat learning_voice_ai_agent learning_multimodal_memory_agents learning_ai_clock learning_ai_jarvis_jr learning_ai_fastgap learning_ai_peakpulse learning_ai_flowmonk learning_ai_notes learning_ai_trails learning_ai_local_memory_gpt learning_ai_auth_app learning_ai_smart_auth learning_ai_productivity_web; do + echo "=== $repo ===" + cd /Users/sd9235/code/mygh/$repo + git status --short + echo +done +``` + +**Agent action:** For each dirty repo, summarize what's changed and ask if it should be committed, stashed, or discarded. + +### 1b. Branch Drift Check + +Verify all repos are on `main` and check if local is ahead/behind origin. + +```bash +for repo in ...; do + echo "=== $repo ===" + cd /Users/sd9235/code/mygh/$repo + BRANCH=$(git branch --show-current) + echo "Branch: $BRANCH" + git log origin/main..HEAD --oneline 2>/dev/null | head -5 + echo +done +``` + +**Agent action:** Flag any repo not on `main` or with unpushed commits. Offer to push. + +### 1c. Lock File Freshness + +Check that `package-lock.json` (npm) or `pnpm-lock.yaml` (pnpm) exist and are committed. + +**Agent action:** Flag repos where the lock file is missing, gitignored, or has uncommitted changes. + +--- + +## 2. Cross-Repo Test Suite + +**Frequency:** After any multi-repo change, or weekly +**Trigger phrase:** "Run cross-repo test audit" + +### 2a. Backend Tests (10 repos) + +```bash +for repo in learning_ai_fastgap learning_ai_jarvis_jr learning_ai_trails learning_ai_flowmonk learning_ai_clock learning_ai_local_memory_gpt learning_ai_notes learning_voice_ai_agent learning_multimodal_memory_agents learning_ai_peakpulse; do + echo "=== $repo ===" + cd /Users/sd9235/code/mygh/$repo/backend + npx vitest run 2>&1 | grep "Tests\|Test Files" | tail -2 + echo +done +``` + +**Current baseline (2026-03-21):** + +| Repo | Backend Tests | Status | +| ----------- | ------------- | ------ | +| NomGap | 209 | ✅ | +| JarvisJr | 209 | ✅ | +| ActionTrail | 191 | ✅ | +| FlowMonk | 211 | ✅ | +| ChronoMind | 182 | ✅ | +| LocalMemGPT | 86 | ✅ | +| NoteLett | 86 | ✅ | +| LysnrAI | 115 | ✅ | +| MindLyst | 103 | ✅ | +| PeakPulse | 65 | ✅ | +| **Total** | **1,457** | | + +### 2b. Web Tests (9 surfaces) + +```bash +# Each web project uses vitest; paths vary per repo +# learning_multimodal_memory_agents → mindlyst-native/web/ +# learning_voice_ai_agent → user-dashboard-web/ +# All others → web/ +``` + +**Current baseline (2026-03-21):** + +| Repo | Web Tests | Status | +| ---------------------- | --------- | ------ | +| ChronoMind | 394 | ✅ | +| NomGap | 130 | ✅ | +| LysnrAI user-dashboard | 110 | ✅ | +| MindLyst | 81 | ✅ | +| JarvisJr | 51 | ✅ | +| ActionTrail | 32 | ✅ | +| LocalMemGPT | 32 | ✅ | +| FlowMonk | 20 | ✅ | +| NoteLett | 14 | ✅ | +| **Total** | **864** | | + +### 2c. Common Platform Tests + +```bash +cd /Users/sd9235/code/mygh/learning_ai_common_plat +pnpm test # runs all package + service tests +``` + +### 2d. Mobile Tests (Expo / native) + +```bash +# NomGap (Expo): cd learning_ai_fastgap && npm test +# MindLyst (KMP): cd learning_multimodal_memory_agents/mindlyst-native && ./gradlew :shared:compileKotlinIosSimulatorArm64 +``` + +**Agent action:** + +1. Run all test suites and collect pass/fail counts. +2. Compare against the baseline table above. +3. If any tests regress or new failures appear, **fix them before moving on**. +4. Update the baseline numbers in this document after fixes. + +--- + +## 3. Backend Test Coverage Gap Analysis + +**Frequency:** Monthly, or after adding new modules +**Trigger phrase:** "Run backend test coverage audit" + +Scan every backend module directory for the presence of a `*.test.ts` file: + +```bash +for repo in learning_ai_fastgap learning_ai_jarvis_jr learning_ai_trails learning_ai_flowmonk learning_ai_clock learning_ai_local_memory_gpt learning_ai_notes learning_voice_ai_agent learning_multimodal_memory_agents learning_ai_peakpulse; do + echo "=== $repo ===" + BDIR="/Users/sd9235/code/mygh/$repo/backend/src" + for mod in $(ls -d $BDIR/modules/*/ 2>/dev/null); do + modname=$(basename $mod) + if find $mod -name "*.test.ts" 2>/dev/null | grep -q .; then + echo " ✅ $modname" + else + echo " ❌ $modname (NO TEST)" + fi + done + echo +done +``` + +**Agent action:** + +1. For each `❌` module, read its `types.ts`, `repository.ts`, and `routes.ts`. +2. Create a `repository.test.ts` following the repo's existing test patterns. +3. For route-only modules (no repository), create a route-level inject test. +4. Run the full backend suite to verify no regressions. +5. Commit with: `test(backend): add tests for module` + +--- + +## 4. Web Test Coverage Gap Analysis + +**Frequency:** Monthly +**Trigger phrase:** "Run web test coverage audit" + +Scan each web project's `src/lib/` for untested modules: + +```bash +for repo in ...; do + WEBDIR="..." # resolve per repo + TESTDIR=$(find $WEBDIR/src -type d -name "__tests__" | head -1) + echo "=== $repo ===" + # List lib modules without corresponding test files + for f in $WEBDIR/src/lib/*.ts; do + base=$(basename $f .ts) + if ! find $TESTDIR -name "*$base*" 2>/dev/null | grep -q .; then + echo " ❌ lib/$base (NO TEST)" + fi + done +done +``` + +**Agent action:** + +1. For each untested lib module, create tests following the repo's existing patterns. +2. Focus on: API clients (mock fetch), platform clients (mock SDK), store modules, utility functions. +3. Run the full web suite to verify. +4. Commit with: `test(web): add tests for ` + +--- + +## 5. TypeScript Type-Check Sweep + +**Frequency:** Weekly, or before releases +**Trigger phrase:** "Run typecheck sweep" + +```bash +# Backend (10 repos) +for repo in learning_ai_fastgap learning_ai_jarvis_jr learning_ai_trails learning_ai_flowmonk learning_ai_clock learning_ai_local_memory_gpt learning_ai_notes learning_voice_ai_agent learning_multimodal_memory_agents learning_ai_peakpulse; do + echo "=== $repo backend ===" && cd /Users/sd9235/code/mygh/$repo/backend && npx tsc --noEmit 2>&1 | tail -3 +done + +# Web (9 surfaces) +for repo in learning_ai_fastgap learning_ai_jarvis_jr learning_ai_trails learning_ai_flowmonk learning_ai_clock learning_ai_local_memory_gpt learning_ai_notes; do + echo "=== $repo web ===" && cd /Users/sd9235/code/mygh/$repo/web && npx tsc --noEmit 2>&1 | tail -3 +done +echo "=== MindLyst web ===" && cd /Users/sd9235/code/mygh/learning_multimodal_memory_agents/mindlyst-native/web && npm run typecheck 2>&1 | tail -3 +echo "=== LysnrAI user-dashboard ===" && cd /Users/sd9235/code/mygh/learning_voice_ai_agent/user-dashboard-web && npx tsc --noEmit 2>&1 | tail -3 + +# Common platform +echo "=== common-plat ===" && cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm typecheck 2>&1 | tail -5 +``` + +**Agent action:** Fix any type errors. Commit with `fix(): resolve typecheck errors`. + +--- + +## 6. Dependency Health Check + +**Frequency:** Monthly +**Trigger phrase:** "Run dependency health check" + +### 6a. Unused Dependencies + +```bash +for repo in ...; do + cd /Users/sd9235/code/mygh/$repo/backend # or web/ + npx depcheck --ignores="@types/*,vitest,typescript" 2>&1 | head -20 +done +``` + +### 6b. @bytelyst/\* Package Consistency + +Verify all product repos use the same set of `@bytelyst/*` packages and that `file:` references point to existing paths: + +```bash +for repo in ...; do + echo "=== $repo ===" + grep "@bytelyst/" /Users/sd9235/code/mygh/$repo/web/package.json 2>/dev/null | sort +done +``` + +### 6c. Outdated Packages + +```bash +cd /path/to/repo && npm outdated 2>/dev/null | head -20 +``` + +**Agent action:** + +1. Remove unused dependencies flagged by depcheck. +2. Fix broken `file:` references to `@bytelyst/*` packages. +3. Flag outdated major versions for user review (do not auto-upgrade majors). +4. Commit with: `chore(): remove unused deps` or `fix(): fix package references` + +--- + +## 7. Secret & Credential Scan + +**Frequency:** Every commit (pre-commit hook) + weekly full scan +**Trigger phrase:** "Run secret scan" + +```bash +# Full repo scan (all tracked files) +for repo in ...; do + echo "=== $repo ===" + cd /Users/sd9235/code/mygh/$repo + ../learning_ai_common_plat/scripts/secret-scan-repo.sh 2>&1 | tail -3 +done +``` + +**What it catches:** API keys, JWT secrets, connection strings, Azure credentials, passwords in code. + +**Agent action:** If secrets are found, flag immediately. Never commit secrets. Use `.env` + AKV references. + +--- + +## 8. Code Quality Patterns + +**Frequency:** Monthly +**Trigger phrase:** "Run code quality audit" + +### 8a. console.log / print() Detection + +Production code must never use `console.log` (use `req.log` / `app.log` in Fastify) or `print()` (use `os.Logger` in Swift). + +```bash +# TypeScript +for repo in ...; do + echo "=== $repo ===" + grep -rn "console\.log" /Users/sd9235/code/mygh/$repo/backend/src/ --include="*.ts" | grep -v test | grep -v node_modules | head -5 +done + +# Swift +for repo in learning_ai_peakpulse learning_ai_clock learning_ai_jarvis_jr; do + grep -rn "print(" /Users/sd9235/code/mygh/$repo/ios/ --include="*.swift" | grep -v Tests | head -5 +done +``` + +### 8b. Hardcoded Colors Detection + +All colors must come from design tokens, never hardcoded hex values. + +```bash +# Web CSS/TSX: look for hex colors not in globals.css +grep -rn "#[0-9a-fA-F]\{6\}" /Users/sd9235/code/mygh/$repo/web/src/ --include="*.tsx" --include="*.ts" | grep -v test | grep -v __tests__ | head -10 +``` + +### 8c. `any` Type Usage + +TypeScript code must not use `any` type. + +```bash +grep -rn ": any" /Users/sd9235/code/mygh/$repo/backend/src/ --include="*.ts" | grep -v node_modules | grep -v test | head -10 +``` + +### 8d. Missing `productId` in Cosmos Documents + +Every Cosmos document must include `productId`. Scan repository files: + +```bash +for repo in ...; do + grep -L "productId" /Users/sd9235/code/mygh/$repo/backend/src/modules/*/repository.ts 2>/dev/null +done +``` + +**Agent action:** Fix violations. Commit with `fix(): remove console.log` / `fix(): replace hardcoded colors with tokens`. + +--- + +## 9. AGENTS.md Consistency Check + +**Frequency:** After structural changes, or monthly +**Trigger phrase:** "Audit AGENTS.md across repos" + +Each repo's `AGENTS.md` must accurately reflect: + +- Current repo layout (directories, key files) +- Current test counts +- Current build/test commands +- API endpoint tables (backend repos) + +```bash +for repo in ...; do + if [ -f "/Users/sd9235/code/mygh/$repo/AGENTS.md" ]; then + echo "=== $repo ===" + # Check if test counts in AGENTS.md match actual + ACTUAL=$(cd /Users/sd9235/code/mygh/$repo/backend && npx vitest run 2>&1 | grep "Tests " | grep -o "[0-9]* passed" | head -1) + DOCUMENTED=$(grep -o "[0-9]* .*test" /Users/sd9235/code/mygh/$repo/AGENTS.md | head -1) + echo " Actual: $ACTUAL | Documented: $DOCUMENTED" + fi +done +``` + +**Agent action:** Update stale AGENTS.md files. Use the existing `/repo_update-agent-docs` workflow. + +--- + +## 10. Docker & Dockerfile Audit + +**Frequency:** Quarterly, or before deployments +**Trigger phrase:** "Audit Dockerfiles" + +Check that all repos with Dockerfiles have: + +- Multi-stage builds +- `.dockerignore` present +- `docker-compose.yml` references correct ports +- `scripts/docker-prep.sh` works (packs @bytelyst/\* tarballs) + +```bash +for repo in ...; do + [ -f "/Users/sd9235/code/mygh/$repo/Dockerfile" ] || [ -f "/Users/sd9235/code/mygh/$repo/backend/Dockerfile" ] && echo "$repo has Dockerfile" + [ -f "/Users/sd9235/code/mygh/$repo/docker-compose.yml" ] && echo "$repo has docker-compose.yml" +done +``` + +--- + +## 11. CI/CD Workflow Audit + +**Frequency:** Quarterly +**Trigger phrase:** "Audit CI workflows" + +Each repo with a `.github/workflows/ci.yml` should: + +- Run backend tests (`npm test` or `vitest run`) +- Run web tests +- Run typecheck (`tsc --noEmit`) +- Match the actual build commands in `package.json` + +```bash +for repo in ...; do + CI="/Users/sd9235/code/mygh/$repo/.github/workflows/ci.yml" + [ -f "$CI" ] && echo "=== $repo ===" && grep "run:" "$CI" | head -10 +done +``` + +**Agent action:** Flag workflows that are disabled (`.yml.disabled`) or missing expected steps. + +--- + +## Automation Priority Matrix + +| Task | Impact | Effort | Frequency | Priority | +| --------------------- | -------- | ------ | ------------- | ----------- | +| Dirty changes check | High | 1 min | Every session | 🔴 Critical | +| Backend test run | High | 2 min | Weekly | 🔴 Critical | +| Web test run | High | 2 min | Weekly | 🔴 Critical | +| Backend coverage gaps | High | 30 min | Monthly | 🟡 High | +| TypeScript typecheck | Medium | 5 min | Weekly | 🟡 High | +| Secret scan | Critical | 1 min | Every commit | 🔴 Critical | +| Unused deps cleanup | Medium | 15 min | Monthly | 🟡 High | +| console.log/print() | Low | 10 min | Monthly | 🟢 Medium | +| Hardcoded colors | Low | 10 min | Monthly | 🟢 Medium | +| AGENTS.md sync | Medium | 20 min | Monthly | 🟡 High | +| Web coverage gaps | Medium | 30 min | Monthly | 🟡 High | +| Docker audit | Low | 10 min | Quarterly | 🟢 Medium | +| CI workflow audit | Medium | 15 min | Quarterly | 🟢 Medium | + +--- + +## Quick-Start Commands + +### Full health check (run all critical tasks): + +``` +Run workspace hygiene sweep, then cross-repo test audit, then typecheck sweep +``` + +### Monthly maintenance: + +``` +Run backend test coverage audit, then web test coverage audit, then dependency health check, then code quality audit, then audit AGENTS.md across repos +``` + +### Pre-release checklist: + +``` +Run workspace hygiene sweep, then cross-repo test audit, then typecheck sweep, then secret scan, then audit Dockerfiles +``` + +--- + +## Existing Workflows (reference) + +These Windsurf workflows in `.windsurf/workflows/` are related and can be composed with the tasks above: + +| Workflow | Purpose | +| -------------------------- | --------------------------------------------- | +| `/repo_commit-workspace` | Commit all workspace changes in logical order | +| `/repo_push-repos` | Push local main to origin for all repos | +| `/repo_sync-repos` | Pull latest from origin main across all repos | +| `/repo_backup-main-branch` | Smart backup of main branches | +| `/repo_update-agent-docs` | Regenerate AGENTS.md across all repos | +| `/run-code-review` | Advanced code review for PRs | +| `/production-readiness` | Full production readiness check | +| `/test-coverage` | Run tests with coverage across repos | + +--- + +## Revision History + +| Date | Change | +| ---------- | ----------------------------------------------------------- | +| 2026-03-21 | Initial version — 11 automation tasks, baseline test counts |