create-rigel 0.1.0

package/templates/nextjs/.claude/skills/03-write-plan/SKILL.md

@@ -0,0 +1,91 @@
+# /write-plan — Write an Execution Plan
+
+Triggered by: `/write-plan`
+
+## Step 1 — Find Ready Spec
+```bash
+ls docs/product-specs/ready/
+```
+If none → tell human to mark a spec READY first. Stop.
+
+> A large feature area may span MULTIPLE plans — slice it into shippable milestones, each its
+> own `PLAN-XXX` that ends green (e.g. live feed; then drill-in; then filters/export). Plans are
+> numbered independently, so just create the next plan for the same spec.
+
+## Step 2 — Get Next Plan Number
+```bash
+ls docs/exec-plans/{active,completed}/ 2>/dev/null | grep "PLAN-" | sort | tail -1
+```
+
+## Step 3 — Read the Spec
+From the spec, identify:
+- API Endpoints Used → determines hooks layer files
+- Screens/Views → determines features + app layers
+- Business rules → determines store needs
+
+## Step 4 — Write the Plan
+Save to: `docs/exec-plans/active/PLAN-XXX-{slug}.md`
+
+```markdown
+# PLAN-XXX — {Feature Name}
+
+**Status:** IN_PROGRESS
+**Spec:** docs/product-specs/ready/SPEC-XXX-{slug}.md
+**Created:** YYYY-MM-DD
+**Completed:** —
+
+---
+
+## Goal
+{one sentence}
+
+---
+
+## Pre-Build Step
+Run `/api-sync` to ensure `src/types/api.generated.ts` is current.
+
+---
+
+## Layer Build Order
+
+| # | Layer | Files | Gate Focuses On |
+|---|---|---|---|
+| 1 | Types | `src/types/domain.types.ts` additions | Zero imports, no API duplication |
+| 2 | Lib | `src/lib/env.ts` update (if new vars), constants | process.env only in env.ts |
+| 3 | Hooks | `src/hooks/use-{domain}.ts` × N | openapi-fetch only, error handling, query keys |
+| 4 | Store | `src/store/{domain}-store.ts` (if client state needed) | UI state only, no server data |
+| 5 | Features | `src/features/{domain}/` — components + forms | Loading/error/empty states, a11y |
+| 6 | Components | `src/components/shared/` — new shared components | Props typed, no domain logic |
+| 7 | App | `app/(dashboard)/{route}/page.tsx` + layout changes | No business logic in pages |
+| 8 | Tests | `tests/unit/`, `tests/e2e/` | Coverage gates, E2E critical paths |
+
+*(Remove layers that don't apply to this feature)*
+
+---
+
+## Acceptance Criteria
+- [ ] {from spec}
+
+---
+
+## Progress Log
+### {date} — Plan created
+
+---
+
+## Decision Log
+*(filled during build)*
+```
+
+## Step 5 — Update Spec + Index
+APPEND `PLAN-XXX` to the spec's `**Plan:**` field (do not overwrite) — a feature split across
+several plans lists them all, e.g. `**Plan:** PLAN-003, PLAN-007`. Update index to `PLANNED`.
+
+## Step 6 — Tell Human
+```
+Plan written: docs/exec-plans/active/PLAN-XXX-{slug}.md
+
+IMPORTANT: Run /api-sync before /build-layer if openapi.json exists.
+
+{N} layers planned. Run /build-layer to start.
+```

package/templates/nextjs/.claude/skills/04-build-layer/SKILL.md

