aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/workflows/storybook-full-setup.yaml

@@ -0,0 +1,280 @@
+# WF-SB: Storybook Full Setup Pipeline
+# Duration: 1 session
+# Best for: New projects needing complete Storybook + shadcn/ui setup from zero
+# Key Agents: @storybook-expert
+
+workflow:
+  id: wf-storybook-full-setup
+  name: "Storybook Full Setup Pipeline"
+  version: "1.0"
+  orchestrator: "@storybook-expert"
+  duration: "1 session"
+  description: |
+    End-to-end pipeline that takes a project from zero Storybook to fully
+    configured with stories for every component. Handles:
+    - Package installation (Storybook v10 + addons)
+    - Configuration (.storybook/main.ts, preview.ts, theme, CSS)
+    - shadcn/ui component expansion (full catalog ~45 components)
+    - Story generation for ALL components (CSF3, TypeScript strict, autodocs)
+    - Verification (typecheck, lint, build, functional)
+
+    This workflow produces:
+    - Complete Storybook installation and configuration
+    - All shadcn/ui components installed
+    - Story files for every component
+    - Verification report confirming zero errors
+
+  best_for:
+    - "New project needs Storybook from scratch"
+    - "Existing project needs stories for all components"
+    - "Design system documentation setup"
+    - "Component library quality gate setup"
+
+  decision_matrix_fit:
+    awareness: "Setup"
+    sophistication: "Standard"
+    primary_output: "Complete Storybook with all stories"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# PHASE 1: INSTALL (Package Installation)
+# ═══════════════════════════════════════════════════════════════════════════════
+phases:
+  - id: PHASE-1
+    name: "Install Storybook Packages"
+    tier: 0
+    description: |
+      Install Storybook core, framework adapter, and all recommended addons
+      as devDependencies. Detect project framework, select correct adapter,
+      add npm scripts.
+
+    tasks:
+      - task_file: sb-install.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Install all Storybook packages and add scripts"
+        output: "installed_packages, framework_adapter"
+
+    checkpoint:
+      criteria:
+        - "All packages in devDependencies"
+        - "storybook and build-storybook scripts in package.json"
+        - "npx storybook --version returns installed version"
+      human_review: false
+      message: "Packages installed. Proceeding to configuration."
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 2: CONFIGURE (Storybook Config Files)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-2
+    name: "Configure Storybook"
+    tier: 0
+    description: |
+      Create .storybook/main.ts and preview.ts. Configure framework adapter,
+      stories glob, addons, theme toggle, global CSS import. Update .gitignore
+      and ESLint config.
+
+    tasks:
+      - task_file: sb-configure.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Create config files and verify Storybook starts"
+        output: ".storybook/main.ts, .storybook/preview.ts"
+
+    checkpoint:
+      criteria:
+        - ".storybook/main.ts exists with correct framework"
+        - ".storybook/preview.ts exists with theme config"
+        - "storybook-static in .gitignore"
+        - "Storybook dev server starts without errors"
+      human_review: false
+      message: "Configuration complete. Storybook starts successfully."
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 3: EXPAND (shadcn Component Library)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-3
+    name: "Expand shadcn Component Library"
+    tier: 1
+    description: |
+      Install ALL shadcn/ui components via CLI. Detect existing components,
+      install missing ones, apply known fixes (sidebar purity, etc.),
+      preserve custom component customizations.
+
+    tasks:
+      - task_file: sb-expand-shadcn.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Install all shadcn components and apply fixes"
+        output: "installed_components, applied_fixes"
+
+    checkpoint:
+      criteria:
+        - "All target components exist in src/components/ui/"
+        - "npm run typecheck passes"
+        - "npm run lint passes"
+        - "Known shadcn bugs fixed"
+      human_review: false
+      message: "All components installed. Proceeding to story generation."
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 4: GENERATE (Story Files for All Components)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-4
+    name: "Generate Stories for All Components"
+    tier: 1
+    description: |
+      Generate .stories.tsx files for EVERY component. CSF3 format with
+      satisfies Meta<typeof Component>, TypeScript strict, autodocs tags,
+      Portuguese content. Handles simple, compound, form, layout, and
+      custom components with appropriate story strategies.
+
+    tasks:
+      - task_file: sb-generate-all-stories.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Write story files for all components"
+        output: "story_files, coverage_report"
+
+    checkpoint:
+      criteria:
+        - "Every component has a .stories.tsx file"
+        - "npm run typecheck passes"
+        - "npm run lint passes"
+        - "All stories use satisfies Meta pattern"
+        - "All content in Portuguese"
+      human_review: false
+      message: "All stories generated. Running final verification."
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 5: VERIFY (Final Quality Gate)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-5
+    name: "Verify Complete Setup"
+    tier: 2
+    description: |
+      Final verification gate. Runs typecheck, lint, build-storybook,
+      dev server smoke test, and story coverage check. Produces verification
+      report with PASS/FAIL per check.
+
+    tasks:
+      - task_file: sb-verify.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Run all verification checks and produce report"
+        output: "verification_report"
+
+    checkpoint:
+      criteria:
+        - "TypeScript: zero errors"
+        - "Lint: zero errors"
+        - "Build: succeeds"
+        - "Coverage: 100%"
+        - "Dev server: HTTP 200"
+      human_review: true
+      message: "Verification complete. Review report before finalizing."
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# ERROR HANDLING
+# ═══════════════════════════════════════════════════════════════════════════════
+error_handling:
+  on_phase_failure:
+    - log_error: true
+    - notify_stakeholders: false
+    - create_remediation_task: false
+    - halt_workflow: true
+
+  on_checkpoint_failure:
+    - log_failure_reason: true
+    - return_to_previous_phase: false
+    - max_retries: 2
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# COMPLETION SIGNALS
+# ═══════════════════════════════════════════════════════════════════════════════
+completion_signal: "<promise>COMPLETE</promise>"
+checkpoint_signal: "<promise>CHECKPOINT:PHASE-X</promise>"
+blocked_signal: "<promise>BLOCKED:T-X.Y</promise>"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# OUTPUT ARTIFACTS
+# ═══════════════════════════════════════════════════════════════════════════════
+outputs:
+  configuration:
+    - ".storybook/main.ts"
+    - ".storybook/preview.ts"
+    - "package.json (updated devDependencies + scripts)"
+    - ".gitignore (storybook-static)"
+  components:
+    - "src/components/ui/*.tsx (all shadcn components)"
+  stories:
+    - "src/components/ui/*.stories.tsx (one per component)"
+  reports:
+    - "Verification report (typecheck, lint, build, coverage)"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# AGENT ASSIGNMENTS BY PHASE
+# ═══════════════════════════════════════════════════════════════════════════════
+agents_by_phase:
+  PHASE-1:
+    primary:
+      - "@storybook-expert"
+  PHASE-2:
+    primary:
+      - "@storybook-expert"
+  PHASE-3:
+    primary:
+      - "@storybook-expert"
+    secondary:
+      - "@brad-frost"
+  PHASE-4:
+    primary:
+      - "@storybook-expert"
+  PHASE-5:
+    primary:
+      - "@storybook-expert"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# QUALITY CHECKLIST
+# ═══════════════════════════════════════════════════════════════════════════════
+quality_checklist:
+  installation:
+    - "[ ] All Storybook packages installed as devDependencies"
+    - "[ ] Framework adapter matches project framework"
+    - "[ ] npm scripts added (storybook, build-storybook)"
+
+  configuration:
+    - "[ ] main.ts has correct stories glob"
+    - "[ ] preview.ts imports global CSS"
+    - "[ ] Theme toggle works (dark/light)"
+    - "[ ] storybook-static in .gitignore"
+
+  components:
+    - "[ ] All target shadcn components installed"
+    - "[ ] Known generated code bugs fixed"
+    - "[ ] Custom components preserved"
+
+  stories:
+    - "[ ] Every component has .stories.tsx"
+    - "[ ] All use satisfies Meta<typeof Component>"
+    - "[ ] All have tags: ['autodocs']"
+    - "[ ] Content in Portuguese (pt-BR)"
+
+  verification:
+    - "[ ] npm run typecheck — zero errors"
+    - "[ ] npm run lint — zero errors"
+    - "[ ] npm run build-storybook — succeeds"
+    - "[ ] Dev server responds HTTP 200"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# METADATA
+# ═══════════════════════════════════════════════════════════════════════════════
+metadata:
+  version: "1.0"
+  framework: "AIOS Design Squad"
+  created: "2026-02-25"
+  primary_use_case: "Complete Storybook setup from zero to production-ready"
+  key_difference: |
+    Unlike individual story writing (*write-story), this workflow handles
+    the ENTIRE pipeline from package installation to full verification.
+    Based on real-world execution experience with Storybook v10 + shadcn/ui
+    + Tailwind v4 + Next.js.

