BXFlow AI Developer Guidelines - Condensed Roadmap

Version: 2.1 | Updated: 2025-10-23 | Project Level: 4 (101 stories, 10 epics)

CRITICAL :FOR ANY development use ref mcp server to gather newest data and synctax and docs.

Always use perplexity for any addition searches in case of doubts.

🚨 CRITICAL: THIS IS A ROADMAP - READ BEFORE ANY IMPLEMENTATION

IMPORTANT: This document describes the COMPLETE system architecture and future state. Many components, files, and features may NOT exist yet. This is intentional - it's a roadmap so you understand the FULL picture before implementing ANY part.

Why This Matters:

• Prevents wrong implementations that need to be rewritten later

• Ensures consistency across all features as they're built

• Maintains architecture integrity from day one

• Avoids technical debt from short-sighted decisions

Your Approach:

1. Read the entire document first - understand what's ahead

2. Ask about current state - which parts exist vs. planned

3. Build with future in mind - your code will need to support features not yet built

4. Follow patterns religiously - even if they seem over-engineered initially, they're needed for upcoming features

5. Never assume - if something isn't clear, ask before implementing

🎯 WHAT IS BXFLOW

Digital business card platform = "Shopify for business cards" + "HiHello builder UI"

Core Concept:

• Designers create themes (React components in codebase) - 5 pre-built themes

• Users customize via JSON (colours, layouts, fonts) - no runtime code execution

• Users add/reorder fields within zones - drag-and-drop interface

• Preview = Public render - EXACT match required

Architecture Pattern:

THEME (Videographer)
  └─ ZONE (Hero) → FIELDS (Header, Image, Video)
  └─ ZONE (Content) → FIELDS (Text, Social Links, Form)
  └─ ZONE (Sticky Bar) → FIELDS (Contact Buttons)

Key Features:

• 5 pre-built themes (Videographer, Realtor, Plumber, Creative, Minimal)

• 10 field types (Header, Phone, Email, Website, Instagram, Social Links, Contact Buttons, Text, Image, Video)

• Theme customisation via JSON only (security!)

• CSS variables ONLY (white-label capability)

• NFC physical card integration + tap tracking

• Privacy-first: send-and-forget webhooks, NO form data storage

📋 TECH STACK - COMPLETE REFERENCE

Frontend

TechVersionNotesNext.js16.0.0App Router, SSR, Turbopack, <500ms TTFBReact19.2.0Server Components by defaultTypeScript5.xStrict mode, NO any allowedHeroUI2.8.5PRIMARY UI library - NEVER create custom Button/Input/CardTailwind CSS4.xCSS variables ONLY, NO hardcoded coloursFramer MotionLatestAnimations, drag-and-dropZustandLatestCard builder state, 300ms debounceReact Hook Form + ZodLatestForms + validationdate-fnsLatestNOT moment.js@heroui/iconsLatestIcon system - NEVER use Lucide Reactnext-intl4.4.0i18n - REQUIRED from day one, all text must be translatable

Backend & Data

TechVersionNotesPostgreSQL16Self-hosted, JSONB supportPrisma6.18.0ORM, type-safe, middleware RLSBetter Auth1.3.28Email OTP + Google OAuth, JWTStripe19.0.0Customer Portal, webhooksBunny.netN/AImages ONLY, WebP conversion, CDNNodemailer6.9.4+ Amazon SES SMTP

Monitoring & Tools

TechVersionNotesSentry8.18.0Error tracking, client + server, payment alertsVercelN/ADeployment platformpnpmLatestONLY package manager - NEVER npm

🚨 ABSOLUTE RULES - NEVER BREAK THESE

1. CSS Variables ONLY - NO Hardcoded Colours

WHY: White-label theming. Resellers rebrand via admin panel.

// ❌ FORBIDDEN - Breaks white-label
<div className="bg-blue-500 text-red-600">
<Button className="bg-orange-400">

// ✅ REQUIRED - Semantic variables
<div className="bg-primary text-error">
<Button color="primary">

Available Tokens:

