create-win-project 1.3.0

package/playbooks/universal/coding-rules.md

@@ -0,0 +1,281 @@
+# Coding Rules (Universal)
+
+Applies to every project regardless of stack.
+
+---
+
+## Core Principle
+```
+simple + explicit + consistent
+over
+complex + abstract + theoretically pure
+```
+
+Complexity must earn abstraction. Start simple. Add layers only when justified.
+
+---
+
+## Naming
+
+### Files
+```
+React components:   PascalCase    UserCard.tsx
+Hooks:              camelCase     useUserData.ts
+Utilities:          camelCase     formatDate.ts
+Constants:          camelCase     apiEndpoints.ts
+Types:              camelCase     userTypes.ts
+CSS Modules:        PascalCase    UserCard.module.css
+Java classes:       PascalCase    UserService.java
+SQL migrations:     snake_case    V1__create_users_table.sql
+```
+
+### Variables and Functions
+```
+Variables:          camelCase     userName, isLoading, hasError
+Functions:          camelCase     getUser(), createOrder(), formatDate()
+Constants:          SCREAMING     MAX_RETRIES, API_BASE_URL
+React components:   PascalCase    UserCard, LoginForm
+Types/Interfaces:   PascalCase    UserResponse, ApiError
+Enums:              PascalCase    UserRole, OrderStatus
+```
+
+### Name for what it does, not what it is
+```
+❌ getData(), handleThing(), doStuff(), temp, x
+✅ getUserById(), handleLoginSubmit(), formatCurrency()
+```
+
+### Boolean naming
+```
+❌ user, loading, error
+✅ isLoading, hasError, isAuthenticated, canEdit
+```
+
+---
+
+## Functions
+- One responsibility per function
+- Max 3 parameters — if more, use an options object
+- Return early to avoid deep nesting
+
+```typescript
+// ❌
+function processUser(user, role, permissions, sendEmail, notify) { ... }
+
+// ✅
+function processUser(user: User, options: ProcessUserOptions) { ... }
+
+// ❌ deep nesting
+function getUser(id) {
+  if (id) {
+    if (isValid(id)) {
+      // logic
+    }
+  }
+}
+
+// ✅ early return
+function getUser(id) {
+  if (!id) return null
+  if (!isValid(id)) return null
+  // logic
+}
+```
+
+---
+
+## Imports
+
+### Frontend
+- Always use absolute imports with `@/` prefix
+- Never use relative `../../` imports
+- Barrel exports (`index.ts`) for public API of a feature only
+
+```typescript
+// ❌
+import { UserCard } from '../../../components/ui/UserCard'
+
+// ✅
+import { UserCard } from '@/components/ui/UserCard'
+```
+
+### Import Order (enforced by ESLint)
+```
+1. External libraries
+2. Internal absolute (@/)
+3. Types
+4. Styles / assets
+```
+
+---
+
+## Constants
+- No magic numbers or strings in logic
+- All constants in `src/constants/index.ts` or feature-level constants file
+
+```typescript
+// ❌
+if (role === 'ADMIN') { ... }
+setTimeout(fn, 900000)
+
+// ✅
+import { ROLES, TOKEN_EXPIRY } from '@/constants'
+if (role === ROLES.ADMIN) { ... }
+setTimeout(fn, TOKEN_EXPIRY.ACCESS)
+```
+
+---
+
+## Async / Error Handling
+
+### Frontend
+- Always async/await — never `.then()` chains
+- Always handle errors at the hook level, not component level
+- Never swallow errors silently
+
+```typescript
+// ❌
+fetchUser().then(data => setUser(data)).catch(e => console.log(e))
+
+// ✅
+try {
+  const user = await fetchUser()
+  setUser(user)
+} catch (error) {
+  logger.error('fetchUser failed:', error)
+  throw error
+}
+```
+
+### Backend
+- Always throw `AppException` — never raw `RuntimeException`
+- Never expose stack traces in API responses
+- Always catch at the `GlobalExceptionHandler` level
+
+```java
+// ❌
+throw new RuntimeException("User not found");
+
+// ✅
+throw new AppException("USER_NOT_FOUND", HttpStatus.NOT_FOUND);
+```
+
+---
+
+## Logging
+- NEVER use `console.log` directly
+- Always use `lib/logger.ts` on frontend
+- Always use SLF4J logger on backend
+
+```typescript
+// ❌
+console.log('user:', user)
+console.error('error:', error)
+
+// ✅
+import { logger } from '@/lib/logger'
+logger.info('user fetched:', user)
+logger.error('fetch failed:', error)
+```
+
+```java
+// ❌
+System.out.println("user: " + user);
+
+// ✅
+private static final Logger log = LoggerFactory.getLogger(UserService.class);
+log.info("user fetched: {}", userId);
+log.error("fetch failed for userId: {}", userId, e);
+```
+
+---
+
+## Comments
+- Comment WHY, not WHAT
+- Code should be readable enough to not need WHAT comments
+- Remove all debug/TODO comments before committing
+
+```typescript
+// ❌ explains what (obvious from code)
+// increment counter
+count++
+
+// ✅ explains why (not obvious from code)
+// Retry once — server returns 503 on cold start for ~200ms
+await retry(fetchUser, { times: 1, delay: 300 })
+```
+
+---
+
+## No Debug Code in Commits
+```
+❌ console.log
+❌ debugger
+❌ TODO comments
+❌ hardcoded test values
+❌ commented-out code blocks
+```
+
+ESLint and Husky enforce this — build fails if present.
+
+---
+
+## One Thing Per File
+```
+❌ UserCardAndForm.tsx — two components in one file
+❌ userUtils.ts — 30 unrelated utility functions
+
+✅ UserCard.tsx
+✅ UserForm.tsx
+✅ formatDate.ts
+✅ formatCurrency.ts
+```
+
+Exception: small helper types or constants directly related to the file.
+
+---
+
+## Exports
+
+### Frontend
+- Named exports everywhere except page/route components
+- Page components use default export (Next.js / React Router requirement)
+
+```typescript
+// ❌ default export for reusable components
+export default function UserCard() { ... }
+
+// ✅ named export
+export function UserCard() { ... }
+
+// ✅ default export for pages only
+export default function UserPage() { ... }
+```
+
+### Backend
+- Spring-managed beans: `@Service`, `@Repository`, `@RestController` — Spring handles export
+- Utility classes: `public static` methods
+
+---
+
+## Agent Rules
+```
+Before writing any code:
+  1. Check if the functionality already exists
+  2. Check which layer owns this responsibility
+  3. Choose the simplest correct implementation
+  4. Follow existing patterns in the codebase — don't introduce new ones
+
+Before creating a new file:
+  1. Check if an existing file should be extended instead
+  2. Follow the selected stack's structure playbook and current feature ownership
+
+Before adding a dependency:
+  1. Check if existing tools already solve it
+  2. Prefer what the playbook recommends over personal preference
+
+Naming:
+  1. Name things for what they do
+  2. Booleans start with is/has/can
+  3. No abbreviations unless universally understood (id, url, dto)
+```