@@ -0,0 +1,141 @@
+# /build-layer — Build Next Layer from Active Plan
+
+Triggered by: `/build-layer` (no argument)
+
+---
+
+## Step 1 — Find Active Plan and Next Layer
+```bash
+PLAN=$(ls docs/exec-plans/active/*.md 2>/dev/null | head -1)
+[[ -z "$PLAN" ]] && echo "No active plan. Run /write-plan first." && exit 1
+cat "$PLAN"
+```
+Find first `[ ]` row. If all `[x]` → run `/garbage-collect`.
+
+---
+
+## Step 2 — Check API Contract
+```bash
+ls src/types/api.generated.ts 2>/dev/null || echo "WARNING: api.generated.ts missing — run /api-sync"
+```
+If missing: stop and tell human to run `/api-sync` first.
+
+---
+
+## Step 3 — Load Context
+Read: active plan, linked spec, `ARCHITECTURE.md`, path-scoped rule for this layer:
+- Types → `.claude/rules/architecture.md`
+- Lib → `.claude/rules/architecture.md` + `.claude/rules/security.md`
+- Hooks → `.claude/rules/api-contract.md`
+- Store → `.claude/rules/architecture.md`
+- Features → `.claude/rules/components.md` + `.claude/rules/architecture.md`
+- Components → `.claude/rules/components.md`
+- App → `.claude/rules/architecture.md` + `.claude/rules/security.md`
+- Tests → `.claude/rules/testing.md`
+
+---
+
+## Step 4 — Build the Layer
+
+### Types (`src/types/domain.types.ts`)
+- Add frontend-only types (form inputs, UI state, component props)
+- NEVER duplicate what's in `api.generated.ts`
+- Check: `import type { components } from '@/types/api.generated'` and use those
+
+### Lib (`src/lib/`)
+- New env vars: add to Zod schema in `env.ts` + `.env.example`
+- New constants: add to `constants.ts`
+- If api-client needs changes: add middleware — never change the base createClient call
+
+### Hooks (`src/hooks/`)
+- One file per domain: `use-{domain}.ts`
+- Export `{domain}Keys` query key factory first
+- Use `apiClient.GET/POST/PUT/PATCH/DELETE` — never raw `fetch()`
+- Always `if (error) throw new Error(...)` after destructuring
+- Include: list hook, single hook, create/update/delete mutations
+
+### Store (`src/store/`)
+- Only if feature needs client-only state (sidebar, modal, filters not in URL)
+- `create<StoreType>()` with named slice
+- NO server data — that's in TanStack Query
+
+### Features (`src/features/{domain}/`)
+Create these sub-files:
+```
+src/features/{domain}/
+  index.ts               ← barrel export
+  {Domain}List.tsx       ← list component
+  {Domain}Card.tsx       ← single item
+  {Domain}Form.tsx       ← create/edit form
+  {Domain}Detail.tsx     ← detail view
+  use-{domain}-page.ts  ← feature-level hooks (compose domain hooks)
+```
+Every component: Loading + Error + Empty states.
+Forms: react-hook-form + zodResolver.
+Every `use client`: has comment `// Client: [reason]`.
+Every interactive element: aria-label, focus-visible.
+
+### Components (`src/components/shared/`)
+- New shared components needed by multiple features
+- Props fully typed
+- No hooks, no API calls — pure rendering
+
+### App (`app/`)
+- Page files: Server Components by default
+- Import Feature component at top, render it
+- NO `useState`, `useEffect`, `fetch` in page.tsx
+- Layout changes: auth guard, breadcrumbs, nav items
+
+### Tests
+- `tests/unit/hooks/use-{domain}.test.ts` — MSW + renderHook
+- `tests/unit/features/{Component}.test.tsx` — RTL + userEvent
+- `tests/unit/utils/{util}.test.ts` — pure function tests
+- `tests/e2e/{feature}.spec.ts` — Playwright happy path + auth
+
+---
+
+## Step 5 — Run Gate
+Call `gate-checker` agent.
+
+**If FAIL:** auto-fix each ITEM, log what was fixed, re-run gate (max 3 attempts).
+**If PASS:** tick checkbox in plan, write ADR if non-obvious decision.
+
+---
+
+## Step 6 — ADR (if needed)
+`docs/design-docs/decisions/ADR-XXX-{slug}.md`
+Update `docs/design-docs/decisions/index.md`.
+
+---
+
+## Step 7 — Commit and Push
+```bash
+git add -A
+git commit -m "{feat|chore|test}({scope}): {description}
+
+{bullet points}
+
+PLAN-XXX Layer N/Total"
+git push origin main
+```
+
+---
+
+## Step 8 — Report to Human
+```
+═══════════════════════════════════════════
+✅ Layer N ({layer-name}) — COMPLETE
+═══════════════════════════════════════════
+Files created: [list]
+Gate attempts: N
+Auto-fixed:    [list]
+ADR written:   ADR-XXX / None needed
+Committed:     [hash]
+
+Progress: [x] Layer 1  [x] Layer 2  [ ] Layer 3 ...
+
+Ready for Layer N+1: {next-layer-name}
+Confirm to continue? [human must respond]
+═══════════════════════════════════════════
+```
+**Wait for human confirmation before next layer.**

