@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/design-system-builder/SKILL.md

@@ -1,150 +1,164 @@
 ---
-name: "design-system-builder"
-displayName: "Design System Builder"
-description: "Create and review design system components: API design, token usage, theming, variants, and documentation"
-keywords:
-  [
-    "design system",
-    "components",
-    "component design",
-    "tokens",
-    "theming",
-    "variants",
-    "widget api",
-  ]
+name: design-system-builder
+description: Build and maintain token-driven design systems with reusable components, semantic APIs, variant patterns, and theming support across frameworks.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # Design System Builder
 
-## Overview
+## Purpose
 
-This power helps you create new design system components or update existing ones, ensuring consistent API design, proper token usage, theming support, and comprehensive documentation.
+Guide the creation and maintenance of design systems — the foundational layer of tokens, primitives, and components that ensure visual and behavioral consistency across an application.
 
 ## When to Use
 
-- Creating new One\* components
-- Updating existing One\* components
-- Reviewing component API design
-- Adding new variants to components
-- Ensuring token compliance in components
-
-## Component Design Principles
-
-### 1. Token-Based Styling
-
-```dart
-// ❌ Don't hardcode values
-Container(
-  padding: EdgeInsets.all(16),
-  decoration: BoxDecoration(
-    color: Color(0xFF123456),
-    borderRadius: BorderRadius.circular(8),
-  ),
-)
-
-// ✅ Use design tokens
-Container(
-  padding: EdgeInsets.all(AppSpacing.lg), // Use your spacing tokens
-  decoration: BoxDecoration(
-    color: Theme.of(context).colorScheme.surface, // Use theme colors
-    borderRadius: BorderRadius.circular(AppRadius.md), // Use radius tokens
-  ),
-)
-```
+- Creating a new design system or component library from scratch
+- Adding components to an existing design system
+- Reviewing component APIs for consistency and composability
+- Setting up design tokens (color, spacing, typography, motion)
+- Building theming support (light/dark, brand variants)
+- Auditing an existing system for token coverage or API drift
+
+## Instructions
+
+### Step 1 — Audit the Current State
+
+Before building anything, understand what exists:
+
+1. Inventory existing components — list every reusable UI element
+2. Catalog design tokens — identify hardcoded values that should be tokens
+3. Check naming conventions — are components and tokens named consistently?
+4. Identify gaps — what's missing vs. what the product actually needs?
+
+**DO**: Start from real product needs, not hypothetical components.
+**DON'T**: Build components speculatively — every component must have at least 2 real use cases.
+
+### Step 2 — Define the Token Layer
+
+Tokens are the single source of truth for all visual decisions.
+
+#### Token Categories
 
-### 2. Semantic API
-
-```dart
-// ✅ Semantic, clear API
-class AppButton extends StatelessWidget {
-  final String label;
-  final VoidCallback? onPressed;
-  final bool isLoading;
-  final bool isDisabled;
-  final Widget? leading;
-  final Widget? trailing;
-
-  // Named constructors for variants
-  AppButton.primary({...});
-  AppButton.secondary({...});
-  AppButton.ghost({...});
-}
 ```
+├── color/
+│   ├── primitive/     (blue-500, gray-100 — raw palette)
+│   ├── semantic/      (text-primary, surface-elevated — meaning-based)
+│   └── component/     (button-bg, card-border — component-specific)
+├── spacing/           (space-1 through space-12, based on 4px or 8px grid)
+├── typography/        (font-family, font-size scale, line-height, font-weight)
+├── radius/            (radius-sm, radius-md, radius-lg, radius-full)
+├── shadow/            (shadow-sm, shadow-md, shadow-lg — elevation levels)
+├── motion/            (duration-fast, duration-normal, easing-default)
+└── breakpoint/        (sm, md, lg, xl — responsive thresholds)
+```
+
+**Rules**:
+- Primitive tokens hold raw values (never use directly in components)
+- Semantic tokens reference primitives and encode meaning
+- Component tokens reference semantic tokens for local overrides
+- Never hardcode values in components — always reference tokens
+
+### Step 3 — Design Component APIs
+
+Every component should follow these API principles:
+
+1. **Predictable** — props follow consistent patterns across components
+2. **Composable** — small components combine into larger patterns
+3. **Constrained** — expose only the variants the system supports
+4. **Accessible** — ARIA, keyboard, and screen reader support built-in
+
+#### Component Anatomy
 
-### 3. Composition Over Configuration
-
-```dart
-// ✅ Compose smaller components
-class AppCard extends StatelessWidget {
-  final Widget child;
-  final EdgeInsets? padding;
-  final Color? backgroundColor;
-
-  AppCard.elevated({...}) : this(
-    padding: EdgeInsets.all(AppSpacing.lg),
-    backgroundColor: Theme.of(context).colorScheme.surface,
-    elevation: 2,
-  );
-}
+```
+ComponentName/
+├── index.{ts,tsx}         (public API — exports only what consumers need)
+├── ComponentName.{tsx}    (implementation)
+├── ComponentName.test.{tsx} (unit + interaction tests)
+├── ComponentName.stories.{tsx} (visual documentation)
+├── variants.ts            (variant definitions — size, color, state)
+└── tokens.ts              (component-level token overrides)
 ```
 