package/playbooks/universal/error-handling.manifest.json

@@ -0,0 +1,10 @@
+{
+  "id": "error-handling",
+  "kind": "universal",
+  "label": "Error Handling",
+  "required": true,
+  "folders": [],
+  "concerns": [
+    { "id": "errors", "required": true, "sections": ["Error Contract", "Boundary Handling", "Security Rules for Errors"] }
+  ]
+}

package/playbooks/universal/error-handling.md

@@ -0,0 +1,21 @@
+# Error Handling
+
+## Error Contract
+
+Failures crossing a process boundary use the protocol’s standard error mechanism plus a stable application code. HTTP APIs should use RFC 9457 `ProblemDetail` unless a selected external service defines its own contract. Successful responses are ordinary DTOs; do not wrap every success in a universal envelope.
+
+Keep status mapping in the transport/web layer. Application services raise application errors without importing HTTP concepts. Record public error codes in `docs/api/errors.md` with meaning, status, retry behavior, and safe client handling.
+
+## Boundary Handling
+
+- Validate requests before side effects and report field errors without echoing secrets.
+- Convert expected domain/application failures once at the outer boundary.
+- Let cancellation remain cancellation; do not display it as a user-visible failure.
+- Retry only transient, idempotent operations with a bound and jitter. Authentication refresh follows its selected auth adapter, not a generic error interceptor.
+- Preserve the original cause in internal diagnostics while returning a safe public detail and correlation identifier.
+
+## Security Rules for Errors
+
+Never expose stack traces, SQL, filesystem paths, internal hostnames, credentials, tokens, session data, or raw third-party responses. Log PII-safe structured context, and do not route client behavior by mutable human-readable messages.
+
+Test stable codes/statuses, validation failures, not-found and conflict races, authorization denial, dependency timeouts, and unexpected-error redaction at the boundary that emits the response.

package/playbooks/universal/git-conventions.manifest.json

@@ -0,0 +1,10 @@
+{
+  "id": "git-conventions",
+  "kind": "universal",
+  "label": "Git Conventions",
+  "required": true,
+  "folders": [],
+  "concerns": [
+    { "id": "git", "required": true, "sections": ["Branch Structure", "Commit Convention", "Daily Workflow"] }
+  ]
+}

package/playbooks/universal/git-conventions.md