package/templates/nextjs/.claude/skills/05-validate-layer/SKILL.md

@@ -0,0 +1,13 @@
+# /validate-layer — Run Gate Without Building
+
+Triggered by: /validate-layer
+
+Calls gate-checker agent on current src/ and app/ state.
+Read-only — no auto-fix, no commit.
+
+## Steps
+1. Find most recently checked layer from active plan
+2. Call gate-checker agent
+3. Present full PASS/FAIL report
+
+To auto-fix failures: run /build-layer

package/templates/nextjs/.claude/skills/06-push-layer/SKILL.md

@@ -0,0 +1,20 @@
+# /push-layer — Commit and Push Current Layer
+
+Triggered by: /push-layer
+
+## Steps
+1. Run the full gate (Cardinal Rule 4 — gate must PASS before commit):
+```bash
+npm run gate   # typecheck + lint + format:check + test:coverage (incl. tests/architecture/)
+```
+If it fails → auto-fix what you can, re-run, and only proceed when green. Never commit a red gate.
+
+2. Commit:
+```bash
+git add -A
+git commit -m "{type}({scope}): {description from active plan}"
+git push origin $(git branch --show-current)
+```
+
+## Commit Types
+feat · fix · chore · refactor · test · docs · style · perf

package/templates/nextjs/.claude/skills/07-layer-check/SKILL.md

@@ -0,0 +1,28 @@
+# /layer-check — Ad-hoc Architecture Violation Scan
+
+Triggered by: /layer-check
+
+Runs:
+1. npm run typecheck
+2. npm run lint
+3. grep for direct fetch() in components/features/pages
+4. grep for process.env outside env.ts
+5. grep for console.log
+6. grep for raw <img> tags
+7. file size check (> 400 lines)
+8. npx vitest run tests/architecture/
+
+Output:
+```
+LAYER CHECK — {timestamp}
+TypeScript:  CLEAN / {N} errors
+ESLint:      CLEAN / {N} errors
+fetch():     NONE / {list}
+process.env: NONE / {list}
+console.log: NONE / {list}
+<img>:       NONE / {list}
+File sizes:  NONE / {list}
+Arch tests:  PASS / FAIL
+
+OVERALL: CLEAN / {N} violations
+```

package/templates/nextjs/.claude/skills/08-garbage-collect/SKILL.md

@@ -0,0 +1,14 @@
+# /garbage-collect — End-of-Feature Cleanup
+
+Triggered by: /garbage-collect
+
+Calls garbage-collector agent which:
+1. Scans file size violations and splits files > 400 lines
+2. Removes unnecessary use client directives
+3. Runs TypeScript + ESLint --fix
+4. Updates stale docs
+5. Updates QUALITY_SCORE.md
+6. Logs tech debt
+7. Closes plan (active/ to completed/)
+8. Marks spec SHIPPED
+9. Final commit + push

package/templates/nextjs/.claude/skills/09-doc-garden/SKILL.md

@@ -0,0 +1,12 @@
+# /doc-garden — Scan and Fix Stale Docs
+
+Triggered by: /doc-garden
+
+Calls doc-gardener agent which checks:
+- AGENTS.md vs .claude/ directory
+- ARCHITECTURE.md vs actual src/ structure
+- docs/product-specs/index.md vs actual spec files
+- .env.example vs src/lib/env.ts schema
+- docs/design-docs/decisions/index.md vs actual ADR files
+
+Updates anything stale. Commits if changed.

package/templates/nextjs/.claude/skills/10-api-sync/SKILL.md