-## Component Checklist
+#### Variant Pattern
 
-### API Design
+Use variants (not boolean flags) for visual options:
 
-- [ ] Semantic property names (label, errorText, leading, trailing)
-- [ ] Sensible defaults (minimal required params)
-- [ ] Named constructors for variants
-- [ ] Consistent with other design system components
+```
+// DO: Constrained variants
+<Button variant="primary" size="md" />
+<Button variant="ghost" size="sm" />
 
-### Token Usage
+// DON'T: Boolean flag explosion
+<Button primary large outlined rounded />
+```
 
-- [ ] No hardcoded colors (use theme colors or color tokens)
-- [ ] No hardcoded spacing (use spacing tokens)
-- [ ] No hardcoded typography (use text styles)
-- [ ] No hardcoded radius (use radius tokens)
+### Step 4 — Build Theming Support
 
-### Theming
+Themes override semantic tokens without changing component logic.
 
-- [ ] Respects light/dark theme
-- [ ] Uses theme-aware colors (context.colors)
-- [ ] Adapts to platform (iOS/Android)
+**Light/Dark**:
+- Swap surface lightness, reduce chroma in dark mode
+- Test contrast ratios in both themes
+- Never use `color-scheme: dark` alone — define explicit token overrides
 
-### Variants
+**Brand Variants**:
+- Override only the accent/brand color tokens
+- Keep neutral palette, spacing, and typography consistent across brands
 
-- [ ] Variants defined as enums or named constructors
-- [ ] Each variant has clear use case
-- [ ] Variants share common base implementation
+**Implementation**:
+- CSS: Use CSS custom properties scoped to `[data-theme]` or `:root`
+- JS frameworks: Use context/provider pattern for runtime theming
+- Ensure tokens cascade correctly (component < semantic < primitive)
 
-### Documentation
+### Step 5 — Document and Enforce
 
-- [ ] Doc comment explaining purpose
-- [ ] At least 2 usage examples
-- [ ] Migration notes from raw Flutter widgets
+Every component needs:
 
-### Testing
+1. **API docs** — props table with types, defaults, and descriptions
+2. **Usage examples** — at least one "do" and one "don't"
+3. **Visual examples** — rendered variants (Storybook or equivalent)
+4. **Accessibility notes** — keyboard behavior, ARIA attributes, screen reader output
 
-- [ ] Widget test for each variant
-- [ ] Test disabled/loading states
-- [ ] Test accessibility (semantic labels)
-- [ ] Consider golden tests for visual regression
+**Enforcement**:
+- Lint rules preventing hardcoded values (e.g., no raw hex colors)
+- Visual regression tests for all component variants
+- Bundle size tracking per component
+- Prop type validation / TypeScript strict mode
+
+### Step 6 — Keep the System Small
+
+**Rules for growth**:
+- A component must have ≥ 2 real use cases before extraction
+- Prefer composition over new components — combine existing primitives first
+- Regularly audit for unused or redundant components
+- Remove components that lost their second use case
 
 ## Output Format
 
-When creating/reviewing a component:
+When creating or reviewing design system work, structure responses as:
+
+1. **Token audit** — what's hardcoded vs. tokenized
+2. **Component API** — props, variants, composition points
+3. **Theme compatibility** — does it work in light/dark/brand contexts?
+4. **Code** — implementation with token references, accessibility, tests
+5. **Migration notes** — how to adopt without breaking existing usage
+
+## References
+
+- [references/token-architecture.md](references/token-architecture.md) — token naming, layering, and CSS custom property patterns
+- [references/component-api-checklist.md](references/component-api-checklist.md) — API review checklist for new components
+- [references/theming-patterns.md](references/theming-patterns.md) — light/dark and brand theming implementation
 
-1. **Component Spec** (purpose, variants, API)
-2. **Token Usage** (which tokens are used)
-3. **Implementation Notes** (composition, theming)
-4. **Examples** (2+ usage snippets)
-5. **Tests** (widget tests + golden ideas)
-6. **Migration Notes** (how to replace old widgets)
+## Examples
 
-## Steering Files
+**User**: "Create a Button component for our design system"
 
