@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/deep-research/POWER.md

@@ -0,0 +1,67 @@
+````markdown
+---
+inclusion: manual
+name: deep-research
+description: "Use when a task needs multi-round research rather than a quick lookup: iterative search, gap finding, corroboration across sources, contradiction handling, evidence-led synthesis before planning or implementation. Also use when the user asks for 'deep research', 'latest info', or 'how does X compare to Y publicly'."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.1"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Deep Research
+
+## Purpose
+
+You are the specialist for iterative evidence gathering and synthesis.
+
+Your job is to find what is missing, not just summarize the first page of results. Stop when remaining uncertainty is low-impact or explicitly reported to the user.
+
+## When to Use
+
+- The task needs deep web or repo research before planning or implementation
+- The first-pass answer is incomplete, contradictory, or likely stale
+- The user explicitly asks for research, latest information, or public-repo comparison
+- Claims are contested or the topic changes fast (AI tooling, frameworks, protocols)
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Define the narrowest possible form of the question and what would count as enough evidence.
+2. Run a first pass and identify gaps, contradictions, and missing facts.
+3. Search specifically for the missing facts, stronger sources, or counterexamples.
+4. Rank sources by directness (primary > secondary > tertiary), recency, and authority.
+5. Separate **sourced facts**, **informed inference**, and **unresolved gaps** in the output.
+6. Apply the sub-agent reader test for substantial research deliverables — pass the synthesis to a fresh context to verify it's self-contained.
+
+### Constraints
+
+- Do not stop at one source when the claim is unstable or contested.
+- Do not present inference as sourced fact.
+- Do not turn research into implementation before the evidence is good enough.
+- Do not bloat the final answer with low-signal citations.
+
+## Output Format
+
+Structure clearly as:
+
+- **Key findings** — the answer, directly stated
+- **Evidence** — sourced facts with citations ranked by confidence
+- **Inference** — what follows logically from the evidence (labeled as inference)
+- **Open questions** — what remains unresolved and why it matters
+
+## References
+
+| File                                      | Load when                                                                                                                                                   |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/multi-round-research-loop.md` | You need the full iterative loop: search, corroboration, contradiction handling, evidence table, sub-agent reader test, stop rules, and failure mode guide. |
+
+## Examples
+
+- "Research how Anthropic structures their agent skills — compare to what CBX does"
+- "What's the latest on evaluator-optimizer patterns in production agent systems?"
+- "Deep research on OKLCH vs HSL for design systems — what do practitioners actually use?"
+- "Find counterexamples to the claim that parallel agents always improve speed"
+````

package/workflows/powers/deep-research/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: deep-research
+description: "Use when a task needs multi-round research rather than a quick lookup: iterative search, gap finding, corroboration across sources, contradiction handling, evidence-led synthesis before planning or implementation. Also use when the user asks for 'deep research', 'latest info', or 'how does X compare to Y publicly'."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.1"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Deep Research
+
+## Purpose
+
+You are the specialist for iterative evidence gathering and synthesis.
+
+Your job is to find what is missing, not just summarize the first page of results. Stop when remaining uncertainty is low-impact or explicitly reported to the user.
+
+## When to Use
+
+- The task needs deep web or repo research before planning or implementation
+- The first-pass answer is incomplete, contradictory, or likely stale
+- The user explicitly asks for research, latest information, or public-repo comparison
+- Claims are contested or the topic changes fast (AI tooling, frameworks, protocols)
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Define the narrowest possible form of the question and what would count as enough evidence.
+2. Run a first pass and identify gaps, contradictions, and missing facts.
+3. Search specifically for the missing facts, stronger sources, or counterexamples.
+4. Rank sources by directness (primary > secondary > tertiary), recency, and authority.
+5. Separate **sourced facts**, **informed inference**, and **unresolved gaps** in the output.
+6. Apply the sub-agent reader test for substantial research deliverables — pass the synthesis to a fresh context to verify it's self-contained.
+
+### Constraints
+
+- Do not stop at one source when the claim is unstable or contested.
+- Do not present inference as sourced fact.
+- Do not turn research into implementation before the evidence is good enough.
+- Do not bloat the final answer with low-signal citations.
+
+## Output Format
+
+Structure clearly as:
+
+- **Key findings** — the answer, directly stated
+- **Evidence** — sourced facts with citations ranked by confidence
+- **Inference** — what follows logically from the evidence (labeled as inference)
+- **Open questions** — what remains unresolved and why it matters
+
+## References
+
+| File                                      | Load when                                                                                                                                                   |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/multi-round-research-loop.md` | You need the full iterative loop: search, corroboration, contradiction handling, evidence table, sub-agent reader test, stop rules, and failure mode guide. |
+
+## Examples
+
+- "Research how Anthropic structures their agent skills — compare to what CBX does"
+- "What's the latest on evaluator-optimizer patterns in production agent systems?"
+- "Deep research on OKLCH vs HSL for design systems — what do practitioners actually use?"
+- "Find counterexamples to the claim that parallel agents always improve speed"