@@ -0,0 +1,50 @@
+# /api-sync — Regenerate API Types from OpenAPI Spec
+
+> **Verified:** 2026-06-05 · **Staleness threshold:** 60 days
+> **Source:** openapi-typescript (https://openapi-ts.dev/)
+> If older than the threshold, fetch current `openapi-typescript` docs via `ctx7` (wired
+> in `.mcp.json`), or `WebFetch`/`WebSearch` if ctx7 is unavailable, before running — its
+> CLI flags and output shape change between majors.
+
+Triggered by: /api-sync
+
+## What it does
+Regenerates src/types/api.generated.ts from openapi.json in the project root.
+This is the source of truth for all API types in the frontend.
+
+## Steps
+
+### Step 1 — Check spec file
+```bash
+ls openapi.json 2>/dev/null
+```
+If missing: tell human to copy openapi.json from backend to project root.
+  - FastAPI backend: generate at http://localhost:8000/openapi.json
+  - Express backend: copy from docs/generated/openapi.json
+
+### Step 2 — Regenerate
+```bash
+npm run api:sync
+# which runs: openapi-typescript openapi.json -o src/types/api.generated.ts
+```
+
+### Step 3 — TypeScript check
+```bash
+npm run typecheck 2>&1
+```
+List every file with errors — these are places that need updating after the contract changed.
+
+### Step 4 — Call contract-checker agent
+Check for hand-written types that duplicate the generated ones.
+
+### Step 5 — Commit
+```bash
+git add src/types/api.generated.ts openapi.json
+git commit -m "chore(api): sync contract from backend openapi.json"
+git push origin main
+```
+
+## Rules
+- NEVER edit api.generated.ts manually
+- Always run typecheck after sync — errors = contract drift to fix
+- Run before starting every new feature

package/templates/nextjs/.claude/skills/11-perf-budget/SKILL.md

@@ -0,0 +1,51 @@
+# /perf-budget — Performance Budget Check
+
+> **Verified:** 2026-06-05 · **Staleness threshold:** 60 days
+> **Sources:** Next.js bundle analyzer (https://nextjs.org/docs/app/guides/package-bundling) ·
+> Core Web Vitals (https://web.dev/vitals)
+> If older than the threshold, fetch current docs via `ctx7` (wired in `.mcp.json`), or
+> `WebFetch`/`WebSearch` if ctx7 is unavailable, before running — `next build` output
+> format and CWV thresholds shift between releases.
+
+Triggered by: /perf-budget
+
+## Step 1 — Bundle Analysis
+```bash
+ANALYZE=true npm run build 2>&1 | grep -E "Page|First Load JS|kB"
+```
+Flag any route with First Load JS > 150kB.
+
+## Step 2 — Client Component Audit
+```bash
+grep -rn "^'use client'" src/ app/ --include="*.tsx" -l
+```
+For each file: verify it actually needs useState/useEffect/browser APIs.
+
+## Step 3 — Image Check
+```bash
+grep -rn "<img " src/ app/ --include="*.tsx"
+grep -rn "<Image " src/ app/ --include="*.tsx" | grep -v "width\|fill"
+```
+
+## Step 4 — Build Time
+```bash
+time npm run build 2>&1 | tail -5
+```
+
+## Report
+```
+PERF BUDGET — {timestamp}
+
+Bundle:
+  [route]: [size]kB  PASS/FAIL (target < 150kB)
+
+Client components: N total
+  Unnecessary (review): [files]
+
+Images using raw <img>: N (should be 0)
+Images missing dimensions: N
+
+Build time: Xs
+
+OVERALL: PASS / N issues
+```

package/templates/nextjs/.dockerignore

@@ -0,0 +1,25 @@
+# Keep the build context small and secret-free.
+node_modules
+.next
+.git
+.github
+.husky
+.claude
+.harness-hold
+coverage
+playwright-report
+test-results
+tests
+docs
+*.md
+.env
+.env.*
+!.env.example
+npm-debug.log*
+yarn-error.log*
+Dockerfile
+.dockerignore
+.prettierrc
+.prettierignore
+.lintstagedrc.json
+lighthouserc.js

package/templates/nextjs/.gitattributes

@@ -0,0 +1,10 @@
+# Normalise line endings. Shell scripts and git hooks MUST be LF or they break
+# on Linux (husky / CI: "bad interpreter"). Let Git decide for everything else.
+* text=auto
+
+*.sh        text eol=lf
+.husky/*    text eol=lf
+*.ps1       text eol=crlf
+
+# Treat the generated API contract as generated (better diffs, not hand-edited).
+src/types/api.generated.ts linguist-generated=true

package/templates/nextjs/.github/CODEOWNERS

@@ -0,0 +1,24 @@
+# CODEOWNERS — GitHub auto-requests these reviewers based on which files changed.
+# Order matters: the LAST matching pattern wins.
+#
+# Replace the placeholder team slugs with your real GitHub teams/usernames, then
+# enable "Require review from Code Owners" in branch protection
+# (see docs/design-docs/team-workflow.md). Until then these are inert placeholders.
+
+# Default — any engineer on the team can review
+*                               @your-team/engineers
+
+# Security-sensitive — leads must review
+/.claude/hooks/                 @your-team/leads
+/src/lib/env.ts                 @your-team/leads
+/src/lib/api-client.ts          @your-team/leads
+/src/features/auth/             @your-team/leads
+/app/api/                       @your-team/leads
+/next.config.ts                 @your-team/leads
+
+# API contract is generated — leads review any drift / accidental hand-edit
+/src/types/api.generated.ts     @your-team/leads
+
+# Platform / infra — platform team owns build, containers, and CI
+/Dockerfile                     @your-team/platform
+/.github/workflows/             @your-team/platform

package/templates/nextjs/.github/dependabot.yml

@@ -0,0 +1,31 @@
+# Dependabot — keeps the (unpinned-at-install, locked-after-scaffold) deps current.
+# The harness installs latest LTS once; the committed package-lock.json freezes that,
+# and Dependabot proposes reviewed bumps so the project doesn't silently drift.
+version: 2
+updates:
+  # npm — application dependencies. Grouped so routine minor/patch bumps are one PR.
+  - package-ecosystem: npm
+    directory: '/'
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch
+    labels:
+      - dependencies
+    commit-message:
+      prefix: chore
+      include: scope
+
+  # GitHub Actions — keep workflow action versions patched.
+  - package-ecosystem: github-actions
+    directory: '/'
+    schedule:
+      interval: weekly
+    labels:
+      - ci
+    commit-message:
+      prefix: ci

package/templates/nextjs/.github/pull_request_template.md

@@ -0,0 +1,59 @@
+<!--
+  PR title format: <type>(<scope>): <summary>
+  type ∈ feat | fix | chore | refactor | docs | test | perf
+  Example: feat(applications): add application list feature
+-->
+
+## What does this PR do?
+
+<!-- One sentence. Link the spec it came from. -->
+
+- Spec: `docs/product-specs/ready/SPEC-XXX.md`
+
+## Execution plan reference
+
+<!-- Link the plan that drove this work. -->
+
+- Plan: `docs/exec-plans/active/PLAN-XXX.md` (or completed/)
+- Closes #
+
+## Layers touched (check each, confirm its rule holds)
+
+- [ ] **Types** — zero imports from other layers; no logic; never duplicates `api.generated.ts`
+- [ ] **Lib** — `env.ts` Zod-validated (only place with `process.env`); `api-client.ts` via openapi-fetch `createClient`; auth token read from React context
+- [ ] **Hooks** — TanStack Query wrapping `api-client`; no raw `fetch()`; loading/success/error states covered
+- [ ] **Features** — no direct `fetch()`; no `process.env`; every `'use client'` has a `// Client: <reason>` comment
+- [ ] **App** — pages are layout + data trigger only (no `useState`/`useEffect`/`fetch`); import feature components, not hooks
+- [ ] **Utils** — zero domain imports; **100% test coverage**
+
+## Gate check (all green)
+
+- [ ] `tsc --noEmit` — type-check passes
+- [ ] `eslint src/ app/ --max-warnings=0` — lint clean
+- [ ] `prettier --check .` — formatting clean
+- [ ] `vitest` — all tests pass
+- [ ] Coverage meets per-layer thresholds (utils 100 · hooks 80 · features 70 · components 70) — enforced by `vitest.config.ts`
+- [ ] Architecture tests pass (`vitest run tests/architecture/`)
+- [ ] No file exceeds 400 lines
+
+## Security checklist
+
+- [ ] No `console.log` in `src/` or `app/`
+- [ ] No raw `process.env` outside `src/lib/env.ts`
+- [ ] No direct `fetch()` in components/features/pages (all API calls via `src/hooks/`)
+- [ ] Access tokens in memory only — never `localStorage`/`sessionStorage`
+- [ ] All images via `next/image` — no raw `<img>`
+- [ ] `src/types/api.generated.ts` not hand-edited (regenerated via `/api-sync`)
+- [ ] Cross-user isolation test **enabled** (remove `test.skip` in `tests/e2e/isolation.spec.ts`) for each new user-owned resource (User B → 404 on User A's resource)
+
+## ADR
+
+- [ ] A non-obvious architectural decision was made → ADR written in `docs/design-docs/decisions/`
+- [ ] No ADR needed (nothing non-obvious)
+
+## Breaking changes
+
+- [ ] None
+- [ ] Yes — documented below (API contract, env var, or config change)
+
+<!-- If breaking: describe the change, the migration path, and rollback steps. -->