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

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