@@ -0,0 +1,186 @@
+# Git Conventions (Universal)
+
+Applies to every project regardless of stack.
+
+---
+
+## Branch Structure
+| Branch       | Purpose                                       |
+|--------------|-----------------------------------------------|
+| `main`       | Production — always stable, always deployable |
+| `dev`        | Integration — all features merge here first   |
+| `feature/*`  | New capability                                |
+| `fix/*`      | Bug fix                                       |
+| `refactor/*` | Restructure without behavior change           |
+| `chore/*`    | Dependencies, config, tooling                 |
+| `docs/*`     | Documentation only                            |
+| `test/*`     | Adding or updating tests only                 |
+
+## Branch Rules
+- NEVER commit directly to `main` or `dev`
+- ALWAYS branch off `dev` — never off `main`
+- NEVER merge or create PRs unless explicitly asked
+- NEVER push to remote unless explicitly asked
+- One logical change per branch — keep branches small and focused
+
+## Starting a Branch
+```bash
+git checkout dev
+git pull origin dev
+git checkout -b <type>/<short-description>
+```
+
+### Examples
+```bash
+git checkout -b feature/user-profile-page
+git checkout -b fix/token-expiry-race
+git checkout -b refactor/auth-feature-module
+git checkout -b chore/update-dependencies
+git checkout -b docs/update-api-endpoints
+```
+
+---
+
+## Commit Convention
+
+### Format
+```
+type(scope): short description
+```
+
+### Rules
+- Lowercase only — no uppercase anywhere
+- No period at the end
+- Present tense — "add" not "added", "fix" not "fixed"
+- Under 72 characters
+- One logical change per commit
+
+### Types
+| Type       | When to use                                       |
+|------------|---------------------------------------------------|
+| `feat`     | New feature or capability                         |
+| `fix`      | Bug fix                                           |
+| `refactor` | Restructure without behavior change               |
+| `chore`    | Deps, config, tooling — no production code change |
+| `docs`     | Documentation only                                |
+| `test`     | Adding or updating tests                          |
+| `ci`       | GitHub Actions or CI/CD workflow changes          |
+| `style`    | Formatting, whitespace — no logic change          |
+
+### Scopes (React + Spring Boot)
+| Scope      | When to use                        |
+|------------|------------------------------------|
+| `frontend` | Anything inside /frontend          |
+| `backend`  | Anything inside /backend           |
+| `docker`   | Dockerfile or docker-compose       |
+| `ci`       | GitHub Actions workflows           |
+| `docs`     | Anything inside /docs              |
+| `deps`     | Dependency updates (either side)   |
+
+### Scopes (Next.js projects)
+| Scope      | When to use                        |
+|------------|------------------------------------|
+| `app`      | Next.js app router, pages, layouts |
+| `api`      | API routes or server actions       |
+| `db`       | Database schema, migrations        |
+| `auth`     | Authentication logic               |
+| `ci`       | GitHub Actions workflows           |
+| `docs`     | Anything inside /docs              |
+| `deps`     | Dependency updates                 |
+
+### Examples
+```bash
+feat(frontend): add user profile page
+feat(backend): add paper download endpoint
+fix(backend): resolve token expiry race condition
+fix(frontend): correct redirect after logout
+refactor(backend): move auth logic into feature module
+refactor(frontend): restructure features folder
+chore(deps): update spring boot to 3.5.1
+chore(docker): add maven cache volume
+docs(api): update error contract with traceId field
+test(backend): add unit tests for auth service
+test(frontend): add vitest tests for useAuth hook
+ci(backend): add postgresql service to ci workflow
+```
+
+---
+
+## Daily Workflow
+```bash
+# 1. Always start from updated dev
+git checkout dev
+git pull origin dev
+
+# 2. Create your branch
+git checkout -b <type>/<description>
+
+# 3. Work in small, logical commits
+git add .
+git commit -m "type(scope): description"
+
+# 4. Push your branch
+git push origin <branch-name>
+
+# 5. Open PR → dev (only when explicitly asked)
+# 6. Merge dev → main (only when explicitly asked)
+```
+
+---
+
+## .gitignore — Always Include
+```
+# Environment
+.env
+.env.local
+.env.production
+
+# Dependencies
+node_modules/
+.mvn/
+
+# Build outputs
+dist/
+build/
+target/
+.next/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Docker volumes (if local)
+postgres-data/
+```
+
+---
+
+## Agent Rules
+```
+Never:
+  → commit directly to main or dev
+  → branch off main
+  → push or create PRs unless explicitly asked
+  → put multiple logical changes in one commit
+  → use vague commit messages ("fix stuff", "update code")
+
+Always:
+  → branch off dev
+  → one logical change per commit
+  → follow type(scope): description format
+  → present tense in commit messages
+
+When asked to commit:
+  → Stage only files relevant to the current task
+  → Write a precise commit message following the convention
+  → Do not push unless explicitly asked
+```

package/playbooks/universal/observability.manifest.json

