create-win-project 1.3.0

package/playbooks/devops/makefile.md

@@ -0,0 +1,556 @@
+# DevOps: Makefile
+
+---
+
+## Core Rules
+- All targets declared in `.PHONY` — no exceptions
+- Always include a `help` target as default
+- Variables declared at top of file
+- One logical action per target
+- Targets that chain: call other make targets, not duplicated raw commands
+- Use variables for repeated tools/commands (`$(COMPOSE)`, `$(SUPABASE)`, `$(NPM)`, etc.)
+- Local development commands must stay local regardless of Git branch
+- Never infer production behavior from `git branch --show-current`
+- Destructive database commands must explicitly target the intended environment
+- `db-reset` means local development reset unless a project manifest explicitly defines otherwise
+- Never create a normal Make target that resets the production database
+- Production deployment/database mutation should be handled by explicit release/CI workflows where possible
+- Help text must clearly label destructive commands and environment scope
+
+---
+
+## Environment Rule
+
+Git workflow and runtime environment are separate concerns.
+
+```text
+Git flow:
+feature/* / fix/*
+        ↓
+       dev
+        ↓
+      main
+        ↓
+   release tag
+```
+
+Local commands must behave the same on every branch:
+
+```text
+feature/* + make dev → LOCAL environment
+dev       + make dev → LOCAL environment
+main      + make dev → LOCAL environment
+```
+
+Do NOT implement logic like:
+
+```makefile
+# BAD — branch silently changes environment
+ifeq ($(shell git branch --show-current),main)
+  ENV := production
+endif
+```
+
+Production credentials and production deployment belong to the deployment/release environment, not to branch-sensitive local Make commands.
+
+---
+
+## Full Makefile Template (React + Spring Boot)
+
+```makefile
+# =============================================================================
+# Makefile — {{PROJECT_NAME}}
+# =============================================================================
+
+# Variables
+COMPOSE        := docker compose
+COMPOSE_PROD   := docker compose -f docker-compose.prod.yml
+FRONTEND       := $(COMPOSE) exec frontend
+BACKEND        := $(COMPOSE) exec backend
+DB             := $(COMPOSE) exec db
+
+# =============================================================================
+# Default
+# =============================================================================
+
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show all available commands
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-24s\033[0m %s\n", $$1, $$2}'
+
+# =============================================================================
+# Project Lifecycle — LOCAL
+# =============================================================================
+
+.PHONY: dev up down restart logs logs-front logs-back clean
+
+dev: ## LOCAL: Start all containers and follow logs
+	$(COMPOSE) up --build
+
+up: ## LOCAL: Start all containers in background
+	$(COMPOSE) up -d --build
+
+down: ## LOCAL: Stop and remove local containers
+	$(COMPOSE) down
+
+restart: down up ## LOCAL: Stop then start all containers
+
+logs: ## LOCAL: Follow logs from all containers
+	$(COMPOSE) logs -f
+
+logs-front: ## LOCAL: Follow frontend logs only
+	$(COMPOSE) logs -f frontend
+
+logs-back: ## LOCAL: Follow backend logs only
+	$(COMPOSE) logs -f backend
+
+clean: ## LOCAL DESTRUCTIVE: Remove containers, volumes, and orphans
+	$(COMPOSE) down -v --remove-orphans
+
+# =============================================================================
+# Individual Services — LOCAL
+# =============================================================================
+
+.PHONY: dev-front dev-back
+
+dev-front: ## LOCAL: Start frontend container only
+	$(COMPOSE) up frontend --build
+
+dev-back: ## LOCAL: Start backend + DB containers only
+	$(COMPOSE) up backend db --build
+
+# =============================================================================
+# Database — LOCAL
+# =============================================================================
+
+.PHONY: migrate seed db-reset db-shell
+
+migrate: ## LOCAL: Run pending Flyway migrations
+	$(BACKEND) ./mvnw flyway:migrate
+
+seed: ## LOCAL: Seed database with development data
+	$(DB) psql -U $${POSTGRES_USER} -d $${POSTGRES_DB} -f /docker-entrypoint-initdb.d/seed.sql
+
+db-reset: ## LOCAL DESTRUCTIVE: Drop + migrate + seed local DB
+	$(BACKEND) ./mvnw flyway:clean flyway:migrate
+	$(MAKE) seed
+
+db-shell: ## LOCAL: Open psql shell inside local DB container
+	$(DB) psql -U $${POSTGRES_USER} -d $${POSTGRES_DB}
+
+# =============================================================================
+# Shells — LOCAL
+# =============================================================================
+
+.PHONY: shell-front shell-back
+
+shell-front: ## LOCAL: Open shell inside frontend container
+	$(FRONTEND) sh
+
+shell-back: ## LOCAL: Open shell inside backend container
+	$(BACKEND) sh
+
+# =============================================================================
+# Quality
+# =============================================================================
+
+.PHONY: lint test test-front test-back
+
+lint: ## Run ESLint on frontend
+	$(FRONTEND) npm run lint
+
+test: test-front test-back ## Run all tests
+
+test-front: ## Run Vitest frontend tests
+	$(FRONTEND) npm run test
+
+test-back: ## Run JUnit backend tests
+	$(BACKEND) ./mvnw test
+
+# =============================================================================
+# Production Runtime
+# =============================================================================
+
+.PHONY: build prod-up prod-down
+
+build: ## Build production Docker images
+	$(COMPOSE_PROD) build
+
+prod-up: ## PRODUCTION: Start production containers
+	$(COMPOSE_PROD) up -d
+
+prod-down: ## PRODUCTION: Stop production containers
+	$(COMPOSE_PROD) down
+
+# NOTE:
+# Do not add prod-db-reset / db-reset-prod targets.
+# Production database schema changes should use the project's migration/release flow.
+
+# =============================================================================
+# Scaffolding
+# =============================================================================
+
+.PHONY: init
+
+init: ## Scaffold project folder structure (run once after cloning)
+	@echo "Scaffolding project structure..."
+	@mkdir -p frontend/src/{app,pages,components/{ui,shared,layout,forms},features,stores,lib,hooks,types,constants}
+	@mkdir -p frontend/e2e
+	@mkdir -p frontend/public
+	@mkdir -p backend/src/main/java/com/app/{auth/{dto,entity},config,common/{exception,response,jwt,audit}}
+	@mkdir -p backend/src/main/resources/db/{migration,dev}
+	@mkdir -p backend/src/test/java/com/app
+	@mkdir -p docs
+	@echo "Done. Run: make dev"
+```
+
+---
+
+## Simplified Makefile (Next.js + Supabase — Local + Production, No Staging)
+
+This template intentionally keeps normal Makefile database operations local.
+
+Production credentials and production migration execution belong to the deployment/release workflow.
+
+```makefile
+# =============================================================================
+# Makefile — {{PROJECT_NAME}} (Next.js + Supabase)
+# =============================================================================
+
+SHELL := /bin/bash
+
+# Variables
+SUPABASE := npm exec -- supabase
+NPM      := npm
+
+# =============================================================================
+# Default
+# =============================================================================
+
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show all available commands
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-24s\033[0m %s\n", $$1, $$2}'
+
+# =============================================================================
+# Development — ALWAYS LOCAL
+# =============================================================================
+
+.PHONY: dev build lint test test-e2e
+
+dev: supabase-start ## LOCAL: Start Supabase + Next.js dev server
+	$(NPM) run dev
+
+build: ## Build Next.js application
+	$(NPM) run build
+
+lint: ## Run ESLint
+	$(NPM) run lint
+
+test: ## Run unit/integration tests
+	$(NPM) run test
+
+test-e2e: ## Run Playwright E2E tests
+	$(NPM) run test:e2e
+
+# =============================================================================
+# Supabase Local Stack — ALWAYS LOCAL
+# =============================================================================
+
+.PHONY: supabase-start supabase-stop supabase-status
+
+supabase-start: ## LOCAL: Start Supabase stack
+	$(SUPABASE) start
+
+supabase-stop: ## LOCAL: Stop Supabase stack
+	$(SUPABASE) stop
+
+supabase-status: ## LOCAL: Show local Supabase URLs and keys
+	$(SUPABASE) status
+
+# =============================================================================
+# Database — ALWAYS LOCAL
+# =============================================================================
+
+.PHONY: db-reset db-reset-clean db-types db-diff
+
+db-reset: ## LOCAL DESTRUCTIVE: Reset DB, apply migrations, run seed
+	$(SUPABASE) db reset --local
+
+db-reset-clean: ## LOCAL DESTRUCTIVE: Reset DB without seed data
+	$(SUPABASE) db reset --local --no-seed
+
+db-types: ## LOCAL: Generate TypeScript types from local schema
+	$(SUPABASE) gen types --lang typescript --local > src/types/database.types.ts
+
+db-diff: ## LOCAL: Generate migration from local diff: make db-diff name=add_vehicle_status
+	@if [ -z "$(name)" ]; then \
+		echo "Usage: make db-diff name=add_vehicle_status"; \
+		exit 1; \
+	fi
+	$(SUPABASE) db diff --local -f $(name)
+
+# =============================================================================
+# Migrations — FILE CREATION ONLY
+# =============================================================================
+
+.PHONY: migration
+
+migration: ## Create migration file: make migration name=add_vehicle_status
+	@if [ -z "$(name)" ]; then \
+		echo "Usage: make migration name=add_vehicle_status"; \
+		exit 1; \
+	fi
+	$(SUPABASE) migration new $(name)
+
+# =============================================================================
+# Production Safety
+# =============================================================================
+
+# Intentionally NO targets for:
+#   db-reset-prod
+#   prod-db-reset
+#   production-reset
+#
+# Do not make `dev` or `db-reset` branch-dependent.
+# `make dev` is LOCAL even when current Git branch is main.
+# Production database migrations should run through an explicit release/CI flow.
+```
+
+### Supabase Command Contract
+
+```text
+make dev               → LOCAL Supabase + local Next.js
+make supabase-start    → LOCAL only
+make supabase-stop     → LOCAL only
+make supabase-status   → LOCAL only
+make db-reset          → LOCAL only, destructive
+make db-reset-clean    → LOCAL only, destructive
+make db-types          → LOCAL schema
+make db-diff name=...  → LOCAL schema diff
+make migration name=.. → creates migration file only
+```
+
+No Make target should silently switch these operations to the hosted production project.
+
+### Production Migration Flow
+
+Production schema deployment is intentionally not a normal local Make target.
+
+Preferred release/CI flow:
+
+```bash
+# Preview pending migrations against the linked production project
+npm exec -- supabase db push --linked --dry-run
+
+# Apply only after review / release approval
+npm exec -- supabase db push --linked
+```
+
+Forbidden against production:
+
+```bash
+npm exec -- supabase db reset --linked
+```
+
+Do not add a Make target that wraps the forbidden reset command.
+
+---
+
+## Simplified Makefile (Next.js + PostgreSQL/Prisma)
+
+```makefile
+# =============================================================================
+# Makefile — {{PROJECT_NAME}} (Next.js + Prisma)
+# =============================================================================
+
+COMPOSE := docker compose
+NPM     := npm
+PRISMA  := npx prisma
+
+.DEFAULT_GOAL := help
+
+.PHONY: help dev build lint test db-start db-stop db-migrate db-seed db-reset db-studio init
+
+help: ## Show all available commands
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-24s\033[0m %s\n", $$1, $$2}'
+
+dev: db-start ## LOCAL: Start PostgreSQL + Next.js dev server
+	$(NPM) run dev
+
+build: ## Build for production
+	$(NPM) run build
+
+lint: ## Run ESLint
+	$(NPM) run lint
+
+test: ## Run tests
+	$(NPM) run test
+
+db-start: ## LOCAL: Start PostgreSQL container
+	$(COMPOSE) up -d db
+
+db-stop: ## LOCAL: Stop local PostgreSQL container
+	$(COMPOSE) down
+
+db-migrate: ## LOCAL: Run Prisma development migrations
+	$(PRISMA) migrate dev
+
+db-seed: ## LOCAL: Seed database
+	$(PRISMA) db seed
+
+db-reset: ## LOCAL DESTRUCTIVE: Reset + migrate + seed
+	$(PRISMA) migrate reset --force
+
+db-studio: ## LOCAL: Open Prisma Studio
+	$(PRISMA) studio
+
+```
+
+Production Prisma migrations should use the deployment/release workflow (for example, `prisma migrate deploy`) rather than a destructive local reset target.
+
+---
+
+## Help Target Convention
+
+Every user-facing target must include a `##` description so `make help` remains useful.
+
+```makefile
+.PHONY: example
+example: ## LOCAL: Explain exactly what the command does
+	@echo "example"
+```
+
+Recommended prefixes in descriptions:
+
+```text
+LOCAL:             non-destructive local command
+LOCAL DESTRUCTIVE: destructive local command
+PRODUCTION:        explicit production runtime/release command
+```
+
+Never label a command as generic if it mutates an environment-specific database.
+
+---
+
+## Database Safety Rules
+
+```text
+Local database reset?
+  → Allowed
+  → Target must explicitly use local environment where CLI supports it
+
+Production database reset?
+  → Forbidden
+  → Do not create the target
+
+Production migration?
+  → Use reviewed migration files
+  → Preview first when tooling supports dry-run
+  → Prefer release/CI execution
+
+Seed development data?
+  → Local only
+  → Never automatically include development seed in production
+```
+
+For Supabase specifically:
+
+```makefile
+db-reset:
+	$(SUPABASE) db reset --local
+```
+
+Do not rely only on the CLI default when the command is intentionally safety-critical.
+
+---
+
+## Git Branch Rules
+
+Make targets must not use branch name as an automatic environment selector.
+
+Bad:
+
+```text
+main branch → production DB
+dev branch  → local DB
+```
+
+Good:
+
+```text
+any branch + local command → local environment
+release/deployment config  → production environment
+```
+
+A branch check may be used as an additional safety gate for an already-explicit release target, but branch detection must never silently convert a development command into a production command.
+
+---
+
+## Agent Rules
+
+```text
+New make target?
+  → Add to .PHONY
+  → Add ## help description
+  → Declare environment scope in help text when relevant
+  → Use tool variables instead of repeated hardcoded commands
+  → Keep one logical action per target
+
+Target chains another target?
+  → Use $(MAKE) target-name or a prerequisite
+  → Do not duplicate the chained target's raw commands
+
+New Docker command?
+  → Use $(COMPOSE) / configured compose variable
+  → Do not hardcode docker compose repeatedly
+
+Supabase local lifecycle?
+  → supabase-start / supabase-stop / supabase-status
+  → Always local
+
+Supabase db reset?
+  → Must explicitly use `db reset --local`
+  → Help text must say LOCAL DESTRUCTIVE
+  → Never use `--linked`
+
+Supabase migration creation?
+  → `make migration name=...`
+  → Validate name is present
+  → Creates migration file only
+
+Supabase schema diff?
+  → Explicitly use local schema
+  → `make db-diff name=...`
+
+Supabase type generation?
+  → Generate from `--local` during normal development
+
+Production Supabase migration?
+  → Do not hide it behind normal local commands
+  → Prefer release/CI workflow
+  → Preview with dry-run before applying
+  → Never reset production
+
+Current Git branch is main?
+  → `make dev` is still LOCAL
+  → `make db-reset` is still LOCAL
+  → Do not switch credentials based on branch
+
+New service in compose?
+  → Add logs-[service] if useful
+  → Add shell-[service] if useful
+
+Default goal?
+  → Always `.DEFAULT_GOAL := help`
+
+Init target?
+  → Scaffold only deterministic project structure
+  → Do not overwrite existing files
+  → Do not create production secrets
+```

