@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/commands/do/sync-code-review.md

@@ -0,0 +1,117 @@
+---
+description: "Sync with GitHub PR code review: evaluate, fix, and respond"
+---
+
+# /do:sync-code-review
+
+**PR URL or Number:** {{{ input }}}
+
+---
+
+## Related Skills
+
+See `.claude/skills/github/SKILL.md` for general GitHub workflow patterns (branches, commits, PRs).
+
+---
+
+## Quick Reference
+
+### Workflow
+
+1. **Fetch PR** → `gh pr view <number> --json comments,headRefName`
+2. **Check for review** → Look for @claude code review comment
+3. **If no review** → Comment `@claude` and poll for response (30s intervals, max 5min)
+4. **Checkout branch** → `git checkout <headRefName>`
+5. **Evaluate issues** → ACCEPT / PARTIAL / DEFER / REJECT
+6. **Implement fixes** → For ACCEPT and PARTIAL issues
+7. **Verify** → `pnpm build`
+8. **Commit & push** → With structured message
+9. **Comment on PR** → With response table
+10. **Request re-review** → Comment `@claude` again to validate fixes
+
+### Evaluation Criteria
+
+| Action | When to Use |
+|--------|-------------|
+| **ACCEPT** | Issue is valid, fix as suggested |
+| **PARTIAL** | Issue is valid, will fix differently |
+| **DEFER** | Valid but out of scope |
+| **REJECT** | Based on incorrect assumption or intentional design |
+
+### Evaluation Process
+
+1. **Read the code review carefully** - Identify all reported issues (vulnerabilities, race conditions, bugs, style issues, etc.)
+2. **Perform your own analysis** - For each issue, verify if it's correctly reported:
+   - Is the issue real or a false positive?
+   - Does the suggested fix make sense?
+   - Are there better alternatives?
+3. **Prioritize by severity** - Critical (security/data loss) > Medium (bugs) > Minor (style)
+4. **Decide action for each** - ACCEPT, PARTIAL, DEFER, or REJECT with reasoning
+
+### Response Format
+
+```markdown
+## Code Review Response
+
+### Changes Implemented
+
+| Issue | Severity | Status | Details |
+|-------|----------|--------|---------|
+| <title> | Critical/Medium/Minor | ✅ Fixed / ⏭️ Deferred / ❌ Won't Fix | <details> |
+
+### Explanation for Deferred/Rejected Issues
+
+> For each DEFER or REJECT, explain your reasoning to reach agreement with the reviewer.
+
+<explanations>
+
+### Verification
+
+- [x] All accepted issues addressed
+- [x] Build passes
+- [x] Ready for re-review
+
+---
+Co-Authored-By: Claude Code <noreply@anthropic.com>
+```
+
+### Commands
+
+```bash
+# Fetch PR data
+gh pr view <number> --repo <owner/repo> --json number,title,comments,headRefName
+
+# Request code review
+gh pr comment <number> --body "@claude"
+
+# Poll for review response (30s intervals, max 5min)
+for i in {1..10}; do
+  REVIEW=$(gh pr view <number> --json comments --jq '.comments[-1].body' | grep -i "code review complete")
+  if [ -n "$REVIEW" ]; then
+    echo "Review received"
+    break
+  fi
+  echo "Waiting for review... ($i/10)"
+  sleep 30
+done
+
+# Commit with attribution
+git commit -m "fix: address code review feedback for PR #<number>
+
+Co-Authored-By: Claude Code <noreply@anthropic.com>"
+
+# Comment response
+gh pr comment <number> --body "<response>"
+
+# Request re-review after fixes
+gh pr comment <number> --body "@claude"
+```
+
+---
+
+## Example
+
+```bash
+/do:sync-code-review https://github.com/NextSpark-js/nextspark/pull/19
+/do:sync-code-review 19
+```

package/claude/commands/do/update-selectors.md