@@ -0,0 +1,10 @@
+{
+  "id": "observability-baseline",
+  "kind": "universal",
+  "label": "Observability Baseline",
+  "required": true,
+  "folders": [],
+  "concerns": [
+    { "id": "observability", "required": true, "sections": ["Structured Events", "Health and Readiness", "Errors and Traces"] }
+  ]
+}

package/playbooks/universal/observability.md

@@ -0,0 +1,29 @@
+# Observability Baseline
+
+## Structured Events
+
+- Emit structured logs in deployed environments; use stable event names and fields.
+- Attach a request/correlation ID at the entry point and propagate it through downstream calls.
+- Record outcome, duration, route/operation, and safe identifiers. Never log secrets, tokens, cookies, passwords, or full sensitive request bodies.
+- Log exceptions once at the boundary that owns the failure; avoid duplicate logs at every layer.
+
+## Health and Readiness
+
+- Liveness answers whether the process should be restarted.
+- Readiness answers whether the instance can serve traffic and may include critical dependency checks.
+- Keep health responses free of credentials, internal topology, and verbose exception details.
+- A Docker healthcheck and deployment probe should call the application's real health endpoint.
+
+## Errors and Traces
+
+- Return a stable application error code and request ID to clients.
+- Capture uncaught server and client errors in the selected monitoring service.
+- Add distributed tracing when requests cross service boundaries; do not introduce it for a single-process starter without a concrete need.
+- Define alerts from user impact and service objectives, not raw log volume.
+
+## Verification
+
+- Test the health endpoint and error response shape.
+- Verify redaction with representative authentication and validation failures.
+- Confirm graceful shutdown stops new work and lets in-flight requests complete within the deployment deadline.
+

package/playbooks/universal/security.manifest.json

@@ -0,0 +1,11 @@
+{
+  "id": "security-baseline",
+  "kind": "universal",
+  "label": "Security Baseline",
+  "required": true,
+  "folders": [],
+  "concerns": [
+    { "id": "security-boundaries", "required": true, "sections": ["Trust Boundaries", "Authentication and Authorization"] },
+    { "id": "secret-safety", "required": true, "sections": ["Secrets and Data", "Failure Safety"] }
+  ]
+}

package/playbooks/universal/security.md

@@ -0,0 +1,30 @@
+# Security Baseline
+
+Security, validation, accessibility, and secret handling never weaken in Small projects. Stack and capability playbooks decide how these invariants are implemented.
+
+## Trust Boundaries
+
+- Treat browser, device, network, URL, header, cookie, webhook, file, environment, and database input as untrusted where it enters a trusted component.
+- Validate shape and business constraints at the trusted boundary. Client validation improves usability; it is not authorization.
+- Authenticate identity and separately authorize the requested action and resource beside protected data or side effects.
+- Default to denial. Make public entry points explicit and return only fields the caller needs.
+
+## Secrets and Data
+
+- Public client configuration is never secret. Keep credentials and privileged keys out of source, logs, generated examples, and client bundles.
+- Use environment or platform secret storage, fail startup when required server configuration is missing, and rotate exposed credentials.
+- Minimize personal data. Structured logs use event names, stable codes, request IDs, and non-sensitive identifiers; redact credentials, tokens, cookies, reset links, and PII.
+- File uploads require size limits, verified content type, generated storage names, isolated storage, and malware/content processing appropriate to risk.
+
+## Authentication and Authorization
+
+Use a maintained framework or identity provider; do not invent password hashing, sessions, JWT issuance, token rotation, or cryptographic protocols. The selected stack/capability playbook owns session storage, refresh, CSRF/CORS, callback allowlists, expiry, logout, and revocation behavior.
+
+For every protected operation, test anonymous access, authenticated-but-unauthorized access, allowed access, another user’s resource, invalid input, and expired/revoked identity where applicable.
+
+## Failure Safety
+
+- User-facing errors are stable, safe, and actionable. Never return stack traces, SQL details, credentials, or internal exception messages.
+- Apply least privilege to databases, cloud identities, CI tokens, and system operations.
+- Rate-limit abuse-sensitive operations and make retries idempotent where duplicate execution can cause harm.
+- Review dependency and secret scanning results; automated updates are proposals until the generated compatibility matrix passes.

package/playbooks/universal/typescript.manifest.json

@@ -0,0 +1,11 @@
+{
+  "id": "typescript",
+  "kind": "universal",
+  "label": "TypeScript",
+  "required": true,
+  "folders": [],
+  "concerns": [
+    { "id": "typescript-strict", "required": true, "sections": ["Strict Mode — Always On", "No any", "Type vs Interface"] },
+    { "id": "validation", "required": false, "when": "Project validates external/runtime input", "sections": ["Zod for Runtime Validation"] }
+  ]
+}