Skill: hiromps/opengemini-next-js-bestpractice-builder (version 1.0.1)

--- name: opengemini-nextjs-bestpractice-builder description: Build opinionated SaaS projects for solo developers with OpenClaw as orchestrator and Gemini CLI as planning and generation copilot, using a fixed best-practice stack: Next.js App Router, Tailwind, shadcn/ui, Neon PostgreSQL, Prisma 6, Clerk, Resend, Stripe, Cloudflare R2, PostHog, Sentry, Vercel, and FastAPI only for Python-required workloads. Use when the user wants to brainstorm, define, scaffold, document, structure, or implement a SaaS with this exact stack and project layout. --- # Purpose 固定スタックの個人開発SaaSを、ブレない設計と実装ルールで立ち上げる。 技術説明ではなく、実装時の行動基準とプロジェクト構造を強制するための Skill。 # Use when - Next.js + FastAPI 境界を持つ SaaS を新規に作るとき - 固定スタックで要件定義から scaffold まで一貫して進めたいとき - Gemini CLI を使って docs・設計・実装計画を高速化したいとき - 個人開発向けに現実的で保守しやすい構成を最初から敷きたいとき # Do not use when - 技術選定を自由に変えたいとき - Python が主役のバックエンドを作るとき - 単なる小規模LPや静的サイトだけを作るとき - この固定 stack を外す予定が強いとき # Project assumptions - Frontend は Next.js App Router - UI は Tailwind + shadcn/ui - DB は Neon PostgreSQL - ORM は Prisma 6 - Auth は Clerk - Email は Resend - Payments は Stripe - Storage は Cloudflare R2 - Analytics は PostHog - Error Monitoring は Sentry - Deploy は Vercel - FastAPI は Python-required workloads のみ # Rules - docs を先に作り、実装を後追いさせる - `GEMINI.md` に source of truth を明記する - Next.js をデフォルト backend とし、FastAPI を乱用しない - Clerk auth を Prisma に複製しない - Stripe 成功判定は webhook 起点にする - R2 にファイル本体を保存し、DBには metadata だけを置く - 各 project-level skill は共通テンプレートの型にそろえる - 各 skill は技術説明ではなく実装時の行動規範として書く - Prisma は 6 系を固定で使う。7 系へ勝手に上げない - 開発DBはローカル可だが、本番DBは Neon PostgreSQL を前提にする # Workflow 1. product goal と MVP を整理する 2. `references/project-bootstrap-checklist.md` を確認する 3. `scripts/bootstrap_tree.sh` で理想構成を作る 4. `scripts/generate_gemini_md.sh` で `GEMINI.md` を作る 5. `scripts/generate_project_docs.sh` で docs を生成する 6. docs を source of truth にして実装へ進む 7. project-level skills を必要に応じて補強する # Checklist - `GEMINI.md` があるか - `docs/requirements.md` から `docs/db-schema.md` まで揃っているか - `skills/*/SKILL.md` が共通テンプレートに沿っているか - FastAPI を使う理由が説明できるか - Stripe / Clerk / R2 の危険なアンチパターンを避けているか - Vercel deploy 前提の env 設計が見えているか - Prisma 6 を固定しているか - 本番DBが Neon を前提に設計されているか # Common pitfalls - Next.js で足りる処理まで FastAPI に逃がす - docs を雑に作って source of truth が死ぬ - skill を技術メモ化して、行動基準として使えなくする - Clerk と Prisma の役割を混ぜる - Stripe webhook を軽視して success redirect に依存する - file upload を DB 中心で考える - Prisma 7 に上げて接続・設定周りでハマる # Output expectations - `GEMINI.md` - docs 一式 - 理想ディレクトリ構成 - project-level skills 一式 - stack に沿った実装 plan または scaffold - 必要なら GitHub / Vercel まで進めるための準備状態 # Source of truth order When generating or updating project files, treat these as the source of truth in order: 1. `docs/requirements.md` 2. `docs/scope.md` 3. `docs/architecture.md` 4. `docs/conventions.md` 5. `docs/decisions/*.md` 6. `docs/notes/brainstorming.md` is reference only ## Fixed stack policy - Frontend: Next.js App Router - UI: Tailwind + shadcn/ui - DB: Neon PostgreSQL - ORM: Prisma 6 - Auth: Clerk - Email: Resend - Payments: Stripe - Storage: Cloudflare R2 - Analytics: PostHog - Error Monitoring: Sentry - Deploy: Vercel - Backend: FastAPI only for Python-required workloads ## Backend boundary Default backend logic lives in Next.js route handlers or server actions. FastAPI exists only for AI, batch jobs, heavy processing, or Python-specific integrations. ## Never do - Do not duplicate Clerk auth state into Prisma as a full auth system - Do not treat Stripe success redirect as source of truth; use webhook state - Do not store uploaded files in PostgreSQL - Do not add FastAPI endpoints for simple CRUD unless explicitly required - Do not upgrade to Prisma 7 by default ## Target project structure Generate or align toward this structure: ```text my-saas/ ├─ GEMINI.md ├─ src/ │ ├─ app/ │ ├─ components/ │ ├─ features/ │ ├─ lib/ │ ├─ server/ │ ├─ hooks/ │ └─ types/ ├─ backend/ │ └─ fastapi/ │ ├─ app/ │ ├─ tests/ │ └─ pyproject.toml ├─ prisma/ │ ├─ schema.prisma │ ├─ migrations/ │ └─ seed.ts ├─ public/ ├─ tests/ │ ├─ unit/ │ ├─ integration/ │ └─ e2e/ ├─ docs/ │ ├─ requirements.md │ ├─ scope.md │ ├─ architecture.md │ ├─ conventions.md │ ├─ integrations.md │ ├─ db-schema.md │ ├─ decisions/ │ └─ notes/ │ └─ brainstorming.md ├─ .gemini/ │ └─ commands/ ├─ skills/ │ ├─ nextjs/SKILL.md │ ├─ clerk/SKILL.md │ ├─ prisma/SKILL.md │ ├─ shadcn/SKILL.md │ ├─ stripe/SKILL.md │ ├─ resend/SKILL.md │ ├─ posthog/SKILL.md │ ├─ sentry/SKILL.md │ ├─ r2/SKILL.md │ ├─ fastapi/SKILL.md │ ├─ api-security/SKILL.md │ └─ vercel/SKILL.md └─ scripts/ ``` ## What this skill should produce For a new project, aim to create at least: - `GEMINI.md` - `docs/requirements.md` - `docs/scope.md` - `docs/architecture.md` - `docs/conventions.md` - `docs/integrations.md` - `docs/db-schema.md` - `docs/notes/brainstorming.md` - `prisma/schema.prisma` - base app structure under `src/` - base FastAPI structure under `backend/fastapi/` - `.env.example` - integration or implementation plan for Clerk, Stripe, Resend, PostHog, Sentry, and R2 ## References Read when needed: - `references/doc-templates.md` - `references/integration-rules.md` - `references/project-bootstrap-checklist.md` - `references/project-skill-template.md` ## Publish readiness notes This skill is strongest when used with Gemini CLI plus OpenClaw file and shell control, and optionally ACP for large implementation loops. The project-level `skills/*/SKILL.md` files should be implementation policies, not generic framework notes. Before publishing or using this for a real project, verify: - Gemini CLI is installed and authenticated - the generated `skills/*/SKILL.md` files follow the shared template shape - project docs are generated before major implementation starts - FastAPI is only introduced when Python is actually required - deployment assumptions match Vercel reality for the target project - Prisma is pinned to 6.x - production DB assumptions match Neon reality

