aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/workflows/audit-only.yaml

@@ -0,0 +1,198 @@
+# Audit-Only Workflow
+# Generate shock report and ROI for executive stakeholders (10% of use cases)
+
+workflow:
+  id: "design-system-audit-only"
+  name: "Design System Audit-Only"
+  description: "Audit-only workflow: scan codebase for UI chaos, generate visual shock report and ROI calculation for stakeholder presentation. Mandatory governance protocol: squads/design/protocols/ai-first-governance.md"
+  version: "2.0.0"
+  type: "sequential"
+
+metadata:
+  author: "Brad (Design System Architect)"
+  created_date: "2025-10-27"
+  last_modified: "2026-02-16"
+  tags:
+    - design-system
+    - audit
+    - shock-report
+    - roi
+    - executive
+    - brad
+
+inputs:
+  codebase_path:
+    type: "string"
+    description: "Path to codebase for audit (e.g., ./src)"
+    required: true
+    validation: "Must be valid directory path"
+
+  project_name:
+    type: "string"
+    description: "Project name for output organization"
+    required: true
+    default: "my-app"
+
+  hourly_rate:
+    type: "number"
+    description: "Developer hourly rate for ROI calculation (USD)"
+    required: false
+    default: 150
+
+  team_size:
+    type: "number"
+    description: "Number of developers on team"
+    required: false
+    default: 5
+
+steps:
+  - id: "step_1_audit"
+    name: "Audit Codebase for Pattern Redundancy"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*audit"
+    inputs:
+      path: "{{codebase_path}}"
+    outputs:
+      inventory_report: "outputs/design-system/{{project_name}}/audit/inventory.yaml"
+      state_file: "outputs/design-system/{{project_name}}/.state.yaml"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_2_consolidate"
+    name: "Consolidate Patterns for Metrics"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*consolidate"
+    inputs:
+      inventory: "{{step_1_audit.inventory_report}}"
+    outputs:
+      consolidation_report: "outputs/design-system/{{project_name}}/consolidation/decisions.yaml"
+      reduction_metrics: "outputs/design-system/{{project_name}}/consolidation/metrics.yaml"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_3_shock_report"
+    name: "Generate Visual Shock Report"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*shock-report"
+    inputs:
+      inventory: "{{step_1_audit.inventory_report}}"
+      consolidation: "{{step_2_consolidate.consolidation_report}}"
+    outputs:
+      shock_report_html: "outputs/design-system/{{project_name}}/reports/shock-report.html"
+      shock_report_pdf: "outputs/design-system/{{project_name}}/reports/shock-report.pdf"
+      screenshots: "outputs/design-system/{{project_name}}/reports/screenshots/"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_4_calculate_roi"
+    name: "Calculate ROI and Cost Savings"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*calculate-roi"
+    inputs:
+      consolidation: "{{step_2_consolidate.consolidation_report}}"
+      reduction_metrics: "{{step_2_consolidate.reduction_metrics}}"
+      hourly_rate: "{{hourly_rate}}"
+      team_size: "{{team_size}}"
+    outputs:
+      roi_report: "outputs/design-system/{{project_name}}/reports/roi.yaml"
+      roi_summary: "outputs/design-system/{{project_name}}/reports/roi-summary.md"
+      executive_summary: "outputs/design-system/{{project_name}}/reports/executive-summary.pdf"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_5_tokenize_preview"
+    name: "Preview Token Recommendations (Optional)"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*tokenize"
+    inputs:
+      consolidation: "{{step_2_consolidate.consolidation_report}}"
+      preview_mode: true
+    outputs:
+      token_preview: "outputs/design-system/{{project_name}}/reports/token-preview.yaml"
+    error_handling:
+      strategy: "skip"
+
+outputs:
+  audit_complete:
+    type: "boolean"
+    description: "Audit completed successfully"
+    source: "step_4_calculate_roi.success"
+
+  shock_report_location:
+    type: "string"
+    description: "Path to visual shock report (HTML)"
+    source: "step_3_shock_report.shock_report_html"
+
+  roi_summary_location:
+    type: "string"
+    description: "Path to ROI summary (Markdown)"
+    source: "step_4_calculate_roi.roi_summary"
+
+  executive_summary_location:
+    type: "string"
+    description: "Path to executive summary (PDF)"
+    source: "step_4_calculate_roi.executive_summary"
+
+  pattern_count_before:
+    type: "number"
+    description: "Total patterns before consolidation"
+    source: "step_2_consolidate.reduction_metrics.before"
+
+  pattern_count_after:
+    type: "number"
+    description: "Recommended patterns after consolidation"
+    source: "step_2_consolidate.reduction_metrics.after"
+
+  reduction_percentage:
+    type: "number"
+    description: "Pattern reduction percentage"
+    source: "step_2_consolidate.reduction_metrics.reduction_percent"
+
+  annual_savings_usd:
+    type: "number"
+    description: "Projected annual cost savings (USD)"
+    source: "step_4_calculate_roi.roi_report.annual_savings"
+
+  roi_ratio:
+    type: "number"
+    description: "ROI ratio (savings/investment)"
+    source: "step_4_calculate_roi.roi_report.roi_ratio"
+
+  breakeven_days:
+    type: "number"
+    description: "Days to breakeven"
+    source: "step_4_calculate_roi.roi_report.breakeven_days"
+
+global_error_handling:
+  on_error: "abort"
+  notification:
+    enabled: true
+    channels:
+      - console
+
+security:
+  authorization_required: false
+  audit_logging: true
+
+quality_gates:
+  internal_quality_chain:
+    required:
+      - "node squads/design/scripts/design-system/generate_components_metadata.cjs"
+      - "node squads/design/scripts/design-system/validate_components_metadata.cjs"
+      - "node squads/design/scripts/design-system/sync_design_manifest.cjs"
+      - "node squads/design/scripts/design-system/validate_design_manifest_drift.cjs"
+      - "node squads/design/scripts/design-system/validate_task_checklist_bindings.cjs"
+      - "node squads/design/scripts/design-system/validate_mcp_skeleton.cjs"
+    optional:
+      - "node squads/design/scripts/design-system/test_mcp_tools.cjs"
+    blocking: true
+    policy: "internal-first"
+    exception:
+      external_tool_allowed_with:
+        - "capability_gap_documented"
+        - "rationale_recorded"