@@ -0,0 +1,112 @@
+---
+description: "Synchronize selectors between components, core definitions, and POM classes"
+---
+
+# do:update-selectors
+
+**Context:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skills First
+
+Read these skills completely before proceeding:
+
+1. `.claude/skills/cypress-selectors/SKILL.md` - 3-level selector system
+
+---
+
+## Selector Architecture
+
+The selector system has THREE layers:
+
+1. **CORE_SELECTORS** - `packages/core/src/lib/selectors/` (source of truth)
+2. **BLOCK_SELECTORS** - Theme block selectors
+3. **THEME_SELECTORS** - Theme-specific UI selectors
+
+---
+
+## Common Sync Issues
+
+### 1. Selector Used but Not Defined
+
+**Symptom:** Console warning `[sel] Invalid selector path: "..."`
+
+**Fix:**
+1. Find usage in component: `grep -rn "sel('...')" packages/core/src/`
+2. Add to appropriate domain file in `packages/core/src/lib/selectors/domains/`
+3. Rebuild to regenerate types
+
+### 2. Hardcoded Selector in Component
+
+**Symptom:** `document.querySelector('[data-cy="..."]')` instead of using `sel()`
+
+**Fix:**
+```diff
+- document.querySelector(`[data-cy="preview-block-${id}"]`)
++ document.querySelector(`[data-cy="${sel('blockEditor.previewCanvas.block', { id })}"]`)
+```
+
+### 3. Hardcoded Selector in POM
+
+**Symptom:** Direct string selectors instead of `cySelector()`
+
+**Fix:**
+```diff
+- moveUpBtn: (id: string) => `[data-cy="preview-block-${id}-move-up"]`,
++ moveUpBtn: (id: string) => cySelector('blockEditor.previewCanvas.moveUp', { id }),
+```
+
+**Note:** Generic selectors for prefix matching MUST keep the bracket format:
+```ts
+sortableBlockGeneric: '[data-cy^="sortable-block-"]',  // OK - needed for prefix matching
+```
+
+---
+
+## Files to Check
+
+| Layer | File Pattern |
+|-------|--------------|
+| Core Selectors | `packages/core/src/lib/selectors/domains/*.selectors.ts` |
+| Component Usage | `packages/core/src/components/**/*.tsx` |
+| POM Classes | `themes/*/tests/cypress/src/core/*POM.ts` |
+| POM Presets | `packages/core/templates/contents/themes/starter/tests/cypress/src/core/*POM.ts` |
+
+---
+
+## Sync Workflow
+
+1. **Find undefined selectors:**
+   ```bash
+   pnpm build 2>&1 | grep -i "selector"
+   ```
+
+2. **Find hardcoded selectors in POMs:**
+   ```bash
+   grep -n "data-cy=" themes/default/tests/cypress/src/core/*.ts
+   ```
+
+3. **Find hardcoded selectors in components:**
+   ```bash
+   grep -rn 'data-cy="' packages/core/src/components/ --include="*.tsx"
+   ```
+
+4. **After sync, update presets:**
+   - `packages/core/templates/contents/themes/starter/tests/cypress/src/core/`
+   - `packages/core/templates/contents/themes/starter/tests/cypress/src/core/`
+
+---
+
+## Verification
+
+```bash
+# Build without errors
+pnpm build
+
+# No invalid selector warnings in browser console
+# Navigate to affected pages and check DevTools console
+
+# Grep should show only defined properties, not method bodies with hardcoded strings
+grep -n "data-cy=" themes/default/tests/cypress/src/core/BlockEditorBasePOM.ts
+```

package/claude/commands/do/use-skills.md