path: _meta.json
content: ownerId: kn7c99atnttfv6hdvds54qzt4581yq4m
slug: opengemini-next-js-bestpractice-builder
version: 1.0.0
publishedAt: 1774924177167

path: references/doc-templates.md
content: # Doc Templates

Use these templates as the minimum structure.

## GEMINI.md

```md
# Source of truth
1. docs/requirements.md
2. docs/scope.md
3. docs/architecture.md
4. docs/conventions.md
5. docs/decisions/*.md
6. docs/notes/brainstorming.md is reference only

# Stack policy
- Frontend: Next.js App Router
- UI: Tailwind + shadcn/ui
- DB: Neon PostgreSQL
- ORM: Prisma
- Auth: Clerk
- Email: Resend
- Payments: Stripe
- Storage: Cloudflare R2
- Analytics: PostHog
- Error Monitoring: Sentry
- Deploy: Vercel
- Backend: FastAPI only for Python-required workloads

# Backend boundary
- Default backend logic lives in Next.js route handlers or server actions
- FastAPI is only for AI, batch, heavy processing, or Python-specific integrations

# Never do
- Do not duplicate Clerk auth state into Prisma as a full auth system
- Do not treat Stripe success redirect as source of truth; use webhook state
- Do not store uploaded files in PostgreSQL
- Do not add FastAPI endpoints for simple CRUD unless explicitly required
```

