@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/commands/session/README.md

@@ -0,0 +1,193 @@
+# /session:* Commands
+
+Unified namespace for development session management.
+
+---
+
+## Top-Level Aliases
+
+| Alias | Full Command | Description |
+|-------|--------------|-------------|
+| `/start` | `/session:start` | Start new session |
+| `/execute` | `/session:execute` | Execute development |
+| `/commit` | `/session:commit` | Prepare commit |
+| `/fix` | `/session:fix:bug` | Fix bug |
+| `/status` | `/session:status` | View status |
+
+---
+
+## Commands by Category
+
+### Lifecycle (session management)
+
+| Command | Description |
+|---------|-------------|
+| `/session:start` | Intelligent entry point |
+| `/session:start:tweak` | Tweak workflow (XS-S) |
+| `/session:start:task` | Task workflow (S-M-L) |
+| `/session:start:story` | Story workflow (L-XL) |
+| `/session:resume` | Resume existing session |
+| `/session:status` | View session status |
+| `/session:close` | Close active session |
+
+### Phases (development phases)
+
+| Command | Description |
+|---------|-------------|
+| `/session:execute` | Execute development |
+| `/session:validate` | Validate implementation |
+| `/session:review` | Final code review |
+| `/session:refine` | Refine requirements or plan |
+
+### Actions (common actions)
+
+| Command | Description |
+|---------|-------------|
+| `/session:commit` | Prepare commit |
+| `/session:demo` | Visual demo with Playwright |
+| `/session:explain` | Explain code/decision |
+| `/session:pending` | Document pending items |
+| `/session:scope-change` | Handle scope change |
+
+### Fix (corrections)
+
+| Command | Description |
+|---------|-------------|
+| `/session:fix:bug` | Fix bug |
+| `/session:fix:build` | Fix build errors |
+| `/session:fix:test` | Fix failing tests |
+
+### Block (page builder)
+
+| Command | Description |
+|---------|-------------|
+| `/session:block:create` | Create new block |
+| `/session:block:update` | Modify existing block |
+| `/session:block:list` | List available blocks |
+| `/session:block:validate` | Validate structure |
+
+### DB (database)
+
+| Command | Description |
+|---------|-------------|
+| `/session:db:entity` | Create entity migration |
+| `/session:db:sample` | Generate sample data |
+| `/session:db:fix` | Fix migrations |
+
+### Test (testing)
+
+| Command | Description |
+|---------|-------------|
+| `/session:test:write` | Write Cypress tests |
+| `/session:test:run` | Run test suite |
+| `/session:test:fix` | Fix failing tests |
+
+### Doc (documentation)
+
+| Command | Description |
+|---------|-------------|
+| `/session:doc:feature` | Document feature |
+| `/session:doc:read` | Read docs before working |
+| `/session:doc:bdd` | Generate BDD from tests |
+
+---
+
+## Command Standards
+
+Each command follows these conventions:
+
+### 1. Required Skills Section
+Commands that need specific knowledge include a **Required Skills** section listing skills to read before executing.
+
+### 2. Mandatory Markers
+Steps marked with **[MANDATORY]** must be performed. Steps without this marker are recommended but can be adapted.
+
+### 3. Workflow Context
+Generic commands include a **Workflow Detection** or **Workflow Context** section explaining how they behave in TWEAK, TASK, and STORY workflows.
+
+### 4. Skill → Command Mapping
+See `skills/README.md` for the complete Command → Skill Mapping table.
+
+---
+
+## Naming Convention
+
+```
+:  (colon) → SUBCOMMAND separator (hierarchy)
+
+   /session:start           → start command
+   /session:start:tweak     → quick subcommand of start
+   /session:fix:bug         → bug subcommand of fix
+
+-  (hyphen) → COMPOUND WORD separator
+
+   /session:scope-change    → "scope change" is a concept
+```
+
+---
+
+## Typical Flow
+
+```
+1. /session:start "description"     # Evaluate and create session
+   ↓
+2. (Claude suggests workflow)
+   ↓
+3. /session:execute                  # Execute development
+   ↓
+4. (if scope changes)
+   /session:scope-change scope-change "reason"
+   ↓
+5. /session:status                   # Verify progress
+   ↓
+6. /session:close "summary"          # Close session
+```
+
+---
+
+## Command Files
+
+### Lifecycle
+- [session-start.md](./session-start.md) - Start session
+- [session-resume.md](./session-resume.md) - Resume session
+- [session-status.md](./session-status.md) - View status
+- [session-close.md](./session-close.md) - Close session
+
+### Phases
+- [session-execute.md](./session-execute.md) - Execute development
+- [session-validate.md](./session-validate.md) - Validate implementation
+- [session-review.md](./session-review.md) - Code review
+- [session-refine.md](./session-refine.md) - Refine requirements/plan
+
+### Actions
+- [session-commit.md](./session-commit.md) - Prepare commit
+- [session-demo.md](./session-demo.md) - Visual demo
+- [session-explain.md](./session-explain.md) - Explain code
+- [session-pending.md](./session-pending.md) - Document pending
+- [session-scope-change.md](./session-scope-change.md) - Scope change
+
+### Fix
+- [session-fix-bug.md](./session-fix-bug.md) - Fix bug
+- [session-fix-build.md](./session-fix-build.md) - Fix build errors
+- [session-fix-test.md](./session-fix-test.md) - Fix failing tests
+
+### Block
+- [session-block-create.md](./session-block-create.md) - Create block
+- [session-block-update.md](./session-block-update.md) - Update block
+- [session-block-list.md](./session-block-list.md) - List blocks
+- [session-block-validate.md](./session-block-validate.md) - Validate blocks
+
+### DB
+- [session-db-entity.md](./session-db-entity.md) - Create entity migration
+- [session-db-sample.md](./session-db-sample.md) - Generate sample data
+- [session-db-fix.md](./session-db-fix.md) - Fix migrations
+
+### Test
+- [session-test-write.md](./session-test-write.md) - Write tests
+- [session-test-run.md](./session-test-run.md) - Run tests
+- [session-test-fix.md](./session-test-fix.md) - Fix tests
+
+### Doc
+- [session-doc-feature.md](./session-doc-feature.md) - Document feature
+- [session-doc-read.md](./session-doc-read.md) - Read documentation
+- [session-doc-bdd.md](./session-doc-bdd.md) - Generate BDD docs

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

