Project Context

Load this skill when you need to know the project's technology decisions, safety rules, or verification process. This is the single source of truth for "what tools do we use and what rules must we follow."

Locked Decisions (Do Not Override)

These are researched, deliberate technology choices. Do not substitute alternatives. If an agent introduces an unauthorized library, catch it during verification and revert.

Decision	Choice	NOT This	Why
Date/time	Luxon	date-fns, moment, dayjs, native Date	Timezone-first API, immutable
Validation	Zod	yup, joi, io-ts	TypeScript-first, runtime + static
State (client)	Zustand	Redux, MobX, Jotai	Minimal boilerplate, no providers
State (server)	TanStack Query	SWR, manual fetch	Cache invalidation, devtools
CSS	Tailwind CSS 4	CSS modules, styled-components	Utility-first, framework standard
Components	shadcn/ui + Radix UI	Material UI, Chakra, Ant Design	Composable, unstyled primitives
Forms	React Hook Form	Formik	Performance, uncontrolled components
Package manager	pnpm	npm, yarn	Strict, fast, workspace-native
Logging	Axiom	console.log, winston, pino	Structured cloud logging
Errors	Sentry	manual error tracking	Source maps, session replay
Analytics	PostHog	Mixpanel, Amplitude	Self-hostable, feature flags

When drift is detected, fix it immediately and save a memory noting the incident (what drifted, where, when). Recurring drift patterns should trigger ESLint no-restricted-imports rules.

For detailed rationale per layer, see standards/reference/tech-stack.md.

Critical Rules

These rules exist because they were violated and caused real problems.

1. No any types -- Use proper TypeScript typing
2. No console.log -- Use Axiom/Sentry logging
3. No TODO without issue reference -- Every TODO must reference a Linear issue
4. No native Date -- Always use Luxon (see Locked Decisions)
5. Validate at edge -- Zod schemas for all external inputs
6. Verify before claiming done -- Run the full verification command and confirm output
7. Sequential git writes -- Never have two branches writing code simultaneously. One at a time: branch, implement, verify, push, merge, next.
8. Check Locked Decisions -- Before introducing any library, check the Locked Decisions table. If there is a locked choice for that domain, use it.
9. Confirmation scoping -- Execute when the path is clear; ask only when genuinely ambiguous. Unambiguous cases (docs change, bug fix with stack trace, single-line chore) proceed without confirmation. Ask when two or more legitimate approaches exist and the choice has meaningful consequences.

Quality Gates

Verification (before pushing PR):

pnpm type-check && pnpm lint && pnpm test:run && pnpm build

Never claim work is "done" without running verification and confirming output. Evidence before assertions.

Code Review (automated): Every PR is reviewed by the Claude Code GitHub Action (.github/workflows/claude-review.yml). It posts a formal GitHub review (approve/request_changes) with a self-fix loop (max 3 rounds). All findings must be addressed before merging -- fix the issue and push, or reply to the comment with rationale.

Pre-PR Review (high-stakes work): For security-sensitive or architecturally significant changes, run a synchronous review team BEFORE pushing the PR:

• Security Engineer -- auth, injection, OWASP
• Backend Architect or relevant domain specialist

Testing requirements:

• Bug fixes: Regression test required (proves the bug is fixed and stays fixed)
• New features: TDD for core business logic, API routes, and data transformations
• UI features: E2E tests for critical user flows (login, checkout, data entry)
• Always: Type-check + lint + build must pass before pushing

See standards/core/testing.md for full testing standards.

Verify-Fix-Retry Loop: When verification fails, the engineer fixes and re-runs. Max 3 attempts. After 3 failures:

1. Add awaiting-input label
2. Post @Ameet comment with: what failed, what was tried, and recommended next step:
   • Reassign -- different agent type for better domain expertise
   • Decompose -- break into smaller, independently verifiable pieces
   • Revise approach -- current approach is fundamentally wrong
   • Accept with limitations -- document known issues, ship anyway
   • Defer -- move to Backlog for later

Prototype Scaffold

tools/prototype-scaffold/ is a full Next.js 16 app with 43 color themes, 32 pre-installed shadcn/ui components (see standards/reference/component-maintenance.md for full inventory), and a pre-built admin dashboard (sidebar, breadcrumbs, search command palette, stat cards, charts, data tables). Key routes: /dashboard, /settings/*, /login, /signup. Data lives in lib/data/ (Zod schemas + static seed data via @faker-js/faker). Uses unified radix-ui package (not scoped @radix-ui/react-*) -- imports look like import { Slot } from "radix-ui".

MCP Configuration

File-based (.mcp.json, gitignored, copy from .mcp.json.example):

• Playwright MCP (@playwright/mcp) -- Browser automation and testing

CLI-based (added via claude mcp add):

• Linear MCP (linear-server) -- Issue tracking via https://mcp.linear.app/sse. Add with: claude mcp add --transport sse linear-server https://mcp.linear.app/sse, then authenticate with /mcp.

See Also

• standards/reference/tech-stack.md -- Detailed tech decisions per layer
• standards/core/testing.md -- Full testing standards
• standards/core/security.md -- Security checklist