## requirements.md

```md
# Requirements
## Summary
## Target Users
## Problem
## Goals
## Non-Goals
## MVP Scope
## Monetization
## User Stories
## Functional Requirements
## Non-Functional Requirements
## Risks
## Success Metrics
```

## scope.md

```md
# Scope
## In Scope
## Out of Scope
## MVP Milestones
## Deferred Features
```

## architecture.md

```md
# Architecture
## System Overview
## Mermaid Diagram
## Frontend Architecture
## Backend Architecture
## Data Architecture
## Auth and Billing Boundaries
## Integrations
## Deployment
## Open Questions
```

## conventions.md

```md
# Conventions
## Code Style
## Folder Structure
## Naming
## Server vs Client Rules
## Feature Boundaries
## Testing Rules
## Env Var Rules
## Error Handling
## Logging and Monitoring
```

## integrations.md

```md
# Integrations
## Clerk
## Stripe
## Resend
## Cloudflare R2
## PostHog
## Sentry
## Neon
## FastAPI
## Vercel
```

## db-schema.md

```md
# DB Schema
## Core Models
## Relationships
## Billing Models
## File Metadata Models
## Audit and Event Notes
```


path: references/integration-rules.md
content: # Integration Rules

## Clerk
- Use Clerk as the auth source of truth
- Store only the app-level user profile fields you actually need in Prisma
- Reference Clerk user IDs instead of recreating auth tables

## Stripe
- Billing state comes from webhook-driven persistence
- Success and cancel redirects are UX only
- Record subscription and checkout state in app-domain tables

## Resend
- Use for transactional emails
- Document trigger points and templates
- Keep email logic server-side

## Cloudflare R2
- Store files in R2, not PostgreSQL
- Save file metadata and ownership in Prisma
- Define access rules clearly

## PostHog
- Track core activation and revenue events
- Do not spray random events everywhere
- Decide event naming up front

## Sentry
- Capture server and client errors intentionally
- Tag critical flows like auth, billing, upload, and AI jobs

## FastAPI
- Use only for Python-required workloads
- Keep API boundaries explicit
- Avoid mirror CRUD APIs when Next.js can already handle it

## Vercel
- Treat it as the default frontend deploy target
- Document env vars and preview vs production behavior


path: references/project-bootstrap-checklist.md
content: # Project Bootstrap Checklist

## Before coding
- Define product goal
- Define target user
- Define MVP boundary
- Decide if FastAPI is truly needed
- Decide billing model
- Decide upload/storage needs
- Decide key analytics events
- Decide key email flows

## Before data modeling
- Define core domain entities
- Separate auth data from app data
- Separate billing truth from UI redirects
- Separate file storage from DB metadata

## Before deployment
- Prepare env var inventory
- Confirm Clerk setup
- Confirm Stripe webhook plan
- Confirm Resend sender strategy
- Confirm PostHog and Sentry setup
- Confirm Vercel deployment shape

## Before adding FastAPI
- Prove Python is necessary
- Define exact boundary
- Define auth and transport between frontend and FastAPI
- Define deployment plan


path: references/project-skill-template.md
content: # Project Skill Template

Use this exact shape for project-level skills under `skills/*/SKILL.md`.

```md
---
name: nextjs
description: Use this skill when working on Next.js App Router pages, layouts, route handlers, server actions, and rendering/data-fetching concerns. Do not use for Python-only backend work.
---

# Purpose
この Skill の目的を1〜3行で書く。

# Use when
- どういうときにこの Skill を使うか
- 何を実装するときに参照するか

# Do not use when
- どういうときは使わないか
- 他の Skill を優先すべきケース

# Project assumptions
このプロジェクトでの前提を書く。

# Rules
AIが守るべきルールを箇条書きで書く。

# Workflow
実装時の手順を順番で書く。

# Checklist
実装後に確認することを書く。

# Common pitfalls
よくあるミスを書く。

# Output expectations
この Skill を使って実装するときの期待アウトプットを書く。
```

