@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/commands/do/README.md

@@ -0,0 +1,88 @@
+# do: Commands
+
+Action-oriented commands that enforce reading skills and how-tos before executing tasks.
+
+## Philosophy
+
+Each `do:` command is **MINIMAL** - it only points to where to read the full instructions:
+- **Skills** (`.claude/skills/`) contain patterns, conventions, and automation scripts
+- **How-tos** (`.claude/commands/how-to/`) contain step-by-step procedures
+
+## Available Commands
+
+### Core Development
+
+| Command | Description | Reads |
+|---------|-------------|-------|
+| `/do:create-entity` | Create a new entity with all files | `entity-system`, `database-migrations` |
+| `/do:create-migration` | Create a database migration | `database-migrations` |
+| `/do:create-api` | Create an API endpoint | `nextjs-api-development`, `entity-api` |
+| `/do:create-plugin` | Create a new plugin | `create-plugin`, `plugins` |
+| `/do:create-theme` | Create a new theme | `create-theme` |
+
+### Database
+
+| Command | Description | Reads |
+|---------|-------------|-------|
+| `/do:mock-data` | Generate sample/mock data | `database-migrations` |
+| `/do:reset-db` | Reset and migrate database | `database-migrations` |
+
+### Page Builder
+
+| Command | Description | Reads |
+|---------|-------------|-------|
+| `/do:validate-blocks` | Validate page builder blocks | `page-builder-blocks`, `block-decision-matrix` |
+| `/do:update-selectors` | Sync selectors between components, core, and POMs | `cypress-selectors` |
+
+### Background Tasks
+
+| Command | Description | Reads |
+|---------|-------------|-------|
+| `/do:setup-scheduled-action` | Create a scheduled action handler | `scheduled-actions` |
+
+### Git & GitHub
+
+| Command | Description | Reads |
+|---------|-------------|-------|
+| `/do:sync-code-review` | Sync with PR code review: evaluate, fix, respond | `github` |
+
+### Meta
+
+| Command | Description | Reads |
+|---------|-------------|-------|
+| `/do:use-skills` | **Enforcement**: Read and apply relevant skills for any task | `skills/README.md` |
+
+## Usage Examples
+
+```bash
+# For specific tasks
+/do:create-entity products
+/do:create-migration add-status-to-orders
+# For general tasks (skill enforcement)
+/do:use-skills create a webhook integration
+/do:use-skills add authentication to the API
+```
+
+## How It Works
+
+1. **User invokes** `/do:create-entity products`
+2. **Claude reads** the command file `do/create-entity.md`
+3. **Command says** "MANDATORY: Read `.claude/skills/entity-system/SKILL.md`"
+4. **Claude reads** the skill completely
+5. **Claude executes** following the skill's patterns and checklists
+
+## Adding New Commands
+
+To add a new `do:` command:
+
+1. Identify the skill(s) that cover the task
+2. Create a minimal `.md` file in `/commands/do/`
+3. Reference the skill with "MANDATORY: Read..."
+4. Include quick reference section for common operations
+5. Update this README
+
+## Related
+
+- `/commands/how-to/` - Detailed step-by-step procedures
+- `/commands/session/` - Session workflow commands
+- `/skills/` - Full skill documentation with scripts

package/claude/commands/do/create-api.md

@@ -0,0 +1,64 @@
+---
+description: "Create a new API endpoint"
+---
+
+# do:create-api
+
+**Endpoint Description:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skills First
+
+Read these skills completely before proceeding:
+
+1. `.claude/skills/nextjs-api-development/SKILL.md` - API patterns
+2. `.claude/skills/entity-api/SKILL.md` - Entity-specific endpoints (if applicable)
+
+---
+
+## Available Scripts
+
+```bash
+ls .claude/skills/nextjs-api-development/scripts/
+```
+
+Common scripts:
+- `scaffold-endpoint.py` - Generate endpoint files
+- `generate-crud-tests.py` - Generate Cypress tests
+- `validate-api.py` - Validate API structure
+
+---
+
+## Key Patterns
+
+From the skill, remember:
+
+1. **Wrapper:** Use `withApiLogging`
+2. **CORS:** Always use `addCorsHeaders(response)`
+3. **Auth:** Use `authenticateRequest(req)` for dual auth
+4. **Response:** Use `createApiResponse()` and `createApiError()`
+5. **Validation:** Use Zod schemas
+
+---
+
+## Endpoint Location
+
+- Custom endpoints: `app/api/v1/(contents)/{endpoint}/route.ts`
+- Core endpoints: `app/api/v1/{endpoint}/route.ts`
+
+---
+
+## After Creation
+
+1. Add API scopes to `core/lib/api/keys.ts`
+2. Generate tests:
+   ```bash
+   python .claude/skills/nextjs-api-development/scripts/generate-crud-tests.py --entity {entity}
+   ```
+
+---
+
+## Verification
+
+Use the checklist from `nextjs-api-development/SKILL.md` to verify compliance.

package/claude/commands/do/create-entity.md