@@ -0,0 +1,90 @@
+---
+description: "Read and apply relevant skills for the requested task"
+---
+
+# do:use-skills
+
+**Task:** {{{ input }}}
+
+---
+
+## Protocol
+
+This command enforces the use of skills for any development task.
+
+### Step 1: Read Skills Index
+
+**MANDATORY:** Read `.claude/skills/README.md` to understand all available skills.
+
+The README contains:
+- Complete list of 44+ skills
+- Categories and descriptions
+- Mapping of tasks → skills
+
+### Step 2: Identify Relevant Skills
+
+Based on the task keywords, identify which skills apply:
+
+| Task Keywords | Relevant Skills |
+|---------------|-----------------|
+| entity, crud, model | `entity-system` |
+| migration, sql, database | `database-migrations` |
+| api, endpoint, route | `nextjs-api-development`, `entity-api` |
+| scheduled, background, webhook | `scheduled-actions` |
+| theme, styling, css | `create-theme`, `tailwind-theming` |
+| plugin, extension | `create-plugin`, `plugins` |
+| block, page-builder | `page-builder-blocks`, `block-decision-matrix` |
+| test, cypress, e2e | `cypress-e2e`, `cypress-api`, `pom-patterns` |
+| auth, login, session | `better-auth`, `permissions-system` |
+| component, ui | `shadcn-components`, `react-patterns` |
+| i18n, translation | `i18n-nextintl` |
+
+### Step 3: Read Each Relevant Skill
+
+For each identified skill, read the complete SKILL.md:
+
+```
+.claude/skills/{skill-name}/SKILL.md
+```
+
+### Step 4: Check for Scripts
+
+Many skills include automation scripts:
+
+```bash
+ls .claude/skills/{skill-name}/scripts/
+```
+
+Use scripts when available to automate tasks.
+
+### Step 5: Apply Patterns
+
+Execute the task following:
+- Conventions documented in the skill
+- Code patterns and templates
+- Directory structure requirements
+
+### Step 6: Validate
+
+Use the skill's checklist (usually at the end of SKILL.md) to verify compliance.
+
+---
+
+## Example Usage
+
+**Task:** "Create a new products entity"
+
+1. Read `.claude/skills/README.md`
+2. Identify: `entity-system`, `database-migrations`
+3. Read both SKILL.md files
+4. Check for scripts in `entity-system/scripts/`
+5. Execute following documented patterns
+6. Validate using checklists
+
+---
+
+## Important
+
+- **ALWAYS** read the skill before implementing
+- **NEVER** skip the checklist validation
+- Skills contain project-specific conventions that must be followed

package/claude/commands/do/validate-blocks.md

@@ -0,0 +1,69 @@
+---
+description: "Validate page builder blocks"
+---
+
+# do:validate-blocks
+
+**Block or Context:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skills First
+
+Read these skills completely before proceeding:
+
+1. `.claude/skills/page-builder-blocks/SKILL.md` - Block development
+2. `.claude/skills/block-decision-matrix/SKILL.md` - Block decisions
+
+---
+
+## Block Structure
+
+Each block must have:
+
+```
+contents/themes/{theme}/blocks/{block-name}/
+├── config.ts       # Block configuration
+├── schema.ts       # Zod validation schema
+├── fields.ts       # Field definitions
+├── component.tsx   # React component
+└── index.ts        # Exports
+```
+
+---
+
+## Validation Checklist
+
+- [ ] All 5 required files exist
+- [ ] `config.ts` has correct metadata
+- [ ] `schema.ts` validates all fields
+- [ ] `component.tsx` has `data-cy` attributes
+- [ ] Block appears in BLOCK_REGISTRY
+
+---
+
+## Registry Check
+
+```bash
+# Rebuild registry
+node core/scripts/build/registry.mjs
+
+# Verify block is registered
+grep "{block-name}" core/lib/registries/block-registry.ts
+```
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Block not in registry | Run registry rebuild |
+| Schema validation fails | Check Zod schema matches fields |
+| Component not rendering | Check exports in index.ts |
+
+---
+
+## Verification
+
+Use the checklist from `page-builder-blocks/SKILL.md` to verify compliance.

package/claude/commands/how-to/README.md

