@nextsparkjs/ai-workflow 0.1.0-beta.87 → 0.1.0-beta.89

package/claude/agents/architecture-supervisor.md

@@ -277,7 +277,7 @@ await Read('core/docs/18-page-builder/01-introduction.md')
 
 **CRITICAL: When planning entity features, reference the presets.**
 
-Location: `core/presets/theme/entities/tasks/`
+Location: `core/templates/contents/themes/starter/entities/tasks/`
 
 ### Required Files (4-File Structure)
 
@@ -299,7 +299,7 @@ Location: `core/presets/theme/entities/tasks/`
 **Include in plan.md when planning entity features:**
 ```markdown
 ## Entity Structure Reference
-Use `core/presets/theme/entities/tasks/` as reference for:
+Use `core/templates/contents/themes/starter/entities/tasks/` as reference for:
 - Entity config structure (5 sections) - `tasks.config.ts`
 - Field definitions pattern - `tasks.fields.ts`
 - TypeScript types - `tasks.types.ts`

package/claude/agents/backend-developer.md

@@ -108,7 +108,7 @@ await clickup.addComment(taskId, "🚀 Starting backend development")
 
 **When creating or modifying entities, use presets as reference:**
 
-Location: `core/presets/theme/entities/tasks/`
+Location: `core/templates/contents/themes/starter/entities/tasks/`
 
 ### Required Files (4-File Structure)
 

package/claude/agents/block-developer.md

@@ -129,7 +129,7 @@ await Read('.rules/testing.md')
 These are **implicit system fields** - see `core/lib/entities/system-fields.ts`
 
 **Entity Presets Available:**
-- `core/presets/theme/entities/tasks/` - Complete entity example
+- `core/templates/contents/themes/starter/entities/tasks/` - Complete entity example
 
 **Note:** Most blocks do NOT require custom entities. Only use this if your block needs persistent data storage beyond page content.
 
@@ -139,7 +139,7 @@ These are **implicit system fields** - see `core/lib/entities/system-fields.ts`
 
 ### Available Block Presets
 
-Location: `core/presets/blocks/`
+Location: `core/templates/blocks/`
 
 | Block | Category | Description |
 |-------|----------|-------------|
@@ -155,7 +155,7 @@ Location: `core/presets/blocks/`
 
 ```bash
 # 1. Copy the preset to the theme
-cp -r core/presets/blocks/hero contents/themes/{THEME}/blocks/
+cp -r core/templates/blocks/hero contents/themes/{THEME}/blocks/
 
 # 2. Customize as needed (config.ts, schema.ts, fields.ts, component.tsx)
 
@@ -167,11 +167,11 @@ node core/scripts/build/registry.mjs
 
 | Scenario | Approach |
 |----------|----------|
-| Need a hero section | **Copy** `core/presets/blocks/hero`, customize |
-| Need a CTA block | **Copy** `core/presets/blocks/cta-section`, customize |
-| Need a features grid | **Copy** `core/presets/blocks/features-grid`, customize |
-| Need testimonials | **Copy** `core/presets/blocks/testimonials`, customize |
-| Need rich text | **Copy** `core/presets/blocks/text-content`, customize |
+| Need a hero section | **Copy** `core/templates/blocks/hero`, customize |
+| Need a CTA block | **Copy** `core/templates/blocks/cta-section`, customize |
+| Need a features grid | **Copy** `core/templates/blocks/features-grid`, customize |
+| Need testimonials | **Copy** `core/templates/blocks/testimonials`, customize |
+| Need rich text | **Copy** `core/templates/blocks/text-content`, customize |
 | Completely unique block | Create from scratch using preset as reference |
 
 ### Preset Inspection Before Creating
@@ -180,14 +180,14 @@ node core/scripts/build/registry.mjs
 
 ```bash
 # List available presets
-ls core/presets/blocks/
+ls core/templates/blocks/
 
 # Read preset README
-cat core/presets/blocks/README.md
+cat core/templates/blocks/README.md
 
 # Inspect a specific preset for patterns
-cat core/presets/blocks/hero/schema.ts
-cat core/presets/blocks/hero/component.tsx
+cat core/templates/blocks/hero/schema.ts
+cat core/templates/blocks/hero/component.tsx
 ```
 
 ## BLOCKS Workflow Integration
@@ -226,7 +226,7 @@ blocks/YYYY-MM-DD-{name}/
 - File structure requirements
 - Base schemas and helpers
 - Development rules and anti-patterns
-- **Block presets in `core/presets/blocks/`** ← NEW
+- **Block presets in `core/templates/blocks/`** ← NEW
 
 **You DISCOVER at runtime** (dynamic knowledge):
 - Which theme to work with
