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
This commit is contained in:
saravanakumardb1 2026-03-21 09:04:35 -07:00
parent af5684587d
commit 2e35334e13

View File

@ -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> 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 <module>`
---
## 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(<scope>): 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(<scope>): remove unused deps` or `fix(<scope>): 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(<scope>): remove console.log` / `fix(<scope>): 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 |