package/pro/squads/index.js

@@ -0,0 +1,145 @@
+/**
+ * Pro Squads Module
+ *
+ * Example module demonstrating feature gate integration pattern.
+ * This pattern should be followed by all pro modules.
+ *
+ * Usage:
+ *   const { PremiumSquads } = require('@aios-fullstack/pro/squads');
+ *
+ *   // The module will throw ProFeatureError if not licensed
+ *   const squads = new PremiumSquads();
+ *
+ * @module pro/squads
+ * @see ADR-PRO-003 - Feature Gating & Licensing
+ * @see Story PRO-6 - License Key & Feature Gating System
+ */
+
+'use strict';
+
+const { featureGate, ProFeatureError } = require('../license');
+
+/**
+ * Premium Squads - Example pro module with feature gating.
+ *
+ * This class demonstrates the recommended pattern for pro modules:
+ *
+ * 1. Check feature availability in constructor
+ * 2. Use featureGate.require() for hard requirements
+ * 3. Use featureGate.isAvailable() for optional enhancements
+ * 4. Provide graceful fallbacks where appropriate
+ */
+class PremiumSquads {
+  /**
+   * Create PremiumSquads instance.
+   *
+   * @throws {ProFeatureError} If pro.squads.premium is not licensed
+   */
+  constructor() {
+    // PATTERN 1: Hard requirement - throw if not available
+    // Use this for features that cannot work without a license
+    featureGate.require('pro.squads.premium', 'Premium Squads');
+
+    this._initialized = true;
+  }
+
+  /**
+   * List available squad templates.
+   *
+   * @returns {string[]} Array of template names
+   */
+  listTemplates() {
+    const templates = ['basic', 'standard', 'advanced'];
+
+    // PATTERN 2: Optional enhancement - check availability
+    // Use this to enable additional features when licensed
+    if (featureGate.isAvailable('pro.squads.marketplace')) {
+      templates.push('marketplace-template-1', 'marketplace-template-2');
+    }
+
+    return templates;
+  }
+
+  /**
+   * Export squad configuration.
+   *
+   * @param {string} squadName - Name of the squad to export
+   * @returns {{ name: string, config: object }}
+   * @throws {ProFeatureError} If export feature is not licensed
+   */
+  exportSquad(squadName) {
+    // PATTERN 3: Per-method requirement
+    // Use this when specific methods require additional features
+    featureGate.require('pro.squads.export', 'Squad Export');
+
+    return {
+      name: squadName,
+      config: {
+        /* squad configuration */
+      },
+      exportedAt: new Date().toISOString(),
+      exportedBy: 'AIOS Pro',
+    };
+  }
+
+  /**
+   * Check if custom squads are available.
+   *
+   * @returns {boolean}
+   */
+  hasCustomSquads() {
+    // PATTERN 4: Feature availability check for conditional UI
+    // Use this to show/hide UI elements based on license
+    return featureGate.isAvailable('pro.squads.custom');
+  }
+}
+
+/**
+ * Create a premium squad with license check.
+ *
+ * This is a factory function pattern alternative to class constructor.
+ *
+ * @param {object} config - Squad configuration
+ * @returns {object} Squad instance
+ * @throws {ProFeatureError} If not licensed
+ */
+function createPremiumSquad(config) {
+  // Factory function pattern
+  featureGate.require('pro.squads.premium', 'Premium Squads');
+
+  return {
+    name: config.name || 'Unnamed Squad',
+    type: 'premium',
+    config,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Conditionally load premium features.
+ *
+ * This pattern allows core code to conditionally use pro features
+ * without throwing errors.
+ *
+ * @returns {object|null} Premium features or null if not available
+ */
+function loadPremiumFeaturesIfAvailable() {
+  // PATTERN 5: Conditional loading
+  // Use this in core code to optionally enhance with pro features
+  if (!featureGate.isAvailable('pro.squads.premium')) {
+    return null;
+  }
+
+  return {
+    premiumSquads: new PremiumSquads(),
+    hasExport: featureGate.isAvailable('pro.squads.export'),
+    hasCustom: featureGate.isAvailable('pro.squads.custom'),
+    hasMarketplace: featureGate.isAvailable('pro.squads.marketplace'),
+  };
+}
+
+module.exports = {
+  PremiumSquads,
+  createPremiumSquad,
+  loadPremiumFeaturesIfAvailable,
+};

package/pro/squads/squad-creator-pro/.state.json

@@ -0,0 +1,32 @@
+{
+  "version": "1.0",
+  "workflow": null,
+  "current_phase": null,
+  "started_at": null,
+  "last_updated": null,
+  "mode": null,
+  "inputs": {},
+  "phase_status": {
+    "phase_0": "pending",
+    "phase_0_5": "pending",
+    "phase_1": "pending",
+    "phase_2": "pending",
+    "phase_3": "pending",
+    "phase_4": "pending",
+    "phase_5": "pending",
+    "phase_6": "pending"
+  },
+  "checkpoints_passed": [],
+  "subagent_results": {
+    "oalanicolas": {},
+    "pedro-valerio": {}
+  },
+  "minds_to_clone": [],
+  "minds_cloned": [],
+  "metrics": {
+    "total_duration_minutes": 0,
+    "agents_created": 0,
+    "quality_scores": [],
+    "tools_discovered": 0
+  }
+}