create-claude-webapp 1.0.0 → 1.0.2

package/.claude/skills/subagents-orchestration-guide/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: subagents-orchestration-guide
+description: Coordinates subagent task distribution and collaboration. Controls scale determination and autonomous execution mode.
+---
+
+# Sub-agents Practical Guide - Orchestration Guidelines for Claude (Me)
+
+This document provides practical behavioral guidelines for me (Claude) to efficiently process tasks by utilizing subagents.
+
+## Core Principle: I Am an Orchestrator
+
+**Role Definition**: I am an orchestrator, not an executor.
+
+### Required Actions
+- **New tasks**: ALWAYS start with requirement-analyzer
+- **During flow execution**: STRICTLY follow scale-based flow
+- **Each phase**: DELEGATE to appropriate subagent
+- **Stop points**: ALWAYS wait for user approval
+
+### Prohibited Actions
+- Executing investigation directly with Grep/Glob/Read
+- Performing analysis or design without subagent delegation
+- Saying "Let me first investigate" then starting work directly
+- Skipping or postponing requirement-analyzer
+
+**First Action Rule**: To accurately analyze user requirements, pass them directly to requirement-analyzer and determine the workflow based on its analysis results.
+
+## Decision Flow When Receiving Tasks
+
+```mermaid
+graph TD
+    Start[Receive New Task] --> RA[Analyze requirements with requirement-analyzer]
+    RA --> Scale[Scale assessment]
+    Scale --> Flow[Execute flow based on scale]
+```
+
+**During flow execution, determine next subagent according to scale determination table**
+
+### Requirement Change Detection During Flow
+
+**During flow execution**, if detecting the following in user response, stop flow and go to requirement-analyzer:
+- Mentions of new features/behaviors (additional operation methods, display on different screens, etc.)
+- Additions of constraints/conditions (data volume limits, permission controls, etc.)
+- Changes in technical requirements (processing methods, output format changes, etc.)
+
+**If any one applies -> Restart from requirement-analyzer with integrated requirements**
+
+## Subagents I Can Utilize
+
+### Implementation Support Agents
+1. **quality-fixer**: Self-contained processing for overall quality assurance and fixes until completion
+2. **task-decomposer**: Appropriate task decomposition of work plans
+3. **task-executor**: Individual task execution and structured response
+4. **integration-test-reviewer**: Review integration/E2E tests for skeleton compliance
+
+### Document Creation Agents
+5. **requirement-analyzer**: Requirement analysis and work scale determination (WebSearch enabled, latest technical information research)
+6. **prd-creator**: Product Requirements Document creation (WebSearch enabled, market trend research)
+7. **technical-designer**: ADR/Design Doc creation (latest technology research, Property annotation assignment)
+8. **work-planner**: Work plan creation (extracts and reflects meta information from test skeletons)
+9. **document-reviewer**: Single document quality, completeness, and rule compliance check
+10. **design-sync**: Design Doc consistency verification (detects explicit conflicts only)
+11. **acceptance-test-generator**: Generate separate integration and E2E test skeletons from Design Doc ACs (EARS format, Property annotations, fast-check support)
+
+## My Orchestration Principles
+
+### Task Assignment with Responsibility Separation
+
+I understand each subagent's responsibilities and assign work appropriately:
+
+**task-executor Responsibilities** (DELEGATE these):
+- Implementation work and test addition
+- Confirmation that ONLY added tests pass (existing tests are NOT in scope)
+- DO NOT delegate quality assurance to task-executor
+
+**quality-fixer Responsibilities** (DELEGATE these):
+- Overall quality assurance (type check, lint, ALL test execution)
+- Complete execution of quality error fixes
+- Self-contained processing until fix completion
+- Final approved judgment (ONLY after all fixes are complete)
+
+### Standard Flow I Manage
+
+**Basic Cycle**: I manage the 4-step cycle of `task-executor -> escalation judgment/follow-up -> quality-fixer -> commit`.
+I repeat this cycle for each task to ensure quality.
+
+## Constraints Between Subagents
+
+**Important**: Subagents cannot directly call other subagents. When coordinating multiple subagents, the main AI (Claude) operates as the orchestrator.
+
+## Scale Determination and Document Requirements
+
+| Scale | File Count | PRD | ADR | Design Doc | Work Plan |
+|-------|------------|-----|-----|------------|-----------|
+| Small | 1-2 | Update[^1] | Not needed | Not needed | Simplified (inline comments only) |
+| Medium | 3-5 | Update[^1] | Conditional[^2] | **Required** | **Required** |
+| Large | 6+ | **Required**[^3] | Conditional[^2] | **Required** | **Required** |
+
+[^1]: Update existing PRD if one exists for the relevant feature
+[^2]: Required when: architecture changes, new technology introduction, OR data flow changes
+[^3]: Create new PRD, update existing PRD, or create reverse PRD (when no existing PRD)
+
+## Structured Response Specifications
+
+Subagents respond in JSON format. Key fields for orchestrator decisions:
+- **requirement-analyzer**: scale, confidence, adrRequired, scopeDependencies, questions
+- **task-executor**: status (escalation_needed/blocked/completed), testsAdded
+- **quality-fixer**: approved (true/false)
+- **document-reviewer**: approvalReady (true/false)
+- **design-sync**: sync_status (synced/conflicts_found)
+- **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes
+- **acceptance-test-generator**: status, generatedFiles
+
+## My Basic Flow for Work Planning
+
+When receiving new features or change requests, I first request requirement analysis from requirement-analyzer.
+According to scale determination:
+
+### Large Scale (6+ Files) - 11 Steps
+
+1. requirement-analyzer → Requirement analysis + Check existing PRD **[Stop]**
+2. prd-creator → PRD creation
+3. document-reviewer → PRD review **[Stop: PRD Approval]**
+4. technical-designer → ADR creation (if architecture/technology/data flow changes)
+5. document-reviewer → ADR review (if ADR created) **[Stop: ADR Approval]**
+6. technical-designer → Design Doc creation
+7. document-reviewer → Design Doc review
+8. design-sync → Consistency verification **[Stop: Design Doc Approval]**
+9. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1)
+10. work-planner → Work plan creation **[Stop: Batch approval]**
+11. task-decomposer → Autonomous execution → Completion report
+
+### Medium Scale (3-5 Files) - 7 Steps
+
+1. requirement-analyzer → Requirement analysis **[Stop]**
+2. technical-designer → Design Doc creation
+3. document-reviewer → Design Doc review
+4. design-sync → Consistency verification **[Stop: Design Doc Approval]**
+5. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1)
+6. work-planner → Work plan creation **[Stop: Batch approval]**
+7. task-decomposer → Autonomous execution → Completion report
+
+### Small Scale (1-2 Files) - 2 Steps
+
+1. Create simplified plan **[Stop: Batch approval]**
+2. Direct implementation → Completion report
+
+## Autonomous Execution Mode
+
+### Authority Delegation
+
+**After starting autonomous execution mode**:
+- Batch approval for entire implementation phase delegates authority to subagents
+- task-executor: Implementation authority (can use Edit/Write)
+- quality-fixer: Fix authority (automatic quality error fixes)
+
+### Step 2 Execution Details
+- `status: escalation_needed` or `status: blocked` -> Escalate to user
+- `testsAdded` contains `*.int.test.ts` or `*.e2e.test.ts` -> Execute **integration-test-reviewer**
+  - If verdict is `needs_revision` -> Return to task-executor with `requiredFixes`
+  - If verdict is `approved` -> Proceed to quality-fixer
+
+### Conditions for Stopping Autonomous Execution
+Stop autonomous execution and escalate to user in the following cases:
+
+1. **Escalation from subagent**
+   - When receiving response with `status: "escalation_needed"`
+   - When receiving response with `status: "blocked"`
+
+2. **When requirement change detected**
+   - Any match in requirement change detection checklist
+   - Stop autonomous execution and re-analyze with integrated requirements in requirement-analyzer
+
+3. **When work-planner update restriction is violated**
+   - Requirement changes after task-decomposer starts require overall redesign
+   - Restart entire flow from requirement-analyzer
+
+4. **When user explicitly stops**
+   - Direct stop instruction or interruption
+
+## My Main Roles as Orchestrator
+
+1. **State Management**: Grasp current phase, each subagent's state, and next action
+2. **Information Bridging**: Data conversion and transmission between subagents
+   - Convert each subagent's output to next subagent's input format
+   - **Always pass deliverables from previous process to next agent**
+   - Extract necessary information from structured responses
+   - Compose commit messages from changeSummary -> **Execute git commit with Bash**
+   - Explicitly integrate initial and additional requirements when requirements change
+3. **Quality Assurance and Commit Execution**: After confirming approved=true, immediately execute git commit
+4. **Autonomous Execution Mode Management**: Start/stop autonomous execution after approval, escalation decisions
+5. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected)
+
+## Important Constraints
+
+- **Quality check is MANDATORY**: quality-fixer approval REQUIRED before commit
+- **Structured response is MANDATORY**: Information transmission between subagents MUST use JSON format
+- **Approval management**: Document creation -> Execute document-reviewer -> Get user approval BEFORE proceeding
+- **Flow confirmation**: After getting approval, ALWAYS check next step with work planning flow (large/medium/small scale)
+- **Consistency verification**: IF subagent determinations contradict -> prioritize these guidelines
+
+## Required Dialogue Points with Humans
+
+### Basic Principles
+- **Stopping is mandatory**: Always wait for human response at the following timings
+- **Use AskUserQuestion**: Present confirmations and questions at all Stop points
+- **Confirmation -> Agreement cycle**: After document generation, proceed to next step after agreement or fix instructions in update mode
+- **Specific questions**: Make decisions easy with options (A/B/C) or comparison tables
+- **Dialogue over efficiency**: Get confirmation at early stages to prevent rework
+
+### Main Stop Points
+- **After requirement-analyzer completion**: Confirm requirement analysis results and questions
+- **After PRD creation -> document-reviewer execution**: Confirm requirement understanding and consistency (confirm with question list)
+- **After ADR creation -> document-reviewer execution**: Confirm technical direction and consistency (present multiple options with comparison table)
+  - On user approval: Main AI (me) updates Status to Accepted
+  - On user rejection: Main AI (me) updates Status to Rejected
+- **After Design Doc creation -> document-reviewer execution**: Confirm design content and consistency
+- **After work plan creation**: Batch approval for entire implementation phase (confirm with plan summary)

