@nextsparkjs/ai-workflow 0.1.0-beta.86

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/close.md

@@ -0,0 +1,146 @@
+# /session:close
+
+Close the active session or a specific session.
+
+---
+
+## Syntax
+
+```
+/session:close [session-path] [summary]
+```
+
+---
+
+## Behavior
+
+### Without path (active session)
+
+```
+/session:close
+```
+
+Closes the current active session (if there is one).
+
+### With path
+
+```
+/session:close stories/2026-01-11-new-entity "Feature completed"
+```
+
+Closes the specified session.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:close                                                  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Verify ACs are met                                          │
+│     - Read requirements.md                                      │
+│     - Verify checklist in progress.md                           │
+│     ↓                                                           │
+│  2. All ACs completed?                                          │
+│     │                                                           │
+│     ├─► YES: Continue                                           │
+│     │                                                           │
+│     └─► NO: Warn                                                │
+│         "There are 2 pending ACs. Close anyway?"                │
+│     ↓                                                           │
+│  3. Execute session-close.sh                                    │
+│     ↓                                                           │
+│  4. Archive?                                                    │
+│     [Yes, archive] [No, keep]                                   │
+│     ↓                                                           │
+│  5. Update task manager (if enabled)                            │
+│     - Post final comment                                        │
+│     - Change status to "done"                                   │
+│     ↓                                                           │
+│  6. Show summary                                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+📋 CLOSING SESSION
+
+Session: stories/2026-01-11-new-products-entity
+Type: Story (STORY)
+Iterations: 2
+
+─────────────────────────────────────────
+
+✅ AC VERIFICATION
+
+AC1: Create products migration           ✓
+AC2: Implement CRUD API                  ✓
+AC3: Create management UI                ✓
+AC4: Automated tests                     ✓
+
+All ACs completed: 4/4
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+- Total duration: 5 days
+- Iterations: 2
+- Files modified: 23
+- Tests created: 12
+
+─────────────────────────────────────────
+
+✓ Session closed
+
+Archive session? [Yes/No]
+```
+
+---
+
+## With Pending ACs
+
+```
+⚠️ WARNING
+
+There are pending ACs:
+- [ ] AC4: Automated tests
+
+Options:
+[1] Close anyway (document pending items)
+[2] Cancel and continue working
+[3] Move pending to new iteration
+```
+
+---
+
+## Task Manager Integration
+
+If `taskManager.enabled`:
+
+```
+📋 TASK UPDATE
+
+ClickUp: #abc123
+
+Posting final comment...
+✓ Comment posted
+
+Updating status to "done"...
+✓ Status updated
+```
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:status` | View status before closing |
+| `/session:pending` | Document pending items |