create-win-project 1.3.0

package/playbooks/universal/typescript.md

@@ -0,0 +1,272 @@
+# TypeScript Rules (Universal)
+
+Applies to every TypeScript project.
+
+---
+
+## Strict Mode — Always On
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+These flags catch real bugs. Never disable them.
+
+---
+
+## No `any`
+- Never use `any` unless absolutely unavoidable
+- When unavoidable: add `// reason:` comment explaining why
+
+```typescript
+// ❌
+const data: any = fetchUser()
+function process(input: any) { ... }
+
+// ✅
+const data: unknown = fetchUser()
+function process(input: UserInput) { ... }
+
+// ✅ justified any with comment
+// reason: third-party library has no types and @types package doesn't exist
+const chart = new (window as any).ChartLib()
+```
+
+### Alternatives to `any`
+| Instead of `any` | Use                     |
+|------------------|-------------------------|
+| Unknown data     | `unknown`               |
+| Flexible object  | `Record<string, unknown>` |
+| Multiple types   | Union `string \| number` |
+| Optional         | `T \| undefined`        |
+| Nullable         | `T \| null`             |
+
+---
+
+## Type vs Interface
+```typescript
+// Interface — for objects that may be extended or implemented
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+// Type — for unions, intersections, primitives, tuples
+type UserId = string
+type UserRole = 'ADMIN' | 'USER' | 'MODERATOR'
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
+type UserWithRole = User & { role: UserRole }
+```
+
+### Rule
+- Objects → `interface` (extends naturally, better error messages)
+- Everything else → `type`
+- Never use `I` prefix for interfaces (`IUser` → `User`)
+
+---
+
+## Discriminated Unions for State
+```typescript
+// ❌ scattered boolean flags
+type State = {
+  isLoading: boolean
+  isError: boolean
+  isSuccess: boolean
+  data?: User
+  error?: Error
+}
+
+// ✅ discriminated union — mutually exclusive states
+type State =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: User }
+  | { status: 'error'; error: Error }
+```
+
+---
+
+## Unknown Over Any for Errors
+```typescript
+// ❌
+} catch (error: any) {
+  console.log(error.message)
+}
+
+// ✅
+} catch (error: unknown) {
+  const message = error instanceof Error ? error.message : 'Unknown error'
+  logger.error(message)
+}
+```
+
+---
+
+## Generics
+Use when genuinely reusable — not for ceremony.
+
+```typescript
+// ✅ genuinely reusable
+function first<T>(array: T[]): T | undefined {
+  return array[0]
+}
+
+// ✅ reusable operation result inside the application
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
+
+// ❌ unnecessary generic
+function getUserName<T extends User>(user: T): string {
+  return user.name
+  // just use: function getUserName(user: User): string
+}
+```
+
+---
+
+## Zod for Runtime Validation
+
+Use Zod for runtime validation **when** this project has runtime validation needs (form input, API responses, external data). If the project has no such need, this section does not apply — the rules are optional.
+
+TypeScript types are compile-time only. Use Zod at runtime boundaries.
+
+```typescript
+// Define schema
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+  email: z.string().email(),
+  role: z.enum(['ADMIN', 'USER']),
+})
+
+// Infer type from schema — single source of truth
+type User = z.infer<typeof UserSchema>
+
+// Validate at runtime
+const user = UserSchema.parse(apiResponse.data)
+```
+
+### When to use Zod
+- Form validation (via React Hook Form resolver)
+- API response parsing
+- Environment variable validation (t3-env)
+- Any external data entering the system
+
+---
+
+## Where Types Live
+
+### Decision tree
+```
+Is this type used across multiple features?
+  → src/types/[name].ts
+
+Is this type specific to one feature?
+  → src/features/[name]/types/index.ts
+
+Is this type a Zod schema + inferred type?
+  → src/features/[name]/schemas/[name].schema.ts
+
+Is this type shared by several transport clients?
+  → src/types/transport.ts
+```
+
+### Global types (src/types/)
+```typescript
+// src/types/transport.ts
+// Successful endpoints return their normal DTO. Model only genuinely shared shapes.
+export type ProblemDetails = { type: string; title: string; status: number; detail?: string; traceId?: string }
+
+// src/types/pagination.ts
+export type PaginatedResponse<T> = {
+  data: T[]
+  total: number
+  page: number
+  limit: number
+}
+```
+
+---
+
+## Type Assertions
+Avoid `as` unless justified.
+
+```typescript
+// ❌ lying to TypeScript
+const user = data as User
+
+// ✅ validate first, then trust
+const user = UserSchema.parse(data)
+
+// ✅ justified assertion with comment
+// reason: DOM ref is always set before this handler fires
+const input = inputRef.current as HTMLInputElement
+```
+
+---
+
+## Enums vs Union Types
+Prefer union types over enums for most cases.
+
+```typescript
+// ❌ enum (compiles to weird JS, harder to iterate)
+enum UserRole {
+  ADMIN = 'ADMIN',
+  USER = 'USER',
+}
+
+// ✅ const object + union type (tree-shakeable, readable compiled output)
+export const ROLES = {
+  ADMIN: 'ADMIN',
+  USER: 'USER',
+} as const
+
+export type UserRole = typeof ROLES[keyof typeof ROLES]
+// → 'ADMIN' | 'USER'
+```
+
+---
+
+## Null vs Undefined
+```typescript
+// Use null: explicitly absent (API returns null, user cleared a field)
+type User = { avatar: string | null }
+
+// Use undefined: optionally present (optional function param, optional object key)
+type Options = { timeout?: number }
+
+// Never mix without reason — pick one for each case and be consistent
+```
+
+---
+
+## Agent Rules
+```
+strict: true — never disable, never add ts-ignore without // reason:
+
+Type a new variable?
+  → Use the most specific type possible
+  → Infer from Zod schema if validating external data
+  → Use unknown for error catch blocks
+
+New shared type?
+  → If used in 2+ features → src/types/
+  → If feature-specific → features/[name]/types/
+
+New form?
+  → Zod schema first → infer type → pass to React Hook Form
+
+Avoid:
+  → any (use unknown)
+  → type assertions without reason comment
+  → enums (use const object + union type)
+  → I prefix on interfaces
+```