-- `component_api_guidelines.md` - API design best practices
+**Response approach**: Define variants (primary, secondary, ghost, danger), sizes (sm, md, lg), states (default, hover, active, disabled, loading). Use tokens for all visual properties. Include ARIA attributes, keyboard handling, and loading state. Show usage examples with composition (Button + Icon, ButtonGroup).
 
-## Templates
+**User**: "Audit our design system tokens"
 
-- `one_component_skeleton` - Component template
-- `component_widget_test` - Widget test template
+**Response approach**: Scan codebase for hardcoded values. Categorize them (color, spacing, typography, shadow, radius). Propose token names following the naming convention. Show before/after migration for each category.

package/workflows/powers/devops-engineer/POWER.md

@@ -1,85 +1,148 @@
 ````markdown
 ---
 inclusion: manual
-name: "devops-engineer"
-description: "Use when setting up CI/CD pipelines, containerizing applications, or managing infrastructure as code. Invoke for pipelines, Docker, Kubernetes, cloud platforms, GitOps."
+name: devops-engineer
+description: Design CI/CD pipelines, infrastructure-as-code, monitoring, deployment strategies, and incident response procedures for reliable software delivery.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
-
 # DevOps Engineer
 
-## Overview
+## Purpose
+
+Guide DevOps practices including CI/CD pipeline design, infrastructure-as-code, deployment strategies, monitoring, and incident response. Bridge development and operations for reliable, automated delivery.
+
+## When to Use
+
+- Setting up or improving CI/CD pipelines
+- Designing deployment strategies (blue-green, canary, rolling)
+- Writing infrastructure-as-code (Terraform, Pulumi, CloudFormation)
+- Configuring monitoring, alerting, and observability
+- Building incident response procedures
+- Containerizing applications (Docker, Kubernetes)
+
+## Instructions
+
+### Step 1 — CI/CD Pipeline Design
+
+**Pipeline stages** (in order):
+
+1. **Lint & Format** — static analysis, code formatting (fastest feedback)
+2. **Unit Tests** — isolated logic tests (< 5 min target)
+3. **Build** — compile, bundle, generate artifacts
+4. **Integration Tests** — API, database, service boundary tests
+5. **Security Scan** — dependency audit, SAST, secret scanning
+6. **Deploy to Staging** — automated deployment to pre-production
+7. **E2E / Smoke Tests** — critical path verification on staging
+8. **Deploy to Production** — automated or gated release
+
+**Principles**:
+
+- Fail fast — put the quickest checks first
+- Parallelize independent stages
+- Cache dependencies between runs (node_modules, Docker layers)
+- Every merge to main should be deployable
+- Never skip tests to "move faster"
+
+### Step 2 — Deployment Strategies
+
+| Strategy      | Risk     | Rollback Speed      | When to Use                                     |
+| ------------- | -------- | ------------------- | ----------------------------------------------- |
+| Rolling       | Low      | Medium              | Default for most services                       |
+| Blue-Green    | Low      | Instant (switch)    | Stateless services, zero-downtime required      |
+| Canary        | Very Low | Fast (route change) | High-traffic services, gradual confidence       |
+| Feature Flags | Very Low | Instant (toggle)    | Decoupling deploy from release                  |
+| Recreate      | High     | Slow (redeploy)     | Only when breaking changes require full restart |
+
+**Rollback plan**: Every deployment must have a documented rollback path that takes < 5 minutes.
+
+### Step 3 — Infrastructure as Code
+
+**Principles**:
+
+- All infrastructure defined in version-controlled code
+- Environments are reproducible from code alone
+- No manual changes to production (drift = risk)
+- Use modules/components for reusable infrastructure patterns
+- Plan before apply — review changes before executing
+
+**Structure**:
+
+```
+infrastructure/
+├── modules/          (reusable components)
+│   ├── networking/
+│   ├── compute/
+│   └── database/
+├── environments/
+│   ├── staging/
+│   └── production/
+└── shared/           (DNS, IAM, secrets)
+```
 
-Senior DevOps engineer specializing in CI/CD pipelines, infrastructure as code, and deployment automation.
+### Step 4 — Monitoring & Alerting
 
-## Role Definition
+**Four Golden Signals** (monitor these for every service):
 
-You are a senior DevOps engineer with 10+ years of experience. You operate with three perspectives:
+| Signal     | Measures               | Example Metric                 |
+| ---------- | ---------------------- | ------------------------------ |
+| Latency    | Time to serve requests | p50, p95, p99 response time    |
+| Traffic    | Demand on the system   | Requests per second            |
+| Errors     | Failed requests        | Error rate (5xx / total)       |
+| Saturation | Resource utilization   | CPU, memory, disk, connections |
 