@@ -0,0 +1,261 @@
+# /how-to:* Commands
+
+Interactive guided tutorials for NextSpark core functionalities.
+
+---
+
+## Philosophy
+
+These commands follow a **guided learning approach**:
+
+1. **Step-by-step instructions** - Claude guides you through each step
+2. **Interactive Q&A** - Ask questions at any point during the tutorial
+3. **Hands-on practice** - Apply concepts to your actual project
+4. **Validation** - Claude validates your implementation as you go
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /how-to:{topic}                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Introduction                                                │
+│     - Brief explanation of the concept                         │
+│     - What you'll learn                                        │
+│     - Prerequisites check                                      │
+│     ↓                                                           │
+│  2. Step-by-Step Guide                                          │
+│     - Each step explained clearly                              │
+│     - Code examples and patterns                               │
+│     - Pause after each step for questions                      │
+│     ↓                                                           │
+│  3. Interactive Implementation                                  │
+│     - Apply to your project                                    │
+│     - Claude validates your work                               │
+│     ↓                                                           │
+│  4. Summary & Next Steps                                        │
+│     - Recap what you learned                                   │
+│     - Related tutorials                                        │
+│     - Best practices reminder                                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Available Commands
+
+### Getting Started
+
+| Command | Description |
+|---------|-------------|
+| `/how-to:start` | **Main index** - Starting point for all tutorials |
+
+### Configuration & Setup
+
+| Command | Description |
+|---------|-------------|
+| `/how-to:setup-claude-code` | **First step** - Configure AI workflow system |
+| `/how-to:setup-database` | Configure PostgreSQL, run migrations |
+| `/how-to:setup-authentication` | Configure Better Auth, OAuth providers |
+| `/how-to:setup-email-providers` | Configure email sending providers |
+| `/how-to:set-app-languages` | Configure supported languages and i18n |
+
+### Entities & Database
+
+| Command | Description |
+|---------|-------------|
+| `/how-to:create-entity` | Create a new entity with full CRUD |
+| `/how-to:create-migrations` | Write database migrations with RLS |
+| `/how-to:create-api` | Create custom API endpoints |
+
+### Page Builder & Blocks
+
+| Command | Description |
+|---------|-------------|
+| `/how-to:create-block` | Create page builder blocks |
+
+### Permissions & Billing
+
+| Command | Description |
+|---------|-------------|
+| `/how-to:set-plans-and-permissions` | Configure subscription plans and features |
+| `/how-to:set-user-roles-and-permissions` | Configure team roles and RBAC |
+
+### Plugins & Extensions
+
+| Command | Description |
+|---------|-------------|
+| `/how-to:create-plugin` | Create a new plugin from scratch |
+| `/how-to:install-plugins` | Install and configure plugins |
+| `/how-to:set-scheduled-actions` | Configure background tasks and cron jobs |
+
+### Customization
+
+| Command | Description |
+|---------|-------------|
+| `/how-to:customize-theme` | Customize design system and styles |
+| `/how-to:customize-dashboard` | Customize dashboard layout and navigation |
+| `/how-to:customize-app` | App-level customizations and settings |
+
+### Testing & Deployment
+
+| Command | Description |
+|---------|-------------|
+| `/how-to:add-translations` | Add translations for your content |
+| `/how-to:run-tests` | Run Cypress API and E2E tests |
+| `/how-to:deploy` | Deploy to production |
+
+---
+
+## Interaction Pattern
+
+During any how-to tutorial, Claude will:
+
+1. **Show the current step** with clear instructions
+2. **Wait for your confirmation** or questions
+3. **Validate your implementation** when requested
+4. **Answer questions** at any point
+
+### Response Options at Each Step
+
+```
+📚 STEP 2 OF 5: Create the Entity Configuration
+
+[Instructions for this step...]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What would you like to do?
+
+[1] Continue to next step
+[2] See code example
+[3] I have a question
+[4] Apply this to my project now
+[5] Skip this step
+[6] Exit tutorial
+```
+
+---
+
+## Example Session
+
+```
+> /how-to:create-entity
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📚 HOW TO: CREATE AN ENTITY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Welcome! This tutorial will guide you through creating
+a new entity in NextSpark with full CRUD capabilities.
+
+📋 What you'll learn:
+   • Entity configuration structure
+   • Database migration with RLS
+   • Automatic API generation
+   • Dashboard integration
+
+⏱️  Estimated time: 15-20 minutes
+
+Prerequisites:
+   ✓ NextSpark project set up
+   ✓ Database running
+   ✓ Active theme configured
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Ready to begin? What entity would you like to create?
+
+> Products entity with name, price, and category
+
+Great! Let's create the Products entity. Starting with Step 1...
+```
+
+---
+
+## Command Standards
+
+Each how-to command follows these conventions:
+
+### 1. Clear Step Numbers
+
+Every step is numbered (STEP 1 OF N) so users know their progress.
+
+### 2. Interactive Checkpoints
+
+After each major step, Claude asks the user to confirm understanding or if they have questions.
+
+### 3. Code Validation
+
+When users implement code, Claude offers to validate their implementation.
+
+### 4. Related Skills
+
+Each tutorial references related skills for deeper learning.
+
+### 5. Exit Gracefully
+
+Users can exit at any point. Progress context is preserved for the session.
+
+---
+
+## Naming Convention
+
+```
+how-to:  (prefix) → TUTORIAL command namespace
+
+   /how-to:create-entity    → "create entity" tutorial
+   /how-to:setup-database   → "setup database" tutorial
+
+-  (hyphen) → COMPOUND WORD separator
+
+   /how-to:set-app-languages     → "set app languages"
+   /how-to:customize-dashboard   → "customize dashboard"
+```
+
+---
+
+## Command Files
+
+- [start.md](./start.md) - Main index
+- [setup-claude-code.md](./setup-claude-code.md) - AI workflow configuration (FIRST STEP)
+- [setup-database.md](./setup-database.md) - Database setup
+- [setup-authentication.md](./setup-authentication.md) - Auth setup
+- [setup-email-providers.md](./setup-email-providers.md) - Email providers
+- [set-app-languages.md](./set-app-languages.md) - i18n setup
+- [create-entity.md](./create-entity.md) - Entity creation
+- [create-migrations.md](./create-migrations.md) - Database migrations
+- [create-api.md](./create-api.md) - API endpoints
+- [create-block.md](./create-block.md) - Block development
+- [create-plugin.md](./create-plugin.md) - Plugin development
+- [create-child-entities.md](./create-child-entities.md) - Child entities
+- [add-metadata.md](./add-metadata.md) - Metadata system
+- [add-taxonomies.md](./add-taxonomies.md) - Tags and categories
+- [add-translations.md](./add-translations.md) - Translations
+- [set-plans-and-permissions.md](./set-plans-and-permissions.md) - Billing & plans
+- [set-user-roles-and-permissions.md](./set-user-roles-and-permissions.md) - RBAC
+- [set-scheduled-actions.md](./set-scheduled-actions.md) - Background jobs
+- [install-plugins.md](./install-plugins.md) - Plugin installation
+- [customize-theme.md](./customize-theme.md) - Theme customization
+- [customize-dashboard.md](./customize-dashboard.md) - Dashboard customization
+- [customize-app.md](./customize-app.md) - App customization
+- [define-features-flows.md](./define-features-flows.md) - Feature registry
+- [manage-test-coverage.md](./manage-test-coverage.md) - Test coverage
+- [run-tests.md](./run-tests.md) - Testing
+- [deploy.md](./deploy.md) - Deployment
+- [use-superadmin.md](./use-superadmin.md) - Superadmin panel
+- [use-devtools.md](./use-devtools.md) - Developer tools
+- [handle-file-uploads.md](./handle-file-uploads.md) - File uploads
+- [implement-search.md](./implement-search.md) - Search implementation
+
+---
+
+## Related
+
+- `/session:*` - Development session commands
+- `.claude/skills/` - Detailed technical knowledge
+- `docs/` - Project documentation