@@ -261,7 +261,7 @@ At the start of task:execute, scope is documented in `context.md` showing allowe
 - `theme: "default"` → You CAN only create/modify blocks in `contents/themes/default/blocks/**/*`
 - `theme: false` → You CANNOT create blocks (report as blocker - need theme scope)
 - `core: false` → You CANNOT modify core block types in `core/types/blocks.ts`
-- Preset copying from `core/presets/blocks/` is READ-ONLY (always allowed for copying)
+- Preset copying from `core/templates/blocks/` is READ-ONLY (always allowed for copying)
 
 **Integration with theme determination:**
 When determining which theme to work in (STEP 1), also verify that scope allows access to that theme:

package/claude/agents/db-developer.md

@@ -76,11 +76,11 @@ await Read('.rules/api.md')            // API patterns (entity registry, metadat
 
 ### Migration Presets (USE THESE TEMPLATES)
 
-**CRITICAL: Use the standardized templates from `core/presets/migrations/`**
+**CRITICAL: Use the standardized templates from `core/templates/migrations/`**
 
 ```typescript
 // Step 1: Determine RLS mode based on entity requirements
-await Read('core/presets/migrations/README.md')
+await Read('core/templates/migrations/README.md')
 
 // Step 2: Select appropriate template folder
 // - team-mode/    → Multi-tenant apps with team isolation
@@ -153,7 +153,7 @@ At the start of task:execute, scope is documented in `context.md` showing allowe
 
 **CRITICAL: Use entity presets as reference when creating new entities.**
 
-Location: `core/presets/theme/entities/tasks/`
+Location: `core/templates/contents/themes/starter/entities/tasks/`
 
 ### Required Files (4-File Structure)
 
@@ -176,10 +176,10 @@ Location: `core/presets/theme/entities/tasks/`
 **Usage:**
 ```bash
 # Inspect preset for patterns before creating new entity
-cat core/presets/theme/entities/tasks/tasks.config.ts   # Entity config
-cat core/presets/theme/entities/tasks/tasks.fields.ts   # Field definitions
-cat core/presets/theme/entities/tasks/tasks.types.ts    # TypeScript types
-cat core/presets/theme/entities/tasks/tasks.service.ts  # Service pattern
+cat core/templates/contents/themes/starter/entities/tasks/tasks.config.ts   # Entity config
+cat core/templates/contents/themes/starter/entities/tasks/tasks.fields.ts   # Field definitions
+cat core/templates/contents/themes/starter/entities/tasks/tasks.types.ts    # TypeScript types
+cat core/templates/contents/themes/starter/entities/tasks/tasks.service.ts  # Service pattern
 ```
 
 ### Entity Service Pattern
@@ -334,7 +334,7 @@ For detailed patterns including:
 
 **Always read:** `.claude/skills/database-migrations/SKILL.md`
 
-**Always use templates from:** `core/presets/migrations/[mode]/`
+**Always use templates from:** `core/templates/migrations/[mode]/`
 
 ### Quick Reference (full details in skill)
 
@@ -520,7 +520,7 @@ core/migrations/
 
 ### Migration Template (USE PRESETS)
 
-**IMPORTANT: Use templates from `core/presets/migrations/[mode]/` instead of writing from scratch!**
+**IMPORTANT: Use templates from `core/templates/migrations/[mode]/` instead of writing from scratch!**
 
 See `.claude/skills/database-migrations/SKILL.md` for complete SQL patterns including:
 - Table structure with field ordering (id → FK → business → system)
@@ -559,8 +559,8 @@ await Read(`${sessionPath}/clickup_task.md`)  // For Team Mode decision
 
 ```typescript
 const mode = 'team-mode' // or 'private-mode', 'shared-mode', 'public-mode'