The point is not generic technology explanation.
The point is implementation-time behavior guidance.


path: scripts/bootstrap_tree.sh
content: #!/usr/bin/env bash
set -euo pipefail

root="${1:-my-saas}"
mkdir -p "$root"/{public,prisma/migrations,tests/unit,tests/integration,tests/e2e,scripts}
mkdir -p "$root"/src/{app,components,features,lib,server,hooks,types}
mkdir -p "$root"/backend/fastapi/{app,tests}
mkdir -p "$root"/docs/{decisions,notes}
mkdir -p "$root"/.gemini/commands
mkdir -p "$root"/skills/{nextjs,clerk,prisma,shadcn,stripe,resend,posthog,sentry,r2,fastapi,api-security,vercel}

touch "$root"/prisma/schema.prisma

touch "$root"/prisma/seed.ts

touch "$root"/backend/fastapi/pyproject.toml

touch "$root"/docs/{requirements.md,scope.md,architecture.md,conventions.md,integrations.md,db-schema.md}

touch "$root"/docs/notes/brainstorming.md

cat > "$root/skills/nextjs/SKILL.md" <<'EOF'
---
name: nextjs
description: Use this skill for Next.js App Router work including pages, layouts, route handlers, server actions, metadata, loading/error states, and server/client component boundaries.
---

# Purpose
Next.js App Router の実装を一貫した方針で行う。

# Use when
- 新しいページを追加するとき
- layout を作る/修正するとき
- route handler を追加するとき
- server action を実装するとき
- server component / client component の切り分けが必要なとき

# Do not use when
- Python API のみを触るとき
- DBスキーマ変更だけが目的のとき
- UIコンポーネント単体設計だけなら shadcn Skill を優先

# Project assumptions
- App Router を採用
- TypeScript strict
- 認証は Clerk
- DB は Prisma
- UI は shadcn/ui
- 原則として backend logic は Next.js 側に置く

# Rules
- app router のファイル規約に従う
- server component をデフォルトにし、必要時のみ client component にする
- 単純CRUDのために FastAPI を増やさない
- route handlers は外部公開APIやwebhook用途を優先する
- フォーム処理は server action を第一候補とする
- metadata, loading, error, not-found の要否を検討する

# Workflow
1. 対象ルートと責務を確認
2. page/layout/loading/error の必要性を判断
3. server/client 境界を決める
4. データ取得方法を決める
5. 認証・認可を確認する
6. 実装
7. テストまたは動作確認

# Checklist
- server/client 境界は妥当か
- 認証保護が必要な画面に guard があるか
- エラー状態が考慮されているか
- metadata が必要なら設定したか
- 不要な use client を増やしていないか

# Common pitfalls
- なんでも client component にする
- route handler と server action の責務が混ざる
- 権限チェックなしで dashboard を出す
- fetch と Prisma の責務を混在させる

# Output expectations
- 変更ファイル一覧
- 実装内容の要約
- 必要なテストまたは動作確認
- 必要なら docs 更新
EOF

cat > "$root/skills/clerk/SKILL.md" <<'EOF'
---
name: clerk
description: Use this skill when implementing authentication, user sessions, protected routes, Clerk middleware, webhook-based user sync, or account/profile flows with Clerk.
---

# Purpose
認証・セッション管理を Clerk 中心で安全に実装する。

# Use when
- サインイン/サインアップ導線を作る
- 認証付きページを追加する
- middleware で保護する
- Clerk webhook を処理する
- ユーザープロフィール連携を作る

# Do not use when
- 課金だけを触るとき
- DBスキーマだけを変えるとき

# Project assumptions
- 認証の source of truth は Clerk
- Prisma には業務用 user/profile/organization データのみ保持
- Clerk の完全な auth state を Prisma に複製しない

# Rules
- 認証判定は Clerk で行う
- 権限/ロールが必要な場合は app DB に最小限の拡張情報だけ持つ
- webhook で必要な同期だけ行う
- middleware 保護と server-side 保護の両方を意識する
- 認可ロジックは「ログインしているか」と「何をしてよいか」を分ける

# Workflow
1. ルートの保護要件を確認
2. Clerk middleware の適用有無を確認
3. UI ルートと server-side チェックを実装
4. 必要なら webhook で user sync
5. 権限・プロフィールを app DB に反映

