@nextsparkjs/ai-workflow 0.1.0-beta.86

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,54 @@
+{
+  "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."
+    }
+  },
+
+  "disabledCommands": [
+    "release:version",
+    "npm-publish",
+    "npm-version",
+    "npm-repackage",
+    "npm-test-local",
+    "npm-test-npm",
+    "workflow-update"
+  ],
+
+  "disabledAgents": [
+    "release-manager"
+  ],
+
+  "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": []
+  }
+}

package/claude/config/team.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Team Configuration",
+  "type": "object",
+  "properties": {
+    "members": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Full name of the team member"
+          },
+          "initials": {
+            "type": "string",
+            "maxLength": 3,
+            "description": "Initials used in branch names"
+          },
+          "role": {
+            "type": "string",
+            "enum": ["lead", "developer", "junior", "qa"],
+            "description": "Team role"
+          },
+          "email": {
+            "type": "string",
+            "format": "email"
+          },
+          "ids": {
+            "type": "object",
+            "properties": {
+              "github": {
+                "type": "string",
+                "description": "GitHub username"
+              },
+              "taskManager": {
+                "type": "string",
+                "description": "User ID in the configured task manager (ClickUp, Jira, etc.)"
+              },
+              "slack": {
+                "type": "string",
+                "description": "Slack member ID"
+              }
+            },
+            "required": ["github"]
+          },
+          "permissions": {
+            "type": "object",
+            "properties": {
+              "canReview": {
+                "type": "boolean",
+                "default": true
+              },
+              "canMerge": {
+                "type": "boolean",
+                "default": true
+              },
+              "canApproveProduction": {
+                "type": "boolean",
+                "default": false
+              }
+            }
+          }
+        },
+        "required": ["name", "initials", "role", "ids"]
+      }
+    },
+    "roles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "description": { "type": "string" },
+          "defaultPermissions": {
+            "type": "object",
+            "properties": {
+              "canReview": { "type": "boolean" },
+              "canMerge": { "type": "boolean" },
+              "canApproveProduction": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "reviewRules": {
+      "type": "object",
+      "properties": {
+        "minRequired": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 1
+        },
+        "requireQaForProduction": {
+          "type": "boolean",
+          "default": false
+        },
+        "defaultReviewers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "GitHub usernames of default reviewers"
+        }
+      }
+    }
+  },
+  "required": ["members"]
+}

package/claude/config/workspace.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "./workspace.schema.json",
+
+  "project": {
+    "name": "",
+    "activeTheme": "default"
+  },
+
+  "preferences": {
+    "language": "en",
+    "defaultWorkflow": "standard",
+    "autoCommit": false,
+    "verboseOutput": false,
+    "confirmDestructive": true
+  },
+
+  "sessions": {
+    "basePath": ".claude/sessions",
+    "autoArchiveAfterDays": 30,
+    "maxActiveStories": 3,
+    "maxActiveTasks": 10
+  },
+
+  "taskManager": {
+    "enabled": false,
+    "provider": "clickup",
+    "syncWithSession": true,
+    "autoUpdateStatus": true,
+    "config": {
+      "apiKey": "${CLICKUP_API_KEY}",
+      "workspaceId": "",
+      "defaultSpace": "",
+      "useMcp": true,
+      "mcpFallback": true
+    }
+  },
+
+  "integrations": {
+    "github": {
+      "enabled": true
+    }
+  },
+
+  "risk": {
+    "aboutPath": "contents/themes/${activeTheme}/about",
+    "alwaysCompleteForCritical": true,
+    "requireConfirmationForHigh": true
+  }
+}

package/claude/config/workspace.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Workspace Configuration",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "activeTheme": { "type": "string" }
+      },
+      "required": ["name"]
+    },
+    "preferences": {
+      "type": "object",
+      "properties": {
+        "language": { "enum": ["es", "en", "pt"] },
+        "defaultWorkflow": { "enum": ["quick", "standard", "complete"] },
+        "autoCommit": { "type": "boolean" },
+        "verboseOutput": { "type": "boolean" },
+        "confirmDestructive": { "type": "boolean" }
+      }
+    },
+    "sessions": {
+      "type": "object",
+      "properties": {
+        "basePath": { "type": "string" },
+        "autoArchiveAfterDays": { "type": "integer", "minimum": 1 },
+        "maxActiveStories": { "type": "integer", "minimum": 1 },
+        "maxActiveTasks": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "taskManager": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "provider": { "enum": ["clickup", "jira", "notion", "asana", "linear", "custom"] },
+        "syncWithSession": { "type": "boolean" },
+        "autoUpdateStatus": { "type": "boolean" },
+        "config": { "type": "object" }
+      }
+    },
+    "integrations": {
+      "type": "object",
+      "properties": {
+        "github": {
+          "type": "object",
+          "description": "GitHub integration - detailed config in .claude/config/github.json",
+          "properties": {
+            "enabled": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "risk": {
+      "type": "object",
+      "properties": {
+        "aboutPath": { "type": "string" },
+        "alwaysCompleteForCritical": { "type": "boolean" },
+        "requireConfirmationForHigh": { "type": "boolean" }
+      }
+    }
+  }
+}