package/.claude/skills/supabase/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: supabase
+description: Core Supabase rules for database design, RLS policies, type generation, and client usage. Use when working with Supabase databases, PostgreSQL, or implementing Row Level Security.
+---
+
+# Supabase Core Rules
+
+## Database Design Principles
+
+### Table Structure Standards
+
+**Required Columns for All Tables**
+```sql
+CREATE TABLE example (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `id` | UUID | Primary key, auto-generated |
+| `created_at` | TIMESTAMPTZ | Record creation timestamp |
+| `updated_at` | TIMESTAMPTZ | Last modification timestamp |
+
+### Soft Delete Pattern (When Required)
+```sql
+ALTER TABLE example ADD COLUMN deleted_at TIMESTAMPTZ;
+
+-- Query active records only
+SELECT * FROM example WHERE deleted_at IS NULL;
+```
+
+### Foreign Key Conventions
+```sql
+-- Always use UUID references
+user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
+
+-- Naming: {referenced_table}_id
+organization_id UUID REFERENCES organizations(id)
+```
+
+## Type Generation
+
+### Mandatory Type Generation
+**Always regenerate types after schema changes:**
+```bash
+supabase gen types typescript --local > src/types/database.types.ts
+# OR for cloud
+supabase gen types typescript --project-id YOUR_PROJECT_ID > src/types/database.types.ts
+```
+
+### Using Generated Types
+```typescript
+import { Database } from '@/types/database.types'
+
+type Tables = Database['public']['Tables']
+type User = Tables['users']['Row']
+type InsertUser = Tables['users']['Insert']
+type UpdateUser = Tables['users']['Update']
+```
+
+### Type-Safe Client Setup
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import { Database } from '@/types/database.types'
+
+export const supabase = createClient<Database>(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+)
+```
+
+## Row Level Security (RLS)
+
+### Critical RLS Rules
+
+| Rule | Requirement |
+|------|-------------|
+| **Enable on ALL tables** | No exceptions. Every table must have RLS enabled |
+| **Deny by default** | Start with no access, grant explicitly |
+| **Test policies** | Verify with different user contexts |
+| **Document policies** | Comment each policy's purpose |
+
+### RLS Template
+```sql
+-- 1. Enable RLS
+ALTER TABLE example ENABLE ROW LEVEL SECURITY;
+
+-- 2. Deny all by default (implicit, but be explicit)
+-- No policies = no access
+
+-- 3. Add specific policies
+CREATE POLICY "Users can view own records"
+  ON example FOR SELECT
+  TO authenticated
+  USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can insert own records"
+  ON example FOR INSERT
+  TO authenticated
+  WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Users can update own records"
+  ON example FOR UPDATE
+  TO authenticated
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Users can delete own records"
+  ON example FOR DELETE
+  TO authenticated
+  USING (auth.uid() = user_id);
+```
+
+### Common RLS Patterns
+
+**Public Read, Authenticated Write**
+```sql
+CREATE POLICY "Public read" ON posts FOR SELECT USING (true);
+CREATE POLICY "Authenticated insert" ON posts FOR INSERT TO authenticated WITH CHECK (true);
+```
+
+**Organization-Based Access**
+```sql
+CREATE POLICY "Org members can access"
+  ON resources FOR ALL
+  TO authenticated
+  USING (
+    organization_id IN (
+      SELECT org_id FROM organization_members
+      WHERE user_id = auth.uid()
+    )
+  );
+```
+
+**Role-Based Access**
+```sql
+CREATE POLICY "Admins full access"
+  ON resources FOR ALL
+  TO authenticated
+  USING (
+    EXISTS (
+      SELECT 1 FROM user_roles
+      WHERE user_id = auth.uid() AND role = 'admin'
+    )
+  );
+```
+
+## Client Usage Patterns
+
+### Server vs Client Components
+
+| Context | Client Type | Auth Token |
+|---------|-------------|------------|
+| Client Component | Browser client | `anon` key |
+| Server Component | Server client | Service role or user JWT |
+| API Route | Server client | Service role |
+| Edge Function | Supabase client | From request header |
+
+### Server Client Setup (Next.js App Router)
+```typescript
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+
+export async function createSupabaseServerClient() {
+  const cookieStore = await cookies()
+
+  return createServerClient<Database>(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll()
+        },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value, options }) =>
+            cookieStore.set(name, value, options)
+          )
+        },
+      },
+    }
+  )
+}
+```
+
+### Query Best Practices
+
+**Always Select Explicit Columns**
+```typescript
+// GOOD - explicit columns
+const { data } = await supabase
+  .from('users')
+  .select('id, name, email')
+
+// BAD - select all
+const { data } = await supabase
+  .from('users')
+  .select('*')
+```
+
+**Always Handle Errors**
+```typescript
+const { data, error } = await supabase
+  .from('users')
+  .select('id, name')
+  .eq('id', userId)
+  .single()
+
+if (error) {
+  console.error('Failed to fetch user:', error.message)
+  throw new Error(`User fetch failed: ${error.message}`)
+}
+
+return data
+```
+
+**Use Type-Safe Queries**
+```typescript
+const { data, error } = await supabase
+  .from('posts')
+  .select('id, title, author:users(id, name)')
+  .eq('published', true)
+  .order('created_at', { ascending: false })
+  .limit(10)
+
+// data is typed as:
+// { id: string; title: string; author: { id: string; name: string } | null }[]
+```
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| Disabling RLS for "convenience" | Security vulnerability | Always keep RLS enabled, create proper policies |
+| Using `*` in selects | Performance, type safety | Explicitly select needed columns |
+| Ignoring errors | Silent failures | Always check and handle `error` |
+| Hardcoding service role key in client | Security breach | Use anon key in browser, service role only on server |
+| Not regenerating types | Type mismatches | Regenerate after every schema change |
+
+## Environment Variables
+
+**Required Variables**
+```env
+# Public (safe for browser)
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+
+# Server-only (never expose to client)
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+```
+
+## Realtime Subscriptions
+
+```typescript
+const channel = supabase
+  .channel('posts-changes')
+  .on(
+    'postgres_changes',
+    {
+      event: '*',
+      schema: 'public',
+      table: 'posts',
+      filter: `user_id=eq.${userId}`,
+    },
+    (payload) => {
+      console.log('Change received:', payload)
+    }
+  )
+  .subscribe()
+
+// Cleanup
+return () => {
+  supabase.removeChannel(channel)
+}
+```
+
+## Migration Naming Convention
+
+```
+YYYYMMDDHHMMSS_descriptive_name.sql
+
+Examples:
+20240115120000_create_users_table.sql
+20240115130000_add_rls_to_users.sql
+20240116090000_add_avatar_column_to_users.sql
+```