package/pro/squads/design/workflows/brownfield-complete.yaml

@@ -0,0 +1,257 @@
+# Brownfield Complete Workflow
+# Most common use case (70%) - audit existing codebase through component building
+
+workflow:
+  id: "design-system-brownfield-complete"
+  name: "Design System Brownfield Complete"
+  description: "Complete workflow for brownfield projects: audit UI chaos, consolidate patterns, extract tokens, plan migration, then build production components. Mandatory governance protocol: squads/design/protocols/ai-first-governance.md"
+  version: "2.0.0"
+  type: "sequential"
+
+metadata:
+  author: "Brad (Design System Architect)"
+  created_date: "2025-10-27"
+  last_modified: "2026-02-16"
+  tags:
+    - design-system
+    - brownfield
+    - audit
+    - consolidation
+    - components
+    - brad
+
+inputs:
+  codebase_path:
+    type: "string"
+    description: "Path to codebase for audit (e.g., ./src)"
+    required: true
+    validation: "Must be valid directory path"
+
+  project_name:
+    type: "string"
+    description: "Project name for output organization"
+    required: true
+    default: "my-app"
+
+steps:
+  - id: "step_1_audit"
+    name: "Audit Codebase for Pattern Redundancy"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*audit"
+    inputs:
+      path: "{{codebase_path}}"
+    outputs:
+      inventory_report: "outputs/design-system/{{project_name}}/audit/inventory.yaml"
+      state_file: "outputs/design-system/{{project_name}}/.state.yaml"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_2_consolidate"
+    name: "Consolidate Patterns Using Clustering"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*consolidate"
+    inputs:
+      inventory: "{{step_1_audit.inventory_report}}"
+    outputs:
+      consolidation_report: "outputs/design-system/{{project_name}}/consolidation/decisions.yaml"
+      reduction_metrics: "outputs/design-system/{{project_name}}/consolidation/metrics.yaml"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_3_tokenize"
+    name: "Extract Design Tokens"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*tokenize"
+    inputs:
+      consolidation: "{{step_2_consolidate.consolidation_report}}"
+    outputs:
+      tokens_yaml: "outputs/design-system/{{project_name}}/tokens/tokens.yaml"
+      tokens_json: "outputs/design-system/{{project_name}}/tokens/tokens.json"
+      tokens_css: "outputs/design-system/{{project_name}}/tokens/tokens.css"
+      tokens_tailwind: "outputs/design-system/{{project_name}}/tokens/tokens.tailwind.js"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_4_migrate"
+    name: "Generate Migration Strategy"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*migrate"
+    inputs:
+      tokens: "{{step_3_tokenize.tokens_yaml}}"
+      consolidation: "{{step_2_consolidate.consolidation_report}}"
+    outputs:
+      migration_plan: "outputs/design-system/{{project_name}}/migration/plan.md"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_5_shock_report"
+    name: "Generate Shock Report (Optional)"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*shock-report"
+    inputs:
+      inventory: "{{step_1_audit.inventory_report}}"
+      consolidation: "{{step_2_consolidate.consolidation_report}}"
+    outputs:
+      shock_report: "outputs/design-system/{{project_name}}/reports/shock-report.html"
+    error_handling:
+      strategy: "skip"
+
+  - id: "step_6_calculate_roi"
+    name: "Calculate ROI (Optional)"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*calculate-roi"
+    inputs:
+      consolidation: "{{step_2_consolidate.consolidation_report}}"
+    outputs:
+      roi_report: "outputs/design-system/{{project_name}}/reports/roi.yaml"
+    error_handling:
+      strategy: "skip"
+
+  - id: "step_7_build_atoms"
+    name: "Build Atomic Components"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*build"
+    inputs:
+      tokens: "{{step_3_tokenize.tokens_yaml}}"
+      patterns: "button,input,label,icon"
+    outputs:
+      components: "outputs/design-system/{{project_name}}/components/atoms/"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_8_compose_molecules"
+    name: "Compose Molecule Components"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*compose"
+    inputs:
+      atoms: "{{step_7_build_atoms.components}}"
+      patterns: "form-field,card,alert"
+    outputs:
+      molecules: "outputs/design-system/{{project_name}}/components/molecules/"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_9_document"
+    name: "Generate Pattern Library Documentation"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*document"
+    inputs:
+      components: "outputs/design-system/{{project_name}}/components/"
+      tokens: "{{step_3_tokenize.tokens_yaml}}"
+    outputs:
+      documentation: "outputs/design-system/{{project_name}}/docs/"
+      storybook: "outputs/design-system/{{project_name}}/.storybook/"
+    error_handling:
+      strategy: "skip"
+
+  - id: "step_10_promote_to_workspace"
+    name: "Promote Outputs to Workspace Canonical Locations"
+    type: "agent"
+    agent: "brad-frost"
+    command: "*sync-registry"
+    description: "Move outputs from outputs/ to workspace canonical paths"
+    inputs:
+      tokens_source: "{{step_3_tokenize.tokens_yaml}}"
+      components_source: "outputs/design-system/{{project_name}}/components/"
+    outputs:
+      tokens_promoted: "workspace/system/tokens/"
+      registry_updated: "workspace/ui/registry.json"
+      metadata_updated: "workspace/domains/design-system/metadata/components.json"
+    promotion_map:
+      - from: "outputs/design-system/{{project_name}}/tokens/tokens.json"
+        to: "workspace/system/tokens/primitive.tokens.json"
+      - from: "outputs/design-system/{{project_name}}/tokens/tokens.yaml"
+        to: "squads/design/data/design-tokens-spec.yaml"
+      - from: "outputs/design-system/{{project_name}}/components/"
+        to: "workspace/ui/components/"
+    validation:
+      - "workspace/ui/registry.json updated with new components"
+      - "workspace/domains/design-system/metadata/components.json reflects changes"
+      - "squads/design/scripts/design-system/validate_components_metadata.cjs passes"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_11_critical_eye"
+    name: "Run Critical Eye Curation Cycle"
+    type: "workflow"
+    agent: "brad-frost"
+    workflow: "critical-eye"
+    description: "Evaluate all promoted patterns through the Critical Eye scoring engine. Scores variants (0-100), applies lifecycle transitions, generates proposals for canonical promotion. Non-blocking — brownfield completes even if curation is skipped."
+    inputs:
+      catalog: "workspace/ui/pattern-catalog.json"
+      scoring_rules: "squads/design/data/critical-eye-scoring-rules.yaml"
+      decisions_log: "workspace/ui/canonical-decisions.json"
+    outputs:
+      catalog_updated: "workspace/ui/pattern-catalog.json"
+      cycle_report: "outputs/design-system/critical-eye/cycle-{{cycle_number}}/report.md"
+    error_handling:
+      strategy: "skip"
+
+outputs:
+  design_system_complete:
+    type: "boolean"
+    description: "Workflow completed successfully"
+    source: "step_10_promote_to_workspace.success"
+
+  tokens_location:
+    type: "string"
+    description: "Path to design tokens"
+    source: "step_3_tokenize.tokens_yaml"
+
+  components_location:
+    type: "string"
+    description: "Path to generated components"
+    source: "outputs/design-system/{{project_name}}/components/"
+
+  migration_plan_location:
+    type: "string"
+    description: "Path to migration plan"
+    source: "step_4_migrate.migration_plan"
+
+  shock_report_location:
+    type: "string"
+    description: "Path to shock report (if generated)"
+    source: "step_5_shock_report.shock_report"
+
+  roi_metrics:
+    type: "string"
+    description: "ROI calculation results"
+    source: "step_6_calculate_roi.roi_report"
+
+global_error_handling:
+  on_error: "abort"
+  notification:
+    enabled: true
+    channels:
+      - console
+
+security:
+  authorization_required: false
+  audit_logging: true
+
+quality_gates:
+  internal_quality_chain:
+    required:
+      - "node squads/design/scripts/design-system/generate_components_metadata.cjs"
+      - "node squads/design/scripts/design-system/validate_components_metadata.cjs"
+      - "node squads/design/scripts/design-system/sync_design_manifest.cjs"
+      - "node squads/design/scripts/design-system/validate_design_manifest_drift.cjs"
+      - "node squads/design/scripts/design-system/validate_task_checklist_bindings.cjs"
+      - "node squads/design/scripts/design-system/validate_mcp_skeleton.cjs"
+    optional:
+      - "node squads/design/scripts/design-system/test_mcp_tools.cjs"
+    blocking: true
+    policy: "internal-first"
+    exception:
+      external_tool_allowed_with:
+        - "capability_gap_documented"
+        - "rationale_recorded"

