@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/commands/session/test-write.md

@@ -0,0 +1,242 @@
+# /session:test:write
+
+Write or update Cypress tests (API and UAT) for a feature.
+
+---
+
+## Required Skills
+
+**[MANDATORY]** Read these skills before executing:
+- `.claude/skills/cypress-api/SKILL.md` - API testing patterns
+- `.claude/skills/cypress-e2e/SKILL.md` - E2E/UAT testing patterns
+- `.claude/skills/cypress-selectors/SKILL.md` - data-cy selector conventions
+- `.claude/skills/pom-patterns/SKILL.md` - Page Object Model patterns
+
+---
+
+## Syntax
+
+```
+/session:test:write [--type <api|uat|both>]
+```
+
+---
+
+## Behavior
+
+Generates Cypress tests based on session requirements and existing patterns.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:test:write                                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load session context                                        │
+│     - Read requirements.md (ACs)                                │
+│     - Read plan.md (entities)                                   │
+│     ↓                                                           │
+│  2. Check for existing POMs                                     │
+│     - Reuse if available                                        │
+│     - Create if needed                                          │
+│     ↓                                                           │
+│  3. Generate API tests                                          │
+│     - CRUD operations                                           │
+│     - Auth scenarios                                            │
+│     - Error cases                                               │
+│     ↓                                                           │
+│  4. Generate UAT tests                                          │
+│     - User flows from ACs                                       │
+│     - Visual verification                                       │
+│     ↓                                                           │
+│  5. Validate selectors exist                                    │
+│     ↓                                                           │
+│  6. Create test files                                           │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🧪 WRITE TESTS
+
+Session: stories/2026-01-11-new-products-entity
+Type: both (API + UAT)
+
+─────────────────────────────────────────
+
+📋 ANALYZING REQUIREMENTS
+
+ACs to cover:
+├─ AC1: Admin can create a new product
+├─ AC2: Admin can upload product images
+├─ AC3: Admin can assign products to categories
+├─ AC4: Products are listed with pagination
+└─ AC5: Team members can view products
+
+Entity: products
+API Endpoints: 5 (CRUD + list)
+
+─────────────────────────────────────────
+
+🔍 CHECKING EXISTING POMs
+
+├─ DashboardPOM: exists ✓
+├─ EntityFormPOM: exists ✓
+└─ ProductsPOM: not found
+
+Creating ProductsPOM...
+✓ Created: cypress/support/pom/ProductsPOM.ts
+
+─────────────────────────────────────────
+
+📝 GENERATING API TESTS
+
+File: cypress/e2e/api/products.cy.ts
+
+```typescript
+import { BaseAPIController } from '@/cypress/support/api/BaseAPIController';
+
+describe('@api @products Products API', () => {
+  const api = new ProductsAPIController();
+
+  describe('@crud CRUD Operations', () => {
+    it('@create should create a product', () => {
+      api.create({
+        name: 'Test Product',
+        price: 99.99,
+        categoryId: fixtures.categoryId
+      }).then((response) => {
+        expect(response.status).to.eq(201);
+        expect(response.body.name).to.eq('Test Product');
+      });
+    });
+
+    it('@read should get product by ID', () => {
+      api.getById(fixtures.productId).then((response) => {
+        expect(response.status).to.eq(200);
+      });
+    });
+
+    it('@update should update product', () => {
+      api.update(fixtures.productId, { name: 'Updated' })
+        .then((response) => {
+          expect(response.status).to.eq(200);
+        });
+    });
+
+    it('@delete should delete product', () => {
+      api.delete(fixtures.productId).then((response) => {
+        expect(response.status).to.eq(200);
+      });
+    });
+  });
+
+  describe('@auth Authentication', () => {
+    it('@apikey should work with API key', () => {
+      // API key authentication test
+    });
+
+    it('@session should work with session', () => {
+      // Session authentication test
+    });
+
+    it('@unauthorized should reject unauthenticated', () => {
+      api.unauthorized().create({}).then((response) => {
+        expect(response.status).to.eq(401);
+      });
+    });
+  });
+});
+```
+
+─────────────────────────────────────────
+
+📝 GENERATING UAT TESTS
+
+File: cypress/e2e/uat/products.cy.ts
+
+```typescript
+import { ProductsPOM } from '@/cypress/support/pom/ProductsPOM';
+
+describe('@uat @products Products Management', () => {
+  const pom = new ProductsPOM();
+
+  beforeEach(() => {
+    cy.login('admin@test.com');
+  });
+
+  describe('@ac1 Create Product', () => {
+    it('should create a new product', () => {
+      pom.navigateToList();
+      pom.clickNewProduct();
+      pom.fillForm({
+        name: 'New Product',
+        price: '49.99',
+        description: 'Test description'
+      });
+      pom.submitForm();
+      pom.verifySuccessToast('Product created');
+    });
+  });
+
+  describe('@ac4 List Products', () => {
+    it('should display products with pagination', () => {
+      pom.navigateToList();
+      pom.verifyProductsDisplayed();
+      pom.verifyPaginationControls();
+      pom.goToNextPage();
+      pom.verifyPageChanged();
+    });
+  });
+});
+```
+
+─────────────────────────────────────────
+
+✅ SELECTOR VALIDATION
+
+- [x] data-cy="products-list" exists
+- [x] data-cy="new-product-btn" exists
+- [x] data-cy="product-form" exists
+- [x] data-cy="submit-btn" exists
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Files created:
+├─ cypress/e2e/api/products.cy.ts (12 tests)
+├─ cypress/e2e/uat/products.cy.ts (8 tests)
+└─ cypress/support/pom/ProductsPOM.ts
+
+Total tests: 20
+ACs covered: 5/5
+
+Next: /session:test:run to execute tests
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--type <type>` | api, uat, or both (default: both) |
+| `--ac <number>` | Generate for specific AC |
+| `--from-pom` | Use existing POM without changes |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:test:run` | Run the tests |
+| `/session:test:fix` | Fix failing tests |

