bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(prompts): add 14 reusable AI prompts for ecosystem-wide workflows

Browse Source 
- roadmap-execution: phased roadmap execution with checkpoints
- new-product-scaffold: scaffold new ByteLyst product repos
- prd-to-implementation: convert PRDs to concrete plans
- cross-repo-debug: systematic multi-repo debugging
- backend-module-crud: Fastify CRUD modules (types/repo/routes/tests)
- platform-integration: wire products into common platform
- refactor-with-tests: test-first safe refactoring
- test-gap-analysis: coverage gap identification and remediation
- type-safety-sweep: TypeScript error triage and fix
- dependency-health-check: cross-repo dependency audit
- pre-release-validation: comprehensive release checklist
- docker-production-prep: production Docker images
- agents-md-sync: keep AI instruction files accurate
- ecosystem-audit: full ecosystem health dashboard
This commit is contained in:
saravanakumardb 2026-05-17 16:48:30 -07:00
parent 7a99bf19d0
commit 32c7b1ba7e
15 changed files with 2256 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
AI.dev/PROMPTS/README.md Normal file
View File

@ -0,0 +1,75 @@
# ByteLyst Ecosystem — Reusable AI Prompts
> **Location:** `AI.dev/PROMPTS/`
> **Audience:** Claude Code, Codex, Cursor, Copilot, Windsurf Cascade, Gemini, and any AI coding agent.
> **Scope:** All 37 repos in `D:\BYTELYST\CODE\` — common platform, product repos, tooling repos.
---
## How to Use
Copy-paste a prompt into your AI assistant, or reference it by path:
```
@file AI.dev/PROMPTS/roadmap-execution.md
```
Each prompt is **self-contained** — it includes the context the agent needs without
requiring you to manually explain the ecosystem every time.
## Prompt Index
### 🗺️ Planning & Roadmap
| Prompt | Purpose |
|--------|---------|
| [roadmap-execution.md](./roadmap-execution.md) | Execute a phased roadmap with checkpoints, commits, and validation |
| [new-product-scaffold.md](./new-product-scaffold.md) | Scaffold a new ByteLyst product repo from scratch |
| [prd-to-implementation.md](./prd-to-implementation.md) | Convert a PRD into a concrete, phased implementation plan |
### 🔧 Development & Debugging
| Prompt | Purpose |
|--------|---------|
| [cross-repo-debug.md](./cross-repo-debug.md) | Systematically debug issues spanning multiple repos |
| [backend-module-crud.md](./backend-module-crud.md) | Add a complete Fastify CRUD module (types → repo → routes → tests) |
| [platform-integration.md](./platform-integration.md) | Wire a product repo into the common platform ecosystem |
| [refactor-with-tests.md](./refactor-with-tests.md) | Safely refactor code with test-first methodology |
### 🧪 Quality & Testing
| Prompt | Purpose |
|--------|---------|
| [test-gap-analysis.md](./test-gap-analysis.md) | Identify and fill test coverage gaps in any repo |
| [type-safety-sweep.md](./type-safety-sweep.md) | Fix TypeScript errors across a repo or the workspace |
| [dependency-health-check.md](./dependency-health-check.md) | Audit and update dependencies across repos |
### 📦 Release & Ops
| Prompt | Purpose |
|--------|---------|
| [pre-release-validation.md](./pre-release-validation.md) | Full pre-release checklist: build, test, lint, security |
| [docker-production-prep.md](./docker-production-prep.md) | Prepare Docker images for production deployment |
### 📚 Documentation
| Prompt | Purpose |
|--------|---------|
| [agents-md-sync.md](./agents-md-sync.md) | Update AGENTS.md across all repos to match current state |
| [ecosystem-audit.md](./ecosystem-audit.md) | Full ecosystem health audit with actionable report |
---
## Conventions
- **Agent-agnostic:** Prompts work across Claude, Copilot, Cursor, Windsurf, Gemini.
- **Ecosystem-aware:** Each prompt embeds the key ByteLyst conventions (productId, Fastify module pattern, @bytelyst/* packages, pnpm workspace).
- **Commit-friendly:** Prompts that produce code changes include commit message guidance.
- **Incremental:** Each prompt favors small, validated, committed steps over big-bang changes.
## Adding a New Prompt
1. Create `AI.dev/PROMPTS/<prompt-name>.md`
2. Include a YAML-style header with `name`, `description`, `argument-hint`
3. Add it to this index
4. Commit: `docs(prompts): add <prompt-name> reusable prompt`

119
AI.dev/PROMPTS/agents-md-sync.md Normal file
View File

@ -0,0 +1,119 @@
---
name: agents-md-sync
description: 'Audit and update AGENTS.md files across all ByteLyst repos to match current codebase reality — layout, test counts, API endpoints, packages.'
argument-hint: 'Scope, e.g. "all repos", "learning_ai_efforise only", "test counts only"'
agent: agent
---
# AGENTS.md Sync Prompt
Ensure all AGENTS.md files across the ByteLyst ecosystem accurately reflect the current state of each repository.
## Context — What AGENTS.md Does
AGENTS.md is the **primary instruction file for AI coding assistants** (Claude Code, Copilot, Cursor, Windsurf, Gemini). It must be accurate because:
- AI agents read it before making changes
- Incorrect docs lead to incorrect code
- Stale test counts erode agent trust
- Wrong layout trees cause file-not-found errors
## Standard AGENTS.md Sections
Every ByteLyst repo should have these sections:
1. **Project Identity** — product name, ID, bundle IDs, ports, ecosystem
2. **Repo Layout** — file tree (keep up to date!)
3. **Tech Stack** — frameworks, languages, tools per layer
4. **Coding Conventions** — MUST follow / MUST NOT do
5. **.npmrc rules** — never edit directly
6. **Cosmos Containers** (if backend) — container, partition key, purpose
7. **Build & Test Commands** — exact `pnpm` commands
8. **API Endpoints** (if backend) — method, path, description
9. **Environment Variables** — var, default, description
10. **Current State** (optional) — phases, commits, test counts
11. **Cross-Repo Automation** — link to CODING_AGENT_AUTOMATION_PLAYBOOK.md
## Sync Protocol
### Step 1: Scan Each Repo
For each repo, programmatically verify:
```bash
# File tree matches layout section
find . -type f -name "*.ts" -o -name "*.tsx" -o -name "*.swift" -o -name "*.kt" | head -50
# Test count matches
pnpm test --reporter=verbose 2>&1 | tail -5
# API endpoints match (backend)
grep -r "app\.\(get\|post\|patch\|put\|delete\)" backend/src/modules/*/routes.ts
# Package count matches
ls node_modules/@bytelyst/ 2>/dev/null | wc -l
# Cosmos containers match
grep -r "getCollection\|getContainer" backend/src/modules/*/repository.ts
```
### Step 2: Identify Drift
Compare AGENTS.md content against reality:
| Section | Check | Drift Signal |
|---------|-------|-------------|
| Repo Layout | `find` vs documented tree | New dirs/files not listed |
| Tech Stack | package.json deps | New framework not mentioned |
| Test Counts | `pnpm test` output | Count differs by >5 |
| API Endpoints | route file scan | Missing endpoints |
| Cosmos Containers | repository scan | New containers |
| Packages Used | node_modules scan | New @bytelyst/* packages |
| Ports | shared/product.json | Port mismatch |
### Step 3: Update AGENTS.md
For each drift found:
- Update the specific section
- Preserve all existing comments and documentation
- Keep formatting consistent with other repos
### Step 4: Update CLAUDE.md
If AGENTS.md changed significantly, also sync CLAUDE.md (the Claude Code-specific instruction file).
### Step 5: Commit Per Repo
```bash
cd <repo>
git add AGENTS.md CLAUDE.md
git commit -m "docs(agents): sync AGENTS.md with current repo state
- Updated: <sections that changed>
- Test count: X → Y
- <other changes>"
git push
```
## Report Format
```markdown
## AGENTS.md Sync Report
| Repo | Status | Sections Updated | Commit |
|------|--------|-----------------|--------|
| learning_ai_common_plat | ✅ Up to date | — | — |
| learning_ai_efforise | 🔄 Updated | Layout, Tests | abc123 |
| learning_ai_flowmonk | 🔄 Updated | API Endpoints | def456 |
| learning_ai_dev_intelli | ❌ Skipped | — | Needs manual review |
### Key Findings
- <finding 1>
- <finding 2>
```
## Guardrails
- **Never delete documentation** — only add or update
- **Preserve comments** — keep existing notes and explanations
- **Verify before commit** — run `pnpm typecheck` to ensure no doc references break
- **One repo per commit** — keep history clean

246
AI.dev/PROMPTS/backend-module-crud.md Normal file
View File

@ -0,0 +1,246 @@
---
name: backend-module-crud
description: 'Add a complete Fastify CRUD module with types, repository, routes, and tests following ByteLyst conventions.'
argument-hint: 'Module name and parent repo, e.g. "habits in efforise", "workouts in peakpulse", "conversations in jarvisjr"'
agent: agent
---
# Backend Module CRUD Prompt
Create a complete Fastify backend module with Zod-validated types, Cosmos repository, REST routes, and comprehensive tests.
## Context — ByteLyst Backend Pattern
Every product backend follows this module structure:
```
backend/src/modules/<module>/
├── types.ts # Zod schemas + TypeScript interfaces
├── repository.ts # Cosmos DB CRUD operations
├── routes.ts # Fastify REST endpoints
└── <module>.test.ts # Vitest tests
```
**Key packages used:**
- `@bytelyst/datastore` — Cosmos DB abstraction (`getCollection()`)
- `@bytelyst/errors` — Typed HTTP errors (`BadRequestError`, `NotFoundError`, etc.)
- `@bytelyst/fastify-auth` — JWT auth middleware
- `zod` — Schema validation (service's own copy, NOT from @bytelyst/config)
## Implementation Steps
### 1. Create `types.ts`
```typescript
import { z } from 'zod';
// ── Create schema (input from API) ──
export const create<Entity>Schema = z.object({
// Required fields
name: z.string().min(1).max(200),
// Optional fields
description: z.string().max(1000).optional(),
// Enum fields
status: z.enum(['active', 'paused', 'completed']).default('active'),
});
// ── Update schema (partial, for PATCH) ──
export const update<Entity>Schema = create<Entity>Schema.partial();
// ── Full document (stored in Cosmos) ──
export const <entity>Schema = create<Entity>Schema.extend({
id: z.string().uuid(),
userId: z.string(),
productId: z.string(),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime(),
});
// ── TypeScript types ──
export type Create<Entity> = z.infer<typeof create<Entity>Schema>;
export type Update<Entity> = z.infer<typeof update<Entity>Schema>;
export type <Entity> = z.infer<typeof <entity>Schema>;
```
### 2. Create `repository.ts`
```typescript
import { getCollection } from '../../lib/datastore.js';
import type { Create<Entity>, Update<Entity>, <Entity> } from './types.js';
import { NotFoundError } from '../../lib/errors.js';
import { randomUUID } from 'node:crypto';
const CONTAINER = '<product>_<entities>';
function getContainer() {
return getCollection(CONTAINER);
}
export async function create<Entity>(
userId: string,
productId: string,
data: Create<Entity>
): Promise<<Entity>> {
const now = new Date().toISOString();
const doc: <Entity> = {
...data,
id: randomUUID(),
userId,
productId,
createdAt: now,
updatedAt: now,
};
const container = getContainer();
await container.create(doc);
return doc;
}
export async function list<Entities>(
userId: string,
productId: string
): Promise<<Entity>[]> {
const container = getContainer();
return container.query<Entity>({
query: 'SELECT * FROM c WHERE c.userId = @userId AND c.productId = @productId ORDER BY c.createdAt DESC',
parameters: [
{ name: '@userId', value: userId },
{ name: '@productId', value: productId },
],
});
}
export async function get<Entity>ById(
id: string,
userId: string,
productId: string
): Promise<<Entity>> {
const container = getContainer();
const doc = await container.read<Entity>(id, userId);
if (!doc || doc.productId !== productId) {
throw new NotFoundError('<Entity> not found');
}
return doc;
}
export async function update<Entity>(
id: string,
userId: string,
productId: string,
data: Update<Entity>
): Promise<<Entity>> {
const existing = await get<Entity>ById(id, userId, productId);
const updated: <Entity> = {
...existing,
...data,
updatedAt: new Date().toISOString(),
};
const container = getContainer();
await container.replace(id, updated, userId);
return updated;
}
export async function delete<Entity>(
id: string,
userId: string,
productId: string
): Promise<void> {
await get<Entity>ById(id, userId, productId); // Verify ownership
const container = getContainer();
await container.delete(id, userId);
}
```
### 3. Create `routes.ts`
```typescript
import type { FastifyInstance } from 'fastify';
import { create<Entity>Schema, update<Entity>Schema } from './types.js';
import * as repo from './repository.js';
import { getUserId, getRequestProductId } from '../../lib/request-context.js';
export default async function <entity>Routes(app: FastifyInstance) {
// GET /api/<entities>
app.get('/<entities>', async (req) => {
const userId = getUserId(req);
const productId = getRequestProductId(req);
return repo.list<Entities>(userId, productId);
});
// GET /api/<entities>/:id
app.get('/<entities>/:id', async (req) => {
const { id } = req.params as { id: string };
const userId = getUserId(req);
const productId = getRequestProductId(req);
return repo.get<Entity>ById(id, userId, productId);
});
// POST /api/<entities>
app.post('/<entities>', async (req, reply) => {
const userId = getUserId(req);
const productId = getRequestProductId(req);
const data = create<Entity>Schema.parse(req.body);
const entity = await repo.create<Entity>(userId, productId, data);
reply.code(201);
return entity;
});
// PATCH /api/<entities>/:id
app.patch('/<entities>/:id', async (req) => {
const { id } = req.params as { id: string };
const userId = getUserId(req);
const productId = getRequestProductId(req);
const data = update<Entity>Schema.parse(req.body);
return repo.update<Entity>(id, userId, productId, data);
});
// DELETE /api/<entities>/:id
app.delete('/<entities>/:id', async (req, reply) => {
const { id } = req.params as { id: string };
const userId = getUserId(req);
const productId = getRequestProductId(req);
await repo.delete<Entity>(id, userId, productId);
reply.code(204);
});
}
```
### 4. Register in `server.ts`
```typescript
import <entity>Routes from './modules/<entities>/routes.js';
// ...
await app.register(<entity>Routes, { prefix: '/api' });
```
### 5. Create tests
Write tests covering:
- ✅ Create with valid data → 201
- ✅ Create with invalid data → 400
- ✅ List returns user's items only
- ✅ Get by ID returns correct item
- ✅ Get by ID with wrong user → 404
- ✅ Update modifies fields + updatedAt
- ✅ Delete removes item → 204
- ✅ Delete with wrong user → 404
### 6. Validate
```bash
cd backend
pnpm test
pnpm typecheck
pnpm build
```
### 7. Commit
```bash
git add .
git commit -m "feat(<entities>): add <entity> CRUD module
- types.ts: Zod schemas for create/update/<entity>
- repository.ts: Cosmos CRUD with user ownership
- routes.ts: GET/POST/PATCH/DELETE endpoints
- tests: N tests covering CRUD + auth + validation"
git push
```

145
AI.dev/PROMPTS/cross-repo-debug.md Normal file
View File

@ -0,0 +1,145 @@
---
name: cross-repo-debug
description: 'Systematically debug issues that span multiple ByteLyst repos, tracing from symptom to root cause across service boundaries.'
argument-hint: 'Symptom description, e.g. "auth token rejected by FlowMonk backend", "design tokens not applied in PeakPulse iOS", "platform-service 500 on /api/flags"'
agent: agent
---
# Cross-Repo Debug Prompt
Systematically diagnose and fix bugs that span multiple repositories in the ByteLyst ecosystem.
## Context — ByteLyst Architecture
**Service topology:**
```
Product clients (web/mobile)
→ Product backend (Fastify, port 40xx)
→ @bytelyst/* packages (shared libraries)
→ platform-service (port 4003: auth, flags, billing, etc.)
→ Cosmos DB (productId multi-tenancy)
→ Azurite (blob storage)
```
**Common cross-repo failure points:**
1. **Auth chain:** platform-service issues JWT → product backend validates → client stores
2. **Package version mismatch:** Zod, jose, or @azure/cosmos version conflicts between packages and services
3. **Config drift:** .env vars, .npmrc, or product.json out of sync
4. **API contract breaks:** platform-service endpoint changed but consumer not updated
5. **Design token gaps:** token JSON updated but generated files not regenerated/copied
## Debug Protocol
### Step 1: Symptom Capture
Document:
- **What:** Exact error message, HTTP status, or unexpected behavior
- **Where:** Which repo/service/file/line
- **When:** Always, intermittent, or after a specific change
- **Who:** Which product(s) affected
### Step 2: Trace the Call Chain
Starting from the symptom, trace backwards:
```
1. Client (web/mobile) — check network tab, API client code
2. Product backend — check routes.ts, request-context.ts, auth.ts
3. Shared packages — check @bytelyst/* import versions
4. Platform service — check the module handling this request
5. Data layer — check Cosmos queries, partition keys, productId
```
For each layer, check:
- Is the service running? (`curl http://localhost:<port>/health`)
- Are env vars set? (compare with `.env.example`)
- Are packages built? (`pnpm build` in common_plat)
- Are types aligned? (`pnpm typecheck`)
### Step 3: Isolate
Run targeted tests to narrow scope:
```bash
# Test the specific module
pnpm --filter @lysnrai/platform-service test -- --grep "auth"
pnpm --filter @bytelyst/auth test
# Test the product backend
cd <product>/backend && pnpm test
# Typecheck across repos
cd learning_ai_common_plat && pnpm typecheck
cd <product> && pnpm typecheck
```
### Step 4: Fix
- Fix in the **lowest-level** repo first (packages → services → products)
- Rebuild packages if you changed a `@bytelyst/*` package:
```bash
cd learning_ai_common_plat && pnpm build
```
- Reinstall in consumer repos if package API changed:
```bash
cd <product> && pnpm install
```
### Step 5: Validate Across Repos
After fixing:
```bash
# 1. Rebuild common platform
cd learning_ai_common_plat && pnpm build && pnpm test
# 2. Reinstall + test affected products
cd <product> && pnpm install && pnpm test
# 3. Verify health endpoints
curl -s http://localhost:4003/health | jq .
curl -s http://localhost:<product-port>/health | jq .
```
### Step 6: Commit in Correct Repos
Commit in dependency order:
```bash
# Fix in common_plat first
cd learning_ai_common_plat
git add . && git commit -m "fix(<package>): <description>" && git push
# Then fix in product repo
cd <product>
git add . && git commit -m "fix(<scope>): <description>" && git push
```
## Common Diagnosis Patterns
### "Module not found" or import errors
- Check: Was `pnpm build` run in common_plat?
- Check: Are `file:` refs in product's `package.json` pointing to correct paths?
- Check: Is the export in the package's `src/index.ts`?
### "Zod validation failed" or schema errors
- Check: Service uses self-contained Zod schemas in `src/lib/config.ts` (not from @bytelyst/config)
- Check: Zod version alignment between package and service
### "401 Unauthorized" across services
- Check: JWT_SECRET matches between platform-service and product backend
- Check: Token is being forwarded in `Authorization: Bearer` header
- Check: Product backend's auth.ts re-exports correctly from @bytelyst/auth
### Design tokens not working
- Check: Token generator was run (`pnpm --filter @bytelyst/design-tokens generate`)
- Check: Generated files were copied to consumer repos
- Check: CSS custom properties use correct product prefix (--er-*, --fm-*, --di-*, etc.)
## Output
For each issue found, report:
```
### Issue: <title>
- **Root cause:** <repo>/<file> — <explanation>
- **Fix:** <what was changed>
- **Commit:** `<hash>` in `<repo>`
- **Validated:** <test commands run>
```

139
AI.dev/PROMPTS/dependency-health-check.md Normal file
View File

@ -0,0 +1,139 @@
---
name: dependency-health-check
description: 'Audit dependencies across ByteLyst repos for outdated packages, security vulnerabilities, version conflicts, and unused deps.'
argument-hint: 'Scope, e.g. "all repos", "learning_ai_common_plat only", "security audit only"'
agent: agent
---
# Dependency Health Check Prompt
Audit and remediate dependency issues across the ByteLyst ecosystem.
## Context — ByteLyst Dependency Conventions
- **Package manager:** pnpm (workspace) — never npm or yarn
- **Heavy deps:** Use `peerDependencies` in `@bytelyst/*` packages, NOT `dependencies`
- **Workspace refs:** `"@bytelyst/<name>": "workspace:*"` for internal deps
- **Product refs:** `"@bytelyst/<name>": "file:../../learning_ai_common_plat/packages/<name>"` for product repos
- **Node version:** 22 (see `.nvmrc`)
- **Key shared deps:** `@azure/cosmos`, `jose`, `bcryptjs`, `zod`, `fastify`
## Audit Protocol
### Step 1: Scan Dependencies
For each repo:
```bash
# Check for outdated packages
pnpm outdated
# Security audit
pnpm audit
# Check for unused dependencies
npx depcheck
# Check for duplicate packages
pnpm why <package>
```
### Step 2: Classify Issues
| Severity | Type | Action |
|----------|------|--------|
| 🔴 **Critical** | Known security vulnerability (CVE) | Update immediately |
| 🔴 **Critical** | Major version conflict causing runtime errors | Resolve version |
| 🟡 **High** | Outdated major version with breaking changes | Plan upgrade |
| 🟡 **High** | Unused dependency adding bundle bloat | Remove |
| 🔵 **Medium** | Minor/patch updates available | Batch update |
| ⚪ **Low** | Cosmetic (deprecated warning, newer alternative) | Track for later |
### Step 3: Check Cross-Repo Version Alignment
Ensure these critical packages are aligned across all repos:
| Package | Expected Range | Check |
|---------|---------------|-------|
| `typescript` | `^5.7` | All repos |
| `zod` | `^3.23` | All repos using Zod |
| `fastify` | `^5` | All backends |
| `vitest` | `^3` | All repos with tests |
| `jose` | `^5` or `^6` | Auth-related packages |
| `@azure/cosmos` | `^4` | Data layer |
| `react` | `^19` | Web/mobile clients |
| `next` | `^15` or `^16` | Next.js web apps |
### Step 4: Safe Update Process
#### Minor/patch updates (low risk):
```bash
pnpm update
pnpm test
pnpm typecheck
git add . && git commit -m "chore(deps): update minor/patch dependencies" && git push
```
#### Major updates (higher risk):
```bash
# Update one package at a time
pnpm update <package>@latest
# Test immediately
pnpm test
pnpm typecheck
pnpm build
# Commit separately
git add . && git commit -m "chore(deps): upgrade <package> to v<version>" && git push
```
#### Cross-repo updates:
```bash
# 1. Update in common_plat first
cd learning_ai_common_plat
pnpm update <package>@latest
pnpm build && pnpm test
git add . && git commit -m "chore(deps): upgrade <package>" && git push
# 2. Then update in product repos
cd <product>
pnpm install # Picks up new versions from common_plat
pnpm test
git add . && git commit -m "chore(deps): sync <package> version" && git push
```
### Step 5: Report
```markdown
## Dependency Health Check: <Scope>
### Executive Summary
- Repos audited: N
- Critical issues: N
- Updates available: N
- Unused deps found: N
### Critical Issues
| Repo | Package | Issue | Action |
|------|---------|-------|--------|
### Version Alignment
| Package | Expected | Repos In Sync | Repos Mismatched |
|---------|----------|---------------|------------------|
### Recommended Updates
| Priority | Repo | Package | Current | Target | Risk |
|----------|------|---------|---------|--------|------|
### Unused Dependencies
| Repo | Package | Safe to Remove |
|------|---------|---------------|
```
## Guardrails
- **Never update all dependencies at once** — do it incrementally
- **Always test after each update** — `pnpm test && pnpm typecheck && pnpm build`
- **Update common_plat first** — product repos depend on it
- **Check peerDependencies** — ensure package consumers are compatible
- **Don't force-resolve version conflicts** — understand why they exist first

195
AI.dev/PROMPTS/docker-production-prep.md Normal file
View File

@ -0,0 +1,195 @@
---
name: docker-production-prep
description: 'Prepare Docker images for production deployment following ByteLyst conventions for corporate network, multi-stage builds, and security.'
argument-hint: 'Product and surface, e.g. "efforise backend", "flowmonk backend + web", "all product backends"'
agent: agent
---
# Docker Production Prep Prompt
Build production-ready Docker images for ByteLyst services following network, security, and performance best practices.
## Context — ByteLyst Docker Conventions
**Critical rules from corporate network:**
- **Never use Alpine** — `apk` cannot bypass TLS interception; use `node:22-slim` (Debian)
- **Never use `corepack`** in Dockerfiles — use `npm install -g pnpm@10` or plain `npm`
- **Always add** `npm config set strict-ssl false` before any `npm install` in build stages
- **Always add** `ENV NODE_TLS_REJECT_UNAUTHORIZED=0` in build stages with native modules
- **Production images** don't need these workarounds (only build stages)
## Dockerfile Template (Backend Service)
```dockerfile
# ── Build Stage ────────────────────────────────────
FROM node:22-slim AS builder
# Corporate network workaround (build stage only)
RUN npm config set strict-ssl false
ENV NODE_TLS_REJECT_UNAUTHORIZED=0
WORKDIR /app
# Install pnpm (never use corepack)
RUN npm install -g pnpm@10
# Copy workspace files
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY backend/package.json backend/
COPY shared/ shared/
# Copy @bytelyst/* tarballs (if using prep-consumer.sh)
COPY .bytelyst-tarballs/ .bytelyst-tarballs/
# Install dependencies
RUN pnpm install --frozen-lockfile
# Copy source and build
COPY backend/ backend/
RUN cd backend && pnpm build
# ── Production Stage ───────────────────────────────
FROM node:22-slim AS production
WORKDIR /app
# Non-root user for security
RUN groupadd -r appuser && useradd -r -g appuser appuser
# Copy only production artifacts
COPY --from=builder /app/backend/dist/ ./dist/
COPY --from=builder /app/backend/package.json ./
COPY --from=builder /app/shared/ ./shared/
COPY --from=builder /app/node_modules/ ./node_modules/
# Security headers
ENV NODE_ENV=production
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD node -e "fetch('http://localhost:${PORT:-4020}/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"
# Run as non-root
USER appuser
EXPOSE ${PORT:-4020}
CMD ["node", "dist/server.js"]
```
## Preparation Steps
### 1. Pack @bytelyst/* Dependencies
If the Docker build doesn't have access to the sibling common_plat repo:
```bash
cd ../learning_ai_common_plat
./scripts/prep-consumer.sh /path/to/<product>
```
This packs tarballs and rewrites `file:` refs in package.json.
### 2. Create/Update docker-compose.yml
```yaml
services:
backend:
build:
context: .
dockerfile: backend/Dockerfile
ports:
- "${PORT:-4020}:${PORT:-4020}"
env_file: ./backend/.env
restart: unless-stopped
depends_on:
platform-service:
condition: service_healthy
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://localhost:${PORT:-4020}/health')"]
interval: 30s
timeout: 3s
retries: 3
web:
build:
context: .
dockerfile: web/Dockerfile
ports:
- "3000:3000"
environment:
- NEXT_PUBLIC_API_URL=http://backend:${PORT:-4020}
```
### 3. Build & Test Locally
```bash
# Build
docker compose build
# Run
docker compose up -d
# Verify health
docker compose ps
curl -s http://localhost:<port>/health | jq .
# Check logs
docker compose logs backend --tail=20
# Run smoke test
curl -s http://localhost:<port>/api/<endpoint> | jq .
# Cleanup
docker compose down
```
### 4. Security Scan
```bash
# Scan the built image
docker scout cves <image>
# Check for leaked secrets
docker history <image> --no-trunc | grep -i "secret\|key\|password"
```
### 5. Optimize Image Size
```bash
# Check image size
docker images | grep <product>
# Target: < 200MB for backend services
# If too large, check:
# - Are devDependencies excluded? (use --prod install)
# - Is the build stage copying unnecessary files?
# - Are node_modules pruned in the production stage?
```
### 6. Commit
```bash
git add Dockerfile docker-compose.yml
git commit -m "chore(docker): production-ready Docker setup
- Multi-stage build (builder + production)
- Non-root user for security
- Health check configured
- Corporate network workarounds in build stage only
- Production image: ~NMB"
git push
```
## Checklist
- [ ] Base image: `node:22-slim` (never Alpine)
- [ ] No `corepack` usage
- [ ] `strict-ssl false` in build stage
- [ ] Multi-stage build (builder → production)
- [ ] Non-root user in production stage
- [ ] Health check configured
- [ ] `NODE_ENV=production` in production stage
- [ ] No secrets in image layers
- [ ] `.dockerignore` excludes: node_modules, .git, .env, dist, coverage
- [ ] Image size < 200MB

148
AI.dev/PROMPTS/ecosystem-audit.md Normal file
View File

@ -0,0 +1,148 @@
---
name: ecosystem-audit
description: 'Run a full health audit across the ByteLyst ecosystem — builds, tests, types, dependencies, config drift, and produce an actionable dashboard.'
argument-hint: 'Depth and focus, e.g. "full audit", "quick health check", "backend focus", "config drift only"'
agent: agent
---
# Ecosystem Audit Prompt
Produce a comprehensive health dashboard across all ByteLyst repos with actionable findings.
## Context — ByteLyst Ecosystem
**37 repos** in `D:\BYTELYST\CODE\`, including:
**Core platform:**
- `learning_ai_common_plat` — shared packages + services
**Active products (with backends):**
- `learning_ai_efforise` (EffoRise, port 4020)
- `learning_ai_flowmonk` (FlowMonk, port 4017)
- `learning_ai_dev_intelli` (DevIntelli, port 4021)
- `learning_ai_peakpulse` (PeakPulse, port 4010)
- `learning_ai_clock` (ChronoMind, port 4011)
- `learning_ai_jarvis_jr` (JarvisJr, port 4012)
- `learning_ai_fastgap` (NomGap, port 4013)
- `learning_multimodal_memory_agents` (MindLyst, port 4014)
**Active products (platform-only):**
- `learning_ai_auth_app` (ByteLyst Auth — no backend)
- `learning_ai_notes` (NoteLett)
- `learning_ai_trails` (ActionTrail)
**Tooling & infrastructure:**
- `learning_ai_local_llms`, `learning_ai_local_memory_gpt`
- `learning_windsurf_setup`, `learning_claude_code_setup`, `learning_sidecar_setup`
- `learning_agent_monitoring_fx`, `learning_agentic_tools_portal`
## Audit Dimensions
### 1. Build Health
For each repo with a `package.json`:
```bash
pnpm install --frozen-lockfile # Can deps resolve?
pnpm build # Does it compile?
```
### 2. Type Safety
```bash
pnpm typecheck # TypeScript clean?
```
### 3. Test Health
```bash
pnpm test --run # All tests pass?
```
Record: total tests, passing, failing, skipped.
### 4. Config Consistency
Check alignment across repos:
- `.npmrc` matches canonical template?
- `.nvmrc` specifies Node 22?
- `tsconfig.json` extends base correctly?
- `.editorconfig` present?
- `shared/product.json` correct?
- `.env.example` up to date?
### 5. Package Version Alignment
Verify shared deps are on compatible versions:
- TypeScript, Zod, Fastify, Vitest, React, Next.js
- `@bytelyst/*` packages (all on `workspace:*` or `file:`)
### 6. Security
```bash
pnpm audit
# Check for high/critical vulnerabilities
```
### 7. Documentation Currency
- AGENTS.md matches current layout?
- README.md has setup instructions?
- CLAUDE.md exists?
### 8. Git Hygiene
- Any repos with uncommitted changes?
- Any repos behind remote?
- Any repos with merge conflicts?
## Output: Ecosystem Dashboard
```markdown
# ByteLyst Ecosystem Health Dashboard
> Generated: <date>
## Executive Summary
- Repos audited: N
- 🟢 Healthy: N
- 🟡 Issues: N
- 🔴 Critical: N
## Scorecard
| Repo | Build | Types | Tests | Config | Deps | Security | Docs | Git |
|------|-------|-------|-------|--------|------|----------|------|-----|
| common_plat | ✅ | ✅ | 876/876 | ✅ | ✅ | ✅ | ✅ | clean |
| efforise | ✅ | ✅ | 65/65 | ✅ | ✅ | ⚠️ 2 | ✅ | clean |
| flowmonk | ✅ | ⚠️ 3 | 196/196 | ✅ | ✅ | ✅ | ✅ | dirty |
| ... | | | | | | | | |
## Critical Issues (Fix First)
| Repo | Issue | Impact | Fix |
|------|-------|--------|-----|
## Action Queue (Prioritized)
| # | Repo | Action | Effort | Impact |
|---|------|--------|--------|--------|
| 1 | ... | ... | S/M/L | High/Med/Low |
## Config Drift Report
| Config | Expected | Drifted Repos |
|--------|----------|--------------|
| .npmrc | canonical template | <list> |
| .nvmrc | "22" | <list> |
## Dependency Alignment
| Package | Version | Aligned | Misaligned |
|---------|---------|---------|-----------|
```
## Execution Tips
- **Start with common_plat** — it's the foundation
- **Skip node_modules-only repos** — focus on active development repos
- **Parallelize where possible** — run independent repo checks simultaneously
- **Time-box expensive checks** — if `pnpm install` takes >2min, skip and note
## Commit
```bash
# If you fix issues during audit:
cd <repo>
git add .
git commit -m "fix(<scope>): resolve audit findings
- <finding 1>
- <finding 2>"
git push
```

179
AI.dev/PROMPTS/new-product-scaffold.md Normal file
View File

@ -0,0 +1,179 @@
---
name: new-product-scaffold
description: 'Scaffold a new ByteLyst product repo with backend, web, mobile, and full ecosystem integration.'
argument-hint: 'Product name, ID, and brief description, e.g. "TrackMate, trackmate, GPS-based workout tracker"'
agent: agent
---
# New Product Scaffold Prompt
Create a new ByteLyst ecosystem product from scratch with proper platform integration, shared package usage, and consistent patterns.
## Context — ByteLyst Ecosystem
You are scaffolding a new product in the ByteLyst multi-repo ecosystem (`D:\BYTELYST\CODE\`).
**Sibling products for reference:**
- EffoRise (`learning_ai_efforise`) — identity-based habit tracker
- FlowMonk (`learning_ai_flowmonk`) — agent-first planning platform
- DevIntelli (`learning_ai_dev_intelli`) — developer intelligence
- PeakPulse (`learning_ai_peakpulse`) — fitness tracker
- NomGap (`learning_ai_fastgap`) — fasting tracker
**All products share:**
- `platform-service` (port 4003) for auth, flags, telemetry, billing
- `@bytelyst/*` packages for infrastructure
- Same Fastify module pattern, Zod validation, Vitest testing
- Design tokens from `@bytelyst/design-tokens`
- pnpm workspaces with `file:` refs to common platform
## Scaffold Checklist
### 1. Create Root Structure
```
learning_ai_<repo_name>/
├── backend/ # Fastify 5 product backend
├── web/ or client/ # Next.js or Vite+React SPA
├── mobile/ # React Native + Expo (optional)
├── shared/
│ └── product.json # Canonical product identity
├── docs/
├── scripts/
│ ├── secret-scan-repo.sh
│ └── secret-scan-staged.sh
├── .editorconfig
├── .gitignore
├── .npmrc # From canonical template (never hand-edit)
├── .nvmrc # "22"
├── .windsurfrules
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── package.json # Root workspace scripts
├── pnpm-workspace.yaml
├── docker-compose.yml
└── tsconfig.json
```
### 2. Create `shared/product.json`
```json
{
"productId": "<product_id>",
"productName": "<ProductName>",
"productDescription": "<one-line description>",
"domain": "<product>.app",
"bundleIdIos": "com.bytelyst.<product_id>",
"bundleIdAndroid": "com.bytelyst.<product_id>",
"backendPort": <next_available_port>,
"tokenNamespace": "--<prefix>-"
}
```
**Port allocation:** Check existing products to find the next available port:
- EffoRise: 4020, DevIntelli: 4021, FlowMonk: 4017, PeakPulse: 4010, ChronoMind: 4011, JarvisJr: 4012, NomGap: 4013, MindLyst: 4014
### 3. Backend Setup
Follow the pattern from EffoRise or FlowMonk:
```
backend/
├── src/
│ ├── server.ts # createServiceApp() + startService()
│ ├── lib/
│ │ ├── config.ts # Zod env schema (self-contained, no @bytelyst/config zod)
│ │ ├── product-config.ts # Read shared/product.json
│ │ ├── auth.ts # Re-export from @bytelyst/fastify-auth
│ │ ├── datastore.ts # @bytelyst/datastore bridge
│ │ ├── errors.ts # Re-export from @bytelyst/errors
│ │ ├── field-encrypt.ts # @bytelyst/field-encrypt if needed
│ │ ├── request-context.ts # getUserId(req), getRequestProductId(req)
│ │ ├── telemetry.ts # @bytelyst/backend-telemetry
│ │ └── feature-flags.ts # @bytelyst/backend-flags
│ └── modules/
│ └── <first_module>/ # types.ts → repository.ts → routes.ts
├── __tests__/
├── .env.example
├── Dockerfile
├── package.json
├── tsconfig.json
└── vitest.config.ts
```
**Required `package.json` dependencies:**
```json
{
"dependencies": {
"@bytelyst/fastify-core": "file:../../learning_ai_common_plat/packages/fastify-core",
"@bytelyst/config": "file:../../learning_ai_common_plat/packages/config",
"@bytelyst/errors": "file:../../learning_ai_common_plat/packages/errors",
"@bytelyst/datastore": "file:../../learning_ai_common_plat/packages/datastore",
"@bytelyst/auth": "file:../../learning_ai_common_plat/packages/auth",
"@bytelyst/fastify-auth": "file:../../learning_ai_common_plat/packages/fastify-auth"
}
}
```
### 4. Web Setup
Use Next.js (App Router) or Vite + React. Include:
- Auth via `@bytelyst/react-auth`
- API client via `@bytelyst/api-client`
- Design tokens via `@bytelyst/design-tokens` with product namespace (`--<prefix>-*`)
- UI components via `@bytelyst/ui`
- Feature flags via `@bytelyst/feature-flag-client`
### 5. AGENTS.md
Follow the exact structure from sibling repos. Include:
- Project Identity table
- Repo Layout tree
- Tech Stack table
- Coding Conventions (MUST / MUST NOT)
- Cosmos Containers table
- Build & Test Commands
- Environment Variables
- Cross-Repo Automation reference
### 6. pnpm-workspace.yaml
```yaml
packages:
- 'backend'
- 'web'
- '../learning_ai_common_plat/packages/*'
```
### 7. Validation
After scaffolding:
```bash
pnpm install
cd backend && pnpm typecheck && pnpm test && pnpm build
cd ../web && pnpm typecheck && pnpm build
```
### 8. Commit & Push
```bash
git init
git add .
git commit -m "feat(<product>): scaffold product repo
- Backend: Fastify 5, @bytelyst/* integration, first module
- Web: Next.js/Vite + React, auth + design tokens
- Shared: product.json, AGENTS.md, README.md
- Tests: initial test suite passing"
git remote add origin <remote_url>
git push -u origin main
```
## Guardrails
- **Never hardcode productId** — always read from `shared/product.json`
- **Never use console.log** — use `req.log` / `app.log`
- **Never hand-edit .npmrc** — sync from canonical template
- **Always include tests** — even the scaffold should have passing tests
- **Always include AGENTS.md** — this is the source of truth for AI assistants

181
AI.dev/PROMPTS/platform-integration.md Normal file
View File

@ -0,0 +1,181 @@
---
name: platform-integration
description: 'Wire a product repo into the ByteLyst common platform ecosystem — auth, flags, telemetry, design tokens, and shared packages.'
argument-hint: 'Product repo name and integration scope, e.g. "learning_ai_efforise — full integration", "learning_ai_peakpulse — auth + flags only"'
agent: agent
---
# Platform Integration Prompt
Connect a product repository to the ByteLyst common platform, wiring up auth, feature flags, telemetry, design tokens, and shared packages.
## Context — Integration Architecture
```
Product Repo (e.g. learning_ai_efforise)
├── backend/ ──→ @bytelyst/fastify-core, config, errors, datastore, auth, fastify-auth
├── web/ ──→ @bytelyst/react-auth, api-client, design-tokens, ui, feature-flag-client
├── mobile/ ──→ @bytelyst/auth-client, telemetry-client, feature-flag-client
└── shared/product.json ──→ Product identity consumed by all layers
│
▼
platform-service (port 4003)
├── Auth (JWT issue/validate)
├── Feature flags (FNV-1a rollout)
├── Telemetry (event ingestion)
├── Billing (Stripe subscriptions)
└── Notifications (email, push)
```
## Integration Checklist
### 1. Product Identity (`shared/product.json`)
Ensure this file exists and is correct:
```json
{
"productId": "<product_id>",
"productName": "<ProductName>",
"backendPort": <port>,
"tokenNamespace": "--<prefix>-"
}
```
### 2. Backend Integration
#### Config (`backend/src/lib/config.ts`)
- Self-contained Zod schema (do NOT import zod from @bytelyst/config)
- Include: PORT, HOST, NODE_ENV, DB_PROVIDER, JWT_SECRET, PLATFORM_SERVICE_URL, CORS_ORIGIN
#### Auth (`backend/src/lib/auth.ts`)
- Re-export from `@bytelyst/fastify-auth`
- Wire auth hook in `server.ts` for protected routes
#### Datastore (`backend/src/lib/datastore.ts`)
- Re-export from `@bytelyst/datastore`
- Support `DB_PROVIDER=memory` for dev/test and `DB_PROVIDER=cosmos` for production
#### Product Config (`backend/src/lib/product-config.ts`)
- Read `shared/product.json`
- Export `PRODUCT_ID`, `PRODUCT_NAME`, etc.
#### Request Context (`backend/src/lib/request-context.ts`)
- `getUserId(req)` — extract userId from JWT
- `getRequestProductId(req)` — return productId from config
#### Feature Flags (`backend/src/lib/feature-flags.ts`)
- Initialize `@bytelyst/backend-flags` with product config
- Register product-specific flags
#### Telemetry (`backend/src/lib/telemetry.ts`)
- Initialize `@bytelyst/backend-telemetry`
- Buffer events for platform-service ingestion
#### Diagnostics (`backend/src/lib/register-diagnostics.ts`)
- Register `/api/diagnostics/flags`, `/api/diagnostics/events` routes
- Health endpoint at `GET /health`
### 3. Web Integration
#### Auth (`web/src/lib/auth.ts`)
```typescript
import { createAuthContext } from '@bytelyst/react-auth';
export const { AuthProvider, useAuth } = createAuthContext({
platformUrl: process.env.NEXT_PUBLIC_PLATFORM_SERVICE_URL || 'http://localhost:4003',
productId: '<product_id>',
});
```
#### API Client (`web/src/lib/api-helpers.ts`)
```typescript
import { createApiClient } from '@bytelyst/api-client';
export function createProductClient(getToken: () => string | null) {
return createApiClient({
baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:<port>',
getToken,
});
}
```
#### Design Tokens (`web/src/app/globals.css` or `client/src/index.css`)
- Import `@bytelyst/design-tokens` CSS
- Use product namespace: `--<prefix>-*` custom properties
- Never hardcode hex colors
#### Platform Clients
- `@bytelyst/feature-flag-client` — feature gating
- `@bytelyst/telemetry-client` — event tracking
- `@bytelyst/kill-switch-client` — remote kill switch
- `@bytelyst/diagnostics-client` — health monitoring
### 4. Mobile Integration (if applicable)
- `@bytelyst/auth-client` — login/register/token management
- `@bytelyst/telemetry-client` — event buffering
- `@bytelyst/feature-flag-client` — feature gating
- `@bytelyst/kill-switch-client` — remote disable
- `@bytelyst/offline-queue` — offline-first data sync
### 5. pnpm Workspace Configuration
`pnpm-workspace.yaml`:
```yaml
packages:
- 'backend'
- 'web'
- 'mobile'
- '../learning_ai_common_plat/packages/*'
```
`.npmrc` — sync from canonical template:
```bash
cd ../learning_ai_common_plat && bash scripts/sync-npmrc.sh
```
### 6. Docker Support
`docker-compose.yml`:
```yaml
services:
backend:
build: ./backend
ports:
- "<port>:<port>"
env_file: ./backend/.env
depends_on:
- platform-service
```
### 7. Validation
```bash
# Backend
cd backend && pnpm install && pnpm typecheck && pnpm test && pnpm build
# Web
cd web && pnpm install && pnpm typecheck && pnpm build
# Verify auth flow
curl -X POST http://localhost:4003/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","password":"password"}'
# Use returned token against product backend:
curl http://localhost:<port>/health
curl http://localhost:<port>/api/<endpoint> \
-H "Authorization: Bearer <token>"
```
### 8. Commit
```bash
git add .
git commit -m "feat(platform): wire @bytelyst/* ecosystem integration
- Auth: JWT via @bytelyst/fastify-auth + @bytelyst/react-auth
- Data: @bytelyst/datastore with memory/cosmos providers
- Flags: @bytelyst/feature-flag-client
- Telemetry: @bytelyst/telemetry-client
- Tokens: @bytelyst/design-tokens with --<prefix>-* namespace
- Tests: all passing"
git push
```

120
AI.dev/PROMPTS/prd-to-implementation.md Normal file
View File

@ -0,0 +1,120 @@
---
name: prd-to-implementation
description: 'Convert a PRD into a concrete, phased implementation plan with file-level detail and dependency ordering.'
argument-hint: 'Path to PRD file or inline feature description, e.g. "docs/PRD.md", "add social fasting feature to NomGap"'
agent: agent
---
# PRD → Implementation Plan Prompt
Transform a Product Requirements Document into a detailed, phased implementation plan that an AI agent or developer can execute directly.
## Context — ByteLyst Ecosystem
You are planning implementation within the ByteLyst ecosystem (`D:\BYTELYST\CODE\`).
**Architecture awareness:**
- Products have: `backend/` (Fastify 5), `web/` (Next.js or Vite+React), `mobile/` (Expo), `shared/`
- Backend modules follow: `types.ts` → `repository.ts` → `routes.ts`
- All data lives in Azure Cosmos DB with `productId` multi-tenancy
- Shared packages are `@bytelyst/*` from `learning_ai_common_plat/packages/`
- Platform service (port 4003) handles: auth, flags, telemetry, billing, notifications
- Design tokens provide all UI colors via CSS custom properties
## Process
### Step 1: PRD Analysis
Read the PRD and extract:
1. **Core features** — what must be built
2. **User flows** — how users interact
3. **Data model** — what gets stored
4. **API surface** — endpoints needed
5. **UI screens** — pages/components needed
6. **Constraints** — performance, security, compatibility
7. **Out of scope** — what to explicitly defer
### Step 2: Dependency Mapping
Determine what already exists:
- Which `@bytelyst/*` packages are needed?
- Does any sibling product have a similar pattern to reference?
- Are new Cosmos containers needed?
- Are new platform-service modules needed?
- Are design token additions needed?
### Step 3: Phase Decomposition
Break into phases following this priority order:
1. **P0 — Foundation** (always first)
- Data model / Cosmos containers
- Backend types + Zod schemas
- Repository layer with basic CRUD
- Routes with auth + validation
- Initial tests
2. **P1 — Core Features**
- Primary business logic
- Main API endpoints
- Web/mobile screens for primary flows
- Integration tests
3. **P2 — Secondary Features**
- Less critical endpoints
- Settings, admin views
- Edge case handling
- Additional tests
4. **P3 — Polish**
- Error handling refinement
- Loading states, empty states
- Accessibility
- Performance optimization
- E2E tests
### Step 4: Generate Plan Document
Output a `docs/IMPLEMENTATION_PLAN.md` with:
```markdown
# <Feature Name> Implementation Plan
> Generated from: <PRD path>
> Product: <product name> (<productId>)
> Estimated phases: N
## Data Model
| Container | Partition Key | Fields | Purpose |
|-----------|--------------|--------|---------|
## API Surface
| Method | Path | Auth | Description |
|--------|------|------|-------------|
## Phase Breakdown
### Phase 0: Foundation
- [ ] `backend/src/modules/<name>/types.ts` — Zod schemas
- [ ] `backend/src/modules/<name>/repository.ts` — Cosmos CRUD
- [ ] `backend/src/modules/<name>/routes.ts` — REST endpoints
- [ ] `backend/src/modules/<name>/<name>.test.ts` — Unit tests
- [ ] Register routes in `backend/src/server.ts`
**Validation:** `pnpm --filter backend test && pnpm --filter backend typecheck`
**Commit:** `feat(<module>): add <name> foundation (types, repo, routes, tests)`
### Phase 1: Core Features
...
```
## Guardrails
- **Every phase must be independently deployable** — no half-built features
- **Every phase includes tests** — minimum: unit tests for repository + routes
- **Backend first, frontend second** — API must exist before UI consumes it
- **Use existing patterns** — reference sibling product repos, don't reinvent
- **Include validation commands** — exact `pnpm` commands for each phase
- **Include commit messages** — pre-written conventional commits

157
AI.dev/PROMPTS/pre-release-validation.md Normal file
View File

@ -0,0 +1,157 @@
---
name: pre-release-validation
description: 'Run comprehensive pre-release checks across one or more ByteLyst repos: build, typecheck, test, lint, security audit, and bundle analysis.'
argument-hint: 'Repos and depth, e.g. "learning_ai_efforise full", "all backends quick", "common_plat + flowmonk"'
agent: agent
---
# Pre-Release Validation Prompt
Execute a comprehensive pre-release validation workflow across ByteLyst repos with incremental fixes and commits.
## Context — ByteLyst Release Conventions
- **Build order:** common_plat packages → common_plat services → product backends → web/mobile
- **Commit after each fix:** Keep history clean, push after each phase
- **Commit format:** `fix(scope): <issue>`, `test(scope): fix failing tests`, `style(scope): format fixes`
## Validation Phases
### Phase 1: Common Platform (always first)
```bash
cd learning_ai_common_plat
# 1. Install & build
pnpm install && pnpm build
# 2. Type-check all packages and services
pnpm typecheck
# Fix → git add . && git commit -m "fix(common): type-check fixes" && git push
# 3. Run all tests
pnpm test
# Fix → git add . && git commit -m "test(common): fix failing tests" && git push
# 4. Security audit
pnpm audit
# Fix → git add . && git commit -m "fix(common): security updates" && git push
```
### Phase 2: Product Backend
```bash
cd <product>/backend
# 1. Install & build
pnpm install && pnpm build
# 2. Type-check
pnpm typecheck
# Fix → git commit -m "fix(backend): type-check fixes"
# 3. Tests
pnpm test
# Fix → git commit -m "test(backend): fix failing tests"
# 4. Verify health endpoint
# Start in background, test, stop:
pnpm dev &
sleep 3
curl -s http://localhost:<port>/health | jq .
kill %1
```
### Phase 3: Web Client
```bash
cd <product>/web # or client/
# 1. Type-check
pnpm typecheck
# Fix → git commit -m "fix(web): type-check fixes"
# 2. Lint
pnpm lint
# Fix → git commit -m "fix(web): lint fixes"
# 3. Build (catches runtime issues)
pnpm build
# Fix → git commit -m "fix(web): build fixes"
# 4. Tests (if any)
pnpm test
# Fix → git commit -m "test(web): fix failing tests"
```
### Phase 4: Mobile (if applicable)
```bash
cd <product>/mobile
# 1. Type-check
pnpm typecheck
# Fix → git commit -m "fix(mobile): type-check fixes"
# 2. Tests (if any)
pnpm test
# Fix → git commit -m "test(mobile): fix failing tests"
```
### Phase 5: Integration Smoke Test
```bash
# Start all services
cd <product> && docker compose up -d
sleep 10
# Health checks
curl -s http://localhost:4003/health | jq .
curl -s http://localhost:<product-port>/health | jq .
# Basic auth flow
TOKEN=$(curl -s -X POST http://localhost:4003/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"test@test.com","password":"password"}' | jq -r '.token')
curl -s http://localhost:<product-port>/api/<endpoint> \
-H "Authorization: Bearer $TOKEN" | jq .
# Cleanup
docker compose down
```
## Validation Matrix
Check all that apply:
| Check | Backend | Web | Mobile | Platform |
|-------|---------|-----|--------|----------|
| `pnpm install` | ☐ | ☐ | ☐ | ☐ |
| `pnpm build` | ☐ | ☐ | ☐ | ☐ |
| `pnpm typecheck` | ☐ | ☐ | ☐ | ☐ |
| `pnpm test` | ☐ | ☐ | ☐ | ☐ |
| `pnpm lint` | ☐ | ☐ | ☐ | ☐ |
| `pnpm audit` | ☐ | ☐ | ☐ | ☐ |
| Health endpoint | ☐ | — | — | ☐ |
| Auth flow | ☐ | ☐ | ☐ | ☐ |
## Report Format
```markdown
## Pre-Release Validation: <Product>
### Results
| Phase | Status | Issues Found | Issues Fixed | Commits |
|-------|--------|-------------|-------------|---------|
| Common Platform | ✅/❌ | N | N | hash1, hash2 |
| Backend | ✅/❌ | N | N | hash3 |
| Web | ✅/❌ | N | N | hash4 |
| Mobile | ✅/❌ | N | N | — |
| Integration | ✅/❌ | N | N | — |
### Blockers
- <any issues that couldn't be fixed>
### Ready for Release: ✅ YES / ❌ NO
```

146
AI.dev/PROMPTS/refactor-with-tests.md Normal file
View File

@ -0,0 +1,146 @@
---
name: refactor-with-tests
description: 'Safely refactor code with test-first methodology — capture behavior, refactor, verify nothing broke.'
argument-hint: 'Target module/file and refactor goal, e.g. "backend/src/modules/auth — extract token service", "simplify scheduler engine in FlowMonk"'
agent: agent
---
# Refactor with Tests Prompt
Safely refactor code by first capturing existing behavior in tests, then restructuring while keeping all tests green.
## Context — ByteLyst Conventions
- **Test runner:** Vitest (TypeScript), pytest (Python)
- **Test location:** Same module directory or `__tests__/`
- **Never modify tests to make them pass** — fix the code
- **Commit format:** `refactor(scope): description`
## Refactor Protocol
### Step 1: Understand Current Behavior
Before touching any code:
1. **Read the code** — understand what it does, not just the structure
2. **Read existing tests** — understand what's already covered
3. **Run existing tests** — confirm they pass:
```bash
pnpm test
pnpm typecheck
```
4. **Identify the API surface** — what do consumers depend on?
- Exported functions/types
- REST endpoint contracts
- Side effects (database writes, events emitted)
### Step 2: Add Missing Tests (Before Refactoring)
If test coverage is insufficient, add tests for current behavior FIRST:
```typescript
// Capture existing behavior before refactoring
describe('<Module> — pre-refactor behavior capture', () => {
it('should return X when given Y', () => {
// Test current behavior, even if the implementation is ugly
});
it('should throw NotFoundError for missing items', () => {
// Edge cases that must be preserved
});
it('should include productId in all created documents', () => {
// Ecosystem invariants
});
});
```
**Commit these tests separately:**
```bash
git add .
git commit -m "test(<scope>): capture pre-refactor behavior (N tests)"
```
### Step 3: Plan the Refactor
Document what will change and what must stay the same:
- **Changing:** Internal structure, file organization, naming
- **Preserving:** API surface, behavior, test contracts
- **New patterns:** What you're moving toward (e.g., extract service class, split module)
### Step 4: Refactor in Small Steps
For each step:
1. Make ONE structural change
2. Run tests: `pnpm test`
3. Run typecheck: `pnpm typecheck`
4. If tests pass → commit
5. If tests fail → undo and retry with smaller step
```bash
# After each small refactor step
pnpm test && pnpm typecheck && \
git add . && git commit -m "refactor(<scope>): <what changed>"
```
### Step 5: Verify Completeness
After all refactoring:
```bash
# Full validation
pnpm build && pnpm typecheck && pnpm test
# Check no exports were broken
# If this is a @bytelyst/* package:
cd learning_ai_common_plat && pnpm build && pnpm test
```
### Step 6: Update Documentation
If the refactor changed:
- File locations → update AGENTS.md repo layout
- API surface → update README.md or API docs
- Module structure → update any roadmap or architecture docs
```bash
git add .
git commit -m "docs(<scope>): update docs after <module> refactor"
git push
```
## Common Refactor Patterns
### Extract Service Class
```
Before: routes.ts has business logic mixed with HTTP handling
After: routes.ts → service.ts → repository.ts (routes are thin)
```
### Split Module
```
Before: modules/schedule/ has 500-line routes.ts
After: modules/schedule/ + modules/schedule-entries/ (each focused)
```
### Extract Shared Package
```
Before: Two products have duplicate utility code
After: New @bytelyst/* package consumed by both
```
### Consolidate Re-exports
```
Before: Each file imports from @bytelyst/* directly
After: src/lib/ re-exports, internal files import from src/lib/
```
## Guardrails
- **Test first, refactor second.** Never refactor without test coverage.
- **Small commits.** Each commit should be revertible without losing other changes.
- **No behavior changes.** Refactoring changes structure, not behavior. If you're fixing bugs, that's a separate commit.
- **No export changes** without updating all consumers.
- **Run the full suite** after every commit, not just the changed module's tests.

124
AI.dev/PROMPTS/roadmap-execution.md Normal file
View File

@ -0,0 +1,124 @@
---
name: roadmap-execution
description: 'Execute a phased roadmap with checkpoint commits, incremental validation, and progress tracking.'
argument-hint: 'Roadmap file path or inline description, e.g. "docs/ROADMAP.md", "Phase 2 of FlowMonk backend", "implement push notifications"'
agent: agent
---
# Roadmap Execution Prompt
Execute a phased implementation roadmap with disciplined checkpoint commits, incremental validation, and progress tracking.
## Context — ByteLyst Ecosystem
You are working in the ByteLyst multi-repo ecosystem (`D:\BYTELYST\CODE\`).
**Key conventions:**
- **Package manager:** pnpm (workspace). Never use npm or yarn.
- **Module system:** ESM everywhere (`"type": "module"`, `.js` extensions in imports)
- **Backend pattern:** Fastify 5 + Zod validation. Modules follow `types.ts` → `repository.ts` → `routes.ts`
- **Shared packages:** `@bytelyst/*` in `learning_ai_common_plat/packages/`
- **Services:** `@lysnrai/*` in `learning_ai_common_plat/services/`
- **Product identity:** Every Cosmos document MUST include `productId` field
- **Design tokens:** Never hardcode colors — use `@bytelyst/design-tokens` CSS custom properties
- **Commit format:** `type(scope): description` — types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
- **Tests:** Vitest for TS, pytest for Python. Never modify tests to make them pass — fix the code.
## Execution Protocol
### Phase 0: Understand the Roadmap
1. **Read the roadmap document** (if provided as file path) or parse the inline description
2. **Identify all phases/milestones** and their dependencies
3. **Estimate scope** for each phase (files touched, tests needed, risk level)
4. **Create a tracker** — write a `docs/IMPLEMENTATION_TRACKER.md` with:
- Phase list with `[ ]` / `[/]` / `[x]` status
- Key files to create/modify per phase
- Validation criteria per phase
- Commit message for each checkpoint
### Phase N: Execute Each Phase
For each phase, follow this cycle:
#### Step 1: Plan
- List files to create or modify
- Identify which `@bytelyst/*` packages are needed
- Note any new dependencies
#### Step 2: Implement
- Write code following the established patterns in this repo
- Use existing `src/lib/` re-exports for shared packages
- Every new API endpoint gets Zod schema validation
- Every new Cosmos container uses `productId` partition-aware queries
#### Step 3: Test
- Add tests alongside implementation (same module directory or `__tests__/`)
- Run tests: `pnpm test` or `pnpm --filter <package> test`
- Run typecheck: `pnpm typecheck` or `pnpm --filter <package> typecheck`
- Fix any failures before proceeding
#### Step 4: Validate
- Verify the feature works end-to-end (API → UI if applicable)
- Check for regressions: run the full test suite
- Review for ecosystem compliance:
- ✅ `productId` on all Cosmos docs
- ✅ No `console.log` (use `req.log` / `app.log`)
- ✅ No `any` types
- ✅ No hardcoded colors
- ✅ No hardcoded secrets
#### Step 5: Checkpoint Commit
```bash
git add .
git commit -m "feat(<scope>): <phase-description>
- <key change 1>
- <key change 2>
- Tests: <N> new tests, all passing"
git push
```
#### Step 6: Update Tracker
- Mark the phase `[x]` in `IMPLEMENTATION_TRACKER.md`
- Add the commit hash
- Note any deferred items or follow-ups
### Completion
After all phases:
1. **Run full validation:**
```bash
pnpm build && pnpm typecheck && pnpm test
```
2. **Update AGENTS.md** if the repo layout, API endpoints, or test counts changed
3. **Update README.md** if new features, commands, or setup steps were added
4. **Final commit:**
```bash
git add .
git commit -m "docs(<scope>): update docs for <roadmap-name> completion"
git push
```
## Output Format
Report progress after each phase:
```
## Phase N: <Name> ✅
**Commit:** `abc1234`
**Files changed:** 5 created, 2 modified
**Tests:** 12 new tests, all passing
**Validation:** typecheck ✅, lint ✅, test ✅
**Notes:** <any deferred items or follow-ups>
```
## Guardrails
- **Never skip tests.** Every phase must include test validation.
- **Never make big-bang commits.** Each phase gets its own checkpoint.
- **Never break existing tests.** If a test fails, fix the code, not the test.
- **Never hardcode values.** Use config, env vars, and design tokens.
- **Always verify before committing.** Run typecheck + test before every commit.

145
AI.dev/PROMPTS/test-gap-analysis.md Normal file
View File

@ -0,0 +1,145 @@
---
name: test-gap-analysis
description: 'Identify test coverage gaps in a repo, prioritize by risk, and generate targeted tests for the most critical uncovered code.'
argument-hint: 'Repo name or path, e.g. "learning_ai_efforise", "learning_ai_flowmonk backend only", "all product backends"'
agent: agent
---
# Test Gap Analysis Prompt
Audit test coverage in a ByteLyst repo, identify the riskiest gaps, and generate high-value tests.
## Context — ByteLyst Testing Conventions
- **Runner:** Vitest for all TypeScript code
- **Pattern:** Tests live in `__tests__/` or alongside source as `<module>.test.ts`
- **Helpers:** `buildTestApp()` via `src/test-helpers.ts` for Fastify inject testing
- **Mocks:** `@bytelyst/testing` for shared mock utilities
- **Coverage targets:** Backend 80%, Web 70%, Shared packages 90%
## Analysis Protocol
### Step 1: Inventory
Scan the repo and build a map:
```
Source files: N files
Test files: M files
Coverage ratio: M/N (% of source files with tests)
```
For each source module, classify:
- ✅ Has tests
- ⚠️ Has partial tests (some functions uncovered)
- ❌ No tests
- 🔒 Low risk (config, types-only, re-exports)
- 🔴 High risk (business logic, data mutations, auth)
### Step 2: Prioritize Gaps
Rank uncovered code by risk:
| Priority | Category | Why |
|----------|----------|-----|
| **P0** | Auth/security logic | Vulnerabilities if broken |
| **P0** | Data mutation (repository.ts) | Data corruption if broken |
| **P1** | Business logic (services, engines) | Core features break |
| **P1** | API routes with validation | Contract violations |
| **P2** | Utility functions | Indirect failures |
| **P3** | UI components (rendering) | Visual but not critical |
| **P4** | Config, types, re-exports | Very low risk |
### Step 3: Generate Tests
For each P0/P1 gap, generate tests following this structure:
```typescript
import { describe, it, expect, beforeEach, vi } from 'vitest';
describe('<Module>', () => {
// Setup
beforeEach(() => {
// Fresh state for each test
});
// Happy path
it('should <expected behavior> when <condition>', async () => {
// Arrange
// Act
// Assert
});
// Validation
it('should reject invalid input', async () => {
// Test Zod schema validation
});
// Auth
it('should enforce user ownership', async () => {
// Test that user A cannot access user B's data
});
// Edge cases
it('should handle <edge case>', async () => {
// Empty arrays, null values, missing fields
});
// Error paths
it('should throw NotFoundError for missing <entity>', async () => {
// Test error handling
});
});
```
### Step 4: Run & Validate
```bash
pnpm test --coverage
pnpm typecheck
```
### Step 5: Report
Output a coverage gap report:
```markdown
## Test Gap Analysis: <Repo>
### Summary
- Source files: N
- Test files: M (before) → M+K (after)
- Coverage: X% → Y%
### Gaps Filled (this session)
| Module | Tests Added | Risk Level |
|--------|-------------|------------|
### Remaining Gaps
| Module | Risk Level | Effort | Suggested Next Step |
|--------|------------|--------|---------------------|
### Recommendations
1. ...
2. ...
```
### Step 6: Commit
```bash
git add .
git commit -m "test(<scope>): fill coverage gaps in <modules>
- Added N tests across M modules
- Coverage: X% → Y%
- Focus: <P0/P1 risk areas addressed>"
git push
```
## Anti-Patterns to Avoid
- ❌ Don't write snapshot tests for API responses (too brittle)
- ❌ Don't test private implementation details (test behavior, not internals)
- ❌ Don't mock the thing you're testing (mock dependencies only)
- ❌ Don't write tests that always pass regardless of code changes
- ❌ Don't chase 100% coverage — focus on high-risk code

137
AI.dev/PROMPTS/type-safety-sweep.md Normal file
View File

@ -0,0 +1,137 @@
---
name: type-safety-sweep
description: 'Fix TypeScript errors across a repo or the full workspace with systematic triage and minimal code changes.'
argument-hint: 'Scope, e.g. "learning_ai_flowmonk", "all backends", "common_plat packages only"'
agent: agent
---
# Type Safety Sweep Prompt
Systematically fix TypeScript errors across ByteLyst repos with minimal, safe changes.
## Context — ByteLyst TypeScript Conventions
- **Target:** ES2022, `moduleResolution: NodeNext`
- **Strict mode:** `strict: true` in all repos
- **Base config:** Extends `../../tsconfig.base.json` (from common_plat)
- **Module system:** ESM (`"type": "module"`) with `.js` extensions in imports
- **No `any`:** Use Zod inference, explicit types, or `unknown` with type guards
## Sweep Protocol
### Step 1: Run Typecheck
```bash
# Single repo
pnpm typecheck
# Workspace-wide
cd learning_ai_common_plat && pnpm typecheck
cd <product> && pnpm typecheck
```
### Step 2: Triage Errors
Categorize each error:
| Category | Fix Strategy | Risk |
|----------|-------------|------|
| **Missing `.js` extension** | Add `.js` to import path | Low |
| **Implicit `any`** | Add explicit type annotation | Low |
| **Missing property** | Add property to interface/schema | Medium |
| **Type mismatch** | Fix the value, not the type (usually) | Medium |
| **Package type conflict** | Check peer dep versions | High |
| **Structural break** | Needs design decision | High |
### Step 3: Fix by Category
#### Low-risk fixes (do first)
```typescript
// Missing .js extension
- import { foo } from './utils';
+ import { foo } from './utils.js';
// Implicit any
- function handle(req, reply) {
+ function handle(req: FastifyRequest, reply: FastifyReply) {
// Unused imports
- import { unused, used } from './types.js';
+ import { used } from './types.js';
```
#### Medium-risk fixes
```typescript
// Missing property — add to schema
const schema = z.object({
name: z.string(),
+ description: z.string().optional(), // Was missing
});
// Type mismatch — fix the value
- const port: number = process.env.PORT; // string assigned to number
+ const port: number = Number(process.env.PORT) || 4003;
```
#### High-risk fixes (get approval first)
- Package version conflicts → document and propose solution
- Structural type breaks → explain what changed and why
### Step 4: Validate
After each batch of fixes:
```bash
pnpm typecheck # Must pass
pnpm test # Must still pass
pnpm build # Must still build
```
### Step 5: Commit
Group fixes logically:
```bash
# Low-risk batch
git add .
git commit -m "fix(<scope>): resolve TypeScript errors (import extensions, explicit types)"
# Medium-risk batch
git add .
git commit -m "fix(<scope>): fix type mismatches in <modules>"
git push
```
## Common ByteLyst Type Issues
### Zod version mismatch
**Symptom:** `Type 'z.ZodString' is not assignable to type 'z.ZodString'`
**Fix:** Services must use self-contained Zod schemas in `src/lib/config.ts`, NOT import from @bytelyst/config
### Package export types
**Symptom:** `Cannot find module '@bytelyst/errors' or its corresponding type declarations`
**Fix:** Build the package first: `cd learning_ai_common_plat && pnpm build`
### Fastify request types
**Symptom:** `Property 'user' does not exist on type 'FastifyRequest'`
**Fix:** Use `getUserId(req)` from `src/lib/request-context.ts` instead of `req.user`
### Cosmos document types
**Symptom:** `Type '{ name: string }' is missing ... 'productId'`
**Fix:** Always include `productId` when creating documents
## Report Format
```markdown
## Type Safety Sweep: <Repo>
| Category | Count | Fixed | Remaining |
|----------|-------|-------|-----------|
| Import extensions | N | N | 0 |
| Implicit any | N | N | 0 |
| Type mismatches | N | N | M |
| Package conflicts | N | 0 | N |
| **Total** | **X** | **Y** | **Z** |
### Deferred Issues
- <issue>: <why deferred> (needs <decision/approval>)
```