learning_ai_common_plat/docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md

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.

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.

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)

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)

# 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

cd /Users/sd9235/code/mygh/learning_ai_common_plat
pnpm test    # runs all package + service tests

2d. Mobile Tests (Expo / native)

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

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:

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"

# 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

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:

for repo in ...; do
  echo "=== $repo ==="
  grep "@bytelyst/" /Users/sd9235/code/mygh/$repo/web/package.json 2>/dev/null | sort
done

6c. Outdated Packages

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"

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

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

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

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:

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)

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)

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

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