package/claude/commands/session/validate.md

@@ -0,0 +1,162 @@
+# /session:validate
+
+Validate the current session state and implementation.
+
+---
+
+## Syntax
+
+```
+/session:validate [--full]
+```
+
+---
+
+## Behavior
+
+Runs validation checks on the current session implementation.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:validate                                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load session context                                        │
+│     - Read scope.json                                           │
+│     - Read progress.md                                          │
+│     ↓                                                           │
+│  2. Run validation checks                                       │
+│     - TypeScript compilation                                    │
+│     - Lint rules                                                │
+│     - Build process                                             │
+│     ↓                                                           │
+│  3. Run tests (if --full)                                       │
+│     - Unit tests                                                │
+│     - API tests                                                 │
+│     - UAT tests                                                 │
+│     ↓                                                           │
+│  4. Check ACs completion                                        │
+│     - Compare with requirements.md                              │
+│     ↓                                                           │
+│  5. Generate validation report                                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+✅ SESSION VALIDATION
+
+Session: stories/2026-01-11-new-products-entity
+
+─────────────────────────────────────────
+
+🔧 BUILD CHECKS
+
+TypeScript:  ✓ No errors
+Lint:        ✓ No warnings
+Build:       ✓ Successful
+
+─────────────────────────────────────────
+
+🧪 TEST RESULTS
+
+Unit Tests:  ✓ 12/12 passing
+API Tests:   ✓ 8/8 passing
+UAT Tests:   ✓ 5/5 passing
+
+─────────────────────────────────────────
+
+📋 AC VERIFICATION
+
+AC1: Create product          ✓ Implemented
+AC2: Upload images           ✓ Implemented
+AC3: Assign categories       ✓ Implemented
+AC4: List with pagination    ✓ Implemented
+AC5: View-only for members   ✓ Implemented
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+All checks passed: ✓
+ACs completed: 5/5 (100%)
+
+Ready for code review.
+```
+
+---
+
+## With Failures
+
+```
+❌ VALIDATION FAILED
+
+─────────────────────────────────────────
+
+🔧 BUILD CHECKS
+
+TypeScript:  ✓ No errors
+Lint:        ⚠ 2 warnings
+Build:       ✓ Successful
+
+─────────────────────────────────────────
+
+🧪 TEST RESULTS
+
+Unit Tests:  ✓ 12/12 passing
+API Tests:   ❌ 6/8 passing
+  - FAIL: POST /products (validation error)
+  - FAIL: PATCH /products (missing field)
+UAT Tests:   ⏸ Skipped (API failures)
+
+─────────────────────────────────────────
+
+📋 AC VERIFICATION
+
+AC1: Create product          ✓ Implemented
+AC2: Upload images           ⚠ Partial (max limit not enforced)
+AC3: Assign categories       ✓ Implemented
+AC4: List with pagination    ✓ Implemented
+AC5: View-only for members   ❌ Not implemented
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Build: ✓ Pass
+Tests: ❌ 2 failures
+ACs: 3/5 complete
+
+Options:
+[1] Fix issues and re-validate
+[2] View detailed errors
+[3] Continue anyway (not recommended)
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--full` | Run complete test suite |
+| `--quick` | Only build checks, skip tests |
+| `--ac-only` | Only check AC completion |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:execute` | Continue implementation |
+| `/session:review` | Request code review |
+| `/session:close` | Close session |