• bg-primary / text-primary - Brand colour (#ff8c00 default, user-customisable)

• bg-background / text-foreground - Page background/text

• bg-success/warning/danger - State colours

• bg-default-* - Neutral greys (100, 200, 500, 600, etc.)

2. HeroUI Components ONLY - NO Custom UI

WHY: Consistent theming, accessibility, maintenance.

// ❌ FORBIDDEN
<button className="px-4 py-2 bg-primary">Click</button>

// ✅ REQUIRED - Always with next-intl
import { useTranslations } from 'next-intl'
import { Button } from '@heroui/react'

export function MyComponent() {
  const t = useTranslations('common')
  return <Button color="primary">{t('click')}</Button>
}

Reference: See src/app/page.tsx for HeroUI component showcase

3. HeroUI Icons ONLY - NO Other Icon Libraries

WHY: Consistent design system integration.

// ❌ FORBIDDEN
import { Home } from 'lucide-react'
import HomeIcon from 'some-other-library'

// ✅ REQUIRED - Always with next-intl for labels
import { useTranslations } from 'next-intl'
import { IconHome, IconUser, IconSettings } from '@heroui/icons'
import { Button } from '@heroui/react'

export function Navigation() {
  const t = useTranslations('navigation')
  return (
    <Button startContent={<IconHome />}>
      {t('home')}
    </Button>
  )
}

Note: HeroUI icons follow Icon[Name] naming convention (PascalCase)

4. Path Aliases Always

// ✅ ALWAYS
import { Component } from '@/components/Component'

// ❌ NEVER
import { Component } from '../../components/Component'

5. Strict TypeScript - NO any

// ❌ FORBIDDEN
const data: any = await fetch()

// ✅ REQUIRED
const data: CardData = await fetch()

6. Package Manager: pnpm ONLY

pnpm install  # ✅
npm install   # ❌

7. Internationalization (i18n) ALWAYS - NO Hardcoded Text

WHY: Multi-language support from day one, easier to maintain, professional standard.

// ❌ FORBIDDEN - Hardcoded text
<Button>Click here</Button>
<h1>Welcome to BXFlow</h1>
<p>Create your digital business card</p>

// ✅ REQUIRED - Always use next-intl
import { useTranslations } from 'next-intl'

export function WelcomePage() {
  const t = useTranslations('welcome')
  return (
    <>
      <h1>{t('title')}</h1>
      <p>{t('description')}</p>
      <Button>{t('getStarted')}</Button>
    </>
  )
}

Translation File Structure:

// messages/en/welcome.json
{
  "title": "Welcome to BXFlow",
  "description": "Create your digital business card",
  "getStarted": "Get Started"
}

// messages/pl/welcome.json
{
  "title": "Witamy w BXFlow",
  "description": "Stwórz swoją cyfrową wizytówkę",
  "getStarted": "Rozpocznij"
}

Server Components:

import { getTranslations } from 'next-intl/server'

export async function ServerComponent() {
  const t = await getTranslations('welcome')
  return <h1>{t('title')}</h1>
}

📁 PROJECT STRUCTURE - WHERE EVERYTHING GOES

bxflow/
├── src/
│   ├── themes/                          # Pre-built themes (NO uploads allowed!)
│   │   ├── videographer/
│   │   │   ├── theme.config.json        # Shopify-style schema
│   │   │   ├── ThemeComponent.tsx       # Main renderer
│   │   │   ├── zones/                   # Zone components (HeroZone, FieldsZone, StickyBar)
│   │   │   ├── styles/theme-variables.css
│   │   │   └── preview.webp
│   │   └── [realtor, plumber, creative, minimal]/
│   │
│   ├── fields/                          # 10 field type definitions
│   │   ├── text/
│   │   │   ├── definition.json          # Zod schema + metadata
│   │   │   ├── input-component.tsx      # Builder UI form
│   │   │   └── render-component.tsx     # Public display
│   │   └── [image, video, social-links, contact-buttons, etc.]/
│   │
│   ├── components/
│   │   ├── fields/FieldRenderer.tsx     # Universal field renderer
│   │   ├── builder/                     # Card builder UI components
│   │   │   ├── ThemeSelector.tsx        # Theme gallery
│   │   │   ├── ThemeCustomizer.tsx      # Colour/font pickers
│   │   │   ├── FieldManager.tsx         # Drag-drop field list
│   │   │   ├── LeftSidebar.tsx          # Navigation (240px)
│   │   │   ├── PreviewArea.tsx          # Live preview (420px min)
│   │   │   └── RightPanel.tsx           # Tabs (Display/Info/Fields/Card)
│   │   ├── admin/                       # Admin panel components
│   │   └── ui/                          # HeroUI wrapper components
│   │
│   ├── app/
│   │   ├── (public)/                    # Marketing pages
│   │   ├── (auth)/                      # Login, register
│   │   ├── (dashboard)/                 # User dashboard
│   │   │   └── builder/[cardId]/        # Card builder UI
│   │   ├── (admin)/                     # Admin panel
│   │   ├── [publicPath]/[slug]/         # PUBLIC cards (SSR)
│   │   ├── t/[tagId]/                   # NFC redirect + tap tracking
│   │   └── api/
│   │       ├── cards/, fields/, themes/
│   │       ├── nfc/
│   │       └── stripe/webhooks/
│   │
│   ├── lib/
│   │   ├── theme-registry/              # Theme discovery + loading + validation
│   │   ├── prisma.ts                    # Prisma client singleton
│   │   ├── auth/                        # Better Auth setup
│   │   ├── email/                       # Nodemailer templates
│   │   ├── storage/                     # Bunny.net API
│   │   └── stripe/                      # Stripe webhooks
│   │
│   └── types/                           # TypeScript definitions
│       ├── theme.ts, field.ts, card.ts
│
├── prisma/
│   ├── schema.prisma                    # Database schema
│   ├── migrations/
│   └── seed.ts
│
├── messages/                            # next-intl translations (REQUIRED from day one)
│   ├── en/
│   │   ├── common.json                  # Shared translations (buttons, labels)
│   │   ├── welcome.json                 # Page-specific translations
│   │   ├── builder.json                 # Card builder UI
│   │   ├── navigation.json              # Navigation items
│   │   └── validation.json              # Form validation errors
│   └── pl/
│       ├── common.json
│       ├── welcome.json
│       ├── builder.json
│       ├── navigation.json
│       └── validation.json
│
├── .env.example
├── package.json
└── tsconfig.json

🗄️ DATABASE SCHEMA - CORE MODELS

Critical Models (Prisma)

model User {
  id            String    @id @default(cuid())
  email         String    @unique
  username      String    @unique
  publicPath    String    @unique      // john-realtor
  name          String?
  tier          UserTier  @default(FREE)
  timezone      String    @default("UTC")
  locale        String    @default("en")
  cards         Card[]
  nfcTags       NFCTag[]
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
  @@index([publicPath, email])
}

enum UserTier { FREE | PRO | ENTERPRISE }

model Card {
  id              String      @id @default(cuid())
  userId          String
  user            User        @relation(fields: [userId], references: [id])
  name            String
  slug            String      @unique
  publicPath      String                    // URL segment
  themeId         String                    // "videographer", "realtor"
  themeConfig     Json                      // User customisation (colours, fonts)
  published       Boolean     @default(false)
  viewCount       Int         @default(0)
  metadata        Json?                     // SEO, OG tags
  fields          Field[]
  nfcTags         NFCTag[]
  createdAt       DateTime    @default(now())
  updatedAt       DateTime    @updatedAt
  @@index([userId, published, slug, publicPath])
  @@unique([userId, publicPath])
}

model Field {
  id              String      @id @default(cuid())
  cardId          String
  card            Card        @relation(fields: [cardId], references: [id], onDelete: Cascade)
  type            FieldType                 // text, image, video, etc.
  zone            String                    // hero, content, sticky_bar
  sortOrder       Int
  config          Json                      // Field-specific data
  createdAt       DateTime    @default(now())
  updatedAt       DateTime    @updatedAt
  @@index([cardId, sortOrder])
}

enum FieldType { HEADER | TEXT | IMAGE | VIDEO | PHONE | EMAIL | WEBSITE | INSTAGRAM | SOCIAL_LINKS | CONTACT_BUTTONS | FORM }

model NFCTag {
  id              String      @id @default(cuid())
  userId          String
  user            User        @relation(fields: [userId], references: [id])
  cardId          String?
  card            Card?       @relation(fields: [cardId], references: [id])
  tagId           String      @unique           // Physical tag ID
  serialNumber    String?
  manufacturer    String?
  activated       Boolean     @default(false)
  lastTap         DateTime?
  tapCount        Int         @default(0)
  analytics       NFCAnalytics[]
  createdAt       DateTime    @default(now())
  updatedAt       DateTime    @updatedAt
  @@index([tagId, userId])
}

model NFCAnalytics {
  id              String      @id @default(cuid())
  tagId           String
  tag             NFCTag      @relation(fields: [tagId], references: [id], onDelete: Cascade)
  tappedAt        DateTime    @default(now())
  userAgent       String?
  ipAddress       String?                   // Hashed for privacy
  country         String?
  city            String?
  @@index([tagId, tappedAt])
}

model Webhook {
  id              String      @id @default(cuid())
  userId          String
  cardId          String?
  type            WebhookType
  url             String
  secret          String?
  events          String[]                  // ["form.submit", "nfc.tap"]
  active          Boolean     @default(true)
  lastTrigger     DateTime?
  triggerCount    Int         @default(0)
  failureCount    Int         @default(0)
  createdAt       DateTime    @default(now())
  updatedAt       DateTime    @updatedAt
  @@index([userId, active])
}

enum WebhookType { FORM_SUBMIT | NFC_TAP | CARD_VIEW }

Row-Level Security (RLS)

// lib/prisma/middleware.ts
export function applyRowLevelSecurity(userId: string) {
  return prisma.$extends({
    query: {
      card: {
        async findMany({ args, query }) {
          args.where = { ...args.where, userId }
          return query(args)
        }
      }
    }
  })
}

🎨 THEME SYSTEM ARCHITECTURE

Theme Structure (Shopify-Style)

// themes/videographer/theme.config.json
{
  "id": "videographer",
  "name": "Videographer Pro",
  "version": "1.0.0",
  "zones": [
    {
      "id": "hero",
      "name": "Hero Section",
      "allowedFields": ["header", "image", "video"],
      "maxFields": 3
    },
    {
      "id": "content",
      "name": "Main Content",
      "allowedFields": "*",
      "maxFields": 10
    },
    {
      "id": "sticky_bar",
      "name": "Sticky Bottom Bar",
      "allowedFields": ["contact_buttons", "phone", "email"],
      "maxFields": 3
    }
  ],
  "customisation": {
    "primaryColour": "#ff8c00",
    "fontFamily": "Inter",
    "borderRadius": "8px"
  }
}

Field Definition Structure

// fields/text/definition.json
{
  "id": "text",
  "name": "Text Block",
  "description": "Rich text content",
  "icon": "IconTextCursor",  // HeroUI icon name
  "schema": {
    "content": { "type": "string", "required": true },
    "alignment": { "type": "enum", "values": ["left", "center", "right"] },
    "fontSize": { "type": "enum", "values": ["sm", "md", "lg"] }
  },
  "defaultConfig": {
    "content": "",
    "alignment": "left",
    "fontSize": "md"
  }
}

🔒 SECURITY & PRIVACY CRITICAL RULES

1. NO Theme Uploads

• Themes are ONLY pre-built in codebase

• Users customise via JSON (colours, fonts)

• NEVER execute user-provided code

2. Privacy-First Form Handling

// ❌ FORBIDDEN - Storing form submissions
await prisma.formSubmission.create({ data: formData })

// ✅ REQUIRED - Send-and-forget webhooks
await sendWebhook(webhookUrl, formData)
// NO database storage!

3. NO Email History Storage

// ❌ FORBIDDEN - Storing email content
await prisma.email.create({ subject, body })

// ✅ REQUIRED - Send and done
await nodemailer.sendMail({ subject, body })
// NO database storage!

4. NFC Tap Data (Privacy-Compliant)

• Store: timestamp, country, city (general location)

• Hash: IP addresses before storage

• NEVER store: precise GPS, device IDs, personal data

🎯 IMPLEMENTATION GUIDELINES

1. File Organisation

// ✅ Named exports
export function CardBuilder() { ... }
export interface CardBuilderProps { ... }

// ✅ PascalCase for components
CardBuilder.tsx, ThemeSelector.tsx

// ✅ RESTful API routes
app/api/cards/route.ts           // GET, POST
app/api/cards/[id]/route.ts      // GET, PUT, DELETE

2. Import Order

// 1. React/Next
import { useState } from 'react'
import { useRouter } from 'next/navigation'
import { useTranslations } from 'next-intl'

// 2. External libraries
import { Button } from '@heroui/react'
import { IconHome, IconUser } from '@heroui/icons'
import { z } from 'zod'

// 3. Internal (@/* aliases)
import { prisma } from '@/lib/prisma'
import { CardBuilder } from '@/components/CardBuilder'

// 4. Relative imports
import { formatDate } from './utils'

// 5. Types
import type { Card } from '@prisma/client'

3. Naming Conventions

// Components: PascalCase
export function CardBuilder() { }

// Utilities: camelCase
export function formatDate() { }

// Constants: SCREAMING_SNAKE_CASE
export const MAX_FILE_SIZE = 5 * 1024 * 1024

// Types/Interfaces: PascalCase
export interface CardData { }

// Database: snake_case
model user_sessions { }

⚡ PERFORMANCE TARGETS

MetricTargetHow to AchieveCard Builder Preview Update<300msDebounce, Zustand statePublic Card TTFB<500msSSR, Edge functionsDashboard Load (3G)<1.5sCode splitting, lazy loadingImage Upload (5MB)<5sDirect to Bunny.net, progress UIAdmin Panel Queries<2sDB indices, pagination

🔍 QUICK DECISION MATRIX

NeedUseNotesButton/Input/CardHeroUINEVER customIcons@heroui/iconsIconHome formatColoursCSS variablesbg-primaryText/Labelsnext-intlALWAYS translatableDatesdate-fnsNOT moment.jsFormsReact Hook Form + ZodValidationStateZustand (builder only)Server state otherwiseAuthBetter AuthEmail OTP + GoogleImagesBunny.netFetch APIErrorsSentryAlways captureEmailNodemailer + SESSMTPPaymentsStripeCustomer PortalPackage ManagerpnpmNEVER npm

🚨 COMMON MISTAKES TO AVOID

1. ❌ Using npm instead of pnpm

2. ❌ Hardcoding colours (bg-blue-500)

3. ❌ Hardcoding text instead of using next-intl translations

4. ❌ Creating custom UI components instead of HeroUI

5. ❌ Using Lucide React or other icon libraries instead of @heroui/icons

6. ❌ Using moment.js instead of date-fns

7. ❌ Storing form submissions (privacy violation!)

8. ❌ Storing email content/history (send-and-forget!)

9. ❌ Allowing theme uploads (security risk!)

10. ❌ Using relative imports instead of @/* aliases

11. ❌ Skipping TypeScript types (using any)

12. ❌ Forgetting Sentry.captureException() on errors

13. ❌ Implementing features without understanding the full roadmap first

🎓 KEY REFERENCE FILES

FilePurposedocs/architecture.mdComplete system architecture (1-1480 lines)docs/PRD.mdProduct requirements (800+ lines)docs/epics.md10 epics, 101 storiesbxflow/src/app/page.tsxHeroUI component showcasebxflow/src/app/hero.tsHeroUI theme configbxflow/src/app/globals.cssCSS variable definitionsbxflow/prisma/schema.prismaDatabase schema

📚 LEARNING RESOURCES

• HeroUI: https://heroui.com/docs

• Next.js 16: https://nextjs.org/docs

• next-intl: https://next-intl-docs.vercel.app/

• Prisma: https://prisma.io/docs

• Better Auth: https://better-auth.com

• Sentry Next.js: https://docs.sentry.io/platforms/javascript/guides/nextjs/

✅ BEFORE YOU START CODING - CHECKLIST

• [ ] I've read the entire guidelines document

• [ ] I understand this is a ROADMAP with planned features

• [ ] I've asked about which parts currently exist vs. planned

• [ ] I understand the theme system architecture completely

• [ ] I know the difference between themes (pre-built) and user customisation (JSON)

• [ ] I understand the privacy-first approach (no form storage, no email history)

• [ ] I know to use CSS variables ONLY (no hardcoded colours)

• [ ] I know to use HeroUI components ONLY (no custom UI)

• [ ] I know to use @heroui/icons ONLY (no Lucide React or other icon libraries)

• [ ] I know to use next-intl ALWAYS (no hardcoded text anywhere)

• [ ] I understand the zone-based layout system

• [ ] I'm ready to build with the future in mind

Version: 2.1 | Total Lines: ~690 (condensed from ~1300)
Remember: This is a ROADMAP. Ask before implementing. Build for the future, not just the present.

BMAD Method (BMM) - Agent & Directory Reference

Directory Structure

bmad/
├── core/                           # Core BMad platform
│   ├── agents/                     # bmad-master orchestrator
│   ├── workflows/                  # brainstorming, party-mode
│   └── tasks/workflow.xml          # Core workflow engine (DO NOT modify)
│
├── bmm/                            # BMad Method Module
│   ├── agents/                     # Specialized development agents
│   │   ├── pm.md                   # Product Manager
│   │   ├── architect.md            # Solution Architect
│   │   ├── sm.md                   # Scrum Master
│   │   ├── dev.md                  # Developer
│   │   ├── tea.md                  # Test Engineer/Analyst
│   │   ├── ux.md                   # UX Designer
│   │   ├── analyst.md              # Business Analyst
│   │   └── game-designer.md        # Game Designer
│   │
│   ├── workflows/                  # 4-phase workflow system
│   │   ├── phase-1-analysis/       # Discovery workflows
│   │   ├── phase-2-planning/       # PRD, tech-spec, GDD
│   │   ├── phase-3-solutioning/    # Architecture, JIT tech-specs
│   │   └── phase-4-implementation/ # Story workflows
│   │
│   ├── teams/                      # Pre-configured agent teams
│   ├── tasks/                      # Reusable task definitions
│   └── testarch/                   # 9 QA workflows (framework, test-design, ATDD, etc)
│
└── _cfg/                           # Configuration
    ├── manifest.yaml               # v6.0.0-alpha.0
    ├── workflow-manifest.csv       # All workflows catalog
    ├── agent-manifest.csv          # All agents catalog
    ├── task-manifest.csv           # All tasks catalog
    └── agents/*.customize.yaml     # Agent customization files

.claude/
├── agents/                         # Claude Code agents
│   ├── bmad-analysis/              # codebase-analyzer, pattern-detector, api-documenter, data-analyst
│   ├── bmad-planning/              # requirements-analyst, user-journey-mapper, epic-optimizer, dependency-mapper
│   ├── bmad-research/              # market-researcher, tech-debt-auditor, trend-spotter
│   └── bmad-review/                # document-reviewer, technical-evaluator, test-coverage-analyzer
│
└── commands/bmad/                  # Slash commands for BMM workflows

docs/
└── stories/                        # User story documentation

Core Agents (bmad/bmm/agents/)

PM (Product Manager)

• Phase 1-2 workflows

• Commands: *product-brief, *prd, *gdd

• Creates PRD, GDD, epics

Architect (Solution Architect)

• Phase 3 workflows

• Commands: *architecture, *tech-spec (Levels 3-4)

• Creates architecture.md with ADRs

SM (Scrum Master)

• Phase 4 implementation orchestration

• Commands: *create-story, *story-ready, *story-context, *retrospective

• Manages bmm-workflow-status.md

• Advances story state machine

DEV (Developer)

• Phase 4 implementation

• Commands: *dev-story, *story-approved, *review-story

• Implements stories, marks done after DoD

TEA (Test Engineer/Analyst)

• Test architecture workflows

• Commands: *testarch-* (9 workflows)

• Creates test plans, automation, CI/CD

UX (UX Designer)

• Phase 2 UX planning

• Commands: *ux-spec

• Creates UX specifications

Analyst (Business Analyst)

• Phase 1 analysis

• Commands: *research, *brainstorm-project

• Requirements gathering

Game Designer

• Game-specific workflows

• Commands: *brainstorm-game, *game-brief, *gdd

• Creates game design documents

Claude Code Agents (.claude/agents/)

bmad-analysis/

• codebase-analyzer: Analyzes existing codebases

• pattern-detector: Identifies code patterns

• api-documenter: Documents APIs

• data-analyst: Data structure analysis

bmad-planning/

• requirements-analyst: Analyzes requirements

• user-journey-mapper: Maps user flows

• epic-optimizer: Optimizes epic structure

• dependency-mapper: Maps dependencies

• trend-spotter: Identifies trends

• technical-decisions-curator: Curates ADRs

bmad-research/

• market-researcher: Market analysis

• tech-debt-auditor: Technical debt assessment

bmad-review/

• document-reviewer: Reviews documentation

• technical-evaluator: Evaluates technical decisions

• test-coverage-analyzer: Analyzes test coverage

Key Artifacts (Output Files)

Status Tracking

• bmm-workflow-status.md: Story backlog (BACKLOG/TODO/IN PROGRESS/DONE)

Planning Outputs (Phase 2)

• PRD.md: Product Requirements (Levels 2-4)

• Epics.md: Epic breakdown with stories (Levels 2-4)

• GDD.md: Game Design Document (games)

• tech-spec.md: Technical spec (Levels 0-2, or per-epic for 3-4)

• epic-stories.md: Epic summary with story links (Level 1)

Solutioning Outputs (Phase 3)

• architecture.md: System architecture with ADRs (Levels 3-4)

• tech-spec-{epic-name}.md: Per-epic tech specs (JIT approach)

Implementation Outputs (Phase 4)

• story-{slug}.md: Individual user stories

• story-context-{slug}.xml: Dynamic expertise injection

Universal Entry Point

ALWAYS start with: *workflow-status

This workflow:

• Checks for existing status file

• Displays current phase/progress

• Recommends next action

• Guides new projects

Agent Invocation Methods

1. Slash commands: .claude/commands/bmad/

2. Direct reference: Drag/drop or @ mention agent files

3. bmad-master: Orchestrator for all workflows

Workflow Execution Rules

1. Never pre-load files - load at runtime

2. Save after EACH step - never batch

3. Follow workflow.xml precisely - core OS

4. Respect scale levels (0-4)

5. Use JIT approach - tech specs one epic at a time (Levels 3-4)

6. Trust status file - exact story locations, no searching

Story State Machine

BACKLOG → TODO → IN PROGRESS → DONE

Workflows advance automatically:

• *story-ready moves TODO → IN PROGRESS

• *story-approved moves IN PROGRESS → DONE

  Configuration

All agents load from:

• bmad/core/config.yaml: Sets user_name, communication_language, output_folder, project_name

• bmad/_cfg/agents/*.customize.yaml: Agent-specific customization

Version Info

• BMM Version: 6.0.0-alpha.0

• Installation Date: 2025-10-21

• Modules: core, bmm

• IDE: claude-code

Translation Management CLI - Quick Reference for AI Assistants

Overview

The xtrans command manages translations across all language files (en, pl, ph) in src/messages/*.json. It supports nested keys using dot notation (e.g., Boss.Users.Edit).

Commands

ADD - Create New Translation

Adds a new translation key to all language files. Fails if key already exists.

pnpm xtrans add '{"key":"Boss.Users.Edit","en":"Edit","pl":"Edytuj","ph":"I-edit"}'

Requirements:

• All three languages (en, pl, ph) must be provided

• Key must not already exist (use check first if unsure)

• Creates nested structure automatically

Common Errors:

• "Key already exists" → Use update command instead

• "Missing translation for language" → Provide all three languages

UPDATE - Modify Existing Translation

Updates an existing translation. Fails if key doesn't exist.

pnpm xtrans update '{"key":"Boss.Users.Edit","en":"Edit User","pl":"Edytuj użytkownika","ph":"I-edit ang user"}'

Requirements:

• All three languages must be provided

• Key must already exist (use check first if unsure)

Common Errors:

• "Key not found" → Use add command instead

REMOVE - Delete Translation

Removes a translation from all language files.

pnpm xtrans remove '{"key":"Boss.Users.Edit"}'

Notes:

• Only requires the key field

• Removes from all language files where it exists

• Cleans up empty parent objects automatically

CHECK - Verify Existence

Checks if a translation exists and displays current values.

pnpm xtrans check '{"key":"Boss.Users.Edit"}'

Use Cases:

• Before adding: verify key doesn't exist

• Before updating: verify key exists and see current values

• Debugging: check what translations are currently set

Important Notes for AI Assistants

1. Always Use Single Quotes for JSON

# ✅ CORRECT
pnpm xtrans add '{"key":"Test","en":"Value","pl":"Wartość","ph":"Halaga"}'

# ❌ WRONG (will fail in shell)
pnpm xtrans add "{"key":"Test","en":"Value","pl":"Wartość","ph":"Halaga"}"

2. Special Characters in Values

For values with special characters (quotes, apostrophes), the shell requires proper escaping:

# For simple text without quotes - WORKS FINE
pnpm xtrans add '{"key":"Test","en":"Hello","pl":"Cześć","ph":"Kamusta"}'

# For text WITH quotes or apostrophes - May need different approach
# Option 1: Avoid problematic characters if possible
pnpm xtrans add '{"key":"Test","en":"Hello there","pl":"Czesc","ph":"Kamusta"}'

# Option 2: Let the script handle it (it will escape properly in JSON files)

3. Nested Keys

Use dot notation for nested structures:

pnpm xtrans add '{"key":"Boss.Analytics.Reports.Title","en":"Reports","pl":"Raporty","ph":"Mga Ulat"}'

This creates:

{
  "Boss": {
    "Analytics": {
      "Reports": {
        "Title": "Reports"
      }
    }
  }
}

4. Workflow Recommendations

When adding new translations:

1. Use check first to verify key doesn't exist

2. If exists → use update

3. If not exists → use add

Safe workflow example:

# 1. Check if exists
pnpm xtrans check '{"key":"Boss.Users.Create"}'

# 2a. If not found, add it
pnpm xtrans add '{"key":"Boss.Users.Create","en":"Create User","pl":"Utwórz użytkownika","ph":"Lumikha ng User"}'

# 2b. If found but need to update
pnpm xtrans update '{"key":"Boss.Users.Create","en":"Create New User","pl":"Utwórz nowego użytkownika","ph":"Lumikha ng Bagong User"}'

Common Patterns

Navigation Items

pnpm xtrans add '{"key":"Navigation.users","en":"Users","pl":"Użytkownicy","ph":"Mga User"}'

Form Labels

pnpm xtrans add '{"key":"Forms.User.firstName","en":"First Name","pl":"Imię","ph":"Pangalan"}'

Button Actions

pnpm xtrans add '{"key":"Buttons.save","en":"Save","pl":"Zapisz","ph":"I-save"}'
pnpm xtrans add '{"key":"Buttons.cancel","en":"Cancel","pl":"Anuluj","ph":"Kanselahin"}'
pnpm xtrans add '{"key":"Buttons.delete","en":"Delete","pl":"Usuń","ph":"Tanggalin"}'

Error Messages

pnpm xtrans add '{"key":"Errors.required","en":"This field is required","pl":"To pole jest wymagane","ph":"Kinakailangan ang field na ito"}'

Success Messages

pnpm xtrans add '{"key":"Success.saved","en":"Saved successfully","pl":"Zapisano pomyślnie","ph":"Matagumpay na nai-save"}'

File Locations

• Language Files: src/messages/en.json, src/messages/pl.json, src/messages/ph.json

• Script: scripts/translation.js

• Supported Languages: en (English), pl (Polish), ph (Filipino)

Quick Command Reference

CommandPurposeRequires All LanguagesaddCreate new translationYesupdateModify existingYesremoveDelete translationNo (only key)checkVerify existenceNo (only key)

Error Handling

The script provides clear error messages:

• Duplicate key: Shows existing value, suggests using update

• Missing key: Suggests using add

• Missing language: Lists which languages are required

• Invalid JSON: Shows parsing error with position

• Invalid key format: Explains key format requirements

All operations are atomic - if any language file fails, all changes are rolled back.

Pro Tips for AI Assistants

1. Always check before deciding add vs update - Use the check command

2. Use consistent key naming - Follow existing patterns in the codebase (e.g., Boss.Section.Action)

3. Keep translations concise - Shorter is better for UI elements

4. Batch related translations - Add all related keys in sequence

5. Verify after adding - Use check to confirm the translation was added correctly

Example Session

# Check if a key exists
pnpm xtrans check '{"key":"Boss.Users.Edit"}'
# Output: Key not found

# Add the translation
pnpm xtrans add '{"key":"Boss.Users.Edit","en":"Edit","pl":"Edytuj","ph":"I-edit"}'
# Output: ✓ Added 'Boss.Users.Edit' to all language files

# Verify it was added
pnpm xtrans check '{"key":"Boss.Users.Edit"}'
# Output: ✓ Key found in all languages

# Update if needed
pnpm xtrans update '{"key":"Boss.Users.Edit","en":"Edit User","pl":"Edytuj użytkownika","ph":"I-edit ang user"}'
# Output: ✓ Updated 'Boss.Users.Edit' in all language files

Crititcal to use

This is fast and powerful tool to understand codebase structure, find files, analyze imports/exports U NEED TO USE THIS EVERYTIME WHEN ASKED TO INVESIGATE ANYTHING IN CODE!!! ALWAYS!!

codemapGenerator - LLM Reference

PURPOSE: Creates ultra-compressed code maps of TypeScript/TSX projects. Use this to understand codebase structure, find files, analyze imports/exports. Outputs condensed AST maps - crucial for large codebase analysis.

Default: Current dir, .ts .tsx .jsx files, respects .gitignore, 64 workers.

Output: Condensed file paths with imports, functions, types. Symbols: /¢/=components /£/=lib /ƒ/=features /α/=app /β/=api /λ/=hooks /τ/=types /µ/=utils /§/=services

Complete Commands

# Scan current directory - outputs condensed map of ALL files
codemapGenerator

# Scan specific directory
MUST ALWAYS USE THIS COMMAND!
codemapGenerator ./src 


# Filter by FILENAME/PATH (searches file paths only)
codemapGenerator /path/to/project --filter '{"filename":["auth","user"]}'

# Filter by CONTENT (searches INSIDE file contents)
codemapGenerator /path/to/project --filter '{"content":["prisma","PrismaClient","database"]}'

# Combine both (must match filename AND content)
codemapGenerator /path/to/project --filter '{"filename":["auth"],"content":["prisma"]}'

# Use regex patterns
codemapGenerator /path/to/project --filter '{"filename":["^auth",".*service$"],"content":["class.*extends"],"regex":true}'

# Custom file extensions
codemapGenerator /path/to/project --extensions .ts .tsx .js

Filter logic:

• filename: OR (matches ANY pattern in filename/path)

• content: OR (matches ANY pattern INSIDE file)

• Between types: AND (must match both if specified) Filter logic: filename=OR, content=OR, between=AND

USE THIS EVERY TIME, EVERYWHERE this is very powerful, entire codebase maping with condense kwnoledge. MOST USE EVERY TIME LOOKING FOR ANSWERS.

SECOND: YOUE NEED TO REQUEST MULTIPE FILES TO READ IN ONE GO USING getMyFiles tool!, it provides highly optimised and compressed files content specifically designed for LLMs.

getMyFiles

getMyFiles --help

Example:

getMyFiles '["src/components/user/editor/types.ts", "src/lib/features/hooks/useFeatureAccess.ts", "src/lib/features/types.ts"]')

MANDATORY TO USE SOPHISTACTED grep searches like:

grep -Rn --include="*.tsx" -C 20 "search_pattern" . Explanation:

-R or --recursive: Search all subdirectories recursively.

-n: Show line numbers where the match occurs.

--include="*.tsx": Only search .tsx files.

-C 20: Show 20 lines before and after matches along with matched lines.

"search_pattern": Replace with your search term.

.: Start searching in the current directory.

LLM-optimized file reader with intelligent comment removal and code compression for maximum token efficiency. ALWAYS USE JSON CLIENT FOR getMyFiles