package/pro/squads/design/workflows/critical-eye.yaml

@@ -0,0 +1,184 @@
+# Critical Eye — Continuous DS Curation Workflow
+# Runs at the END of each extraction cycle as a "second critical look"
+# Authority: Nathan Curtis, Brad Frost, GOV.UK, USWDS, Adobe Spectrum
+
+workflow:
+  id: "design-system-critical-eye"
+  name: "Critical Eye — Continuous DS Curation"
+  description: "Recurring workflow that evaluates all pattern variants across categories, scores them (0-100), and promotes/demotes through lifecycle states (CANDIDATE → EXPERIMENTAL → STABLE → CANONICAL → DEPRECATED). Runs after each extraction cycle. Mandatory governance protocol: squads/design/protocols/ai-first-governance.md"
+  version: "1.0.0"
+  type: "sequential"
+
+metadata:
+  author: "Brad Frost (Design System Architect)"
+  created_date: "2026-02-18"
+  last_modified: "2026-02-18"
+  tags:
+    - design-system
+    - curation
+    - critical-eye
+    - scoring
+    - lifecycle
+    - governance
+    - brad
+
+inputs:
+  catalog_path:
+    type: "string"
+    description: "Path to the pattern catalog JSON"
+    required: true
+    default: "workspace/ui/pattern-catalog.json"
+
+  scoring_rules_path:
+    type: "string"
+    description: "Path to the scoring rules YAML"
+    required: true
+    default: "squads/design/data/critical-eye-scoring-rules.yaml"
+
+  decisions_log_path:
+    type: "string"
+    description: "Path to the append-only decisions log"
+    required: true
+    default: "workspace/ui/canonical-decisions.json"
+
+  cycle_number:
+    type: "integer"
+    description: "Current evaluation cycle (auto-incremented from catalog.evaluationCycle)"
+    required: false
+
+  categories_filter:
+    type: "array"
+    description: "Optional: evaluate only specific categories (empty = all)"
+    required: false
+    default: []
+
+steps:
+  - id: "step_1_inventory"
+    name: "Inventory All Variants Per Category"
+    type: "agent"
+    agent: "brad-frost"
+    task: "ds-critical-eye-inventory"
+    description: "Scan pattern-catalog.json and group all variants by category. Detect new variants from latest extraction. Cross-reference with registry.json and metadata."
+    inputs:
+      catalog: "{{catalog_path}}"
+      categories_filter: "{{categories_filter}}"
+    outputs:
+      inventory: "outputs/design-system/critical-eye/cycle-{{cycle_number}}/inventory.json"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_2_score"
+    name: "Score Each Variant Using 5 Dimensions"
+    type: "agent"
+    agent: "brad-frost"
+    task: "ds-critical-eye-score"
+    description: "Apply scoring engine (breadth 25 + quality 30 + consistency 20 + maturity 15 + simplicity 10 = 100) to every variant. Check a11y blocker (score=0 → auto-REJECT)."
+    inputs:
+      inventory: "{{step_1_inventory.inventory}}"
+      scoring_rules: "{{scoring_rules_path}}"
+    outputs:
+      scored_variants: "outputs/design-system/critical-eye/cycle-{{cycle_number}}/scored.json"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_3_compare"
+    name: "Compare and Rank Variants Within Category"
+    type: "agent"
+    agent: "brad-frost"
+    task: "ds-critical-eye-compare"
+    description: "Within each category, rank variants by total score. Apply tiebreaker rule (breadth wins within 10% margin). Identify top candidate per category."
+    inputs:
+      scored_variants: "{{step_2_score.scored_variants}}"
+      scoring_rules: "{{scoring_rules_path}}"
+    outputs:
+      rankings: "outputs/design-system/critical-eye/cycle-{{cycle_number}}/rankings.json"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_4_decide"
+    name: "Make Lifecycle Transition Decisions"
+    type: "agent"
+    agent: "brad-frost"
+    task: "ds-critical-eye-decide"
+    description: "Apply lifecycle transition rules. Auto-transitions (CANDIDATE→EXPERIMENTAL, EXPERIMENTAL→STABLE) execute immediately. Checkpoint transitions (STABLE→CANONICAL, CANONICAL→DEPRECATED) generate proposals for design-chief review."
+    inputs:
+      rankings: "{{step_3_compare.rankings}}"
+      catalog: "{{catalog_path}}"
+      decisions_log: "{{decisions_log_path}}"
+    outputs:
+      decisions: "outputs/design-system/critical-eye/cycle-{{cycle_number}}/decisions.json"
+      proposals: "outputs/design-system/critical-eye/cycle-{{cycle_number}}/proposals.json"
+      updated_catalog: "{{catalog_path}}"
+      updated_decisions_log: "{{decisions_log_path}}"
+    error_handling:
+      strategy: "fail"
+
+  - id: "step_5_review"
+    name: "Human Review for Canonical Promotions"
+    type: "checkpoint"
+    agent: "design-chief"
+    task: "ds-critical-eye-review-checklist"
+    description: "Design Chief reviews proposals for STABLE→CANONICAL and CANONICAL→DEPRECATED transitions. Uses review checklist. Required only when proposals exist."
+    condition: "{{step_4_decide.proposals}} is not empty"
+    inputs:
+      proposals: "{{step_4_decide.proposals}}"
+      rankings: "{{step_3_compare.rankings}}"
+    outputs:
+      review_decisions: "outputs/design-system/critical-eye/cycle-{{cycle_number}}/review-decisions.json"
+    error_handling:
+      strategy: "wait"
+
+  - id: "step_6_report"
+    name: "Generate Cycle Report"
+    type: "agent"
+    agent: "brad-frost"
+    task: "ds-critical-eye-report"
+    description: "Compile comprehensive cycle report: summary stats, all scores, transitions executed, proposals pending, category health."
+    inputs:
+      inventory: "{{step_1_inventory.inventory}}"
+      scored_variants: "{{step_2_score.scored_variants}}"
+      rankings: "{{step_3_compare.rankings}}"
+      decisions: "{{step_4_decide.decisions}}"
+      review_decisions: "{{step_5_review.review_decisions}}"
+      cycle_number: "{{cycle_number}}"
+    outputs:
+      report: "outputs/design-system/critical-eye/cycle-{{cycle_number}}/report.md"
+    error_handling:
+      strategy: "skip"
+
+outputs:
+  cycle_complete:
+    type: "boolean"
+    description: "Critical Eye cycle completed successfully"
+    source: "step_6_report.success"
+
+  catalog_updated:
+    type: "string"
+    description: "Updated pattern catalog with new scores and lifecycle states"
+    source: "{{catalog_path}}"
+
+  decisions_logged:
+    type: "string"
+    description: "Append-only decisions log with new entries"
+    source: "{{decisions_log_path}}"
+
+  report_location:
+    type: "string"
+    description: "Path to the cycle report"
+    source: "step_6_report.report"
+
+  pending_proposals:
+    type: "integer"
+    description: "Number of proposals awaiting human review"
+    source: "step_4_decide.proposals.length"
+
+global_error_handling:
+  on_error: "abort"
+  notification:
+    enabled: true
+    channels:
+      - console
+
+security:
+  authorization_required: false
+  audit_logging: true