package/claude/config/context.json

@@ -0,0 +1,40 @@
+{
+  "context": "consumer",
+  "description": "NextSpark application development - Build your app using themes and plugins",
+
+  "capabilities": {
+    "modifyCore": false,
+    "allThemes": false,
+    "allPlugins": true,
+    "createReleases": false,
+    "maintainWorkflows": false
+  },
+
+  "allowedPaths": [
+    "contents/themes/${NEXT_PUBLIC_ACTIVE_THEME}/**/*",
+    "contents/plugins/**/*",
+    ".claude/sessions/**/*"
+  ],
+
+  "restrictions": {
+    "core": {
+      "level": "forbidden",
+      "message": "Core is installed via npm (node_modules/) and cannot be modified. To customize behavior, create a theme override or plugin instead."
+    },
+    "otherThemes": {
+      "level": "forbidden",
+      "message": "Only the active theme (NEXT_PUBLIC_ACTIVE_THEME) can be modified. To work on a different theme, update your .env file."
+    },
+    "app": {
+      "level": "discouraged",
+      "requiresExplicitConfirmation": true,
+      "message": "Modifying /app directly is discouraged as it reduces portability. Use theme page overrides when possible. Only proceed if user explicitly requests and understands the trade-offs."
+    }
+  },
+
+  "notes": {
+    "gettingStarted": "Your active theme is defined in .env (NEXT_PUBLIC_ACTIVE_THEME). All customizations should go there.",
+    "creatingPlugins": "Use /create:plugin to scaffold a new plugin in contents/plugins/.",
+    "needCoreChanges": "If you need functionality not available in core, create a plugin or request the feature in NextSpark repository."
+  }
+}

package/claude/config/github.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "./github.schema.json",
+
+  "repository": {
+    "name": "",
+    "defaultBranch": "main"
+  },
+
+  "gitflow": {
+    "environments": ["develop", "qa", "main"],
+    "featureBranch": {
+      "baseBranch": "main",
+      "targetBranch": "develop"
+    },
+    "hotfixBranch": {
+      "baseBranch": "main",
+      "targetBranch": "main",
+      "skipEnvironments": true
+    },
+    "promotionFlow": {
+      "develop": "qa",
+      "qa": "main"
+    }
+  },
+
+  "branches": {
+    "pattern": "{type}/{issue-key}-{description}-{initials}",
+    "types": {
+      "feature": {
+        "description": "New features or enhancements",
+        "base": "main",
+        "target": "develop"
+      },
+      "bugfix": {
+        "description": "Non-urgent bug fixes",
+        "base": "main",
+        "target": "develop"
+      },
+      "hotfix": {
+        "description": "Urgent production fixes",
+        "base": "main",
+        "target": "main"
+      },
+      "chore": {
+        "description": "Maintenance tasks, deps updates",
+        "base": "main",
+        "target": "develop"
+      }
+    }
+  },
+
+  "commits": {
+    "pattern": "[{issue-key}] {description}",
+    "requireIssueKey": true,
+    "suggestedPrefixes": ["Add", "Fix", "Update", "Refactor", "Remove", "Improve", "Implement"]
+  },
+
+  "pullRequests": {
+    "titlePattern": "[{issue-key}] {description}",
+    "bodyTemplate": "## Description\n{description}\n\n## Changes\n- \n\n## Testing\n- [ ] \n\n## Screenshots\n\n\n## Related Issues\n- {issue-key}",
+    "squashMerge": true,
+    "deleteBranchOnMerge": true
+  },
+
+  "reviewers": {
+    "source": ".claude/config/team.json",
+    "askUserToSelect": true
+  }
+}