@@ -0,0 +1,66 @@
+---
+description: "Create a new entity with all required files"
+---
+
+# do:create-entity
+
+**Entity Name:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skills First
+
+Read these skills completely before proceeding:
+
+1. `.claude/skills/entity-system/SKILL.md` - Entity configuration
+2. `.claude/skills/database-migrations/SKILL.md` - Migration patterns
+
+---
+
+## Available Scripts
+
+Check for automation scripts:
+
+```bash
+ls .claude/skills/entity-system/scripts/
+```
+
+Common scripts:
+- `scaffold-entity.py` - Generate entity files
+- `generate-migration.py` - Generate migration SQL
+
+---
+
+## Files to Create
+
+```
+contents/themes/{theme}/entities/{entity}/
+├── {entity}.config.ts    # Entity configuration
+├── {entity}.fields.ts    # Field definitions
+├── {entity}.types.ts     # TypeScript types
+├── messages/
+│   ├── en.json           # English translations
+│   └── es.json           # Spanish translations
+└── migrations/
+    └── XXX_{entity}_table.sql
+```
+
+---
+
+## After Creation
+
+1. Run registry rebuild:
+   ```bash
+   node core/scripts/build/registry.mjs
+   ```
+
+2. Run migrations:
+   ```bash
+   pnpm db:migrate
+   ```
+
+---
+
+## Verification
+
+Use the checklist from `entity-system/SKILL.md` to verify compliance.

package/claude/commands/do/create-migration.md

@@ -0,0 +1,64 @@
+---
+description: "Create a new database migration"
+---
+
+# do:create-migration
+
+**Migration Description:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skill First
+
+Read `.claude/skills/database-migrations/SKILL.md` completely before proceeding.
+
+---
+
+## Available Scripts
+
+```bash
+ls .claude/skills/database-migrations/scripts/
+```
+
+Common scripts:
+- `validate-migration.py` - Validate migration conventions
+- `generate-sample-data.py` - Generate sample data
+
+---
+
+## Key Conventions
+
+From the skill, remember:
+
+1. **IDs:** TEXT type, not UUID
+2. **Timestamps:** TIMESTAMPTZ, not TIMESTAMP
+3. **Field Order:** id → FK → business → system
+4. **RLS:** Apply appropriate policy pattern
+5. **Naming:** camelCase for tables and columns
+
+---
+
+## Migration Location
+
+- Core migrations: `core/migrations/XXX_*.sql`
+- Theme migrations: `contents/themes/{theme}/migrations/XXX_*.sql`
+
+---
+
+## After Creation
+
+1. Validate migration:
+   ```bash
+   python .claude/skills/database-migrations/scripts/validate-migration.py --file <path>
+   ```
+
+2. Run migration:
+   ```bash
+   pnpm db:migrate
+   ```
+
+---
+
+## Verification
+
+Use the checklist from `database-migrations/SKILL.md` to verify compliance.

package/claude/commands/do/create-plugin.md

@@ -0,0 +1,56 @@
+---
+description: "Create a new plugin"
+---
+
+# do:create-plugin
+
+**Plugin Name:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skills First
+
+Read these skills completely before proceeding:
+
+1. `.claude/skills/create-plugin/SKILL.md` - Plugin creation
+2. `.claude/skills/plugins/SKILL.md` - Plugin system overview
+
+---
+
+## Plugin Scaffold Command
+
+```bash
+pnpm create:plugin {plugin-name} --complexity {simple|medium|complex}
+```
+
+---
+
+## Plugin Structure
+
+```
+contents/plugins/{plugin-name}/
+├── plugin.config.ts      # Plugin configuration
+├── package.json          # Plugin metadata
+├── README.md             # Documentation
+├── lib/                  # Plugin logic
+├── components/           # UI components (if any)
+├── entities/             # Entities (if any)
+└── migrations/           # Migrations (if any)
+```
+
+---
+
+## After Creation
+
+1. Register plugin in test theme
+2. Rebuild registry:
+   ```bash
+   node core/scripts/build/registry.mjs
+   ```
+3. Verify plugin appears in PLUGIN_REGISTRY
+
+---
+
+## Verification
+
+Use the checklist from `create-plugin/SKILL.md` to verify compliance.

package/claude/commands/do/create-theme.md

@@ -0,0 +1,70 @@
+---
+description: "Create a new theme"
+---
+
+# do:create-theme
+
+**Theme Name:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skill First
+
+Read `.claude/skills/create-theme/SKILL.md` completely before proceeding.
+
+---
+
+## Theme Scaffold Command
+
+```bash
+pnpm create:theme {theme-name}
+```
+
+---
+
+## Theme Structure
+
+```
+contents/themes/{theme-name}/
+├── theme.config.ts       # Theme configuration
+├── config/
+│   ├── app.config.ts     # Application config
+│   ├── dashboard.config.ts
+│   └── permissions.config.ts
+├── components/           # Theme components
+├── entities/             # Theme entities
+├── styles/
+│   └── globals.css       # Theme styles
+└── lib/                  # Theme utilities
+```
+
+---
+
+## Configuration Files
+
+1. `theme.config.ts` - Theme metadata
+2. `app.config.ts` - Team Mode, features
+3. `dashboard.config.ts` - Dashboard layout
+4. `permissions.config.ts` - Role permissions
+
+---
+
+## After Creation
+
+1. Rebuild registry:
+   ```bash
+   node core/scripts/build/registry.mjs
+   ```
+
+2. Set as active theme in `.env`:
+   ```
+   NEXT_PUBLIC_ACTIVE_THEME={theme-name}
+   ```
+
+3. Verify theme appears in THEME_REGISTRY
+
+---
+
+## Verification
+
+Use the checklist from `create-theme/SKILL.md` to verify compliance.