-await Read(`core/presets/migrations/${mode}/001_entity_table.sql.template`)
-await Read(`core/presets/migrations/${mode}/002_entity_metas.sql.template`)
+await Read(`core/templates/migrations/${mode}/001_entity_table.sql.template`)
+await Read(`core/templates/migrations/${mode}/002_entity_metas.sql.template`)
 ```
 
 ### Step 3: Create Migrations from Templates
@@ -592,7 +592,7 @@ Check PM Decisions in requirements.md:
 
 ### Step 3: Create Migrations
 
-1. **Select RLS mode** from `core/presets/migrations/`
+1. **Select RLS mode** from `core/templates/migrations/`
 2. Copy and customize template files
 3. Create sample data migration file
 4. Create/update test users migration
@@ -652,7 +652,7 @@ Before completing, verify:
 - [ ] Created migration files in `migrations/` folder
 
 ### Template Compliance
-- [ ] Used template from `core/presets/migrations/[mode]/`
+- [ ] Used template from `core/templates/migrations/[mode]/`
 - [ ] Selected correct RLS mode (team/private/shared/public)
 - [ ] All `{{VARIABLE}}` placeholders replaced
 

package/claude/agents/db-validator.md

@@ -39,7 +39,7 @@ You are an expert Database Validator responsible for verifying that database mig
 ## Core Mission
 
 Validate that the database is **100% ready for development** by checking:
-1. **Template Compliance**: Migrations follow `core/presets/migrations/` standards
+1. **Template Compliance**: Migrations follow `core/templates/migrations/` standards
 2. **Schema Correctness**: Proper types, naming, and structure
 3. Migrations execute without errors
 4. All expected tables exist with correct schema
@@ -372,7 +372,7 @@ psql $DATABASE_URL -c "SELECT p.id, u.email FROM \"product\" p JOIN \"user\" u O
 
 Before completing, verify:
 
-### Template Compliance (from `core/presets/migrations/`)
+### Template Compliance (from `core/templates/migrations/`)
 - [ ] No snake_case field names
 - [ ] ID type is TEXT (not UUID)
 - [ ] Timestamps use TIMESTAMPTZ NOT NULL DEFAULT now()

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

@@ -71,7 +71,7 @@ sortableBlockGeneric: '[data-cy^="sortable-block-"]',  // OK - needed for prefix
 | 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/presets/theme/tests/cypress/src/core/*POM.ts` |
+| POM Presets | `packages/core/templates/contents/themes/starter/tests/cypress/src/core/*POM.ts` |
 
 ---
 