# Checklist
- 非ログイン時の挙動が定義されているか
- サーバー側でも認証確認しているか
- Clerk webhook の署名検証があるか
- DBに auth 本体を重複保存していないか

# Common pitfalls
- Clerk と Prisma の両方を auth 正本にする
- middleware だけで十分だと思い込む
- webhook なしで user 同期前提の実装をする

# Output expectations
- 保護対象ルート
- 認証/認可の実装内容
- webhook の有無
- 必要な docs 更新
EOF

cat > "$root/skills/prisma/SKILL.md" <<'EOF'
---
name: prisma
description: Use this skill for Prisma schema changes, migrations, database access patterns, seed scripts, and query/model design with PostgreSQL.
---

# Purpose
Prisma と PostgreSQL の変更を安全に行う。

# Use when
- schema.prisma を変更するとき
- migration を作るとき
- 新しい model/relation を作るとき
- query を追加するとき
- seed を更新するとき

# Do not use when
- UI変更のみのとき
- 認証フローのみのとき

# Project assumptions
- DB は Neon PostgreSQL
- ORM は Prisma
- DB変更時は migration 必須
- DB access は Prisma client 経由を基本とする

# Rules
- schema 変更だけで終わらせず migration を作る
- 命名規則を統一する
- nullable は安易に増やさない
- index / unique / relation を明示的に考える
- 課金や権限に関わる状態は曖昧にしない

# Workflow
1. 要件からデータモデルを整理
2. schema.prisma を更新
3. migration を作成
4. seed / 型 / 参照コードを更新
5. 既存データ影響を確認
6. テスト

# Checklist
- migration があるか
- relation は妥当か
- enum/unique/index の見落としはないか
- 削除時の挙動が定義されているか
- webhook 由来の外部IDを保存するならカラム設計があるか

# Common pitfalls
- Prisma schema だけ変えて migration を作らない
- 後から困る external_id を保存しない
- Stripe / Clerk 由来の識別子を曖昧にする

# Output expectations
- schema 変更点
- migration の有無
- 影響範囲
- テスト/確認項目
EOF

cat > "$root/skills/shadcn/SKILL.md" <<'EOF'
---
name: shadcn
description: Use this skill when building or modifying UI with Tailwind CSS and shadcn/ui components, including forms, dialogs, tables, cards, and design consistency work.
---

# Purpose
shadcn/ui と Tailwind で統一感のあるUIを作る。

# Use when
- 新しいUIを作る
- フォームやダイアログを作る
- テーブルやカードを整える
- デザイン整合性を保つ

# Do not use when
- DBやAPIのみを触るとき
- Pythonバックエンドだけの作業

# Project assumptions
- UIは shadcn/ui ベース
- Tailwind utility-first
- 既存コンポーネントを優先して再利用する

# Rules
- まず既存UIを探して再利用する
- コンポーネントの責務を分ける
- アクセシビリティを意識する
- 状態ごとの見た目を作る
- 空状態/エラー状態/ローディング状態を省略しない

# Workflow
1. 既存UIを確認
2. 再利用できるか判断
3. 状態ごとのUIを設計
4. 実装
5. モバイル確認

# Checklist
- ラベルと入力が対応しているか
- キーボード操作を妨げないか
- 余白・サイズ・階層が既存画面と一致しているか
- モバイルで破綻しないか

# Common pitfalls
- 似たコンポーネントを量産する
- Tailwind class を各所に重複させる
- 空状態とエラー状態を作らない

# Output expectations
- 変更コンポーネント一覧
- 状態パターン
- UI確認項目
EOF

cat > "$root/skills/stripe/SKILL.md" <<'EOF'
---
name: stripe
description: Use this skill for Stripe checkout, billing portal, subscriptions, webhook handling, payment state synchronization, and product/price integration.
---

# Purpose
Stripe連携を安全に実装する。

# Use when
- Checkout を作る
- Billing Portal を作る
- subscription 状態を扱う
- webhook を処理する
- price / product ID を使う

# Do not use when
- 認証だけの作業
- UIの見た目調整だけの作業

# Project assumptions
- 支払い状態の source of truth は Stripe webhook
- アプリDBには必要最小限の billing state を保存
- success URL のみで課金成功確定にしない

# Rules
- 決済結果は webhook で反映する
- product/price ID は環境変数や設定ファイルで管理する
- idempotency と再送を意識する
- ユーザー/組織との紐づけを明確にする
- テストモードと本番モードを混同しない