package/claude/commands/do/mock-data.md

@@ -0,0 +1,67 @@
+---
+description: "Generate sample/mock data for entities"
+---
+
+# do:mock-data
+
+**Entity or Context:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skill First
+
+Read `.claude/skills/database-migrations/SKILL.md` completely before proceeding.
+
+Pay special attention to the "Sample Data" section.
+
+---
+
+## Available Scripts
+
+```bash
+ls .claude/skills/database-migrations/scripts/
+```
+
+Use script:
+```bash
+python .claude/skills/database-migrations/scripts/generate-sample-data.py \
+  --entity {entity} \
+  --count 20
+```
+
+---
+
+## Key Requirements
+
+1. **Quantity:** 20+ records per entity
+2. **Test Users:** Use standard password hash from skill
+3. **Varied Data:** Cover different scenarios and edge cases
+4. **ON CONFLICT:** Use upsert pattern for idempotency
+
+---
+
+## Test User Password Hash
+
+```
+3db9e98e2b4d3caca97fdf2783791cbc:34b293de615caf277a237773208858e960ea8aa10f1f5c5c309b632f192cac34d52ceafbd338385616f4929e4b1b6c055b67429c6722ffdb80b01d9bf4764866
+```
+
+Password: `Cypress123!`
+
+---
+
+## After Generation
+
+Run sample data migration:
+```bash
+pnpm db:migrate
+```
+
+---
+
+## Verification
+
+- [ ] 20+ records created per entity
+- [ ] Test users have correct password hash
+- [ ] Uses ON CONFLICT clause
+- [ ] Varied realistic data

package/claude/commands/do/reset-db.md

@@ -0,0 +1,71 @@
+---
+description: "Reset database and run all migrations"
+---
+
+# do:reset-db
+
+**Context:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skill First
+
+Read `.claude/skills/database-migrations/SKILL.md` for migration patterns.
+
+---
+
+## Reset Commands
+
+### Full Reset (Development Only)
+
+```bash
+# Drop and recreate database
+pnpm db:reset
+
+# Or manually:
+pnpm db:drop
+pnpm db:create
+pnpm db:migrate
+```
+
+### Migration Only (Safe)
+
+```bash
+# Run pending migrations
+pnpm db:migrate
+
+# Check migration status
+pnpm db:status
+```
+
+---
+
+## Warning
+
+**NEVER run `db:reset` on production databases.**
+
+Only use reset in development environments.
+
+---
+
+## After Reset
+
+1. Verify tables exist:
+   ```bash
+   pnpm db:verify
+   ```
+
+2. Check sample data:
+   ```bash
+   pnpm db:seed  # If available
+   ```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Connection refused | Check DATABASE_URL in .env |
+| Permission denied | Check database user permissions |
+| Migration failed | Check SQL syntax in migration files |

package/claude/commands/do/setup-scheduled-action.md

@@ -0,0 +1,75 @@
+---
+description: "Create a new scheduled action handler"
+---
+
+# do:setup-scheduled-action
+
+**Action Description:** {{{ input }}}
+
+---
+
+## MANDATORY: Read Skill First
+
+Read `.claude/skills/scheduled-actions/SKILL.md` completely before proceeding.
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `contents/themes/{theme}/lib/scheduled-actions/handlers/` | Handler implementations |
+| `contents/themes/{theme}/lib/scheduled-actions/index.ts` | Handler registration |
+| `contents/themes/{theme}/config/app.config.ts` | Configuration |
+
+---
+
+## Handler Template
+
+```typescript
+// handlers/{name}.ts
+import { registerScheduledAction } from '@/core/lib/scheduled-actions'
+
+export function registerMyHandler() {
+  registerScheduledAction('my-action:type', async (payload, action) => {
+    try {
+      // Implementation
+      return { success: true, message: 'Done' }
+    } catch (error) {
+      return { success: false, message: error.message }
+    }
+  })
+}
+```
+
+---
+
+## Registration
+
+Add to `index.ts`:
+
+```typescript
+import { registerMyHandler } from './handlers/my-handler'
+
+export function registerAllHandlers() {
+  // ... existing handlers
+  registerMyHandler()  // Add here
+}
+```
+
+---
+
+## After Creation
+
+1. Rebuild registry:
+   ```bash
+   node core/scripts/build/registry.mjs
+   ```
+
+2. Restart dev server to load handlers
+
+---
+
+## Verification
+
+Use the checklist from `scheduled-actions/SKILL.md` to verify compliance.