@@ -93,7 +93,7 @@ sortableBlockGeneric: '[data-cy^="sortable-block-"]',  // OK - needed for prefix
    ```
 
 4. **After sync, update presets:**
-   - `packages/core/presets/theme/tests/cypress/src/core/`
+   - `packages/core/templates/contents/themes/starter/tests/cypress/src/core/`
    - `packages/core/templates/contents/themes/starter/tests/cypress/src/core/`
 
 ---

package/claude/skills/create-plugin/SKILL.md

@@ -57,7 +57,7 @@ Cada plugin DEBE tener un `package.json` con esta estructura:
 ## Prerequisites
 
 - **Command:** `pnpm create:plugin <plugin-name>`
-- **Preset Location:** `core/presets/plugin/`
+- **Preset Location:** `core/templates/contents/plugins/starter/`
 - **Output Location (monorepo):** `plugins/<plugin-name>/`
 - **Output Location (user project):** `contents/plugins/<plugin-name>/`
 
@@ -361,7 +361,7 @@ Each entity requires 4 files:
 | `[entity].types.ts` | TypeScript types |
 | `[entity].service.ts` | Data access service |
 
-**Reference:** `core/presets/theme/entities/tasks/`
+**Reference:** `core/templates/contents/themes/starter/entities/tasks/`
 
 ---
 

package/claude/skills/create-theme/SKILL.md

@@ -53,7 +53,7 @@ Complete guide for scaffolding and configuring new themes from the preset templa
 ## Prerequisites
 
 - **Command:** `pnpm create:theme <theme-name>`
-- **Preset Location:** `core/presets/theme/`
+- **Preset Location:** `core/templates/contents/themes/starter/`
 - **Output Location:** `themes/<theme-name>/`
 
 ---
@@ -250,7 +250,7 @@ Each theme entity requires 4 files:
 | `[entity].types.ts` | TypeScript types |
 | `[entity].service.ts` | Data access service |
 
-**Reference:** `core/presets/theme/entities/tasks/`
+**Reference:** `core/templates/contents/themes/starter/entities/tasks/`
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/ai-workflow",
-  "version": "0.1.0-beta.87",
+  "version": "0.1.0-beta.89",
   "description": "AI workflow templates for NextSpark - Claude Code agents, commands, skills, and multi-editor support",
   "license": "MIT",
   "author": "NextSpark <hello@nextspark.dev>",
@@ -29,6 +29,7 @@
   ],
   "scripts": {
     "setup": "node scripts/setup.mjs",
-    "sync": "node scripts/sync.mjs"
+    "sync": "node scripts/sync.mjs",
+    "postinstall": "node scripts/postinstall.mjs"
   }
 }

package/scripts/postinstall.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * @nextsparkjs/ai-workflow postinstall hook
+ *
+ * Automatically syncs AI workflow files (.claude/, .cursor/, etc.) when the package is updated.
+ * Only runs in NextSpark projects that already have AI workflow set up.
+ *
+ * Debug mode: Set NEXTSPARK_DEBUG=1 to see detailed logs
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname, resolve, isAbsolute } from 'path';
+import { fileURLToPath } from 'url';
+
+const DEBUG = process.env.NEXTSPARK_DEBUG === '1';
+
+function debug(message) {
+  if (DEBUG) {
+    console.log(`  [DEBUG] ${message}`);
+  }
+}
+
+/**
+ * Find the project root by walking up from the current directory
+ * until we find a package.json that isn't inside node_modules
+ */
+function findProjectRoot() {
+  // When running postinstall, we're in node_modules/@nextsparkjs/ai-workflow
+  // We need to find the project root (where the user's package.json is)
+  let current = process.cwd();
+
+  // If we're inside node_modules, walk up to find the project root
+  if (current.includes('node_modules')) {
+    // Go up until we're out of node_modules
+    const parts = current.split('node_modules');
+    current = parts[0].replace(/[/\\]$/, ''); // Remove trailing slash
+  }
+
+  return current;
+}
+
+/**
+ * Validate that the project root path is safe to use
+ */
+function validateProjectRoot(projectRoot) {
+  // Must be an absolute path
+  if (!isAbsolute(projectRoot)) {
+    debug(`Invalid path: not absolute - ${projectRoot}`);
+    return false;
+  }
+
+  // Must exist
+  if (!existsSync(projectRoot)) {
+    debug(`Invalid path: does not exist - ${projectRoot}`);
+    return false;
+  }
+
+  // Resolve to canonical path and verify it doesn't escape
+  const resolved = resolve(projectRoot);
+  if (resolved !== projectRoot && !projectRoot.startsWith(resolved)) {
+    debug(`Invalid path: resolution mismatch - ${projectRoot} vs ${resolved}`);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Detect if we're in a NextSpark project (not the monorepo)
+ */
+function isNextSparkProject(projectRoot) {
+  // If we're in the monorepo, skip
+  const pnpmWorkspace = join(projectRoot, 'pnpm-workspace.yaml');
+  if (existsSync(pnpmWorkspace)) {
+    debug('Skipping: monorepo detected (pnpm-workspace.yaml exists)');
+    return false;
+  }
+
+  // Check for package.json with nextspark dependency
+  const pkgPath = join(projectRoot, 'package.json');
+  if (!existsSync(pkgPath)) {
+    debug('Skipping: no package.json found');
+    return false;
+  }
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    const hasNextSpark = !!(deps['@nextsparkjs/core'] || deps['@nextsparkjs/cli']);
+    if (!hasNextSpark) {
+      debug('Skipping: no NextSpark dependencies found');
+    }
+    return hasNextSpark;
+  } catch {
+    debug('Skipping: failed to parse package.json');
+    return false;
+  }
+}
+
+/**
+ * Check if the project has a .claude/ folder (AI workflow already set up)
+ */
+function hasAIWorkflowSetup(projectRoot) {
+  const hasClaudeDir = existsSync(join(projectRoot, '.claude'));
+  if (!hasClaudeDir) {
+    debug('Skipping: no .claude/ folder found (AI workflow not set up yet)');
+  }
+  return hasClaudeDir;
+}
+
+/**
+ * Find the setup.mjs script path relative to this postinstall script
+ */
+function getSetupScriptPath() {
+  // This script is at packages/ai-workflow/scripts/postinstall.mjs
+  // setup.mjs is at packages/ai-workflow/scripts/setup.mjs
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  const setupPath = join(__dirname, 'setup.mjs');
+
+  if (existsSync(setupPath)) {
+    return setupPath;
+  }
+
+  debug(`Setup script not found at ${setupPath}`);
+  return null;
+}
+
+// Main execution
+try {
+  const projectRoot = findProjectRoot();
+  debug(`Project root: ${projectRoot}`);
+
+  // Validate project root path
+  if (!validateProjectRoot(projectRoot)) {
+    debug('Skipping: invalid project root path');
+    process.exit(0);
+  }
+
+  // Only run in NextSpark projects with an existing .claude/ folder
+  if (isNextSparkProject(projectRoot) && hasAIWorkflowSetup(projectRoot)) {
+    console.log('\n  📦 @nextsparkjs/ai-workflow updated - syncing AI workflow files...\n');
+
+    const setupScript = getSetupScriptPath();
+    if (setupScript) {
+      try {
+        execSync(`node "${setupScript}" claude`, {
+          stdio: 'inherit',
+          cwd: projectRoot,
+        });
+      } catch (syncError) {
+        console.warn('\n  ⚠️  Auto-sync failed. Run manually: npx nextspark sync:ai\n');
+        debug(`Sync error: ${syncError.message}`);
+      }
+    } else {
+      debug('Skipping: setup.mjs script not found');
+    }
+  }
+} catch (error) {
+  // Postinstall hooks should not break installations
+  // The user can always run the sync manually
+  if (DEBUG) {
+    console.warn('\n  [DEBUG] Postinstall error:', error.message);
+    if (error.stack) {
+      console.warn(error.stack);
+    }
+  }
+}