package/workflows/powers/deep-research/references/multi-round-research-loop.md

@@ -0,0 +1,80 @@
+# Multi-Round Research Loop
+
+Load this when the research task is broad, unstable, contested, or likely to have conflicting public sources — or when the user explicitly asks for deep or latest research.
+
+## The Core Principle
+
+Your job is to find what is _missing_, not just summarize the first page of results. Stop when remaining uncertainty is low-impact or explicitly reported back to the user.
+
+---
+
+## The Loop
+
+### Round 1: Define and search broadly
+
+1. **Narrow the question** — State the most specific version of what you're trying to find. Vague questions produce vague results.
+2. **Search** — Run initial queries across the most likely sources (official docs, engineering blogs, GitHub repos, research papers as appropriate).
+3. **Record gaps** — What did this pass _not_ answer? What's contradictory? What's suspiciously absent?
+
+### Round 2: Target the gaps
+
+4. **Search directly for the missing facts** — Use specific, targeted queries (not broad topic queries). Prefer: official docs > primary source blog > authoritative community reference > general article.
+5. **Search for contradictions** — If two sources disagree, search specifically for why. Age, version differences, and context often explain it.
+6. **Seek counterexamples** — Actively search for "X doesn't work", "X is wrong", "problems with X" — not just confirmation.
+
+### Round 3: Corroborate and synthesize
+
+7. **Cross-verify** unstable claims against at least one independent source.
+8. **Rank sources** by directness (primary > secondary > tertiary), recency (newer > older for fast-moving topics), and authority (official > community > anecdotal).
+9. **Write the evidence table** — Track what you found, not just conclusions:
+
+| Fact    | Source       | Confidence          | Open question            |
+| ------- | ------------ | ------------------- | ------------------------ |
+| [Claim] | [URL or doc] | High / Medium / Low | [What's still uncertain] |
+
+---
+
+## Stop Rule
+
+Stop when:
+
+- Remaining uncertainty is low-impact (won't change the recommendation)
+- OR the question is genuinely unresolvable from public sources (report this explicitly)
+- OR you've completed 3 rounds without new signal (diminishing returns — report what's known and what's not)
+
+Do NOT stop after one source when the claim is unstable, contested, or from a secondary source.
+
+---
+
+## Output Format
+
+Separate clearly:
+
+- **Sourced facts** — you have direct evidence
+- **Informed inference** — logically follows from evidence but not directly stated
+- **Unresolved gaps** — you searched and didn't find it; note what's unknown
+
+Do not present inference as fact. Do not present absence of evidence as evidence of absence.
+
+---
+
+## Common Research Failure Modes
+
+| Failure                               | Fix                                                |
+| ------------------------------------- | -------------------------------------------------- |
+| Stopping at first result              | Check at least 2-3 sources for any unstable claim  |
+| Only finding confirmation             | Actively search for counterexamples and criticisms |
+| Treating recent = correct             | Cross-check recency with authority and context     |
+| Vague queries returning vague results | Restate the question as a specific, narrow query   |
+| Reporting uncertainty as fact         | Use "inference" or "unknown" tags explicitly       |
+| Burying the answer in context         | Lead with the finding; evidence follows            |
+
+---
+
+## Sub-Agent Reader Test
+
+After completing research, if the output will be used by another agent or handed to a human without context:
+
+- Pass the research summary to a fresh sub-agent with no conversation history
+- Ask: "What is the main finding?", "What is still uncertain?", "What sources support the key claims?"
+- If the fresh reader gets it wrong, the synthesis has context bleed — revise before delivery

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

@@ -1,153 +1,167 @@
 ````markdown
 ---
 inclusion: manual
-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.
 ````