@@ -0,0 +1,190 @@
+# /session:block:create
+
+Create a new page builder block with complete file structure.
+
+---
+
+## Required Skills
+
+**[MANDATORY]** Read these skills before executing:
+- `.claude/skills/page-builder-blocks/SKILL.md` - Block development patterns
+- `.claude/skills/block-decision-matrix/SKILL.md` - Decision framework for new vs variant
+- `.claude/skills/design-system/SKILL.md` - Token mapping for styling
+
+---
+
+## Syntax
+
+```
+/session:block:create <block-name> [--theme <name>]
+```
+
+---
+
+## Behavior
+
+Creates a new block with all 5 required files following project patterns.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:block:create                                           │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Determine target theme                                      │
+│     - Use --theme or NEXT_PUBLIC_ACTIVE_THEME                   │
+│     ↓                                                           │
+│  2. Discover existing blocks                                    │
+│     - Read 1-2 similar blocks for patterns                      │
+│     ↓                                                           │
+│  3. Ask about block requirements                                │
+│     - What fields?                                              │
+│     - What sections?                                            │
+│     - Reference mock?                                           │
+│     ↓                                                           │
+│  4. Generate 5 files                                            │
+│     - config.ts                                                 │
+│     - schema.ts                                                 │
+│     - fields.ts                                                 │
+│     - component.tsx                                             │
+│     - index.ts                                                  │
+│     ↓                                                           │
+│  5. Rebuild block registry                                      │
+│     ↓                                                           │
+│  6. Validate block structure                                    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🧱 CREATE BLOCK
+
+Block name: hero-banner
+Theme: default
+
+─────────────────────────────────────────
+
+📋 BLOCK REQUIREMENTS
+
+What is the purpose of this block?
+> Full-width hero section with image background and CTA
+
+What fields does it need?
+> Title, subtitle, background image, CTA button
+
+Does it have sections (repeatable items)?
+> No, single content area
+
+Reference mock or existing block?
+> Similar to existing hero block but with image background
+
+─────────────────────────────────────────
+
+🔍 ANALYZING PATTERNS
+
+Reading existing blocks...
+├─ hero: Title/subtitle/CTA pattern
+├─ cta-section: Background image handling
+└─ Found: buildSectionClasses usage
+
+─────────────────────────────────────────
+
+📁 CREATING FILES
+
+contents/themes/default/blocks/hero-banner/
+├─ config.ts    ✓ Created
+├─ schema.ts    ✓ Created
+├─ fields.ts    ✓ Created
+├─ component.tsx ✓ Created
+└─ index.ts     ✓ Created
+
+─────────────────────────────────────────
+
+🔄 REBUILDING REGISTRY
+
+Running pnpm build:blocks...
+✓ Registry updated
+
+─────────────────────────────────────────
+
+✅ VALIDATION
+
+- [x] 5 files present
+- [x] Schema extends baseBlockSchema
+- [x] Fields match schema
+- [x] Component exports default
+- [x] data-cy attributes present
+
+─────────────────────────────────────────
+
+✓ Block 'hero-banner' created successfully
+
+Preview at: /devtools/blocks/hero-banner
+```
+
+---
+
+## Generated File Structure
+
+### config.ts
+
+```typescript
+import type { BlockConfig } from '@/core/block-system/types';
+
+export const config: BlockConfig = {
+  name: 'hero-banner',
+  displayName: 'Hero Banner',
+  category: 'hero',
+  icon: 'Image',
+  defaultProps: {
+    title: 'Welcome',
+    subtitle: 'Your subtitle here',
+  },
+};
+```
+
+### schema.ts
+
+```typescript
+import { baseBlockSchema } from '@/core/block-system/schemas';
+import { z } from 'zod';
+
+export const schema = baseBlockSchema.extend({
+  title: z.string().default('Welcome'),
+  subtitle: z.string().optional(),
+  backgroundImage: z.string().optional(),
+  cta: z.object({
+    label: z.string(),
+    href: z.string(),
+  }).optional(),
+});
+
+export type HeroBannerProps = z.infer<typeof schema>;
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--theme <name>` | Target theme (default: active theme) |
+| `--from-mock <path>` | Generate from mock HTML |
+| `--minimal` | Create minimal structure |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:block:update` | Modify existing block |
+| `/session:block:list` | List available blocks |
+| `/session:block:validate` | Validate block structure |

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