package/claude/config/github.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GitHub Workflow Configuration",
+  "type": "object",
+  "properties": {
+    "repository": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Repository name in format: organization/repo-name"
+        },
+        "defaultBranch": {
+          "type": "string",
+          "default": "main"
+        }
+      },
+      "required": ["defaultBranch"]
+    },
+    "gitflow": {
+      "type": "object",
+      "properties": {
+        "environments": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Ordered list of environment branches from dev to prod",
+          "default": ["develop", "qa", "main"]
+        },
+        "featureBranch": {
+          "type": "object",
+          "properties": {
+            "baseBranch": { "type": "string", "default": "main" },
+            "targetBranch": { "type": "string", "default": "develop" }
+          }
+        },
+        "hotfixBranch": {
+          "type": "object",
+          "properties": {
+            "baseBranch": { "type": "string", "default": "main" },
+            "targetBranch": { "type": "string", "default": "main" },
+            "skipEnvironments": { "type": "boolean", "default": true }
+          }
+        },
+        "promotionFlow": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Maps source branch to target branch for promotions"
+        }
+      }
+    },
+    "branches": {
+      "type": "object",
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "description": "Branch naming pattern with placeholders: {type}, {issue-key}, {description}, {initials}"
+        },
+        "types": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "description": { "type": "string" },
+              "base": { "type": "string" },
+              "target": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "commits": {
+      "type": "object",
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "description": "Commit message pattern with placeholders: {issue-key}, {description}"
+        },
+        "requireIssueKey": { "type": "boolean", "default": true },
+        "suggestedPrefixes": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "pullRequests": {
+      "type": "object",
+      "properties": {
+        "titlePattern": { "type": "string" },
+        "bodyTemplate": { "type": "string" },
+        "squashMerge": { "type": "boolean", "default": true },
+        "deleteBranchOnMerge": { "type": "boolean", "default": true }
+      }
+    },
+    "reviewers": {
+      "type": "object",
+      "properties": {
+        "source": {
+          "type": "string",
+          "default": ".claude/config/team.json",
+          "description": "Reference to team config file"
+        },
+        "askUserToSelect": { "type": "boolean", "default": true }
+      }
+    }
+  }
+}

package/claude/config/team.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "./team.schema.json",
+
+  "members": [],
+
+  "roles": {
+    "lead": {
+      "description": "Team lead with full permissions",
+      "defaultPermissions": {
+        "canReview": true,
+        "canMerge": true,
+        "canApproveProduction": true
+      }
+    },
+    "developer": {
+      "description": "Developer with standard permissions",
+      "defaultPermissions": {
+        "canReview": true,
+        "canMerge": true,
+        "canApproveProduction": false
+      }
+    },
+    "junior": {
+      "description": "Junior developer requiring review",
+      "defaultPermissions": {
+        "canReview": false,
+        "canMerge": false,
+        "canApproveProduction": false
+      }
+    },
+    "qa": {
+      "description": "QA engineer",
+      "defaultPermissions": {
+        "canReview": false,
+        "canMerge": false,
+        "canApproveProduction": false
+      }
+    }
+  },
+
+  "reviewRules": {
+    "minRequired": 1,
+    "requireQaForProduction": false,
+    "defaultReviewers": []
+  }
+}