# Workflow
1. 商品・価格・課金モデルを確認
2. checkout / portal 導線を実装
3. webhook 署名検証を実装
4. DBへ billing state を同期
5. UIの制限解除条件を webhook state に連動させる

# Checklist
- webhook 検証があるか
- success redirect 依存になっていないか
- Stripe customer ID を保存しているか
- subscription status の扱いが明確か

# Common pitfalls
- success page だけで有料化する
- webhook 再送を考慮しない
- customer / subscription / price のID管理が曖昧

# Output expectations
- Checkout/Portal/Webhook の実装範囲
- 保存する billing state
- テスト観点
EOF

cat > "$root/skills/resend/SKILL.md" <<'EOF'
---
name: resend
description: Use this skill when sending transactional email, onboarding email, passwordless or verification-related messaging, or templated app notifications via Resend.
---

# Purpose
Resend を使ったアプリメール送信を整理する。

# Use when
- トランザクションメールを送る
- オンボーディングメールを送る
- 通知メールやテンプレメールを作る

# Do not use when
- 認証の中核管理だけを触るとき
- UIだけを作るとき

# Project assumptions
- メールは transactional を中心に扱う
- 送信ロジックは server-side に置く

# Rules
- 送信用途を transactional に限定して整理する
- メール文面はテンプレート化する
- 宛先・件名・本文生成の責務を分ける
- ローカル/本番の送信動作差を意識する

# Workflow
1. 送信トリガーを整理
2. テンプレートを定義
3. 送信処理を server-side に実装
4. 失敗時ログと再送方針を確認

# Checklist
- 送信元ドメイン設定前提を満たすか
- 再送時の影響を考慮しているか
- エラー時のログがあるか

# Common pitfalls
- 文面をコードにベタ書きする
- 再送影響を考えない

# Output expectations
- 送信トリガー
- テンプレ一覧
- エラー処理方針
EOF

cat > "$root/skills/posthog/SKILL.md" <<'EOF'
---
name: posthog
description: Use this skill when implementing product analytics, feature flags, event naming, funnel tracking, or server/client analytics integration with PostHog.
---

# Purpose
計測イベントを一貫して設計する。

# Use when
- 主要イベントを計測する
- Funnel を作る
- feature flag を使う

# Do not use when
- UIだけを直すとき
- DB変更だけをするとき

# Project assumptions
- 重要イベントだけを絞って送る
- PII は最小限にする

# Rules
- イベント名を人間が読める命名にする
- server/client どちらで送るかを決める
- 重要イベントだけを絞って入れる
- PII を安易に送らない

# Workflow
1. 計測したい行動を定義
2. イベント名を決める
3. server/client の送信場所を決める
4. 二重送信を防ぐ

# Checklist
- イベント名が統一されているか
- 二重送信していないか
- 課金や登録完了など主要イベントがあるか

# Common pitfalls
- イベントを増やしすぎる
- 命名がブレる

# Output expectations
- イベント一覧
- 実装箇所
- 計測意図
EOF

cat > "$root/skills/sentry/SKILL.md" <<'EOF'
---
name: sentry
description: Use this skill when adding error monitoring, exception capture, tracing, performance monitoring, or structured production diagnostics with Sentry.
---

# Purpose
本番障害の追跡性を上げる。

# Use when
- エラー監視を入れる
- 例外捕捉を強化する
- tracing を追加する

# Do not use when
- 単純なUI作業だけのとき

# Project assumptions
- PII は最小限
- フロント/サーバー両方で必要箇所を監視

# Rules
- 握りつぶす例外を減らす
- 重要な境界で context を付与する
- PII を不用意に送らない
- フロント/サーバー双方の監視対象を意識する

# Workflow
1. 重要フローを特定
2. 例外捕捉点を決める
3. 文脈情報を整理
4. ノイズを抑える

# Checklist
- 重要処理で例外が捕捉されるか
- user id / org id など最小限の文脈が付くか
- ノイズだらけのログになっていないか

# Common pitfalls
- なんでも送ってノイズ化する
- 文脈が足りず調査不能になる

# Output expectations
- 監視対象
- 例外捕捉箇所
- 文脈情報
EOF

cat > "$root/skills/r2/SKILL.md" <<'EOF'
---
name: r2
description: Use this skill for file upload flows, signed URL generation, object key design, metadata handling, and Cloudflare R2-backed storage patterns.
---