@@ -0,0 +1,203 @@
+# /session:block:list
+
+List available blocks in the page builder.
+
+---
+
+## Syntax
+
+```
+/session:block:list [--theme <name>] [--category <name>]
+```
+
+---
+
+## Behavior
+
+Shows all available blocks in a theme, organized by category.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:block:list                                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Determine theme                                             │
+│     ↓                                                           │
+│  2. Scan blocks directory                                       │
+│     ↓                                                           │
+│  3. Read each block's config                                    │
+│     ↓                                                           │
+│  4. Organize by category                                        │
+│     ↓                                                           │
+│  5. Display formatted list                                      │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🧱 AVAILABLE BLOCKS
+
+Theme: default
+Location: contents/themes/default/blocks/
+
+─────────────────────────────────────────
+
+## Hero (3 blocks)
+
+hero
+├─ Display: Hero Section
+├─ Fields: title, subtitle, cta
+└─ Preview: /devtools/blocks/hero
+
+hero-banner
+├─ Display: Hero Banner
+├─ Fields: title, subtitle, backgroundImage, cta, overlay
+└─ Preview: /devtools/blocks/hero-banner
+
+hero-video
+├─ Display: Hero Video
+├─ Fields: title, subtitle, videoUrl, cta
+└─ Preview: /devtools/blocks/hero-video
+
+─────────────────────────────────────────
+
+## Content (5 blocks)
+
+text-block
+├─ Display: Text Block
+├─ Fields: content, alignment
+└─ Preview: /devtools/blocks/text-block
+
+features-grid
+├─ Display: Features Grid
+├─ Fields: title, features[]
+└─ Preview: /devtools/blocks/features-grid
+
+testimonials
+├─ Display: Testimonials
+├─ Fields: title, items[]
+└─ Preview: /devtools/blocks/testimonials
+
+faq
+├─ Display: FAQ Accordion
+├─ Fields: title, items[]
+└─ Preview: /devtools/blocks/faq
+
+pricing
+├─ Display: Pricing Table
+├─ Fields: title, plans[]
+└─ Preview: /devtools/blocks/pricing
+
+─────────────────────────────────────────
+
+## CTA (2 blocks)
+
+cta-section
+├─ Display: Call to Action
+├─ Fields: title, description, buttons[]
+└─ Preview: /devtools/blocks/cta-section
+
+newsletter
+├─ Display: Newsletter Signup
+├─ Fields: title, description, placeholder
+└─ Preview: /devtools/blocks/newsletter
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Total blocks: 10
+Categories: 3
+
+Blocks with sections: 4
+  - features-grid, testimonials, faq, pricing
+```
+
+---
+
+## Filter by Category
+
+```
+/session:block:list --category hero
+```
+
+Output:
+
+```
+🧱 BLOCKS: Hero Category
+
+Theme: default
+
+─────────────────────────────────────────
+
+hero
+├─ Display: Hero Section
+├─ Fields: title, subtitle, cta
+└─ Preview: /devtools/blocks/hero
+
+hero-banner
+├─ Display: Hero Banner
+├─ Fields: title, subtitle, backgroundImage, cta, overlay
+└─ Preview: /devtools/blocks/hero-banner
+
+hero-video
+├─ Display: Hero Video
+├─ Fields: title, subtitle, videoUrl, cta
+└─ Preview: /devtools/blocks/hero-video
+
+─────────────────────────────────────────
+
+Total: 3 blocks in 'hero' category
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--theme <name>` | List blocks from specific theme |
+| `--category <name>` | Filter by category |
+| `--json` | Output as JSON |
+| `--detailed` | Show all fields and types |
+
+---
+
+## Detailed Output
+
+```
+/session:block:list --detailed
+```
+
+Shows complete field definitions:
+
+```
+hero
+├─ Display: Hero Section
+├─ Category: hero
+├─ Fields:
+│   ├─ title: string (required, default: "Welcome")
+│   ├─ subtitle: string (optional)
+│   └─ cta: object (optional)
+│       ├─ label: string (required)
+│       └─ href: string (required)
+└─ Preview: /devtools/blocks/hero
+```
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:block:create` | Create new block |
+| `/session:block:update` | Modify block |
+| `/session:block:validate` | Validate blocks |