package/scripts/compatibility-matrix.mjs

@@ -0,0 +1,48 @@
+import fs from 'fs-extra'
+
+const catalog = await fs.readJson(new URL('../compatibility/profiles.json', import.meta.url))
+const scope = process.argv.find((arg) => arg.startsWith('--scope='))?.split('=')[1] || 'smoke'
+if (!['smoke', 'full'].includes(scope)) throw new Error('--scope must be smoke or full')
+
+const cases = [
+  'nextjs-none', 'nextjs-supabase', 'nextjs-springboot', 'nextjs-postgres', 'nextjs-laravel',
+  'react-none', 'react-supabase', 'react-springboot', 'react-laravel',
+  'react-native-none', 'react-native-supabase', 'react-native-springboot', 'react-native-laravel',
+  'laravel-api', 'laravel-blade', 'laravel-livewire', 'laravel-inertia-react',
+]
+
+function authChoices(caseName) {
+  const mobile = caseName.startsWith('react-native')
+  const nonBrowser = mobile || caseName === 'laravel-api'
+  const base = ['not-yet', 'none'].map((authentication) => ({ authentication, audience: nonBrowser ? 'multi-client' : 'website' }))
+  if (caseName.includes('supabase')) base.push({ authentication: 'yes', audience: mobile ? 'multi-client' : 'website' })
+  if (caseName.includes('springboot') || caseName.includes('laravel')) {
+    if (caseName.startsWith('laravel-') && caseName !== 'laravel-api') base.push({ authentication: 'yes', audience: 'website' })
+    else if (mobile || caseName === 'laravel-api') base.push({ authentication: 'yes', audience: 'multi-client' })
+    else base.push({ authentication: 'yes', audience: 'website' }, { authentication: 'yes', audience: 'multi-client' })
+  }
+  return base
+}
+
+const current = catalog.defaultProfile
+const full = Object.entries(catalog.profiles).filter(([profile]) => profile === current).flatMap(([profile, versions]) =>
+  cases.flatMap((caseName) => ['small', 'medium', 'large'].flatMap((architecture) =>
+    authChoices(caseName).map((auth) => ({ profile, case: caseName, architecture, ...auth, node: versions.runtimes.node, java: versions.runtimes.java, php: versions.runtimes.php })))),
+)
+
+const smokeSelections = [
+  ['nextjs-none', 'small', 'not-yet', 'website'],
+  ['nextjs-supabase', 'medium', 'yes', 'website'],
+  ['react-springboot', 'large', 'yes', 'website'],
+  ['react-native-supabase', 'medium', 'yes', 'multi-client'],
+  ['react-native-springboot', 'small', 'yes', 'multi-client'],
+  ['laravel-api', 'medium', 'not-yet', 'multi-client'],
+  ['laravel-blade', 'small', 'yes', 'website'],
+  ['laravel-livewire', 'medium', 'none', 'website'],
+  ['laravel-inertia-react', 'large', 'yes', 'website'],
+  ['react-laravel', 'medium', 'yes', 'website'],
+]
+const smoke = full.filter((entry) => entry.profile === current && smokeSelections.some(([caseName, architecture, authentication, audience]) =>
+  entry.case === caseName && entry.architecture === architecture && entry.authentication === authentication && entry.audience === audience))
+
+process.stdout.write(JSON.stringify(scope === 'full' ? full : smoke))

