@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/commands/session/block-update.md

@@ -0,0 +1,192 @@
+# /session:block:update
+
+Modify an existing page builder block.
+
+---
+
+## Required Skills
+
+**[MANDATORY]** Read before executing:
+- `.claude/skills/page-builder-blocks/SKILL.md` - Block development patterns
+
+---
+
+## Syntax
+
+```
+/session:block:update <block-name> [--theme <name>]
+```
+
+---
+
+## Behavior
+
+Updates an existing block while maintaining backward compatibility.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:block:update                                           │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Locate block in theme                                       │
+│     ↓                                                           │
+│  2. Read current structure                                      │
+│     - config.ts                                                 │
+│     - schema.ts                                                 │
+│     - fields.ts                                                 │
+│     - component.tsx                                             │
+│     ↓                                                           │
+│  3. Ask what to modify                                          │
+│     - Add field?                                                │
+│     - Modify field?                                             │
+│     - Update component?                                         │
+│     ↓                                                           │
+│  4. Apply changes                                               │
+│     - Update schema                                             │
+│     - Update fields                                             │
+│     - Update component                                          │
+│     ↓                                                           │
+│  5. Ensure backward compatibility                               │
+│     - New fields have defaults                                  │
+│     - Existing data still works                                 │
+│     ↓                                                           │
+│  6. Rebuild and validate                                        │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🧱 UPDATE BLOCK
+
+Block: hero-banner
+Theme: default
+Location: contents/themes/default/blocks/hero-banner/
+
+─────────────────────────────────────────
+
+📋 CURRENT STRUCTURE
+
+Fields:
+├─ title: string (required)
+├─ subtitle: string (optional)
+├─ backgroundImage: string (optional)
+└─ cta: object (optional)
+    ├─ label: string
+    └─ href: string
+
+─────────────────────────────────────────
+
+What would you like to modify?
+[1] Add new field
+[2] Modify existing field
+[3] Remove field
+[4] Update component logic
+[5] Update styling
+
+> 1
+
+─────────────────────────────────────────
+
+📝 ADD NEW FIELD
+
+Field name?
+> overlay
+
+Field type?
+[1] string
+[2] number
+[3] boolean
+[4] select (enum)
+[5] object
+
+> 4
+
+Select options?
+> none, light, dark
+
+Default value?
+> none
+
+─────────────────────────────────────────
+
+🔧 APPLYING CHANGES
+
+Updating schema.ts...
++ overlay: z.enum(['none', 'light', 'dark']).default('none'),
+✓ Schema updated
+
+Updating fields.ts...
++ {
++   name: 'overlay',
++   type: 'select',
++   label: 'Overlay',
++   options: [
++     { value: 'none', label: 'None' },
++     { value: 'light', label: 'Light' },
++     { value: 'dark', label: 'Dark' },
++   ],
++ }
+✓ Fields updated
+
+Updating component.tsx...
++ const overlayClass = overlay === 'none' ? '' :
++   overlay === 'light' ? 'bg-white/50' : 'bg-black/50';
+✓ Component updated
+
+─────────────────────────────────────────
+
+🔄 REBUILDING REGISTRY
+
+Running pnpm build:blocks...
+✓ Registry updated
+
+─────────────────────────────────────────
+
+✅ BACKWARD COMPATIBILITY CHECK
+
+- [x] New field has default value
+- [x] Existing pages will render correctly
+- [x] No breaking changes detected
+
+─────────────────────────────────────────
+
+✓ Block 'hero-banner' updated successfully
+```
+
+---
+
+## Backward Compatibility Rules
+
+| Change Type | Requirement |
+|-------------|-------------|
+| Add field | Must have default value |
+| Modify field | Keep existing values valid |
+| Remove field | Must be optional first |
+| Rename field | Create alias, deprecate old |
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--theme <name>` | Target theme |
+| `--add-field <name>` | Directly add field |
+| `--no-validate` | Skip validation |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:block:create` | Create new block |
+| `/session:block:validate` | Validate structure |

package/claude/commands/session/block-validate.md

@@ -0,0 +1,218 @@
+# /session:block:validate
+
+Validate block structure and consistency.
+
+---
+
+## Syntax
+
+```
+/session:block:validate [block-name] [--theme <name>]
+```
+
+---
+
+## Behavior
+
+Validates that blocks follow project conventions and have consistent structure.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:block:validate                                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Locate block(s) to validate                                 │
+│     ↓                                                           │
+│  2. Check file structure                                        │
+│     - All 5 files present?                                      │
+│     ↓                                                           │
+│  3. Validate schema                                             │
+│     - Extends baseBlockSchema?                                  │
+│     - Valid Zod types?                                          │
+│     ↓                                                           │
+│  4. Validate fields                                             │
+│     - Match schema?                                             │
+│     - Valid field types?                                        │
+│     ↓                                                           │
+│  5. Validate component                                          │
+│     - Uses props correctly?                                     │
+│     - Has data-cy attributes?                                   │
+│     ↓                                                           │
+│  6. Report results                                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example: Validate Single Block
+
+```
+/session:block:validate hero-banner
+```
+
+Output:
+
+```
+✅ BLOCK VALIDATION: hero-banner
+
+Theme: default
+
+─────────────────────────────────────────
+
+📁 FILE STRUCTURE
+
+- [x] config.ts exists
+- [x] schema.ts exists
+- [x] fields.ts exists
+- [x] component.tsx exists
+- [x] index.ts exists
+
+─────────────────────────────────────────
+
+📐 SCHEMA VALIDATION
+
+- [x] Extends baseBlockSchema
+- [x] All fields have valid Zod types
+- [x] Required fields have no default OR are truly required
+- [x] Optional fields marked correctly
+
+─────────────────────────────────────────
+
+📋 FIELDS VALIDATION
+
+- [x] All schema fields have field definitions
+- [x] Field types match schema types
+- [x] Labels defined for all fields
+
+─────────────────────────────────────────
+
+🎨 COMPONENT VALIDATION
+
+- [x] Default export present
+- [x] Props destructured from schema type
+- [x] data-cy attribute on root element
+- [x] Handles optional fields gracefully
+
+─────────────────────────────────────────
+
+📊 RESULT
+
+Status: VALID
+Issues: 0
+Warnings: 0
+
+✓ Block 'hero-banner' is valid
+```
+
+---
+
+## Example: Validate All Blocks
+
+```
+/session:block:validate
+```
+
+Output:
+
+```
+✅ BLOCK VALIDATION: All Blocks
+
+Theme: default
+Blocks found: 10
+
+─────────────────────────────────────────
+
+## Results
+
+| Block | Files | Schema | Fields | Component | Status |
+|-------|-------|--------|--------|-----------|--------|
+| hero | ✓ | ✓ | ✓ | ✓ | VALID |
+| hero-banner | ✓ | ✓ | ✓ | ✓ | VALID |
+| hero-video | ✓ | ⚠ | ✓ | ✓ | WARNING |
+| text-block | ✓ | ✓ | ✓ | ✓ | VALID |
+| features-grid | ✓ | ✓ | ✓ | ❌ | INVALID |
+| testimonials | ✓ | ✓ | ✓ | ✓ | VALID |
+| faq | ✓ | ✓ | ✓ | ✓ | VALID |
+| pricing | ✓ | ✓ | ✓ | ✓ | VALID |
+| cta-section | ✓ | ✓ | ✓ | ✓ | VALID |
+| newsletter | ✓ | ✓ | ✓ | ✓ | VALID |
+
+─────────────────────────────────────────
+
+## Issues
+
+### features-grid (INVALID)
+
+❌ Component: Missing data-cy attribute on root element
+
+Location: component.tsx:15
+Current:
+```tsx
+<div className="features-grid">
+```
+
+Expected:
+```tsx
+<div className="features-grid" data-cy="block-features-grid">
+```
+
+─────────────────────────────────────────
+
+## Warnings
+
+### hero-video (WARNING)
+
+⚠ Schema: Field 'autoplay' is boolean but defaults to undefined
+
+Suggestion: Add explicit default value:
+```typescript
+autoplay: z.boolean().default(false)
+```
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Valid: 8
+Warnings: 1
+Invalid: 1
+
+Run '/session:block:update features-grid' to fix issues.
+```
+
+---
+
+## Validation Rules
+
+| Check | Severity | Description |
+|-------|----------|-------------|
+| Missing file | Error | All 5 files required |
+| No baseBlockSchema | Error | Must extend base |
+| Missing data-cy | Error | Required for testing |
+| Missing field definition | Warning | Should match schema |
+| No default for optional | Warning | Recommended |
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--theme <name>` | Validate in specific theme |
+| `--fix` | Attempt to auto-fix issues |
+| `--strict` | Treat warnings as errors |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:block:create` | Create new block |
+| `/session:block:update` | Fix invalid blocks |
+| `/session:block:list` | List all blocks |

package/claude/commands/session/changelog.md

@@ -0,0 +1,115 @@
+# /session:changelog
+
+Generate a simple, complete changelog for the current feature branch.
+
+---
+
+## Syntax
+
+```
+/session:changelog
+```
+
+---
+
+## Behavior
+
+Generate a changelog summarizing everything done in the current feature branch. The audience is the development team — keep it concise, concrete, and complete.
+
+---
+
+## Steps
+
+### 1. Gather context
+
+Run these commands to understand the full scope:
+
+```bash
+# Get the base branch
+BASE=$(git merge-base origin/main HEAD 2>/dev/null || git merge-base origin/master HEAD 2>/dev/null)
+
+# All commits (excluding version bumps)
+git log --oneline --reverse $BASE..HEAD | grep -v "^.* chore: bump"
+
+# Overall stats
+git diff --stat $BASE..HEAD | tail -3
+
+# Check for an existing PR
+gh pr list --head $(git branch --show-current) --json number,title,url --jq '.[0]'
+```
+
+If a PR exists, also read its body for additional context:
+```bash
+gh pr view <number> --json body --jq '.body'
+```
+
+### 2. Generate changelog
+
+Write the changelog using this exact format:
+
+```
+## Changelog `<version>`
+
+- **Feature/change title**: one-line description of what it does and why it matters
+- **Feature/change title**: one-line description
+- ...repeat for every meaningful change
+
+**Migration notes for existing projects:**
+- Step-by-step instructions for any manual changes needed
+- Config additions, dependency updates, etc.
+- Only include this section if there ARE breaking/manual changes
+```
+
+### 3. Format rules
+
+- **One bullet per logical change** — group related commits into a single bullet
+- **Skip version bump commits** — they are noise
+- **Bold the title** of each bullet, plain text for the description
+- **Use present tense** — "adds", "fixes", "removes" (not "added", "fixed")
+- **Be specific** — name the files, commands, or packages involved
+- **No emojis**
+- **No sub-bullets** inside changelog items (keep it flat)
+- **Version number** comes from the latest package version on the branch
+- **Migration notes** section only appears if existing consumer projects need manual changes (config additions, dependency changes, breaking API changes, etc.)
+
+---
+
+## Example Output
+
+```
+## Changelog `0.1.0-beta.92`
+
+- **New `@nextsparkjs/ai-workflow` package**: agents, commands, skills and workflows now distributed as a standalone npm package
+- **Auto-sync for `.claude/`**: running `pnpm update` automatically syncs AI workflow files, same pattern as core does with `/app`
+- **New `nextspark sync:ai` command**: manual sync with `--editor` and `--force` options
+- **Core template cleanup**: legacy AI workflow files removed from `@nextsparkjs/core`, presets consolidated into `templates/`
+- **Fix postinstall for pnpm v10 workspaces**: postinstall scripts for core and ai-workflow now work correctly in consumer projects with pnpm workspaces (web-only and web-mobile)
+
+**Migration notes for existing projects:**
+- Add to your root `package.json`:
+  ```json
+  "pnpm": {
+    "onlyBuiltDependencies": ["@nextsparkjs/core", "@nextsparkjs/ai-workflow"]
+  }
+  ```
+- Install the new package: `pnpm add -D -w @nextsparkjs/ai-workflow@latest`
+```
+
+---
+
+## Anti-patterns
+
+- DO NOT list every commit individually
+- DO NOT include "bumped to version X" bullets
+- DO NOT write paragraphs — one line per bullet
+- DO NOT include implementation details (file paths, function names) unless they are user-facing (CLI commands, config keys)
+- DO NOT skip changes — every non-bump commit should be represented in at least one bullet
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:review` | Code review before changelog |
+| `/session:close` | Close session after changelog |