# Purpose
ファイル保存を DB ではなく R2 に安全に寄せる。

# Use when
- ファイルアップロードを実装する
- signed URL を扱う
- metadata 設計をする

# Do not use when
- DB設計のみをする
- UIだけを触るとき

# Project assumptions
- バイナリはR2
- メタデータはDB

# Rules
- バイナリ本体を PostgreSQL に保存しない
- object key 命名規則を統一する
- 公開/非公開アクセス方針を先に決める
- メタデータはDBに保持する

# Workflow
1. アクセス方針を決める
2. key 設計を決める
3. upload と metadata 保存を分ける
4. 削除整合を確認する

# Checklist
- key 設計が衝突しないか
- アクセス制御があるか
- 削除時に DB と Storage の整合がとれるか

# Common pitfalls
- DBにバイナリ保存する
- key が雑で衝突する

# Output expectations
- key 設計
- upload フロー
- metadata モデル
EOF

cat > "$root/skills/fastapi/SKILL.md" <<'EOF'
---
name: fastapi
description: Use this skill only for Python-required backend workloads such as AI pipelines, batch jobs, heavy processing, or Python-native integrations exposed through FastAPI.
---

# Purpose
FastAPI を必要最小限に保つ。

# Use when
- Pythonライブラリ必須
- AI処理
- 重い非同期処理
- バッチ/ワーカーAPI

# Do not use when
- 単純CRUD
- 認証付き通常画面API
- Next.js で十分な処理

# Project assumptions
- FastAPI は補助的 backend
- 主 backend は Next.js 側

# Rules
- FastAPI を万能バックエンドにしない
- 公開境界と内部境界を明確にする
- 認証・署名・レート制限を意識する
- Next.js 側と責務を分ける

# Workflow
1. Python が本当に必要か確認
2. 入出力境界を定義
3. 認証と制限を定義
4. Next.js 側との責務を固定

# Checklist
- 本当に Python が必要か
- 同じ処理を Next.js に置けないか
- 入出力スキーマが定義されているか

# Common pitfalls
- 何でも FastAPI に逃がす
- 境界が曖昧

# Output expectations
- FastAPI 側で持つ責務
- API 入出力
- Next.js との境界
EOF

cat > "$root/skills/api-security/SKILL.md" <<'EOF'
---
name: api-security
description: Use this skill when building any route handler, webhook, external API integration, internal API boundary, authorization rule, or security-sensitive request flow.
---

# Purpose
API境界の安全性を保つ。

# Use when
- route handler を作る
- webhook を作る
- 外部APIを繋ぐ
- 認可や入力検証が必要

# Do not use when
- UIだけを触るとき

# Project assumptions
- 認証と認可を分ける
- 入力検証は必須

# Rules
- 認証と認可を分けて考える
- webhook は署名検証する
- 入力検証を必須にする
- 秘密情報をログに出さない
- 最小権限で設計する

# Workflow
1. 誰が呼ぶAPIかを定義
2. 入力スキーマを決める
3. 認証と認可を分ける
4. 署名やレート制限要否を確認

# Checklist
- 誰が呼べるAPIか明確か
- 入力バリデーションがあるか
- エラー時に秘密が漏れないか
- rate limit の要否を検討したか

# Common pitfalls
- 認証だけ見て認可を忘れる
- webhook 署名検証を省く

# Output expectations
- セキュリティ境界
- バリデーション
- 保護方式
EOF

cat > "$root/skills/vercel/SKILL.md" <<'EOF'
---
name: vercel
description: Use this skill when configuring deployment, environment variables, preview environments, production settings, domain setup, and Vercel-specific deployment behavior.
---

# Purpose
Vercel への安定デプロイを保つ。

# Use when
- deployment 設定をする
- env var を整理する
- preview / production 差分を調整する
- callback URL や webhook URL を確認する

# Do not use when
- ローカルUI調整だけのとき

# Project assumptions
- Vercel が Next.js の標準デプロイ先
- Preview / Production を分けて考える

# Rules
- 環境変数は整理して管理する
- Preview / Production の差異を意識する
- webhook URL や callback URL の環境差分を確認する
- ビルド時と実行時の差を意識する

# Workflow
1. 必須 env を洗い出す
2. preview / production 差分を確認
3. auth/callback/webhook URL を確認
4. deploy 後の確認項目を回す