package/playbooks/devops/pr-template.manifest.json

@@ -0,0 +1,10 @@
+{
+  "id": "pr-template",
+  "kind": "devops",
+  "label": "PR Template",
+  "required": false,
+  "folders": [],
+  "concerns": [
+    { "id": "pr", "required": true, "sections": ["Template"] }
+  ]
+}

package/playbooks/devops/pr-template.md

@@ -0,0 +1,106 @@
+# DevOps: Pull Request Template
+
+---
+
+## Template
+```markdown
+## What does this PR do?
+
+<!-- Describe the change clearly. What problem does it solve? What was added or fixed? -->
+
+---
+
+## Type of change
+
+- [ ] `feat` — new feature
+- [ ] `fix` — bug fix
+- [ ] `refactor` — restructure without behavior change
+- [ ] `chore` — deps, config, tooling
+- [ ] `docs` — documentation only
+- [ ] `test` — adding or updating tests
+
+---
+
+## Scope
+
+- [ ] `frontend`
+- [ ] `backend`
+- [ ] `docker`
+- [ ] `ci`
+- [ ] `docs`
+- [ ] `deps`
+
+---
+
+## How to test this?
+
+1.
+2.
+3.
+
+---
+
+## Checklist
+
+### General
+- [ ] Branched off `dev`, not `main`
+- [ ] Branch name follows convention (`feat/`, `fix/`, `refactor/`, `chore/`)
+- [ ] Commits follow `type(scope): description` convention
+- [ ] No `console.log` or debug code
+- [ ] No hardcoded secrets or credentials
+
+### Quality
+- [ ] `make lint` passes
+- [ ] `make test` passes
+- [ ] `make build` passes
+
+### Backend (if applicable)
+- [ ] New endpoints documented in `docs/api/endpoints.md`
+- [ ] DTOs used — no raw entity exposed in responses
+- [ ] New Flyway migration created if schema changed
+- [ ] Migration file follows naming: `V{n}__{description}.sql`
+- [ ] Unit test added for each new service method
+- [ ] Integration test added for each new controller endpoint
+
+### Frontend (if applicable)
+- [ ] New API calls live inside `features/[name]/api/`
+- [ ] New hooks live inside `features/[name]/hooks/`
+- [ ] No business logic inside `pages/` or page components
+- [ ] Route added to router if new page
+
+### Docs
+- [ ] `docs/api/endpoints.md` updated if endpoints changed
+- [ ] `docs/api/errors.md` updated if new error codes added
+- [ ] `AGENTS.md` updated if new rules or conventions added
+- [ ] `README.md` updated if setup steps changed
+
+---
+
+Closes #
+```
+
+---
+
+## File Location
+```
+.github/PULL_REQUEST_TEMPLATE.md
+```
+
+GitHub automatically uses this template for all new PRs in the repo.
+
+---
+
+## Agent Rules
+```
+When told to open a PR?
+  → Fill every section of this template
+  → Description must explain what AND why
+  → How to test must have actual numbered steps
+  → Checklist must be fully checked before opening
+  → Never open PR unless explicitly asked
+
+When reviewing a PR?
+  → Check AGENTS.md rules are followed
+  → Check RULES.md patterns are followed
+  → Check docs are updated if endpoints or rules changed
+```