-- **Build Hat**: Automating build, test, and packaging
-- **Deploy Hat**: Orchestrating deployments across environments
-- **Ops Hat**: Ensuring reliability, monitoring, and incident response
+**Alerting rules**:
 
-## When to Use This Skill
+- Alert on symptoms (high error rate), not causes (high CPU)
+- Every alert must be actionable — if no one needs to act, it's noise
+- Use severity levels: critical (page), warning (ticket), info (dashboard)
+- Include runbook link in every alert
 
-- Setting up CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
-- Containerizing applications (Docker, Docker Compose)
-- Kubernetes deployments and configurations
-- Infrastructure as code (Terraform, Pulumi)
-- Cloud platform configuration (AWS, GCP, Azure)
-- Deployment strategies (blue-green, canary, rolling)
-- Building internal developer platforms and self-service tools
-- Incident response, on-call, and production troubleshooting
-- Release automation and artifact management
+### Step 5 — Incident Response
 
-## Core Workflow
+**Incident lifecycle**:
 
-1. **Assess** - Understand application, environments, requirements
-2. **Design** - Pipeline structure, deployment strategy
-3. **Implement** - IaC, Dockerfiles, CI/CD configs
-4. **Deploy** - Roll out with verification
-5. **Monitor** - Set up observability, alerts
+1. **Detect** — monitoring alerts or user reports
+2. **Respond** — acknowledge, assess severity, assemble responders
+3. **Mitigate** — stop the bleeding (rollback, feature flag, scale up)
+4. **Resolve** — fix root cause
+5. **Review** — blameless postmortem within 48 hours
 
-## Available Steering Files
+**Postmortem template**:
 
-Load detailed guidance on-demand:
+- What happened? (timeline)
+- What was the impact? (users affected, duration)
+- What was the root cause?
+- What prevented earlier detection?
+- Action items (with owners and deadlines)
 
-| Topic          | Reference                           | Load When                                                      |
-| -------------- | ----------------------------------- | -------------------------------------------------------------- |
-| GitHub Actions | `references/github-actions.md`        | Setting up CI/CD pipelines, GitHub workflows                   |
-| Docker         | `references/docker-patterns.md`       | Containerizing applications, writing Dockerfiles               |
-| Kubernetes     | `references/kubernetes.md`            | K8s deployments, services, ingress, pods                       |
-| Terraform      | `references/terraform-iac.md`         | Infrastructure as code, AWS/GCP provisioning                   |
-| Deployment     | `references/deployment-strategies.md` | Blue-green, canary, rolling updates, rollback                  |
-| Platform       | `references/platform-engineering.md`  | Self-service infra, developer portals, golden paths, Backstage |
-| Release        | `references/release-automation.md`    | Artifact management, feature flags, multi-platform CI/CD       |
-| Incidents      | `references/incident-response.md`     | Production outages, on-call, MTTR, postmortems, runbooks       |
+## Output Format
 
-## Constraints
+```
+## DevOps Recommendation
+[approach and reasoning]
 
-### MUST DO
+## Implementation
+[configuration files, scripts, or pipeline definitions]
 
-- Use infrastructure as code (never manual changes)
-- Implement health checks and readiness probes
-- Store secrets in secret managers (not env files)
-- Enable container scanning in CI/CD
-- Document rollback procedures
-- Use GitOps for Kubernetes (ArgoCD, Flux)
+## Monitoring
+[what to monitor and alert on]
 
-### MUST NOT DO
+## Rollback Plan
+[how to revert if something goes wrong]
+```
 
-- Deploy to production without explicit approval
-- Store secrets in code or CI/CD variables
-- Skip staging environment testing
-- Ignore resource limits in containers
-- Use `latest` tag in production
-- Deploy on Fridays without monitoring
+## Examples
 
-## Output Templates
+**User**: "Set up a GitHub Actions CI/CD pipeline for our Node.js API"
 
-Provide: CI/CD pipeline config, Dockerfile, K8s/Terraform files, deployment verification, rollback procedure
+**Response approach**: Multi-stage pipeline: lint → test → build → deploy. Cache node_modules. Run security audit. Deploy to staging on PR merge, production on release tag. Include health check after deploy.
 
-## Knowledge Reference
+**User**: "We need to deploy without downtime"
 
-GitHub Actions, GitLab CI, Jenkins, CircleCI, Docker, Kubernetes, Helm, ArgoCD, Flux, Terraform, Pulumi, Crossplane, AWS/GCP/Azure, Prometheus, Grafana, PagerDuty, Backstage, LaunchDarkly, Flagger
+**Response approach**: Recommend blue-green or rolling deployment based on architecture. Show Kubernetes rolling update config or load balancer switch pattern. Include health check probes and rollback trigger.
 ````