@seanyao/roll 0.5.0

package/conventions/config.yaml

@@ -0,0 +1,15 @@
+# Roll Configuration
+# Edit this file, then run `roll sync` to apply.
+
+# Sync targets: where global conventions are distributed to.
+# These are the default paths for each AI tool's global config.
+# Override if your tool uses a non-standard location.
+sync_claude: ~/.claude/CLAUDE.md
+sync_kimi: ~/.kimi/AGENTS.md
+sync_codex: ~/.codex/AGENTS.md
+sync_gemini: ~/.gemini/GEMINI.md
+
+# User preferences
+default_language: zh
+default_project_type: fullstack
+editor: ${EDITOR:-vim}

package/conventions/global/.cursor-rules

@@ -0,0 +1,31 @@
+# Global Rules — Cursor
+
+# Extends AGENTS.md in ~/.roll/conventions/global/ — read that first.
+# This file adds Cursor-specific rules only.
+
+## Identity
+
+- Git: Sean Yao <sean.dlut@gmail.com>
+- Default branch: main
+
+## Commit Message Format
+
+- Format: [sean's claw] <type>: <description>
+- TCR micro-commits: tcr: <description> (no prefix)
+- Types: Story N, Fix, Refactor, Docs, Chore
+
+## Cursor-Specific
+
+- When using Composer, break large changes into reviewable chunks.
+- Prefer inline edits over full file rewrites.
+- Use @-references to relevant files when context is needed.
+- Tab completion suggestions should follow the code style in AGENTS.md.
+- When a project has Roll workflow, follow the AGENTS.md conventions.
+
+## Frontend Default Stack
+
+- React + shadcn/ui + Tailwind CSS is the default.
+- Use shadcn/ui components first. Custom only when shadcn doesn't cover it.
+- Tailwind utility classes only. No inline styles, no CSS modules.
+
+## All shared conventions are defined in AGENTS.md.

package/conventions/global/AGENTS.md

@@ -0,0 +1,100 @@
+# Global Agent Conventions — Sean Yao
+
+> Master conventions file. All AI coding agents follow these principles.
+> Tool-specific files (CLAUDE.md, GEMINI.md, .cursor-rules) extend this document.
+
+## Communication
+
+- Respond in the language I write in. Chinese message → Chinese response. English → English.
+- Code, commit messages, variable names, comments: always English.
+- Error messages in API responses: English.
+- UI-facing text: Chinese (internal tool for Chinese-speaking team).
+- Be concise. Don't summarize what you just did — I can read the diff.
+- Don't ask for confirmation on routine actions. Just do it and show the result.
+- If something is ambiguous, make a reasonable judgment call. Only ask when the choice has real consequences.
+- Use plain language. No academic jargon or pretentious framing.
+- **Roll workflow milestones may be narrated.** It's fine to report high-level progress such as running baseline, sketching a design, completing an Action, passing a Verification Gate, or finishing TCR (Green/Commit or Red/Revert).
+- **Implementation details are invisible.** Do not include code diffs, file paths, line numbers, function names, variable names, test scripts, model parameters, or raw git output in conversational responses.
+- **Strategic reasoning is okay; tactical code-walking is not.** You may explain *why* a design choice was made at the product/business level. Do not narrate step-by-step code modifications or internal debugging monologues.
+- **Report in user-centric outcomes.** After making changes, summarize what improved for the user or product in 1–2 sentences.
+- **No code dumps unless explicitly asked.** Never paste code snippets, stack traces, or technical speculations into the chat.
+- **Business context over technical mechanics.** When explaining a bug or fix, lead with the user-visible effect. Root causes, if mentioned at all, belong in a single trailing sentence.
+
+## Code Style
+
+- TypeScript strict mode. No `any` unless absolutely unavoidable.
+- Functional components with hooks. No class components.
+- Prefer `const` over `let`. Never `var`.
+- Early returns over nested conditionals.
+- Name things clearly — no abbreviations except well-known ones (e.g., `id`, `url`, `api`).
+- Keep functions short and single-purpose. If it needs a comment to explain, it's too complex.
+- Don't add comments unless the logic is genuinely non-obvious.
+- Don't add docstrings, JSDoc, or type annotations to code you didn't change.
+
+## Git
+
+- Conventional commit format: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`
+- Write in English, concise, imperative mood.
+- Never force push to main.
+- Never skip hooks (`--no-verify`).
+- Never commit `.env`, credentials, or secrets.
+
+## Behavior
+
+- Do not refactor files unrelated to the current task.
+- Do not add features, refactoring, or "improvements" not requested.
+- Always ask before making structural changes (directory reorganization, architecture changes).
+- Don't wrap simple things in abstractions. Three similar lines > a premature helper.
+- Don't add error handling for impossible scenarios. Trust the framework.
+- Delete unused things completely — no `// removed` comments, no backward-compat shims.
+- Don't create README.md or documentation files unless asked.
+
+## Testing
+
+- All business logic must have unit tests (coverage >80%).
+- All API endpoints must have integration tests — no DB mocks.
+- Critical user flows must have E2E tests (Playwright).
+- New architecture introductions (State/Cache/EventBus) must have data flow integration tests.
+- Run existing tests before pushing to verify no regressions.
+
+## Engineering Common Sense
+
+Non-negotiable requirements for all code changes. Violating these is a bug:
+
+- **Idempotency**: Same operation N times = same result. Test by running 3 times.
+- **Cross-module contract**: Shared IDs, formats, algorithms must be identical across modules.
+- **Data flow integrity**: Producer → Storage → Consumer chain must be complete and tested.
+- **Atomicity**: Operations complete fully or not at all. Partial failure → rollback.
+- **Input validation**: All external input (API, user, file) must be validated.
+- **Graceful degradation**: Dependency fails → limited functionality, not crash.
+- **Observability**: User must see progress, state, and errors.
+- **Concurrency safety**: Shared resources under multi-thread/multi-process access must be safe.
+
+## Roll Workflow (When Project Has It)
+
+When a project has Roll workflow configured:
+
+### Workspace Structure
+
+- `BACKLOG.md` = index table, one-line summary per story only.
+- `docs/features/<feature>.md` = US details (AC, Files, Dependencies).
+- `docs/features/<feature>-plan.md` = architecture design doc (optional).
+- Never write project docs to `~/.kimi/` or any global config directory.
+
+### Development Discipline
+
+- **TCR mandatory**: All code changes follow Test → Green = Commit / Red = Revert. No WIP commits.
+- **Action granularity**: Each Action independently deployable, completable in 2–5 min. No placeholders (no TBD/TODO/pending).
+- **Verification Gate**: Before marking done, provide fresh evidence (test output, screenshot, curl). "I confirmed it works" is not evidence.
+- **Complete delivery**: push to GitHub + CI passes + deployed online. Local-only done is not done.
+
+### Skill Selection
+
+```
+Uncertain approach?        → $roll-design
+Want to ship something?    → $roll-build  (handles US-XXX, FIX-XXX, or vague ideas)
+Single bug fix?            → $roll-fix
+High-risk logic?           → $roll-spar
+Page/production issue?     → $roll-debug
+Initialize new project?    → roll init  (CLI command, not a skill)
+```

package/conventions/global/CLAUDE.md

@@ -0,0 +1,32 @@
+# Global Preferences — Claude Code
+
+> Extends [AGENTS.md](./AGENTS.md) — read that first for shared conventions.
+> This file adds Claude Code-specific configuration only.
+
+## Identity
+
+- Git: `Sean Yao <sean.dlut@gmail.com>`
+- Default branch: `main`
+
+## Commit Message Format
+
+- Format: `<type>: <description>` (遵循 Git Hook 自动生成的前缀)
+- TCR micro-commits: `tcr: <description>` (No prefix)
+- Types: Story N, Fix, Refactor, Docs, Chore
+- Example: `Story 7: Review assignment by org structure`
+
+## Claude Code-Specific
+
+- When a project has Roll skills, use them (`$roll-design`, `$roll-story`, etc.).
+- Use plan mode for complex multi-step tasks before executing.
+- Prefer Edit tool over Bash for file modifications.
+- Use Agent tool with worktree isolation for parallel independent subtasks.
+- When I say "帮我看下" or "处理下", go ahead and do it, not just analyze it.
+
+## Frontend Default Stack
+
+- React + shadcn/ui + Tailwind CSS is the default.
+- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
+- `components/ui/` is shadcn-generated — never edit manually.
+- Tailwind utility classes only. No inline styles, no CSS modules.
+- Icons: Lucide React.

package/conventions/global/GEMINI.md

@@ -0,0 +1,28 @@
+# Global Preferences — Gemini CLI
+
+> Extends AGENTS.md in this directory — read that first for shared conventions.
+> This file adds Gemini CLI-specific configuration only.
+
+## Identity
+
+- Git: `Sean Yao <sean.dlut@gmail.com>`
+- Default branch: `main`
+
+## Commit Message Format
+
+- Format: `<type>: <description>` (遵循 Git Hook 自动生成的前缀)
+- TCR micro-commits: `tcr: <description>` (No prefix)
+- Types: Story N, Fix, Refactor, Docs, Chore
+
+## Gemini-Specific
+
+- When running shell commands, prefer the most specific tool available.
+- For file operations, verify the file exists before modifying.
+- When a project has Roll workflow, follow the AGENTS.md conventions and use Roll skills.
+- Prefer targeted edits over full file rewrites.
+
+## Frontend Default Stack
+
+- React + shadcn/ui + Tailwind CSS is the default.
+- Use shadcn/ui components first. Custom only when shadcn doesn't cover it.
+- Tailwind utility classes only. No inline styles, no CSS modules.

package/conventions/templates/backend-service/.cursor-rules

@@ -0,0 +1,17 @@
+# Project Rules — Backend Service (Cursor)
+
+# Extends global .cursor-rules + project AGENTS.md.
+
+## Stack
+
+- Node.js / TypeScript
+- Database: Prisma or Drizzle ORM
+- Testing: Vitest + Supertest
+
+## Rules
+
+- No frontend code in this project. API-only service.
+- Routes are thin — delegate to services for business logic.
+- Validate all inputs at route level (zod/joi).
+- Environment config via .env. Never hardcode secrets.
+- Follow AGENTS.md for architecture constraints and Roll workflow.

package/conventions/templates/backend-service/AGENTS.md

@@ -0,0 +1,88 @@
+# Project Conventions — Backend Service
+
+> Project-type-specific conventions — reference material for skills.
+> **Note: Reference Template** — used by skills to infer project conventions. Not selected by users.
+
+## API Design
+
+- RESTful API with consistent URL structure: `/api/{resource}/{id}`.
+- For internal microservices, gRPC is acceptable.
+- Structured error responses: `{ error: string, code: string, details?: object }`.
+- Health check endpoint: `GET /api/health` returning `{ status: "ok", version: string }`.
+- API versioning via URL prefix (`/api/v1/`) when breaking changes are needed.
+
+## Configuration
+
+- Environment config via `.env`. Never hardcode secrets.
+- Use `.env.example` as the template with all required variables documented.
+- Validate all env vars at startup — fail fast if missing.
+- Separate configs for development, staging, production.
+
+## Logging
+
+- Structured JSON logging (e.g., pino, winston with JSON transport).
+- Log levels: `error`, `warn`, `info`, `debug`. Default to `info` in production.
+- Include correlation IDs for request tracing.
+- Never log secrets, tokens, or PII.
+
+## Error Handling
+
+- Domain errors: typed error classes with error codes.
+- HTTP errors: map domain errors to appropriate status codes.
+- Unhandled errors: catch-all middleware, log full stack, return 500 with safe message.
+- Validation errors: 400 with detailed field-level error messages.
+
+## Project Structure
+
+```
+src/
+├── routes/               # HTTP route handlers (thin — delegate to services)
+├── services/             # business logic (pure functions where possible)
+├── models/               # data models, ORM entities, schemas
+├── middleware/            # auth, logging, error handling, validation
+├── utils/                # shared utilities
+├── types/                # TypeScript type definitions
+├── config/               # environment config, constants
+└── index.ts              # entry point, server bootstrap
+
+tests/
+├── unit/                 # service/model unit tests
+├── integration/          # API endpoint tests (supertest)
+└── regression/           # Sentinel regression
+```
+
+## Database
+
+- Migrations managed via a migration tool (Prisma, Drizzle, Knex).
+- Never modify production data manually — always through migrations.
+- Index frequently queried columns. Monitor slow queries.
+- Use transactions for multi-table operations.
+
+## Security
+
+- Input validation on all endpoints (zod, joi, or similar).
+- Rate limiting on public endpoints.
+- CORS configured explicitly — no wildcard in production.
+- Authentication middleware applied at route level, not globally.
+- Secrets rotated periodically. Never in git history.
+
+## Architecture Constraints
+
+- **Domain Driven**: organize code by business domain, not technical layer. `src/services/` contains domain logic, not generic utilities.
+- **Clean Architecture**: routes (thin) → services (business logic) → models (data) ← infrastructure (DB/external APIs). Routes delegate; they don't contain business logic.
+- **Data Schema First**: define types/schemas before writing business logic.
+- **API Contract**: typed request/response schemas. API changes must bump version or be backward-compatible.
+
+## Development Discipline
+
+- **TCR mandatory**: All code changes follow Test → Green = Commit / Red = Revert. No WIP commits.
+- **Action granularity**: Each Action independently deployable, completable in 2–5 min. No placeholders (no TBD/TODO/pending).
+- **Verification Gate**: Before marking done, provide fresh evidence (test output, curl response). "I confirmed it works" is not evidence.
+- **Complete delivery**: push to GitHub + CI passes + deployed online. Local-only done is not done.
+
+## Workspace Structure
+
+- `BACKLOG.md` = index table, one-line summary per story only.
+- `docs/features/<feature>.md` = US details (AC, Files, Dependencies).
+- `docs/features/<feature>-plan.md` = architecture design doc (optional).
+- Never write project docs to `~/.kimi/` or any global config directory.

package/conventions/templates/backend-service/CLAUDE.md

@@ -0,0 +1,18 @@
+# Project Preferences — Backend Service (Claude Code)
+
+> Extends global CLAUDE.md + project AGENTS.md.
+
+## Stack
+
+- Node.js / TypeScript / Express or Hono or Fastify
+- Database: Prisma or Drizzle ORM
+- Testing: Vitest (unit) + Supertest (integration)
+- Deploy: Railway / Fly.io / Docker
+
+## Claude Code Notes
+
+- No frontend in this project. API-only service.
+- Use `$roll-design` to plan API contracts and data models before implementation.
+- Write integration tests that hit real endpoints (supertest), not mocked handlers.
+- Verify health check endpoint responds before reporting deploy as done.
+- Run `npm run build && npm run test` before pushing.

package/conventions/templates/backend-service/GEMINI.md

@@ -0,0 +1,16 @@
+# Project Preferences — Backend Service (Gemini CLI)
+
+> Extends global GEMINI.md + project AGENTS.md.
+
+## Stack
+
+- Node.js / TypeScript / Express or Hono or Fastify
+- Database: Prisma or Drizzle ORM
+- Testing: Vitest + Supertest
+
+## Gemini Notes
+
+- No frontend in this project. API-only service.
+- Write integration tests that hit real endpoints, not mocked handlers.
+- Run `npm run build && npm run test` before pushing.
+- Follow the project AGENTS.md for architecture constraints and Roll workflow.

package/conventions/templates/cli/.cursor-rules

@@ -0,0 +1,17 @@
+# Project Rules — CLI Tool (Cursor)
+
+# Extends global .cursor-rules + project AGENTS.md.
+
+## Stack
+
+- Node.js / TypeScript
+- CLI framework: commander or citty
+
+## Rules
+
+- No server, no frontend. CLI tool only.
+- One file per command in src/commands/.
+- Exit codes: 0 = success, 1 = user error, 2 = system error.
+- Errors to stderr, results to stdout.
+- Support --help and --version on every command.
+- Follow AGENTS.md for architecture constraints and Roll workflow.

package/conventions/templates/cli/AGENTS.md

@@ -0,0 +1,66 @@
+# Project Conventions — CLI Tool
+
+> Project-type-specific conventions — reference material for skills.
+> **Note: Reference Template** — used by skills to infer project conventions. Not selected by users.
+
+## Design Principles
+
+- Lightweight. No server, no frontend, no heavy frameworks.
+- Clear command structure: `tool <command> [options] [args]`.
+- Helpful error messages with actionable suggestions.
+- Consistent exit codes: 0 = success, 1 = user error, 2 = system error.
+- Support `--help` and `--version` on every command.
+- Respect `NO_COLOR` env var for output formatting.
+
+## Architecture
+
+- Single entry point dispatching to command handlers.
+- Each command in its own file — easy to find, easy to test.
+- Config loading: CLI flags > environment variables > config file > defaults.
+- Use a CLI framework (commander, yargs, or citty) for argument parsing.
+
+## Output
+
+- Default to human-readable output. Support `--json` for machine-readable.
+- Progress indicators for long operations (ora, cli-progress).
+- Errors to stderr, results to stdout.
+- Quiet mode (`--quiet` or `-q`) suppresses non-essential output.
+
+## Project Structure
+
+```
+src/
+├── index.ts              # entry point, CLI bootstrap
+├── commands/             # one file per command
+│   ├── init.ts
+│   ├── build.ts
+│   └── ...
+├── utils/                # shared utilities
+├── types/                # type definitions
+└── config.ts             # config loading logic
+
+tests/
+├── unit/                 # command logic tests
+└── integration/          # full CLI invocation tests (execa)
+```
+
+## Distribution
+
+- Compile to single executable or publish to npm.
+- Include `bin` field in `package.json`.
+- Test installation flow: `npm install -g` should work cleanly.
+- Include a man page or `--help` output that covers all commands.
+
+## Development Discipline
+
+- **TCR mandatory**: All code changes follow Test → Green = Commit / Red = Revert. No WIP commits.
+- **Action granularity**: Each Action independently deployable, completable in 2–5 min. No placeholders (no TBD/TODO/pending).
+- **Verification Gate**: Before marking done, run the actual command and paste the output. "I confirmed it works" is not evidence.
+- **Complete delivery**: push to GitHub + CI passes + published/deployed. Local-only done is not done.
+
+## Workspace Structure
+
+- `BACKLOG.md` = index table, one-line summary per story only.
+- `docs/features/<feature>.md` = US details (AC, Files, Dependencies).
+- `docs/features/<feature>-plan.md` = architecture design doc (optional).
+- Never write project docs to `~/.kimi/` or any global config directory.

package/conventions/templates/cli/CLAUDE.md

@@ -0,0 +1,18 @@
+# Project Preferences — CLI Tool (Claude Code)
+
+> Extends global CLAUDE.md + project AGENTS.md.
+
+## Stack
+
+- Node.js / TypeScript
+- CLI framework: commander or citty
+- Testing: Vitest + execa (CLI integration tests)
+- Distribution: npm package with bin entry
+
+## Claude Code Notes
+
+- No server, no frontend. CLI tool only.
+- Test commands by running them in Bash, not just unit tests.
+- Use `$roll-design` to plan command structure and options before implementation.
+- Verify `--help` output is clear and complete for each command.
+- Run `npm run build && node dist/index.js --help` before pushing.

package/conventions/templates/cli/GEMINI.md

@@ -0,0 +1,16 @@
+# Project Preferences — CLI Tool (Gemini CLI)
+
+> Extends global GEMINI.md + project AGENTS.md.
+
+## Stack
+
+- Node.js / TypeScript
+- CLI framework: commander or citty
+- Testing: Vitest
+
+## Gemini Notes
+
+- No server, no frontend. CLI tool only.
+- Test commands by running them, not just unit tests.
+- Run `npm run build && node dist/index.js --help` before pushing.
+- Follow the project AGENTS.md for architecture constraints and Roll workflow.

package/conventions/templates/frontend-only/.cursor-rules

@@ -0,0 +1,16 @@
+# Project Rules — Frontend Only (Cursor)
+
+# Extends global .cursor-rules + project AGENTS.md.
+
+## Stack
+
+- React + shadcn/ui + Tailwind CSS + Vite
+- Testing: Vitest + Playwright
+
+## Rules
+
+- No backend code in this project. API consumption only.
+- src/components/ui/ is shadcn-generated. Never edit manually.
+- Organize code by domain: src/domains/{domain}/
+- All business logic in hooks or services, not in components.
+- Follow AGENTS.md for architecture constraints and Roll workflow.

package/conventions/templates/frontend-only/AGENTS.md

@@ -0,0 +1,71 @@
+# Project Conventions — Frontend Only
+
+> Project-type-specific conventions — reference material for skills.
+> **Note: Reference Template** — used by skills to infer project conventions. Not selected by users.
+
+## Frontend
+
+- Stack: React 18+ / TypeScript / Vite / Tailwind CSS / shadcn/ui / Lucide React
+- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
+- `src/components/ui/` is shadcn-generated — never edit manually.
+- `src/components/[feature]/` for custom feature components.
+- Tailwind utility classes only. No inline styles, no CSS modules.
+- Organize by domain: `src/domains/{domain}/components/`, `hooks/`, `services/`, `types.ts`
+- Shared utilities in `src/shared/` (api/, types/, utils/, hooks/).
+
+## Architecture
+
+- **Domain Driven Design**: organize code by business domain, not technical layer.
+- **Clean Architecture**: UI → Application (hooks) → Domain (services) → Infrastructure (API client).
+- **Decoupling**: UI renders only, logic lives in hooks. API calls wrapped in services.
+- **Data Schema First**: define types/schemas before writing business logic.
+- No backend code in this project. API consumption only.
+
+## State Management
+
+- Prefer React built-in state (useState, useReducer, useContext) for simple cases.
+- Use a state library (Zustand, Jotai) only when shared state gets complex.
+- Server state via TanStack Query (React Query) for API data fetching and caching.
+
+## Project Structure
+
+```
+src/
+├── components/ui/        # shadcn/ui (generated, don't edit)
+├── domains/              # DDD by business domain
+│   └── {domain}/
+│       ├── components/   # domain-specific UI
+│       ├── hooks/        # domain logic + state
+│       ├── services/     # API client calls
+│       └── types.ts      # domain types
+├── shared/
+│   ├── api/              # HTTP client, interceptors
+│   ├── types/            # shared type definitions
+│   └── utils/            # utility functions
+├── App.tsx
+└── main.tsx
+
+tests/
+├── unit/                 # Vitest + Testing Library
+└── e2e/                  # Playwright
+```
+
+## Development Discipline
+
+- **TCR mandatory**: All code changes follow Test → Green = Commit / Red = Revert. No WIP commits.
+- **Action granularity**: Each Action independently deployable, completable in 2–5 min. No placeholders (no TBD/TODO/pending).
+- **Verification Gate**: Before marking done, provide fresh evidence (test output, screenshot). "I confirmed it works" is not evidence.
+- **Complete delivery**: push to GitHub + CI passes + deployed online. Local-only done is not done.
+
+## Testing Requirements
+
+- All hooks and domain logic must have unit tests (Vitest + Testing Library, coverage >80%).
+- Critical user flows must have E2E tests (Playwright).
+- Run existing tests before pushing to verify no regressions.
+
+## Workspace Structure
+
+- `BACKLOG.md` = index table, one-line summary per story only.
+- `docs/features/<feature>.md` = US details (AC, Files, Dependencies).
+- `docs/features/<feature>-plan.md` = architecture design doc (optional).
+- Never write project docs to `~/.kimi/` or any global config directory.

package/conventions/templates/frontend-only/CLAUDE.md

@@ -0,0 +1,16 @@
+# Project Preferences — Frontend Only (Claude Code)
+
+> Extends global CLAUDE.md + project AGENTS.md.
+
+## Stack
+
+- React + shadcn/ui + Tailwind CSS + Vite
+- Testing: Vitest (unit) + Playwright (E2E)
+- Deploy: Vercel
+
+## Claude Code Notes
+
+- No backend in this project. All data via external API consumption.
+- Use `$roll-design` to plan component architecture and state management.
+- Start dev server and verify UI changes in browser before reporting done.
+- Run `npm run build` to verify production bundle compiles before pushing.

package/conventions/templates/frontend-only/GEMINI.md

@@ -0,0 +1,14 @@
+# Project Preferences — Frontend Only (Gemini CLI)
+
+> Extends global GEMINI.md + project AGENTS.md.
+
+## Stack
+
+- React + shadcn/ui + Tailwind CSS + Vite
+- Testing: Vitest + Playwright
+
+## Gemini Notes
+
+- No backend in this project. All data via external API consumption.
+- Run `npm run build` to verify production bundle compiles before pushing.
+- Follow the project AGENTS.md for architecture constraints and Roll workflow.

package/conventions/templates/fullstack/.cursor-rules

@@ -0,0 +1,17 @@
+# Project Rules — Fullstack Web (Cursor)
+
+# Extends global .cursor-rules + project AGENTS.md.
+
+## Stack
+
+- Frontend: React + shadcn/ui + Tailwind CSS + Vite
+- Backend: Node.js API
+- Testing: Vitest + Playwright
+
+## Rules
+
+- src/components/ui/ is shadcn-generated. Never edit manually.
+- Organize code by domain: src/domains/{domain}/
+- API contracts live in api/types.ts and src/shared/types/ — keep in sync.
+- All business logic in hooks or services, not in components.
+- Follow AGENTS.md for architecture constraints and Roll workflow.