package/scripts/validate-content.mjs

@@ -0,0 +1,76 @@
+import fs from 'fs-extra'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { loadCatalog, resolveStack } from '../lib/catalog.js'
+import { buildRulesIndex } from '../lib/playbooks.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const playbooksDir = path.join(root, 'playbooks')
+const catalog = await loadCatalog(playbooksDir)
+const errors = []
+
+for (const manifest of catalog.manifests) {
+  for (const entry of manifest._playbooks || []) {
+    const relative = typeof entry === 'string' ? entry : entry.file
+    if (!await fs.pathExists(path.join(playbooksDir, relative))) {
+      errors.push(`${manifest.id}: missing playbook ${relative}`)
+    }
+  }
+}
+
+const architectures = ['small', 'medium', 'large']
+const authIntents = ['not-yet', 'none']
+for (const frontend of catalog.frontends) {
+  for (const backend of frontend.appliesTo?.backend || []) {
+    const authCases = [...authIntents]
+    if (['supabase', 'springboot'].includes(backend)) authCases.push('yes')
+    for (const architecture of architectures) {
+      for (const authentication of authCases) {
+        const audiences = authentication === 'yes' && backend === 'springboot'
+          ? ['website', 'multi-client']
+          : [frontend.platform === 'mobile' ? 'multi-client' : 'website']
+        for (const authAudience of audiences) {
+          const stack = resolveStack({
+            frontend: frontend.id, backend, architecture, authentication, authAudience,
+            styling: frontend.stylingOptions?.[0], testing: 'basic', githubActions: true,
+          }, catalog)
+          try { await buildRulesIndex(stack, catalog, playbooksDir) }
+          catch (error) { errors.push(`${frontend.id}/${backend}/${architecture}/${authentication}/${authAudience}: ${error.message}`) }
+        }
+      }
+    }
+  }
+}
+
+const markdownFiles = (await fs.readdir(playbooksDir, { recursive: true, withFileTypes: true }))
+  .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+  .map((entry) => path.join(entry.parentPath, entry.name))
+for (const file of markdownFiles) {
+  const content = await fs.readFile(file, 'utf8')
+  const relative = path.relative(playbooksDir, file)
+  const limit = relative.startsWith('stack/') || relative.startsWith('platform/') || relative.startsWith('capabilities/') ? 250 : 650
+  if (content.split('\n').length > limit) errors.push(`${relative}: exceeds ${limit} lines`)
+  for (const match of content.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+    const target = match[1].split('#')[0]
+    if (!target || /^(?:https?:|mailto:)/.test(target)) continue
+    if (!await fs.pathExists(path.resolve(path.dirname(file), target))) errors.push(`${relative}: broken link ${match[1]}`)
+  }
+}
+
+const staleClaims = ['stack/nextjs.md', 'stack/react-vite.md', 'stack/react-native.md', 'stack/springboot.md', 'database/supabase.md', 'folder-structure.md']
+for (const directory of [path.join(root, 'README.md'), path.join(root, 'docs'), playbooksDir]) {
+  const stats = await fs.stat(directory)
+  const files = stats.isDirectory()
+    ? (await fs.readdir(directory, { recursive: true, withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.endsWith('.md')).map((entry) => path.join(entry.parentPath, entry.name))
+    : [directory]
+  for (const file of files) {
+    const content = await fs.readFile(file, 'utf8')
+    for (const stale of staleClaims) if (content.includes(stale)) errors.push(`${path.relative(root, file)}: stale reference ${stale}`)
+  }
+}
+
+if (errors.length) {
+  console.error(errors.join('\n'))
+  process.exit(1)
+}
+console.log(`Validated ${catalog.manifests.length} manifests and ${markdownFiles.length} playbooks across the architecture/authentication matrix.`)

package/scripts/verify-generated.mjs

@@ -0,0 +1,153 @@
+import fs from 'fs-extra'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { generateProject } from '../lib/generator.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const args = Object.fromEntries(process.argv.slice(2).map((arg) => {
+  const [key, value = 'true'] = arg.replace(/^--/, '').split('=')
+  return [key, value]
+}))
+
+const cases = {
+  'nextjs-none': { frontend: 'nextjs', backend: 'none', styling: 'tailwind' },
+  'nextjs-supabase': { frontend: 'nextjs', backend: 'supabase', styling: 'tailwind' },
+  'nextjs-springboot': { frontend: 'nextjs', backend: 'springboot', styling: 'css-modules', packageName: 'com.example' },
+  'nextjs-postgres': { frontend: 'nextjs', backend: 'postgres', styling: 'tailwind' },
+  'nextjs-laravel': { frontend: 'nextjs', backend: 'laravel', styling: 'tailwind', applicationShape: 'separate' },
+  'react-supabase': { frontend: 'react', backend: 'supabase', styling: 'tailwind' },
+  'react-none': { frontend: 'react', backend: 'none', styling: 'css-modules' },
+  'react-springboot': { frontend: 'react', backend: 'springboot', styling: 'css-modules', packageName: 'com.example' },
+  'react-laravel': { frontend: 'react', backend: 'laravel', styling: 'tailwind', applicationShape: 'separate' },
+  'react-native-supabase': { frontend: 'react-native', backend: 'supabase' },
+  'react-native-springboot': { frontend: 'react-native', backend: 'springboot', packageName: 'com.example' },
+  'react-native-none': { frontend: 'react-native', backend: 'none' },
+  'react-native-laravel': { frontend: 'react-native', backend: 'laravel', applicationShape: 'mobile' },
+  'laravel-api': { frontend: 'no-frontend', backend: 'laravel', applicationShape: 'api' },
+  'laravel-blade': { frontend: 'laravel-ui', backend: 'laravel', applicationShape: 'fullstack', laravelUi: 'blade', styling: 'tailwind' },
+  'laravel-livewire': { frontend: 'laravel-ui', backend: 'laravel', applicationShape: 'fullstack', laravelUi: 'livewire', styling: 'tailwind' },
+  'laravel-inertia-react': { frontend: 'laravel-ui', backend: 'laravel', applicationShape: 'fullstack', laravelUi: 'inertia-react', styling: 'tailwind' },
+}
+
+if (!args.profile || !cases[args.case]) {
+  throw new Error(`Usage: node scripts/verify-generated.mjs --profile=<id> --case=<${Object.keys(cases).join('|')}> [--architecture=small|medium|large] [--authentication=yes|not-yet|none] [--auth-audience=website|multi-client]`)
+}
+
+const architecture = args.architecture || 'medium'
+const authentication = args.authentication || 'not-yet'
+const authAudience = args['auth-audience'] || (cases[args.case].frontend === 'react-native' ? 'multi-client' : 'website')
+if (!['small', 'medium', 'large'].includes(architecture)) throw new Error(`Invalid architecture: ${architecture}`)
+if (!['yes', 'not-yet', 'none'].includes(authentication)) throw new Error(`Invalid authentication: ${authentication}`)
+if (!['website', 'multi-client'].includes(authAudience)) throw new Error(`Invalid auth audience: ${authAudience}`)
+
+function run(command, commandArgs, cwd, extraEnv = {}) {
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    env: { ...process.env, ...extraEnv },
+    encoding: 'utf8',
+    stdio: 'inherit',
+  })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new Error(`${command} ${commandArgs.join(' ')} failed with status ${result.status}`)
+}
+
+const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'create-win-compat-'))
+const selected = cases[args.case]
+const projectName = `${args.case.replaceAll('react-native', 'expo')}-${architecture}-${authentication.replaceAll('-', '')}-${authAudience}`
+
+try {
+  process.chdir(fixtureRoot)
+  await generateProject({
+    projectName,
+    projectDescription: `Compatibility verification for ${args.case}`,
+    compatibilityProfile: args.profile,
+    architecture,
+    authentication,
+    authAudience,
+    testing: selected.frontend === 'react-native' ? 'basic' : 'full',
+    docker: selected.frontend !== 'react-native' || selected.backend === 'laravel',
+    makefile: false,
+    githubActions: true,
+    expectedConcerns: [],
+    ...selected,
+  }, root)
+
+  const projectRoot = path.join(fixtureRoot, projectName)
+  const metadata = await fs.readJson(path.join(projectRoot, 'create-win-project.profile.json'))
+  if (metadata.compatibilityProfile.id !== args.profile || metadata.architectureProfile !== architecture ||
+      metadata.authentication.intent !== authentication || metadata.authentication.audience !== authAudience) {
+    throw new Error('Generated profile metadata does not match the requested matrix entry')
+  }
+  const packageRoot = selected.frontend === 'react' ? path.join(projectRoot, 'frontend') : projectRoot
+  const publicEnv = {
+    NEXT_PUBLIC_SUPABASE_URL: 'https://example.supabase.co',
+    NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: 'test-publishable-key',
+    VITE_SUPABASE_URL: 'https://example.supabase.co',
+    VITE_SUPABASE_PUBLISHABLE_KEY: 'test-publishable-key',
+    EXPO_PUBLIC_SUPABASE_URL: 'https://example.supabase.co',
+    EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY: 'test-publishable-key',
+    NEXT_PUBLIC_API_URL: 'http://localhost:8080',
+    VITE_API_URL: 'http://localhost:8080',
+    EXPO_PUBLIC_API_URL: 'http://localhost:8080',
+    POSTGRES_USER: 'postgres',
+    POSTGRES_PASSWORD: 'compatibility-test',
+    POSTGRES_DB: projectName.replaceAll('-', '_'),
+    DATABASE_URL: `postgresql://postgres:compatibility-test@localhost:5432/${projectName.replaceAll('-', '_')}`,
+    SPRING_PROFILES_ACTIVE: 'test',
+    OIDC_ISSUER_URI: 'http://localhost:9090/realms/app',
+    OIDC_AUDIENCE: 'api',
+    AUTH0_DOMAIN: 'example.auth0.com',
+    AUTH0_AUDIENCE: 'https://api.example.test',
+    SPRING_SECURITY_USER_NAME: 'compat-user',
+    SPRING_SECURITY_USER_PASSWORD: 'compat-password',
+  }
+
+  if (await fs.pathExists(path.join(packageRoot, 'package.json'))) {
+    run('npm', ['install'], packageRoot)
+    const packageJson = await fs.readJson(path.join(packageRoot, 'package.json'))
+    if (packageJson.scripts.lint) run('npm', ['run', 'lint'], packageRoot, publicEnv)
+    if (packageJson.scripts.typecheck) run('npm', ['run', 'typecheck'], packageRoot, publicEnv)
+    if (packageJson.scripts.test) run('npm', ['test', '--', ...(selected.frontend === 'react-native' ? ['--runInBand'] : [])], packageRoot, publicEnv)
+
+    if (selected.frontend === 'react-native') {
+      run('npx', ['expo', 'install', '--check'], packageRoot, { ...publicEnv, CI: '1' })
+      run('npm', ['run', 'build', '--', '--platform', 'web'], packageRoot, publicEnv)
+    } else {
+      run('npm', ['run', 'build'], packageRoot, publicEnv)
+      if (packageJson.scripts['test:e2e']) {
+        run('npx', ['playwright', 'install', ...(process.env.CI ? ['--with-deps'] : []), 'chromium'], packageRoot)
+        run('npm', ['run', 'test:e2e'], packageRoot, publicEnv)
+      }
+    }
+  }
+
+  if (selected.backend === 'springboot') {
+    const backendRoot = path.join(projectRoot, 'backend')
+    run('./mvnw', ['--batch-mode', 'test'], backendRoot)
+    run('./mvnw', ['--batch-mode', 'package', '-DskipTests'], backendRoot)
+  }
+
+  if (selected.backend === 'laravel') {
+    const backendRoot = ['laravel-ui', 'no-frontend'].includes(selected.frontend) ? projectRoot : path.join(projectRoot, 'backend')
+    run('composer', ['install', '--no-interaction', '--prefer-dist'], backendRoot)
+    run('docker', ['compose', 'up', '-d', '--wait', 'db'], projectRoot, publicEnv)
+    try {
+      run('composer', ['check'], backendRoot, { ...publicEnv, DB_HOST: '127.0.0.1', DB_PORT: '5432', DB_DATABASE: publicEnv.POSTGRES_DB, DB_USERNAME: publicEnv.POSTGRES_USER, DB_PASSWORD: publicEnv.POSTGRES_PASSWORD, APP_KEY: 'base64:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' })
+    } finally {
+      run('docker', ['compose', 'down', '--volumes'], projectRoot, publicEnv)
+    }
+  }
+
+  if (selected.frontend !== 'react-native') {
+    run('docker', ['compose', 'config'], projectRoot, publicEnv)
+    if (args.containers === 'true') {
+      run('docker', ['compose', 'build'], projectRoot, publicEnv)
+      if (selected.backend === 'postgres') run('docker', ['build', '-t', `${projectName}:compat`, '.'], projectRoot, publicEnv)
+    }
+  }
+} finally {
+  process.chdir(root)
+  await fs.remove(fixtureRoot)
+}

