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

**Current backend baseline (2026-03-21):**

| Service              | Test Files | Tests | Status |
| -------------------- | ---------- | ----- | ------ |
| `platform-service`   | 117        | 1,344 | ✅     |
| `extraction-service` | 12         | 136   | ✅     |

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

Shared services can be audited the same way when the change touches common infrastructure:

```bash
for service in platform-service extraction-service; do
  echo "=== $service ==="
  BDIR="/Users/sd9235/code/mygh/learning_ai_common_plat/services/$service/src/modules"
  for mod in $(ls -d $BDIR/*/ 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
```

**Current note (2026-03-21):** Product backends and shared common-platform backend modules all have colocated test coverage, including `platform-service/src/modules/ai-diagnostics`.

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