# Checklist
- 必須 env が揃っているか
- Preview でも auth/callback が壊れないか
- 本番ドメイン前提の値を直書きしていないか

# Common pitfalls
- callback URL の環境差分を忘れる
- env の入れ忘れ

# Output expectations
- 必須 env 一覧
- deploy 設定
- post-deploy checks
EOF

echo "Bootstrapped $root"


path: scripts/generate_gemini_md.sh
content: #!/usr/bin/env bash
set -euo pipefail

out="${1:-GEMINI.md}"
cat > "$out" <<'EOF'
# Source of truth
1. docs/requirements.md
2. docs/scope.md
3. docs/architecture.md
4. docs/conventions.md
5. docs/decisions/*.md
6. docs/notes/brainstorming.md is reference only

# Stack policy
- Frontend: Next.js App Router
- UI: Tailwind + shadcn/ui
- DB: Neon PostgreSQL
- ORM: Prisma
- Auth: Clerk
- Email: Resend
- Payments: Stripe
- Storage: Cloudflare R2
- Analytics: PostHog
- Error Monitoring: Sentry
- Deploy: Vercel
- Backend: FastAPI only for Python-required workloads

# Backend boundary
- Default backend logic lives in Next.js route handlers or server actions
- FastAPI is only for AI, batch, heavy processing, or Python-specific integrations

# Never do
- Do not duplicate Clerk auth state into Prisma as a full auth system
- Do not treat Stripe success redirect as source of truth; use webhook state
- Do not store uploaded files in PostgreSQL
- Do not add FastAPI endpoints for simple CRUD unless explicitly required
EOF

echo "Wrote $out"


path: scripts/generate_project_docs.sh
content: #!/usr/bin/env bash
set -euo pipefail

if [ "$#" -lt 2 ]; then
  echo "Usage: $0 <project-root> '<project brief>'" >&2
  exit 1
fi

root="$1"
brief="$2"

mkdir -p "$root/docs/notes" "$root/docs/decisions"

./skills/opengemini-nextjs-bestpractice-builder/scripts/generate_gemini_md.sh "$root/GEMINI.md"

gemini -p "Create docs/requirements.md in markdown for a solo-developer SaaS using this stack: Next.js App Router, Tailwind, shadcn/ui, Neon PostgreSQL, Prisma, Clerk, Resend, Stripe, Cloudflare R2, PostHog, Sentry, Vercel, FastAPI only for Python-required workloads. Brief: ${brief}. Include summary, target users, problem, goals, non-goals, MVP scope, monetization, user stories, functional requirements, non-functional requirements, risks, success metrics. Return markdown only." > "$root/docs/requirements.md"

gemini -p "Create docs/scope.md in markdown for this SaaS. Brief: ${brief}. Include in scope, out of scope, MVP milestones, deferred features. Return markdown only." > "$root/docs/scope.md"

gemini -p "Create docs/architecture.md in markdown for this SaaS. Brief: ${brief}. Respect this stack: Next.js App Router, Tailwind, shadcn/ui, Neon PostgreSQL, Prisma, Clerk, Resend, Stripe, Cloudflare R2, PostHog, Sentry, Vercel, FastAPI only for Python-required workloads. Include system overview, Mermaid diagram, frontend architecture, backend architecture, data architecture, auth and billing boundaries, integrations, deployment, open questions. Return markdown only." > "$root/docs/architecture.md"

gemini -p "Create docs/conventions.md in markdown for this SaaS. Brief: ${brief}. Include code style, folder structure, naming, server vs client rules, feature boundaries, testing rules, env var rules, error handling, logging and monitoring. Return markdown only." > "$root/docs/conventions.md"

gemini -p "Create docs/integrations.md in markdown for this SaaS. Brief: ${brief}. Cover Clerk, Stripe, Resend, Cloudflare R2, PostHog, Sentry, Neon, FastAPI, Vercel. Return markdown only." > "$root/docs/integrations.md"

gemini -p "Create docs/db-schema.md in markdown for this SaaS. Brief: ${brief}. Include core models, relationships, billing models, file metadata models, audit and event notes. Respect these rules: do not duplicate Clerk as full auth in Prisma, do not store uploaded files in PostgreSQL, use Stripe webhook state. Return markdown only." > "$root/docs/db-schema.md"

echo "Generated core docs under $root/docs"


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)