package/playbooks/platform/laravel-ui/blade/architecture.md

@@ -0,0 +1,5 @@
+# Blade Architecture
+
+Blade is Laravel's server-rendered presentation adapter. Small uses Controller → Eloquent → View;
+Medium moves meaningful workflows into Actions/Services; Large aligns views with modular-monolith
+ownership. Templates never own queries, authorization, transactions, or business workflows.

package/playbooks/platform/laravel-ui/blade/runtime.md

@@ -0,0 +1,5 @@
+# Blade Runtime
+
+Use GET rendering and POST/PUT/PATCH/DELETE followed by redirect to a fresh GET. Form Requests own
+server validation; Blade renders feedback. Pass intentionally shaped view data, escape untrusted
+output, flash only small non-sensitive messages, and keep secrets out of rendered HTML.

package/playbooks/platform/laravel-ui/blade/security.md

@@ -0,0 +1,5 @@
+# Blade Security
+
+Use escaped output unless explicitly sanitized, framework CSRF tokens for mutations, server-side
+Policies/Gates, validated relative redirects, and throttling for authentication/recovery. Hiding a
+button is not authorization. Production error pages expose no stack, SQL, secret, or private data.

package/playbooks/platform/laravel-ui/blade/structure.md

@@ -0,0 +1,5 @@
+# Blade Structure
+
+Put route views in `resources/views/<feature>`, reusable shells in `layouts`, domain-free primitives
+in `components/ui`, and genuinely shared presentation in `components/shared`. Keep feature-specific
+components close to their feature and create directories only with real files.

package/playbooks/platform/laravel-ui/blade/testing.md

@@ -0,0 +1,5 @@
+# Blade Testing
+
+Feature tests prove middleware, validation, authorization, redirects, database effects, selected
+views, and required accessible content. Test component output only when it is behaviorally important;
+use Playwright for critical login, navigation, submission, forbidden, and recovery journeys.

package/playbooks/platform/laravel-ui/inertia-react/architecture.md

@@ -0,0 +1,5 @@
+# Inertia React Architecture
+
+Laravel owns routes, authorization, data selection, and navigation responses; React owns rendering
+and browser interaction. Medium uses Laravel Actions/Services and reusable React feature modules.
+Large adds public feature APIs and module checks—not an internal REST API or microservices.