package/templates/agents/nextjs.md

@@ -0,0 +1,47 @@
+# AGENTS.md
+
+> Small operating contract for agents. Project intent lives in `CONTEXT.md`; task guidance is routed through `RULES.md`.
+
+## Project
+
+{{PROJECT_NAME}} — {{PROJECT_DESCRIPTION}}
+
+- Stack: `{{STACK}}`
+- Platform: `{{PLATFORM}}`
+- Architecture profile: `{{ARCHITECTURE}}`
+
+## Commands
+
+- Install: `npm install` initially; use `npm ci` after committing the lockfile.
+- Develop: `npm run dev`
+- Validate: `npm run lint && npm run typecheck && npm run test --if-present && npm run build`
+- End-to-end: `npm run test:e2e --if-present`
+- Spring backend, when present: `cd backend && ./mvnw --batch-mode test` (`mvnw.cmd` on Windows)
+
+## Required workflow
+
+1. Read `CONTEXT.md` and inspect neighboring implementation and tests.
+2. Find the concern in `RULES.md`; open only its linked playbook section.
+3. State assumptions when product behavior is ambiguous.
+4. Make the smallest coherent change and add risk-appropriate tests.
+5. Run lint, typecheck, relevant tests, and a production build before completion.
+
+## Always-on constraints
+
+{{CONSTRAINTS}}
+
+- Validate untrusted input at the server boundary.
+- Authenticate and authorize separately; enforce authorization near data and side effects.
+- Never expose server secrets through public environment prefixes or client modules.
+
+## Authority boundaries
+
+- Do not deploy, publish, merge, push, send messages, or modify production data unless explicitly asked.
+- Do not delete user work or weaken tests/security controls to make a check pass.
+
+## Definition of done
+
+- Acceptance behavior works and has appropriate coverage.
+- Validation commands pass, or the exact blocker is reported.
+- Errors do not leak secrets, personal data, or internal details.
+- Relevant architecture, API, and environment documentation is updated.

