Skip to content

Commit efa1064

Browse files
iamzifeiiamzifei
authored
🔄 synced file(s) with OrrisTech/.github (#1)
* 🔄 created local '.claude/org-rules.md' from remote 'sync/.claude/org-rules.md' * 🔄 created local '.github/pull_request_template.md' from remote 'sync/.github/pull_request_template.md' * 🔄 created local '.github/workflows/ci.yml' from remote 'sync/.github/workflows/ci.yml' * 🔄 created local 'lefthook.yml' from remote 'sync/lefthook.yml' * 🔄 created local '.vscode/settings.json' from remote 'sync/.vscode/settings.json' --------- Co-authored-by: iamzifei <null>
1 parent 2c80096 commit efa1064

5 files changed

Lines changed: 459 additions & 0 deletions

File tree

‎.claude/org-rules.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# OrrisTech Organization Rules
2+
3+
These rules apply to ALL repositories in the OrrisTech GitHub organization.
4+
Claude Code automatically loads this file from `.claude/org-rules.md`.
5+
6+
---
7+
8+
## Pre-Change Verification
9+
10+
Before ANY commit, the following checks MUST pass. Do not commit code that breaks
11+
existing functionality.
12+
13+
1. **Lint** -- Run lint and fix all errors. Warnings are acceptable only if pre-existing.
14+
2. **Type check** -- Run `tsc --noEmit` (or the repo's `typecheck` script). Zero errors.
15+
3. **Tests** -- Run the full test suite. All tests must pass.
16+
4. **Build** -- Run a production build. It must complete without errors.
17+
18+
If any of these steps fail, fix the issue before committing. Never use `--no-verify`
19+
to skip pre-commit hooks.
20+
21+
---
22+
23+
## Testing Requirements
24+
25+
- All new features MUST have unit tests (prefer Vitest; Jest is acceptable).
26+
- All user-facing features MUST have BDD-style tests that describe behavior from the
27+
user's perspective (Given/When/Then or describe/it patterns).
28+
- All existing tests MUST continue to pass after your changes.
29+
- Coverage: maintain or improve the current coverage percentage. Never merge a PR that
30+
reduces coverage without explicit approval.
31+
- Place all test files in a `__tests__/` directory co-located with the source, or in a
32+
top-level `tests/` directory -- follow the convention already established in the repo.
33+
34+
---
35+
36+
## React Best Practices
37+
38+
### Server Components (RSC) -- Next.js App Router
39+
- Default to Server Components. Only add `"use client"` when the component genuinely
40+
needs interactivity, React hooks, or browser-only APIs.
41+
- Data fetching belongs in Server Components or Server Actions -- not in client-side
42+
`useEffect`.
43+
44+
### React 19 Patterns
45+
- Use `useActionState` for form state management (replaces `useFormState`).
46+
- Use `useOptimistic` for optimistic UI updates.
47+
- Use Server Actions for mutations (`"use server"` functions).
48+
- Use the `use()` hook for reading promises and context in render.
49+
50+
### Performance
51+
- No premature optimization. Profile first with React DevTools or Lighthouse, then
52+
optimize the identified bottleneck.
53+
- Use `React.memo`, `useMemo`, and `useCallback` only when profiling shows a real
54+
performance problem -- not preemptively.
55+
- Use `<Suspense>` boundaries around async data to show meaningful loading states.
56+
- Prefer streaming and partial rendering over blocking the entire page.
57+
58+
---
59+
60+
## Documentation Requirements
61+
62+
- Update `/docs` when changing architecture, adding features, or modifying APIs.
63+
- Keep `README.md` current with accurate setup instructions and prerequisites.
64+
- Delete stale documentation when removing features -- do not leave orphan docs.
65+
- PRD (Product Requirements Document) must be updated for feature changes.
66+
- Inline comments: add them only where the logic is non-obvious. Do not add comments
67+
that merely restate the code.
68+
69+
---
70+
71+
## UI / Design Standards
72+
73+
### Component Library & Styling
74+
- Use **shadcn/ui** components as the base component library.
75+
- Use **Tailwind CSS v4** for all styling. No inline styles, no CSS modules, no
76+
styled-components unless the repo already uses them.
77+
- SVG icons only. No icon fonts (Font Awesome, Material Icons CDN), no PNG/JPG icons.
78+
79+
### Design Principles
80+
- Clarity over cleverness. Every UI element should have an obvious purpose.
81+
- Consistent spacing using Tailwind's spacing scale.
82+
- Strong visual hierarchy: size, weight, and color should guide the user's eye.
83+
84+
### Animations
85+
Follow Emil Kowalski's animation principles:
86+
- Every animation must have a **purpose** (feedback, orientation, delight).
87+
- Duration: **< 300ms** for UI transitions. Longer only for page-level choreography.
88+
- Easing: **ease-out** for elements entering, **ease-in** for elements exiting.
89+
- Prefer CSS transitions over JS animation libraries when possible.
90+
- No animation is better than bad animation.
91+
92+
### Responsive & Accessibility
93+
- Mobile-first responsive design. Start with the smallest breakpoint and scale up.
94+
- Dark mode support where applicable (use Tailwind's `dark:` variant).
95+
- Keyboard navigable: all interactive elements must be reachable via Tab.
96+
- Screen reader friendly: use semantic HTML, ARIA labels where needed, alt text on
97+
images.
98+
99+
---
100+
101+
## SEO Requirements
102+
103+
- Every page MUST have unique metadata: `title`, `description`, and `og:image`.
104+
- Use structured data (JSON-LD) where applicable (articles, products, FAQ, breadcrumbs).
105+
- Proper heading hierarchy: one `<h1>` per page, logical `<h2>` through `<h6>` nesting.
106+
- Internal linking: related pages should link to each other.
107+
- Alt text on ALL images. Decorative images use `alt=""`.
108+
- No orphan pages -- every page must be reachable from at least one other page.
109+
- Use `<link rel="canonical">` to prevent duplicate content issues.
110+
111+
---
112+
113+
## Blog Content Standards
114+
115+
Follow Google's helpful content guidelines:
116+
117+
- **Length**: 1000-2500+ words for substantive posts. Short posts are acceptable for
118+
changelogs or announcements.
119+
- **Structure**: Include categories, tags, author, publication date, and a table of
120+
contents for posts over 1500 words.
121+
- **CTA**: Every post needs a clear call-to-action or takeaway for the reader.
122+
- **Quality**: Write for humans first. Provide unique insight, real examples, or
123+
original research.
124+
125+
### Banned AI Writing Patterns
126+
Never use these words/phrases that signal low-quality AI-generated content:
127+
- "delve", "landscape", "tapestry", "in conclusion", "it's worth noting"
128+
- "navigate the complexities", "in today's fast-paced", "game-changer"
129+
- "dive deep", "unlock the power", "revolutionary"
130+
- Excessive hedging ("it's important to note that...")
131+
- Lists of generic advice with no specific examples
132+
133+
---
134+
135+
## Terminology & Style
136+
137+
- Maintain a `STYLE_GUIDE.md` in each repo for project-specific terminology.
138+
- Use **American English** spelling (color, not colour; optimize, not optimise).
139+
- Technical terms must be consistent across all content within a repo. Pick one term
140+
and stick with it (e.g., "sign in" vs "log in" -- choose one).
141+
- Brand names: use the official casing (GitHub, TypeScript, Next.js, Tailwind CSS).
142+
143+
---
144+
145+
## Package Manager
146+
147+
- **New projects**: Use **Bun** as the default package manager. Initialize with `bun init` and
148+
commit a `bun.lock` file.
149+
- **Existing repos**: Respect the package manager already in use. CI auto-detects based on lock
150+
files:
151+
- `pnpm-lock.yaml` → **pnpm**
152+
- `package-lock.json` → **npm**
153+
- No recognized lock file → **Bun** (default)
154+
- Do NOT mix package managers within a single repo. If migrating, remove the old lock file and
155+
regenerate with the new package manager in a dedicated PR.
156+
- Use `--frozen-lockfile` (pnpm/bun) or `npm ci` (npm) in CI to ensure reproducible installs.
157+
158+
---
159+
160+
## Environment Variables
161+
162+
- Every repo MUST have a `.env.example` at the root listing ALL required environment
163+
variables with placeholder values. This file is used by CI to provide dummy env vars
164+
during builds.
165+
- If a `.env.sample` file exists, **rename it to `.env.example`** and use that instead.
166+
Do not keep both files.
167+
- When adding, removing, or renaming an env var in code, **update `.env.example`** in
168+
the same commit. Do not leave `.env.example` out of sync with the actual code.
169+
- Format: one `KEY=placeholder_value` per line. Use comments to group related vars:
170+
```
171+
# Supabase
172+
SUPABASE_URL=https://your-project.supabase.co
173+
SUPABASE_ANON_KEY=your-anon-key
174+
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
175+
176+
# Stripe
177+
STRIPE_SECRET_KEY=sk_test_xxx
178+
```
179+
- Never put real secret values in `.env.example` — only descriptive placeholders.
180+
- `.env.example` MUST be committed to git. `.env`, `.env.local`, and `.env.production`
181+
MUST be in `.gitignore` and never committed.
182+
183+
---
184+
185+
## Security Requirements
186+
187+
- **No new vulnerabilities**: `npm audit` / `pnpm audit` must not introduce new
188+
high or critical severity vulnerabilities.
189+
- **No committed secrets**: Never commit API keys, tokens, passwords, or credentials.
190+
Use environment variables and `.env.local` (which must be in `.gitignore`).
191+
- **Input validation**: All user-facing forms must validate input on both client and
192+
server side. Use Zod schemas for type-safe validation.
193+
- **XSS prevention**: Sanitize all user-generated content before rendering. Never
194+
render unsanitized HTML from user input. Use a sanitizer library like DOMPurify
195+
when rendering dynamic HTML is unavoidable.
196+
- **CSRF protection**: All mutations (POST, PUT, DELETE) must use CSRF tokens or
197+
Server Actions (which handle CSRF automatically).
198+
- **Dependencies**: Keep dependencies up to date. Review changelogs before major
199+
version bumps.
200+
201+
---
202+
203+
## Dead Link Prevention
204+
205+
- Check all internal links before merging PRs that add or modify content.
206+
- When deleting a page, update or remove all links that pointed to it.
207+
- Use relative links for internal navigation (e.g., `/blog/my-post` not
208+
`https://example.com/blog/my-post`).
209+
- Redirects: when moving a page to a new URL, add a redirect from the old URL.

‎.github/pull_request_template.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
## Description
2+
<!-- Brief description of changes -->
3+
4+
## Type of Change
5+
- [ ] Bug fix
6+
- [ ] New feature
7+
- [ ] Breaking change
8+
- [ ] Documentation update
9+
- [ ] Performance improvement
10+
- [ ] Refactoring
11+
12+
## Checklist
13+
14+
### Code Quality
15+
- [ ] Lint passes (`pnpm lint` / `npm run lint`)
16+
- [ ] TypeScript compiles (`pnpm typecheck` / `npm run typecheck`)
17+
- [ ] Build succeeds (`pnpm build` / `npm run build`)
18+
- [ ] No debug code (`console.log`, `debugger`, leftover `TODO`)
19+
- [ ] No AI slop (unnecessary abstractions, over-engineering)
20+
21+
### Testing
22+
- [ ] Unit tests added for new functionality
23+
- [ ] BDD tests added for user-facing features
24+
- [ ] All existing tests pass
25+
- [ ] Edge cases covered
26+
27+
### Security
28+
- [ ] No new npm audit vulnerabilities (high/critical)
29+
- [ ] No committed secrets or API keys
30+
- [ ] Input validation on user-facing forms
31+
- [ ] XSS prevention (sanitized user content)
32+
33+
### Documentation
34+
- [ ] `/docs` updated (if architecture changed)
35+
- [ ] README updated (if setup changed)
36+
- [ ] No stale documentation left behind
37+
- [ ] Inline comments for complex logic only
38+
39+
### UI / Design (if applicable)
40+
- [ ] Follows design system (shadcn/ui + Tailwind CSS v4)
41+
- [ ] SVG icons only (no icon fonts, no PNGs)
42+
- [ ] Animations < 300ms, purposeful
43+
- [ ] Mobile responsive
44+
- [ ] Accessible (keyboard nav, screen reader, alt text)
45+
46+
### SEO (if applicable)
47+
- [ ] Metadata set (title, description, og:image)
48+
- [ ] Structured data (JSON-LD) where applicable
49+
- [ ] Heading hierarchy correct (single h1)
50+
- [ ] Alt text on all images
51+
- [ ] No broken internal links
52+
53+
### Blog Content (if applicable)
54+
- [ ] 1000+ words for substantive posts
55+
- [ ] Categories, tags, and author set
56+
- [ ] Table of contents included
57+
- [ ] No banned AI writing patterns
58+
- [ ] Clear takeaway / CTA for the reader

‎.github/workflows/ci.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# CI Pipeline -- Thin caller workflow
2+
# Calls reusable workflows from the OrrisTech/.github org repo.
3+
# Synced to all repos via files-to-sync.yml.
4+
name: CI
5+
6+
on:
7+
pull_request:
8+
push:
9+
branches: [main, master]
10+
11+
# Permissions needed by reusable workflows:
12+
# - contents:read — checkout code
13+
# - pull-requests:write — react-doctor posts PR comments
14+
permissions:
15+
contents: read
16+
pull-requests: write
17+
18+
# Cancel in-progress runs for the same branch/PR to save runner minutes
19+
concurrency:
20+
group: ci-${{ github.ref }}
21+
cancel-in-progress: true
22+
23+
jobs:
24+
lint-typecheck:
25+
name: Lint & Type Check
26+
uses: OrrisTech/.github/.github/workflows/ci-lint-typecheck.yml@main
27+
secrets: inherit
28+
29+
test:
30+
name: Test
31+
uses: OrrisTech/.github/.github/workflows/ci-test.yml@main
32+
secrets: inherit
33+
34+
build:
35+
name: Build
36+
needs: [lint-typecheck]
37+
uses: OrrisTech/.github/.github/workflows/ci-build.yml@main
38+
secrets: inherit
39+
40+
security:
41+
name: Security Audit
42+
uses: OrrisTech/.github/.github/workflows/ci-security.yml@main
43+
secrets: inherit
44+
45+
react-doctor:
46+
name: React Doctor
47+
if: github.event_name == 'pull_request'
48+
uses: OrrisTech/.github/.github/workflows/ci-react-doctor.yml@main
49+
secrets: inherit

0 commit comments

Comments
 (0)