learning_ai_common_plat/AI.dev/PROMPTS/new-product-scaffold.md

name	description	argument-hint	agent
new-product-scaffold	Scaffold a new ByteLyst product repo with backend, web, mobile, and full ecosystem integration.	Product name, ID, and brief description, e.g. "TrackMate, trackmate, GPS-based workout tracker"	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                # Generated by update-agent-docs.sh
├── .aider.conf.yml              # Generated by update-agent-docs.sh
├── .gitignore
├── .github/
│   └── copilot-instructions.md  # Generated by update-agent-docs.sh (thin pointer)
├── .npmrc                       # From canonical template (never hand-edit)
├── .nvmrc                       # "22"
├── AGENTS.md                    # Hand-maintained; canonical pointer auto-prepended
├── README.md
├── package.json                 # Root workspace scripts
├── pnpm-workspace.yaml
├── docker-compose.yml
└── tsconfig.json

Deprecated files — do NOT create: .cursorrules, .windsurfrules, .clinerules, CLAUDE.md. These were replaced by the single-source-of-truth pattern. Agents read AGENTS.md plus the canonical behavior file at ../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md.

After adding the new repo to learning_ai_common_plat/.windsurf/workflows/repos.txt, run bash ../learning_ai_common_plat/scripts/update-agent-docs.sh to populate .editorconfig, .aider.conf.yml, and .github/copilot-instructions.md.

2. Create shared/product.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:

{
  "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

packages:
  - 'backend'
  - 'web'
  - '../learning_ai_common_plat/packages/*'

7. Validation

After scaffolding:

pnpm install
cd backend && pnpm typecheck && pnpm test && pnpm build
cd ../web && pnpm typecheck && pnpm build

8. Commit & Push

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