package/templates/agents/react-native.md

@@ -0,0 +1,48 @@
+# AGENTS.md
+
+> Small operating contract for agents. Project intent lives in `CONTEXT.md`; task guidance is routed through `RULES.md`.
+
+## Project
+
+{{PROJECT_NAME}} — {{PROJECT_DESCRIPTION}}
+
+- Stack: `{{STACK}}`
+- Platform: `{{PLATFORM}}`
+
+## Commands
+
+- Install: `npm install` initially; use `npm ci` after committing the lockfile.
+- Develop: `npm run dev`
+- Typecheck: `npm run typecheck`
+- Tests: `npm test -- --runInBand` when configured.
+- Export check: `npm run build -- --platform web`
+- Spring backend, when present: `cd backend && ./mvnw --batch-mode test` (`mvnw.cmd` on Windows)
+
+## Required workflow
+
+1. Read `CONTEXT.md` and inspect neighboring screens, hooks, services, and tests.
+2. Find the concern in `RULES.md`; open only its linked playbook section.
+3. State assumptions when behavior is ambiguous.
+4. Make the smallest coherent change and test it on the affected platform.
+5. Run typecheck, relevant tests, and an export/build check.
+
+## Always-on constraints
+
+{{CONSTRAINTS}}
+
+- Keep screens thin; side effects belong in hooks and services.
+- Store sensitive credentials with platform secure storage, never AsyncStorage.
+- Public-prefixed Expo values are bundled into the application and are never secrets.
+- Client navigation guards are user experience, not server authorization.
+
+## Authority boundaries
+
+- Do not publish builds, deploy, merge, push, or modify production data unless explicitly asked.
+- Do not add native modules or eject without explaining the impact.
+
+## Definition of done
+
+- Acceptance behavior works on the affected platform with appropriate tests.
+- Typecheck, tests, and export/build pass, or the exact blocker is reported.
+- Loading, offline, error, safe-area, keyboard, and accessibility behavior are considered.
+- Relevant docs are updated.